Using the pyaoscx Package

Executing Workflows

After installing the package, you'll be able to run the example workflows.

We'll start with analyzing and then executing the simplest example workflow, print_system_info.py. In order to do this, navigate to your Python package installation directory. If you don't know where that is, run the command pyaoscx and you'll see it after "Location: " (for example, something like "Location: c:\users\administrator\appdata\local\programs\python\python37-32\lib\site-packages"). Make sure you run the command with your virtual environment activated. Then copy the workflows from inside the package install location to the location you've created for your project and virtual environment.

The print_system_info.py workflow simply logs into a switch and then prints switch configuration info to the console. Open your copy of the script and you’ll notice that the try: block in the main() function consists of these statements:

session_dict = dict(s=session.login(base_url, username, password), url=base_url)

system_info_dict = system.get_system_info(params={"selector": "configuration"}, **session_dict)

pprint.pprint(system_info_dict)

The first two lines call the session.login() and system.get_system_info() functions in the session and system modules, respectively. The third line simply prints the system information out to the console in readable format.

Execute the workflow. There are multiple ways to do this, such as via an Integrated Development Environment (IDE) that supports executing Python scripts. Another way to execute the workflow is invoking the Python executable through the command line as follows: python3 /<path>/<to>/<workflow>

You’ll be asked to input the switch’s out-of-band management IP address, login username, and password. After you do that successfully, the rest of the script should run and you should see this output:

C:\Users\administrator\AppData\Local\Programs\Python\Python37-32\python.exe "C:/Users/administrator/Documents/git/packaging/pyaoscx/workflows/print_system_info.py"
Switch IP Address: <IP address redacted>
Switch login username: <username redacted>
Switch login password: <password redacted>
INFO:root:SUCCESS: Login succeeded
INFO:root:SUCCESS: Getting dictionary of system information succeeded
{'aaa': {'fail_through': False,
                 'login_lockout_time': 300,
                 'radius_auth': 'pap',
                 'radius_retries': 1,
                 'radius_timeout': 5,
.
.
. <additional output here omitted for the sake of brevity
.
.
}
INFO:root:SUCCESS: Logout succeeded

Congratulations! You’ve just run your first AOS-CX Python workflow!

Creating Workflows

To create your own workflows, follow the structure of the three provided example workflows. Generally speaking, the key elements of a workflow script are:

1. Importing the appropriate modules from pyaoscx
2. Logging into the switch(es) by calling session.login()
3. Calling the functions in the imported modules to execute the desired actions (the ‘core steps’ of the workflow)
4. Logging out of the switch(es) by calling session.logout()

If you open configure_l2_l3_vlans.py and compare it to print_system_info.py, you’ll notice that the main difference between the two scripts is the core steps. Inside the try: block, instead of getting the system information and printing it, we have calls to create a VLAN and VLAN interface, among other operations.

vlan.create_vlan_and_svi(999, 'VLAN999', 'vlan999', 'vlan999',
                         'For LAB 999', '10.10.10.99/24', vlan_port_desc='### SVI for LAB999 ###',
                         **session_dict)

# Add DHCP helper IPv4 addresses for SVI
dhcp.add_dhcp_relays('vlan999', "default", ['1.1.1.1', '2.2.2.2'], **session_dict)

# Add a new entry to the Port table if it doesn't yet exist
interface.add_l2_interface('1/1/20', **session_dict)

# Update the Interface table entry with "user-config": {"admin": "up"}
interface.enable_disable_interface('1/1/20', **session_dict)

# Set the L2 port VLAN mode as 'access'
vlan.port_set_vlan_mode('1/1/20', "access", **session_dict)

# Set the access VLAN on the port
vlan.port_set_untagged_vlan('1/1/20', 999, **session_dict)

📘

Module Documentation

In order to see the available modules, and the functionality provided in each module, please see our pyaoscx "Read the Docs" documentation here. This is the easiest way to discover what each function does and how to call it.

Similarly, the core steps in cleanup_l2_l3_vlans.py unconfigure the configuration done by configure_l2_l3_vlans.py by essentially performing the opposite actions:

# Delete all DHCP relays for interface
dhcp.delete_dhcp_relays('vlan999', "default", **session_dict)

# Delete VLAN and SVI
vlan.delete_vlan_and_svi(999, 'vlan999', **session_dict)

# Initialize L2 interface
interface.initialize_interface('1/1/20', **session_dict)

In the example workflows, the arguments in the function calls are hardcoded in the scripts, and the switch IP address and login credentials are provided by the user at runtime. Alternatively, you could have the script accept these data points, along with the arguments for the other functions, from an input file.