# PyVyOS Documentation PyVyOS is a Python library for interacting with VyOS devices via their API. This documentation provides a guide on how to use PyVyOS to manage your VyOS devices programmatically. You can find the complete PyVyOS documentation on [Read the Docs](https://pyvyos.readthedocs.io/en/latest/). ## Installation You can install PyVyOS using pip: ```bash pip install pyvyos ``` ## Getting Started ### Importing and Disabling Warnings for verify=False Before using PyVyOS, it's a good practice to disable urllib3 warnings and import the required modules, IF you use verify=False: ``` import urllib3 urllib3.disable_warnings() ``` ### Using API Response Class PyVyOS uses a custom ApiResponse data class to handle API responses: ``` @dataclass class ApiResponse: status: int request: dict result: dict error: str ``` ### Initializing a VyDevice Object #### Configuring Your Environment for VyDevice 1. Rename the file .env.example to .env. 1. Open the .env file in a text editor. 1. Replace the placeholder values with your VyOS device credentials: - **VYDEVICE_HOSTNAME**: Your device's hostname or IP address. - **VYDEVICE_APIKEY**: Your API key for authentication. - **VYDEVICE_PORT**: The port number for the API. Default 443 - **VYDEVICE_PROTOCOL**: The protocol (e.g., http or https). Default https - **VYDEVICE_VERIFY_SSL**: Set to True or False for SSL verification. ``` # Retrieve VyOS device connection details from environment variables and configure VyDevice from dotenv import load_dotenv load_dotenv() hostname = os.getenv('VYDEVICE_HOSTNAME') apikey = os.getenv('VYDEVICE_APIKEY') port = os.getenv('VYDEVICE_PORT') protocol = os.getenv('VYDEVICE_PROTOCOL') verify_ssl = os.getenv('VYDEVICE_VERIFY_SSL') # Convert the verify_ssl value to a boolean verify = verify_ssl.lower() == "true" if verify_ssl else True device = VyDevice(hostname=hostname, apikey=apikey, port=port, protocol=protocol, verify=verify) ``` ## Using PyVyOS ### configure, then set The configure_set method sets a VyOS configuration: ``` # Set a VyOS configuration response = device.configure_set(path=["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"]) # Check for errors and print the result if not response.error: print(response.result) ``` ### configure, then show a single OBJECT value ``` # Retrieve VyOS return values for a specific interface response = device.retrieve_return_values(path=["interfaces", "dummy", "dum1", "address"]) print(response.result) ``` ### configure, then show OBJECT The retrieve_show_config method retrieves the VyOS configuration: ``` # Retrieve the VyOS configuration response = device.retrieve_show_config(path=[]) # Check for errors and print the result if not response.error: print(response.result) ``` ### configure, then delete OBJECT ``` # Delete a VyOS interface configuration response = device.configure_delete(path=["interfaces", "dummy", "dum1"]) ``` ### configure, then save ``` # Save VyOS configuration without specifying a file (default location) response = device.config_file_save() ``` ### configure, then save FILE ``` # Save VyOS configuration to a specific file response = device.config_file_save(file="/config/test300.config") ``` ## show OBJECT ``` # Show VyOS system image information response = device.show(path=["system", "image"]) print(response.result) ``` ### generate OBJECT ``` # Generate an SSH key with a random string in the name randstring = ''.join(random.choice(string.ascii_letters + string.digits) for _ in range(20)) keyrand = f'/tmp/key_{randstring}' response = device.generate(path=["ssh", "client-key", keyrand]) ``` ### reset OBJECT The reset method allows you to run a reset command: ``` # Execute the reset command response = device.reset(path=["conntrack-sync", "internal-cache"]) # Check for errors and print the result if not response.error: print(response.result) ``` ### configure, then load FILE ``` # Load VyOS configuration from a specific file response = device.config_file_load(file="/config/test300.config") ```