summaryrefslogtreecommitdiff
path: root/examples
diff options
context:
space:
mode:
Diffstat (limited to 'examples')
-rw-r--r--examples/basic.py67
-rw-r--r--examples/integration_smoke.py105
-rw-r--r--examples/vagrant/.env.example12
-rw-r--r--examples/vagrant/VAGRANT.md41
-rw-r--r--examples/vagrant/Vagrantfile47
-rw-r--r--examples/vagrant/virtualbox-wsl2.sh2
6 files changed, 274 insertions, 0 deletions
diff --git a/examples/basic.py b/examples/basic.py
new file mode 100644
index 0000000..1e1b552
--- /dev/null
+++ b/examples/basic.py
@@ -0,0 +1,67 @@
+"""Basic read-only pyvyos usage example.
+
+Run with environment variables loaded from a .env file or exported in your
+shell:
+
+ VYDEVICE_HOSTNAME=192.0.2.1 \\
+ VYDEVICE_APIKEY=secret \\
+ python examples/basic.py
+
+This example only runs read-only commands.
+"""
+
+import os
+import pprint
+
+from dotenv import load_dotenv
+
+from pyvyos import ApiResponse, VyDevice
+
+load_dotenv()
+
+
+def env_bool(name: str, default: str = "true") -> bool:
+ return os.environ.get(name, default).lower() in ("1", "true", "yes")
+
+
+def make_device() -> VyDevice:
+ return VyDevice(
+ hostname=os.environ["VYDEVICE_HOSTNAME"],
+ apikey=os.environ["VYDEVICE_APIKEY"],
+ port=int(os.environ.get("VYDEVICE_PORT", "443")),
+ protocol=os.environ.get("VYDEVICE_PROTOCOL", "https"),
+ verify=env_bool("VYDEVICE_VERIFY_SSL"),
+ timeout=int(os.environ.get("VYDEVICE_TIMEOUT", "60")),
+ )
+
+
+def print_response(label: str, response: ApiResponse) -> None:
+ print(f"\n== {label} ==")
+ if response.error:
+ print(f"Error {response.status}: {response.error}")
+ return
+
+ pprint.pprint(response.result)
+
+
+def main() -> None:
+ device = make_device()
+
+ print_response(
+ "Running system configuration",
+ device.retrieve_show_config(path=["system"]),
+ )
+
+ print_response(
+ "System images",
+ device.show(path=["system", "image"]),
+ )
+
+ print_response(
+ "Interface address values",
+ device.retrieve_return_values(path=["interfaces"]),
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/examples/integration_smoke.py b/examples/integration_smoke.py
new file mode 100644
index 0000000..137ca9b
--- /dev/null
+++ b/examples/integration_smoke.py
@@ -0,0 +1,105 @@
+"""Integration smoke test for pyvyos.
+
+This script changes configuration on the target VyOS device and should only
+be used against a disposable lab device, such as the one provided by
+``examples/vagrant/``.
+
+It may create and delete dummy interfaces, generate temporary files on the
+device, and save/load configuration files.
+
+Run only against a lab device::
+
+ PYVYOS_ALLOW_MUTATING_EXAMPLE=1 \\
+ VYDEVICE_HOSTNAME=127.0.0.1 \\
+ VYDEVICE_APIKEY=secret \\
+ python examples/integration_smoke.py
+"""
+
+import os
+import pprint
+import random
+import string
+import sys
+
+from dotenv import load_dotenv
+
+from pyvyos import VyDevice
+
+load_dotenv()
+
+
+def env_bool(name: str, default: str = "true") -> bool:
+ return os.environ.get(name, default).lower() in ("1", "true", "yes")
+
+
+def make_device() -> VyDevice:
+ return VyDevice(
+ hostname=os.environ["VYDEVICE_HOSTNAME"],
+ apikey=os.environ["VYDEVICE_APIKEY"],
+ port=int(os.environ.get("VYDEVICE_PORT", "443")),
+ protocol=os.environ.get("VYDEVICE_PROTOCOL", "https"),
+ verify=env_bool("VYDEVICE_VERIFY_SSL"),
+ timeout=int(os.environ.get("VYDEVICE_TIMEOUT", "60")),
+ )
+
+
+def main() -> None:
+ if os.environ.get("PYVYOS_ALLOW_MUTATING_EXAMPLE") != "1":
+ sys.exit(
+ "This example mutates the target device. "
+ "Set PYVYOS_ALLOW_MUTATING_EXAMPLE=1 to run it."
+ )
+
+ device = make_device()
+
+ # Retrieve the running configuration for the system tree.
+ pprint.pprint(device.retrieve_show_config(path=["system"]))
+
+ # Configure a dummy interface, read it back, then delete it.
+ pprint.pprint(
+ device.configure_set(
+ path=["interfaces", "dummy", "dum1", "address", "192.168.56.100/24"]
+ )
+ )
+ pprint.pprint(
+ device.retrieve_return_values(
+ path=["interfaces", "dummy", "dum1", "address"]
+ )
+ )
+ pprint.pprint(device.configure_delete(path=["interfaces", "dummy", "dum1"]))
+
+ # Generate a one-shot SSH client key.
+ randstring = "".join(
+ random.choice(string.ascii_letters + string.digits) for _ in range(20)
+ )
+ pprint.pprint(
+ device.generate(path=["ssh", "client-key", f"/tmp/key_{randstring}"])
+ )
+
+ # Operational commands.
+ pprint.pprint(device.show(path=["system", "image"]))
+ pprint.pprint(device.reset(path=["conntrack-sync", "internal-cache"]))
+
+ # Save and reload the running configuration to/from a file on the device.
+ pprint.pprint(device.config_file_save(file="/config/test300.config"))
+ pprint.pprint(device.config_file_load(file="/config/test300.config"))
+
+ # Batch multiple configuration operations in a single request.
+ pprint.pprint(
+ device.configure_multiple_op(
+ op_path=[
+ {
+ "op": "set",
+ "path": [
+ "interfaces", "dummy", "dum1", "address",
+ "192.168.56.100/24",
+ ],
+ },
+ {"op": "delete", "path": ["interfaces", "dummy", "dum1"]},
+ ]
+ )
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/examples/vagrant/.env.example b/examples/vagrant/.env.example
new file mode 100644
index 0000000..905f259
--- /dev/null
+++ b/examples/vagrant/.env.example
@@ -0,0 +1,12 @@
+# vyos https api key
+VYDEVICE_APIKEY="your_api_key"
+
+# vyos network interface
+VYDEVICE_IP=192.168.56.10
+VYDEVICE_NETMASK=255.255.255.0
+VYDEVICE_HTTPS_PORT=443
+
+# HOST_IP is the ip address of the host machine of the virtualbox
+# use your windows network interface for virtualbox running on windows host and using wsl2 for vagrant
+VYDEVICE_HOST_IP=192.168.0.114
+# use 127.0.0.1, virtualbox running on linux host or windows host
diff --git a/examples/vagrant/VAGRANT.md b/examples/vagrant/VAGRANT.md
new file mode 100644
index 0000000..e6312e2
--- /dev/null
+++ b/examples/vagrant/VAGRANT.md
@@ -0,0 +1,41 @@
+# Vagrant only for development and tests
+
+Vagrant is a tool for building and managing virtual machine environments
+in pyvyos we use vagrant to deploy vyos virtual machines
+for development and automated tests
+
+If you want to only use pyvyos you dont need to install vagrant
+
+# Vagrant install instructions
+
+1. Install Vagrant
+2. Install VirtualBox
+3. Install Vagrant plugins
+```
+vagrant plugin install vagrant-vyos
+
+```
+4. Install mkisofs
+```
+sudo apt install genisoimage
+```
+
+5. Create .env file
+```
+mv .env.example .env
+```
+
+6. Run vagrant up
+```
+vagrant up
+```
+7. Run vagrant ssh
+```
+vagrant ssh
+```
+
+# For Windows with wsl2:
+```
+export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"
+export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"
+``` \ No newline at end of file
diff --git a/examples/vagrant/Vagrantfile b/examples/vagrant/Vagrantfile
new file mode 100644
index 0000000..01dd23e
--- /dev/null
+++ b/examples/vagrant/Vagrantfile
@@ -0,0 +1,47 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Documentation:
+# - read VAGRANT.md
+# - need vagrant plugin install vagrant-vyos
+
+
+env_vars = File.readlines('.env').each_with_object({}) do |line, hash|
+ next if line.strip.empty? || line.start_with?('#')
+ key, value = line.strip.split('=', 2)
+ hash[key.strip] = value.strip.gsub(/(^['"]|['"]$)/, '')
+end
+
+HTTPS_PORT = env_vars['VYDEVICE_HTTPS_PORT']
+API_KEY = env_vars['VYDEVICE_APIKEY']
+NETMASK = env_vars['VYDEVICE_NETMASK']
+VYOS_VM_IP = env_vars['VYDEVICE_IP']
+VYOS_VM_HOST_IP = env_vars['VYDEVICE_HOST_IP']
+
+
+$script = <<-SHELL
+ cfg=/opt/vyatta/sbin/vyatta-cfg-cmd-wrapper
+ $cfg begin
+ $cfg set service https api debug
+ $cfg set service https api keys id apikey key #{API_KEY}
+ $cfg set service https listen-address $1
+ $cfg set service https port #{HTTPS_PORT}
+ $cfg commit
+ $cfg end
+SHELL
+
+Vagrant.configure("2") do |config|
+ # Device VyOS
+ config.vm.define "pyvyos_device" do |pyvyos|
+ pyvyos.vm.box = "vyos/current"
+ pyvyos.vm.hostname = "pyvyos-device"
+ pyvyos.vm.network "private_network", ip: VYOS_VM_IP , netmask: NETMASK
+ pyvyos.ssh.host = VYOS_VM_HOST_IP
+ pyvyos.vm.network "forwarded_port", guest: 443, host: 8433, id: "https", auto_correct: true, protocol: "tcp", host_ip: VYOS_VM_HOST_IP
+ pyvyos.vm.network "forwarded_port", guest: 22, host: 2022, id: "ssh", auto_correct: true, protocol: "tcp", host_ip: VYOS_VM_HOST_IP
+ pyvyos.ssh.username = "vyos"
+ pyvyos.ssh.password = "vyos"
+ pyvyos.ssh.insert_key = false
+ pyvyos.vm.provision "shell", inline: $script, args: [VYOS_VM_IP]
+ end
+end \ No newline at end of file
diff --git a/examples/vagrant/virtualbox-wsl2.sh b/examples/vagrant/virtualbox-wsl2.sh
new file mode 100644
index 0000000..4cd545d
--- /dev/null
+++ b/examples/vagrant/virtualbox-wsl2.sh
@@ -0,0 +1,2 @@
+export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"
+export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"
generated by cgit v1.2.3 (git 2.39.1) at 2026-07-14 22:09:43 +0000