Mastering PAN-OS Vsys in Python

Photo by Maarten Deckers on Unsplash

Time for a comprehensive lesson in vsys with pandevice, a python SDK from Palo Alto Networks.

To begin, let’s have a brief refresher on the places where configuration could be located in PAN-OS:

1. Stored inside a vsys. Examples include objects and firewall rules.
2. Stored outside a vsys. Examples include interface management profiles or HA configuration.
3. Stored outside a vsys but imported into the vsys. Examples include interfaces or virtual routers.

When you are working with vsys in pandevice you have two ways to specify what you want the vsys to be:

1. Simple vsys mode: Set the vsys parameter for the pandevice.firewall.Firewall object. “vsys1” is assumed if no other vsys is specified.
2. Explicit vsys mode: Create a pandevice.device.Vsys object as a child of your pandevice.firewall.Firewall object.

Let’s take a look at some example code to see how pandevice deals with the three configuration locations mentioned above.

1. Objects Stored in a Vsys

Let’s say we want to create an address object in vsys2. Here’s what the code would look like using simple vsys mode (setting the vsys param to something):

And here’s what it would look like using explicit vsys mode (using a pandevice.device.Vsys object to specify the vsys):

2. Objects Stored Outside a Vsys

When objects are stored outside of vsys, pandevice will ignore the vsys setting, so it doesn’t matter whether you’re using simple or explicit vsys mode. Here’s an example where we are creating an interface management profile:

3. Objects Imported into a Vsys

Here’s the list of things that that PAN-OS currently imports into a vsys:

• Interfaces
• VLANs
• Virtual Wires
• Virtual Routers

When it comes to objects imported into a vsys, pandevice tries its best to handle things behind the curtains, but some care is still needed. This is because there are two situations to be aware of with importable objects: either the vsys is both known and correctly configured in your pandevice object hierarchy or not. Besides configuring vsys importables, we will also need to discuss how refreshes (getting the list of objects) work with importables.

As a side note: vsys importable objects have aset_vsys() method, so you can programmatically determine if what you’re dealing with is a vsys importable or not.

Setting Config When Everything is Known

If the vsys is both known and correctly configured in your pandevice object hierarchy, then this is straightforward. The code for creating a vsys importable and then importing it looks exactly like the code above does for things that live inside a vsys. This is great from an ease of use perspective when it comes to pandevice, but from a learning perspective, it’s not a super useful example.

Instead, let’s make things a little trickier: let’s say we want to change ethernet1/2’s import from vsys1 to vsys2. Let’s also say that we want to change the static IP addresses to just be 10.2.3.1/24. Here’s what that code could look like:

Setting Config When Something is Unknown

Let’s say we still want to do what we did above, but we don’t know (or don’t care) where the interface is currently imported into. Let’s also assume we don’t have the freedom to delete the interface this time as there are other parts of the config that reference ethernet1/2. Also, since we only need to change the static IP addresses, let’s make our code more succinct and just update the IP addresses of ethernet1/2 instead of re-applying the entire interface’s config. This would both speed up the script (since we don’t need to do the refresh API call anymore) and decrease network load (less data sent over the wire). The code would look something like this:

Vsys Importable Refreshes

When doing refreshall() and dealing with vsys importables, specifying a vsys (either using simple or explicit mode) instructs pandevice to limit results to objects that are imported into the specified vsys. Here’s an example where we want to print out a list of interfaces that are available to vsys2:

If instead you want all configured interfaces, you have two options. If you have specified a vsys (perhaps you’re using simple mode), then you can specify matching_vsys as False in the EthernetInterface.refreshall() invocation. Alternatively, you can make sure that there is no vsys specified, and then pandevice will not perform any secondary filtering.

Managing Object Hierarchy With Multiple Vsys

If you have the need to work with multiple vsys in the same script within the same script execution, there is a pandevice.firewall.Firewall method that will come in handy: organize_into_vsys(). This will add a pandevice.device.Vsys object for each vsys on your firewall, then move imported objects (that are children of your firewall object) underneaththe appropriatepandevice.device.Vsys object.

So the use case for something like this is very specific, but if this is something you have a need for, it will drastically simplify the discovery portion of the automation system you’re creating.

There are a few things to keep in mind when using this method:

1. Make sure that your firewall object’s vsys param is set to None (this is the default) before invoking this command.
2. Objects attached to your pandevice.firewall.Firewall object that either natively reside in the vsys or that live outside of a vsys are not moved in the firewall object’s hierarchy, because organize_into_vsys() is specifically for vsys importable objects.
3. Whether you have pandevice.device.Vsys objects already present or not, you will effectively be working in explicit vsys mode after invoking organize_into_vsys().

Choosing a Pandevice Vsys Mode

So which way is best: simple or explicit vsys mode? In practice the main reason you’d want to use the pandevice.device.Vsys object is because you’re consciously designing automation that works with multiple vsys at the same time.

Another thing to consider is that (as of pandevice v0.13.0) when running op commands, pandevice assumes the firewall’s vsys param is set to the vsys to run the op command in, so it’s probably best to stick with simple vsys mode if there is no explicit need for a multi-vsys script.

Conclusion

You now know all there is to know about vsys and how to handle it using pandevice. Congratulations, and venture forward with all the confidence and understanding you have gained!