A few months ago, I had written a blog post on building a simple chatbot with Webex. You can find that here.

At the time I was already thinking about some follow-up content, where I could walk through how to use AdaptiveCards to make the bot a little fancier - but I decided to wait a bit & see how the first post performed first.

Well, now it’s a few months later & I suppose it’s about time I write this 😄.

So in this post - We’ll build on the code I used in the last post. We’ll show how to add cards to both display information, as well as take user input.

What are AdaptiveCards?

AdaptiveCards are actually not a Webex/Cisco-specific thing! They were actually created by Microsoft with the intention of being a platform-agnostic way of displaying information. So in theory, a card schema written for a Webex bot could be taken & re-used on another messaging platform that implements AdaptiveCards - without any/much rework.

Hopefully this should mean a more consistent user experience for a bot that is supported across multiple platforms. The cards themselves can also enhance the experience by making your bot more dynamic & interactive. Maybe a developer or network engineer is okay with issuing specific syntax-based commands to a bit - but what about someone who is less computer savvy? Using cards makes it easy to provide guided input with textboxes, buttons, and toggles.

AdaptiveCards are built on a standard JSON structure with a pre-defined schema of card properties. Let’s take a quick look at a simple example:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.2",
    "body": [
        {
            "type": "TextBlock",
            "text": "Hello there! What's your name?",
            "wrap": true
        },
        {
            "type": "Input.Text",
            "placeholder": "Your name here",
            "id": "user_name"
        },
        {
            "type": "ActionSet",
            "actions": [
                {
                    "type": "Action.Submit",
                    "title": "Submit"
                }
            ]
        }
    ]
}

So in the JSON payload above, we’re creating a card that asks for user input. We have a block of text that asks the user “What’s your name?”, then we provide a text input field, and finally a submit button. Looks pretty straightforward, yeah?

We’ll get into the specifics around how to create that card JSON in a bit, but you can always use Microsoft’s AdaptiveCard Designer to play around with card elements/structure.

So what would that card look like when rendered in Webex? Let’s take a look:

That card seems a lot more user-friendly than trying to explain to your users that they need to remember some sytax like /botcommand username set <firstname> <lastname>. Instead, they can just enter the info on the card & click submit.

Sending a Static, Default Card from a JSON File

So first we’ll start off with the easier scenario. We’ll have a pre-defined JSON card built, and use the bot to load & send this card response.

One note before we get started - I’ll be building on my simple weather chatbot code that I mentioned earlier. If you’re following along, you can pull down that code from here.

Okay, to start off - we’ll be creating a card that allows a user to enter their desired zip code. Instead of having to remember the specific command syntax, a user will instead just issue the weather command & our bot will prompt for information via a card.

I’ve used the Microsoft Adaptive Card Designer to build out the basic card structure, which I’ve kept simple for now. Here’s what that looks like:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.2",
    "body": [
        {
            "type": "TextBlock",
            "text": "Get Current Weather",
            "wrap": true,
            "size": "Medium",
            "weight": "Bolder"
        },
        {
            "type": "TextBlock",
            "text": "Enter a Zip code:",
            "wrap": true
        },
        {
            "type": "Input.Number",
            "placeholder": "00000",
            "id": "zip_code",
            "min": 1,
            "max": 99950
        },
        {
            "type": "ActionSet",
            "actions": [
                {
                    "type": "Action.Submit",
                    "title": "Get Weather",
                    "data": {
                        "callback_keyword": "weather"
                    }
                }
            ]
        }
    ]
}

This card looks pretty similar to the example I used earlier. We have an initial text block that displays the title “Get Current Weather”, and we’ve added attributes for bold text & a medium size.

Next, we have a normal text block prompting the user to enter their zip code. This is followed by a number input box for that data entry.

The input box has a “min” & “max” value for the zip code from 1 to 99950 - which is the full range of US zip codes. We also need to assign any input a unique “id” value - which we’ll see later is used to pull out the user input from the response.

Last, we have our actions - which similar to earlier. This will present as a simple submit button with the text “Get Weather”. The important note here is adding a data dictionary with a callback_keyword sub-element. We set the callback_keyword to the command we want this submission to be sent to. In our case, we want the input to be sent back to the weather command.

Now to implement. Back in our bot, we’ll edit the weather.py file to load the card & assign as the default command response. Let’s take a look:

### Script snippet

with open("./input-card.json", "r") as card:
    INPUT_CARD = json.load(card)

class WeatherByZIP(Command):
    def __init__(self):
        super().__init__(
            command_keyword="weather",
            help_message="Get current weather conditions by ZIP code.",
            card=INPUT_CARD,
        )
        
### Script snippet

In the above snippet, I’ve extracted just the pieces we’ll be editing. For full examples, please see the final example repo here.

I’ve saved that JSON payload from earlier as input-card.json. Then we’ll open that card file & assign that JSON payload to a variable called INPUT_CARD.

Since we’ll expect this card to be the primary method of collecting a zip code - we’ll make this card the default response from our bot when the command is triggered. In my original code, we initialized the WeatherByZIP class with card=None - which instead passed our input directly to the execute() function. In this case, we’ll set that to card=INPUT_CARD to send our form.

With all that done, let’s test it out:

Collecting & Processing Card Submissions

Now that we have our input card, let’s move on to processing the response.

In the original example, we expected the user to enter a command like weather 12345 - and it was easy enough to just strip the 5-digit zip code from the response.

Since a card could have many input boxes, we instead receive that data back in a structured JSON format.

If we check out the logging in the webex_bot console, we can see the payload that gets returned to us when the card is submitted:

2022-03-03 14:59:26  [INFO]  [webex_websocket_client.root._process_incoming_websocket_message]:62 attachment_actions from message_base_64_id: Webex Teams AttachmentAction:
{
  "id": "--removed--",
  "type": "submit",
  "messageId": "--removed--",
  "inputs": {
    "callback_keyword": "weather",
    "zip_code": "12345"
  },
  "personId": "--removed--",
  "roomId": "--removed--",
  "created": "2022-03-03T19:59:24.820Z"
}

Using this output, we can see exactly what data is passed back to our bot. Under imports, we do see the correct callback_keyword that we defined in our card JSON. But we also see the user input - which is 12345. This is listed under the key zip_code which is the id we assigned to our input field earlier.

Now we can easily dig through this response to pull out the data we need. This JSON payload is delivered to the execute function under the attachment_actions parameter.

So we’ll make some minor modifications to our original code to pull that value out.

def execute(self, message, attachment_actions, activity):
    zip_code = attachment_actions.inputs['zip_code']

As a reminder, zip_code is the variable we’re using inside the execute() function to store the requested zip code - which is then passed to the OpenWeather API.

Previously, we had just assigned the value of message to zip_code, which was the incoming text message from the user.

Instead, this time we’ll fetch the zip code from the incoming card response, using attachment_actions.inputs & pulling out the zip_code key.

With that simple change completed, we should be able to ask the bot for the weather, input our zip code, then receive the same text-based output as before.

Here’s what that looks like now:

As we would expect, upon hitting Get Weather - the bot returns the text-based weather report.

Next, we’ll take a look at dynamically building a card to display weather info.

Dynamically Building Cards

Now we get to the real fun part. We’ll need to dynamically build an AdaptiveCard response, depending on what values we want to present to the user.

I will be using a Python module called adaptivecardbuilder. There are a handful of modules available that can help dynamically build cards, but this was the one I found to be most intuitive for me. While I will walk through an example here, I would also recommend reviewing their docs for additional context/examples.

You could also generate a JSON payload manually, or build one using the card designer & try to edit the JSON dynamically to change card values - but I won’t be doing that here.

So we’ll start off by installing the adaptive card module:

pip install adaptivecardbuilder

Before we build out the full card response, let’s take a quick look at how we can use this module.

In our execute() function, we’ll create a simple card that shows what zip code was entered.

First, we’ll need to add two new imports:

from webex_bot.models.response import Response
from adaptivecardbuilder import *

We’ll import the Response module from webex_bot, which will be required to send any attachments / custom response to the client. We’ll also import our adaptivecardbuilder module.

Next, we’ll modify the execute() function to look like the following:

    def execute(self, message, attachment_actions, activity):
        zip_code = attachment_actions.inputs['zip_code']
        
        card = AdaptiveCard()
        card.add(TextBlock(text=f"Weather for {zip_code}", size="Medium", weight="Bolder"))
        card_data = json.loads(asyncio.run(card.to_json()))

        card_payload = {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "content": card_data,
        }

        response = Response()
        response.text = "Test Card"
        response.attachments = card_payload

        return response

First we create a new AdaptiveCard() instance. With this new object we can add different card elements.

In this case, we add a single card element - a TextBlock. This has multiple attributes, including the actual text content, and we’re specifying that we want a medium font size & bold text.

Next we serialize the card payload to JSON using asyncio.run.

In order to prepare the card object to be attached to our response, we will need to set the appropriate headers. In this case we need to wrap the JSON structure with the contentType header. We could use the response.attachments object to send any number of different file types to the user, but in this case we’ll set that value to application/vnd.microsoft.card.adaptive.

Then we can assemble the response to the client. We’ll create a new instance of the Response() object, where we’ll define some necessary attributes.

We’ll set our response.text first. This will be the text message sent to the client. If the client supports adaptive cards, then this message won’t be shown to the user - however, it may still appear in pop notifications. If the client does not support adaptive cards, only this message will be shown to the user.

Next we attach our complete card payload using response.attachments.

Last but not least, we can return that response object - which is then sent back to the user.

In this case, we can see the bot responds back to our request with a simple card that displays the zip code.

Let’s move onto building out the remainder of the card. For the purposes of this example, I’ll also be pulling out a few additional items from the OpenWeather API - including sunrise, sunset, pressure, and high/low temperatures.

I’ll go ahead and show the full card build here:

card = AdaptiveCard()
card.add(TextBlock(text=f"Weather for {city}", size="Medium", weight="Bolder"))
card.add(ColumnSet())
card.add(Column(width="stretch"))
card.add(FactSet())
card.add(Fact(title="Temp", value=f"{temperature}"))
card.add(Fact(title="Conditions", value=f"{conditions}"))
card.add(Fact(title="Wind", value=f"{wind}"))
card.up_one_level()
card.up_one_level()
card.add(Column(width="stretch"))
card.add(FactSet())
card.add(Fact(title="High", value=f"{high_temp}"))
card.add(Fact(title="Low", value=f"{low_temp}"))
card.add(Fact(title="Humidity", value=f"{humidity}"))
card_data = json.loads(asyncio.run(card.to_json()))

If this looks a little messy, it is. There is a cleaner way to do this, which I’ll show in a moment.

The first thing to know is that the card JSON structure is hierarchical. So individual card items need to be added under the correct hierarchy - for example, you create a ColumnSet first, then add a Column underneath, then the items within that Column last.

See the below visualization of this card:

Top Level
 ↳ Text Block
 ↳ ColumnSet
   ↳ Column
     ↳ Fact Set
       ↳ Fact
       ↳ Fact
       ↳ Fact
    ↳ Column
     ↳ Fact Set
       ↳ Fact
       ↳ Fact
       ↳ Fact

So on our card, we first placed the title TextBlock. Underneath that we created a ColumnSet, which will contain two Columns.

Each one of those Columns contains a FactSet, which is a key/value pair listing of information. And of course, we add each Fact pair underneath the FactSet.

You’ll notice after building one Column and FactSet, we use card.up_one_level() twice - to return back to the ColumnSet level, where we then add a second Column.

This can certainly get a little confusing at first, but I’ll show a more intuitive method in a moment.

Let’s take a peak at what this looks like now:

Sub-cards & Better Card Building

In this section we’ll do two quick things. First we’ll take a look at a simpler, more visual way of building the cards. Then we’ll also expand our example with sub-cards.

The adaptivecardsbuilder module supports a second way of building cards, which I personally find to be much easier to use.

In this method, we just create a single card.add() object - and feed it a list of all the items on the card.

For me, this makes it easier because you can add indentation to each list item - which helps keep track of where you are at in the hierarchical structure.

To navigate within the structure, we use "<" to go up one level, or "^" to return to the top level.

I’ve re-written the earlier example with this new structure below:

card = AdaptiveCard()
card.add(
    [
        TextBlock(text=f"Weather for {city}", size="Medium", weight="Bolder"),
        ColumnSet(),
            Column(width="stretch"),
                FactSet(),
                    Fact(title="Temp", value=f"{temperature}F"),
                    Fact(title="Conditions", value=f"{conditions}"),
                    Fact(title="Wind", value=f"{wind} mph"),
                    "<",
                "<",
            Column(width="stretch"),
                FactSet(),
                Fact(title="High", value=f"{high_temp}F"),
                Fact(title="Low", value=f"{low_temp}F"),
                "^",
        ActionSet(),
            ActionShowCard(title="More Details"),
                ColumnSet(),
                    Column(width="stretch"),
                        FactSet(),
                            Fact(title="Humidity", value=f"{humidity}%"),
                            Fact(title="Pressure", value=f"{pressure}"),
                            "<",
                        "<",
                    Column(width="stretch"),
                        FactSet(),
                            Fact(title="Sunrise", value=f"{sunrise}"),
                            Fact(title="Sunset", value=f"{sunset}"),
    ]
)
card_data = json.loads(asyncio.run(card.to_json()))

Again, you’re welcome to use whichever method suits you - but I find this method to be a bit cleaner & easier to read/troubleshoot.

You can also see that I’ve added a new ActionSet, with a single action: ActionShowCard. This adds a nice little button to our card where we can optionally display additional information.

Here’s what that looks like now:

And if we expand that sub-card:

Sub-cards can be an easy way to hide excess information to keep the response clean & focus on the important information.

Well that’s it for this blog post. There’s a lot more you can do with cards, including adding images, video, tables, dropdown menus, etc. But I just wanted to show a few examples of building cards. They can be a simple way to make chatbots a little less boring!

Enjoy!

I’ve been spending some of my time lately working on a new project that involves an interactive chatbot - where you can send commands to the bot & ask for it to take certain actions or return information.

I didn’t previously have a ton of experience building something like this. Mostly what I’ve done before is just using Webex or Discord APIs to send alerts or messages to a room.

As with anything new - I’ve stumbled my way through a couple of things, but have been enjoying the challenge of trying something different. Building out some of the more interactive parts of the bot hasn’t been quite as difficult as I originally imagined, and some of the newer modules & SDKs have made the process much simpler.

With all that being said - I wanted to throw together a quick guide on how to get started building a basic chatbot, in case anyone else is interested but worried that it may be too complicated.

Repo here for all the sample code used below

Step 1: Getting API Keys

So the first thing we’ll worry about is getting signed up for a Webex developer account & generating API keys.

So head on over to the Webex Developer site & log in (or sign up for a new account).

Once logged in, we’ll go to the upper-right corner of the screen and click on our user icon - and select “My Webex Apps” from the drop down:

Then we’ll be asked what type of app we’re creating. In this case, we’ll select bot:

Next we’ll need to provide some details about our bot. This includes a display name, username, image, and some details. Once the bot is completed, we have the ability to publish it via the Webex App Hub where anyone could interact with it. If you’re looking to do this, make sure you give a good description of your bot!

After we finish all that, we’ll finally get our API key!

Webhook vs Websocket: Which to use?

Next, I wanted to cover the two primary methods of sending & receiving messages from the Webex APIs: Webhooks and websockets.

Webhooks

Likely webhooks are the method most people are familiar with. Using this method, we need to run out bot code on a publicly reachable URL. When we run our bot, one of our first actions will be sending a request to the Webex APIs with our bot URL. This way, every time Webex receives a message from a user that wants to interact with our bot, the Webex cloud knows where to send that chat message.

Now, the potential downside of using webhooks is that we need to 1) manage a web server and 2) expose the bot publicly to the internet. Both of these could be overcome with easy workarounds, if needed. For example, we could use something like FastAPI to quickly build our web listener & handle incoming POST requests. We could also use a tunneling method (like ngrok) to avoid having to directly open ports to our webserver.

Websockets

On the other hand, we could use websockets to accomplish the same function. With a websocket, we’re instead opening a direct, persistent TCP connection to the Webex APIs. Through this persistent connection, we can send & receive messages very quickly and easily.

This method offers a few advantages over webhooks. Primarily not having to expose our app publicly to the internet. Websockets act almost similar to something like ngrok, where we create an outbound tunnel - except in this case, only Webex knows about it and has access to it (where ngrok is still providing you a public URL that anyone could hit, if they knew about it). Additionally, this method removes the need for maintaining a web server & having to handle all of the incoming HTTP requests in your bot’s code. There may also be a handful of API calls which are only supported via websockets today as well - like having your bot show that they’ve read a message, for example.

I’ve also found that the websocket method seems to be much more responsive, likely because there is a persistent TCP connection open - and you no longer have to rely on a full HTTP session establishment & teardown for every message to the bot.

Historically, websockets were only officially supported via the Webex JavaScript SDK. However, it seems recently that someone has built a Python equivalent earlier this year - which we’ll be using throughout this blog post. You can find that package here

Getting started: Registering the Bot with Webex

So we’ll start with some basic functionality. Let’s grab the modules we need, apply our API key, and see if we can get a response from our bot.

Luckily, the module we’re using makes this super easy. So let’s install via pip:

pip install webex_bot

Once that’s installed, we’ll create a new Python file - I’ll call mine bot.py

In that file, we’ll start our script like this:

from webex_bot.webex_bot import WebexBot

api_token = "<TOKEN_HERE>"

bot = WebexBot(api_token, approved_domains=["0x2142.com"])

bot.run()

Looks easy enough, yeah? We’ll import our webex_bot module first, as always. Then we’ll define our API key. Obviously this can be stored as an environmental variable or another more secure location, but we’ll define it here for demonstration.

Then we create a new instance of WebexBot, by providing our API key and an optional approved_domains value. In my case, I’ve provided the 0x2142.com domain - which means the bot will reject messages from anyone who isn’t from that organization.

Last, we start our bot with bot.run().

Let’s go ahead and run our bot with python bot.py and see what happens!

You should see something similar to this:

matt@0x2142:~/demo-webex-bot$ python bot.py
2021-10-25 15:42:52  [INFO]  [webex_bot.webex_bot.webex_bot.__init__]:39 Registering bot with Webex cloud
2021-10-25 15:42:52  [INFO]  [restsession.webexteamssdk.restsession.user_agent]:167 User-Agent: webexteamssdk/0+unknown {"implementation": {"name": "CPython", "version": "3.8.10"}, "system": {"name": "Linux", "release": "5.10.16.3-microsoft-standard-WSL2"}, "cpu": "x86_64"}
2021-10-25 15:42:52  [WARNING]  [command.webex_bot.models.command.__init__]:33 no card actions data so no entry for 'callback_keyword' for echo
2021-10-25 15:42:52  [INFO]  [command.webex_bot.models.command.set_default_card_callback_keyword]:47 Added default action for 'echo' callback_keyword=callback___echo
2021-10-25 15:42:53  [INFO]  [webex_bot.webex_bot.webex_bot.get_me_info]:74 Running as bot '0x2142 Bot' with email ['0x2142@webex.bot']
2021-10-25 15:42:54  [INFO]  [webex_websocket_client.root._connect_and_listen]:151 Opening websocket connection to wss://mercury-connection-partition2-a.wbx2.com/v1/apps/wx2/registrations/06b5c858-174a-4977-a268-04530d777563/messages
2021-10-25 15:42:54  [INFO]  [webex_websocket_client.root._connect_and_listen]:154 WebSocket Opened.

So long as we continue to run this script in the foreground - we’ll be able to see the live log of anything that happens, including messages to our bot. So for now, we’ll leave this up & running.

Now we should be able to try sending our bot a message in Webex.

In the Webex app, if we do a quick search for our bot (by email or name), we should see it pop up pretty quickly:

With our new space, we can interact with our bot. I’ll send a “Hello” message:

And the webex_bot module will automatically respond back with a built-in help card.

Currently the bot only supports one command: echo. We’ll add our own commands shortly, but for now let’s give that a try:

So in the example above, I used the echo command. The bot returns a card with an input field. Once you fill out the textbox & hit submit, the bot will echo back whatever text was provided!

So now we have a running bot. But what about implementing our own commands? Let’s take a look!

Creating custom bot commands

Now we get to the fun part!! To demonstrate, let’s add a command to ask our bot for the current weather conditions. To accomplish this, we’ll use the OpenWeather APIs.

So to begin - We’ll probably want a separate Python file for each command we want to add. First we’ll add weather.py to our current directory.

Next, we’ll throw in a bit of boilerplate code that will be used for each command:

from webex_bot.models.command import Command
import logging

log = logging.getLogger(__name__)

class WeatherByZIP(Command):
    def __init__(self):
        super().__init__(
            command_keyword="weather",
            help_message="Get current weather conditions by ZIP code.",
            card=None,
        )

    def execute(self, message, attachment_actions, activity):
        return f"Got the message: {message}"

So first we’ll import Command from our webex_bot module, which will be used to create our custom command class.

Next we create a new class, in this case WeatherByZIP, and inherit the Command class from webex_bot. Within this new class, we’ll create our __init__ function & define some information about our command.

So using super().__init__(), we’ll provide what keyword should trigger this command, any help message to be provided to the user, and an optional card. We saw how the card could work earlier with the echo command - but to keep this module simple, we’ll go without a card for now.

After that - we just need to create an execute function. This is what gets called by webex_bot when our command is triggered. By default, webex_bot will pass us the user’s message - and, in the case of an action (like a card submission), it will provide those details.

Two things to keep in mind with our execute function:

1. the message variable will contain the user’s message with the command keyword removed. So in our case, if the user’s message was “weather 12345” - then the message variable would just contain “12345”.
2. Any text we return from our function will be sent via the bot as a chat response. If we wanted to provide extras, like cards or attachments, we would need to use the webex_bot Response object. I might cover this in a separate blog post later

Okay! So right now our new command is configured to just echo back any test that is sent to the bot - similar to the echo command earlier, except without the card.

We’ll add our weather functionality shortly - but let’s first add our command to the bot & give it a quick test.

In our bot.py file, we’ll just need to import our command module and call bot.add_command():

from webex_bot.webex_bot import WebexBot
from weather import WeatherByZIP

api_token = "<TOKEN_HERE>"

bot = WebexBot(api_token, approved_domains=["0x2142.com"])

bot.add_command(WeatherByZIP())

bot.run()

That’s it! Now we should be able to try it out. We’ll restart our bot, and send the command weather 12345:

Sure enough, our bot gets the message, passes it to our custom command, and returns the stripped message - all as expected.

So let’s add our weather query & actually make this thing work.

Using the OpenWeather APIs, I’ll create a new API key - then create a variable in the command module called OPENWEATHER_KEY. Then, I’ve updated my execute function to look like this:

def execute(self, message, attachment_actions, activity):
    # Message may include spaces. Strip whitespace:
    zip_code = message.strip()

    # Define our URL, with requested ZIP code & API Key
    url = "https://api.openweathermap.org/data/2.5/weather?"
    url += f"zip={zip_code}&units=imperial&appid={OPENWEATHER_KEY}"

    # Query weather
    response = requests.get(url)
    weather = response.json()

    # Pull out desired info
    city = weather['name']
    conditions = weather['weather'][0]['description']
    temperature = weather['main']['temp']
    humidity = weather['main']['humidity']
    wind = weather['wind']['speed']

    response_message = f"In {city}, it's currently {temperature}F with {conditions}. "
    response_message += f"Wind speed is {wind}mph. Humidity is {humidity}%"

    return response_message

So because of the way that message is passed to us, we’ll first need to strip whitespace. This is because when the user enters a command like “weather 12345”, webex_bot will only remove the “weather” portion - leaving us with " 12345". So by stripping that value, we’re left with just the numeric ZIP Code: “12345”.

Next we assemble our URL, supplying our parameters: zip, units, and appid. Zip is the numeric ZIP code provided by our user, units will be either imperial or metric, and appid is our API key.

After that, it’s as simple as sending the GET request & parsing the data. In the code above, I assemble the final text response into response_message which is then returned to the user.

All that being done - Let’s try it out!!

In this example, I used the ZIP code for Richfield, OH - and our bot quickly returned that information to us.

And that’s it! In just a few steps we created a new Webex bot & added custom commands. Once we have that process down, it’s easy enough to continue extending our bot by adding additional commands.

There are obviously more advanced use cases - and a whole lot of fun that comes with using Adaptive Cards… But I hope this post was helpful in getting you started!

Update 2022/03/12 - If you’re interested in seeing additional content around Cards, please check out the new blog post & video here

“As a network administrator, do I really need to learn to code?”

“How much to I need to learn?”

“This will NEVER be in enterprise networks”

Well, today I’m here to give some thoughts. As with all my content, I reserve the right to be wrong or not 100% in alignment with everyone else’s view of the world.

Do I need to learn code?

Nope.

Wait really?!?

Correct, no one can make you learn if you don’t have an interest in it.

Okay, but will I benefit from it?

100% yes you will. To what degree may vary, but I think it’s worth a look.

Well how much do I need to know?

As the network architect might say, it depends.

Is automation coming for my job?

¯\_(ツ)_/¯

So what’s the right answer here? It depends on what’s right for you - what you’re interested in, what you think will help you in your job, and what you think will help you succeed.

Yes, it’s true that much of the networking industry has been shifting focus to automation & programmability. Open APIs have become much more important in recent years as we seek to expand our capabilities through custom code & integrations. I don’t see this slowing down anytime soon.

But will that spell the end of the network engineer as we know it? I don’t know that anyone can 100% say definitively, but I’m willing to bet that network engineers aren’t going anywhere anytime soon. The role will definitely change & evolve over time (as it already has been, and will continue), but truly go away? I think not.

The benefits of programmability

I’m sure most people are familiar with a lot of this by now, but why should we care about automation? Well there are lots of reasons! For example, here’s a few:

• Reducing human error
• Reducing time spent on repetitive tasks
• Accomplishing things that aren’t natively possible in a product
• Adding custom functionality or integrations with other systems
• And more!

How much you should learn

This one REAALLY depends. To throw out some ideas, here are some factors that could help determine how much you’ll need to know:

• How much you enjoy it
• How much your company cares or has any automation initiatives
• The type (and age) of gear you’re working with
• Whether or not you have an in-house development or devops team

So on one side, I think that most people who get into writing Python & find that they truly enjoy it will likely end up transitioning to a more developer-focused role - whether that be a network-centric devops role or pure development role. Or simply just seeking out more ways to focus on programmability within their current network engineering role. These types of people are finding that they love solving problems & being able to have the creative freedom to write whatever code they want to accomplish a task. They’ve found something that they enjoy - Good for them!

On the other side, even if a network engineer isn’t going to write code very often - just knowing the fundamentals can be hugely beneficial. For example, as a network engineer, have you ever had to learn how VMware works? Likely you didn’t feel the need to become a VMware administrator overnight - but understanding how a vSwitch works has helped you support those teams. How much easier did it become to communicate with the VMware admins?

With programmability, it’s much the same. If you’re not going to dive in, that’s okay. But you’ll likely benefit from a good overall understanding of how things work. For me personally, it was easy to recognize the benefit when I was a network administrator. Application team puts in a ticket saying something isn’t working right? Well guess who understands API calls, HTTP requests, and JSON/XML? It suddenly became much easier to help find root cause, and often easier to shift blame away from the network. Plus, when you speak with an application/development team & you can use their terms, they feel like you understand them. This helps reduce friction between teams. In my experience, what I found was that those application teams would then ask for my help more often - because I was willing to go further than “checked the firewall, it’s not the network”.

In my opinion, whether or not you learn to code & how much you learn comes down to your goals. Can you keep being a network admin & avoid code? Sure - just like you could continue being a network admin & never learn design, business goals, or what other teams in your company do. But will learning those things expand your knowledge & give you a better big-picture view? Yup. Would learning those things give you an advantage? Absolutely.

What happens when you run into a difficult challenge where manual effort would be reckless? Maybe you pass off the job to a development team to write a utility or some custom integration. But guess what happens next? That development team doesn’t understand how your network gear operates. Again, this situation really benefits from having an individual who can speak both languages. Even if you don’t understand functions & classes, you might be able to read API docs for your network gear and help guide the developer through where to start.

What about that in-between state? Maybe you want to learn to code a bit, but not 100% of the time. What then? Well, could you pull & terminate ethernet cables without a cable tester? Yes, but would you be more efficient with one? Also yes. Similarly, being able to code can just be as simple as adding another tool to your skill set. Would you automate a single port change? Nope. But what if you find yourself making that same port change several times a week? That’s when you pull out your Python skills and write a quick script.

And for those who would rather just not do any of it? You’re fine. How many parts of the Internet still run legacy protocols? Someone has to support that. And there are companies out there who want commercially supported products, so they have someone to blame. Vendors know this, which is why we end up with big, centralized controllers & complex GUI apps to help slowly pull networking out of the CLI days. But you can’t tell me that SD-Access, ACI, or EVPN are simple technologies - companies will still benefit from employing people who understand the underlying technologies & protocols. Let’s be honest: automated or not, things still break - and someone will need to have the knowledge to fix it.

So what’s the answer here?

¯\_(ツ)_/¯

It seems like these debates continue because everyone comes from different backgrounds & has different experiences. Some people work in companies that would never entertain the idea of custom code, where others may find their team being pushed to become more agile & learn Python to automate tasks. Neither approach is wrong, but of course our human instinct is that we have to assert that everyone else must be wrong, since their view doesn’t match ours. The world is never a one-size-fits-all for every situation, yet for some reason we’re all inclined to think it is.

All that being said, companies are going to adopt this stuff at different paces. Some find immediate value in it now, and some are scared or just set in their ways. Again, neither is wrong - but they both have their own advantages & disadvantages.

And that’s why I say - if you don’t want to learn any of this, you have nothing to fear. There will always be organizations at different stages of the cycle.

But if you do learn? At worst, you gain knowledge outside of your primary domain. At best, you gain a new tool to leverage & find ways to improve your work.

At the end of the day, you have to focus on what’s right for you, your career, and your current employer. And that answer is going to be different for everyone.

Maybe it’s just me - but I feel like when we want to demonstrate product APIs to someone, we usually jump into Postman first. It’s not without good reason though. Postman is a very easy to use platform for running API calls against REST endpoints & see the nicely formatted output.

That being said, often times I’ve seen that we stop there. We might mention Python as an advanced method of using our APIs, or maybe we talk about how “if APIs are the new CLI, Postman is the new PuTTY”. I’ve seen some engineers who hear these statements and feel like Postman is being pushed on them - even when they’re perfectly happy with an SSH-based CLI.

Network automation isn’t usually accomplished with just one tool - it’s a whole storage closet full of different tools & utilities, each with their own use cases or specializations. In this particular example - learning Python allows you to move beyond one-off API calls in Postman, and into being able to accomplish much more complex automation.

So the purpose of this post is to explore how to get beyond just Postman, and into using Python for REST API calls. This isn’t going to be a complete run-down of all the capabilities of both tools - but rather a few examples of simple GET requests using both methods.

If you don’t have Postman yet, go ahead and snag the download here.

Note: Much of the code below is minimal and does not contain any error handling. Therefore, it should not be used in a production network. Full example code here.

Postman: Simple GET Request

So first, let’s start off with an example of using Postman for a simple GET request.

In this example, we’ll keep things simple & use a non-authenticated API endpoint. We’ll accomplish this using a free website called JSON Placeholder.

Let’s go ahead and start up Postman, and we’ll see a blank workspace:

What we’ll need to pay attention to first, is what type of HTTP request we’re sending - as well as the URL we want to send our request to. If we expand the request type dropdown, we’ll see a handful of options - but we’ll only be using a GET request for now:

In order to create our first request, we’ll just need to enter our API endpoint URL. We’ll use the users endpoint offered by JSON Placeholder, which is located at: https://jsonplaceholder.typicode.com/users

In the screenshot above, you’ll see in the highlighted box that we entered our URL. Next, we just click the big Send button on the right side.

I already sent the GET request, so in the screenshot you’ll also notice that we have our JSON response from the API. The mock data offered by this API provides us with a list of 10 different users, along with the data that’s been entered for each user.

What if we only wanted to get data for one specific user? Well, our test API site supports using query parameters to filter our response. Let’s say we want to find information for a user named Delphine. We would append ?username=Delphine to our URL:

So as we can see above - now our JSON response only contains the data for a single user. If we needed to find a user’s phone number, this could be an easy way to quickly filter our data & get to what we need.

This is really where Postman is great. We’re able to quickly & visually test out an API call. We can see what the response data looks like, and understand the structure of requests & responses.

But what about when we want to iterate through a number of users and pull only a specific few statistics? Or maybe we need a way to take a list of user information, and automatically upload or convert that data into another system.

For use cases like that, we’ll jump over to Python.

Python: Simple GET Request

In this section, we’ll walk through the same example from above - but this time using Python.

First thing we’ll need to do, is install the Python requests library. While there are a handful of libraries that can accomplish this work, requests is fairly popular & easy to use.

So we’ll kick things off by using pip to install our library:

pip install requests

Then, we’ll create a very simple Python script to perform the same initial GET request from earlier. So we’ll pull a list of ALL users from the API.

import requests

URL = "https://jsonplaceholder.typicode.com/users"

response = requests.get(URL)

print(response.text)

The code above should be pretty straightforward. First we’ll import our requests library. Then, just to keep the code clean, we’ll create a variable called URL to hold the URL for the API endpoint.

Next, we send that GET request, using requests.get. Last but not least, we’ll go ahead and print out the text payload that we receive back. That output looks pretty similar:

matt@DESKTOP:~/postman-python$ python3 simpleGET.py 
[
  {
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "Sincere@april.biz",
    "address": {
      "street": "Kulas Light",
      "suite": "Apt. 556",
      "city": "Gwenborough",
      "zipcode": "92998-3874",
      "geo": {
        "lat": "-37.3159",
        "lng": "81.1496"
      }
    },
    "phone": "1-770-736-8031 x56442",
    "website": "hildegard.org",
    "company": {
     -- output truncated --

Now, let’s add a little extra logic to our next step. Rather than just specifying a static username that we want to search for, let’s ask our user to specify a username:

import requests

URL = "https://jsonplaceholder.typicode.com/users"

print("Search by Username:")
user = input("> ")
queryURL = URL + f"?username={user}"
response = requests.get(queryURL)

print(response.text)

In the code above, we made just a few changes. One is printing out a prompt to “Search by Username”. Then we use the Python input function to collect input from our user, then store that in the user variable.

Next, we create a queryURL - which is similar to the URL we used in the Postman example. Except in this case, we’re supplying a dynamic username input based on whatever the end user wants to search for. We use a Python f-string to inject the username into our query parameters.

Let’s see what that looks like:

matt@DESKTOP:~/postman-python$ python3 simpleGET.py 

Search by Username:
> Delphine
[
  {
    "id": 9,
    "name": "Glenna Reichert",
    "username": "Delphine",
    "email": "Chaim_McDermott@dana.io",
    "address": {
      "street": "Dayna Park",
      "suite": "Suite 449",
      "city": "Bartholomebury",
      "zipcode": "76495-3109",
      "geo": {
        "lat": "24.6463",
        "lng": "-168.8889"
      }
    },
    "phone": "(775)976-6794 x41206",
    "website": "conrad.com",
    "company": {
      "name": "Yost and Sons",
      "catchPhrase": "Switchable contextually-based project",
      "bs": "aggregate real-time technologies"
    }
  }
]

Perfect! We get the result we expected, which is the single dataset from the user that we specified.

Let’s take this one step further! Maybe we want to build a quick utility to search for a user’s contact information. We can take the raw JSON output, pull out a few pieces of info, then apply some formatting to make it more user-friendly.

In the following example, we’ll update our code to search that JSON response & collect the user’s name, email address, and phone number.

import requests
import json

URL = "https://jsonplaceholder.typicode.com/users"

print("Search by Username:")
user = input("> ")
queryURL = URL + f"?username={user}"
response = requests.get(queryURL)

userdata = json.loads(response.text)[0]

name = userdata["name"]
email = userdata["email"]
phone = userdata["phone"]

print(f"{name} can be reached via the following methods:")
print(f"Email: {email}")
print(f"Phone: {phone}")

So a few things have changed in the above example. First thing you may notice, is that we’ve added an additional import: the json library. We use this in line 11, where we convert the JSON output into a native python object using the json.loads function.

What this allows us to do is easily pull individual data values from the JSON output. In the original JSON data that we received, we saw a bunch of user data organized into key-value pairs. So once we load that JSON into a Python dictionary, we can pull out individual values and assign them to variables.

Finally - we can print all of that data out to our terminal:

matt@DESKTOP:~/postman-python$ python3 simpleGET.py

Search by Username:
> Delphine
Glenna Reichert can be reached via the following methods:
Email: Chaim_McDermott@dana.io
Phone: (775)976-6794 x41206

Nothing super fancy here - but this could be the beginnings of building out a user search web page, or maybe importing certain data fields into another system. Once we get the basics of working with REST APIs out of the way, there are a ton of possibilities for what can be built.

Okay - What About Network Automation?

Many new network technologies are now API enabled. Nearly every cloud-hosted platform or management controller offers some method of interacting programmatically. In fact, most routers & switches even offer a REST-based API that can be used for automated configuration or monitoring.

So let’s take the following example: We have a couple of Meraki networks, and we’ve been tasked with providing a report of how many total clients have connected to our network in the last 30 days. In addition, it would be nice to see a breakdown of the distribution of operating systems.

Let’s take a look at the following screenshot from Postman:

Using Meraki’s API docs, we can determine the exact URL endpoint we need to query. This URL requires that we know the exact network ID for the network we want to get info from, which we’ll pretend we already know. Also not shown here, we have an additional HTTP header that includes our API key - which was generated in Meraki Dashboard.

In addition, we have a few query parameters to help make sure we get the data we need. By default, this API endpoint will return 10 devices. In this particular network, we already know we have more than 10 - so we use the perPage query parameter to request up to 100 devices. We also wanted to query the last 30 days of devices, so we use the timespan parameter. This parameter expects the lookback to be in seconds, so we specify 43,200 seconds.

So we got back a list of devices - and specifically in the example shown, it looks like we have an Android device on our network. Easy enough to spot that info, right?

Well - maybe we have more than a handful of devices. We don’t want to manually sort through all of that data & assemble a list. Or maybe this task needs to be run more than once. This is where we can use Python to automatically assemble that report with just a few lines of code.

import requests
import json

URL = "https://api.meraki.com/api/v1"
APIKEY = {"X-Cisco-Meraki-API-Key": "xxxxxxxxxxxxxxxxx"}

--- Code omitted ---

def getClients(orgID, networkList):
    """
    Query clients for each network, return client list
    """
    clientCount = {}
    total = 0
    # Query Parameters: Return up to 100 devices seen in the past 43,200 seconds (30 days)
    q = {"perPage": "100",
         "timespan": "43200"}
    for network in networkList:
        # Query clients for each network
        queryURL = URL + f"/networks/{network}/clients"
        response = requests.get(queryURL, params=q, headers=APIKEY)
        data = json.loads(response.text)
        # Grab client OS from each device & append to clientCount dictionary
        for client in data:
            try:
                clientCount[client["os"]] += 1
            except KeyError:
                clientCount[client["os"]] = 1
            except TypeError:
                continue
            total += 1
    # Append final count of all devices & return dict
    clientCount["Total Devices"] = total
    return clientCount

def printReport(clientOS):
    """
    Print final output to terminal
    """
    print("Count of clients by operating system:")
    for OS in clientOS:
        print(f"{OS}: {clientOS[OS]}")
        
--- Code omitted ---

To keep things simple - we’ll only look at a snippet of the code. The entire example will be posted to GitHub, and contains two additional functions that will automatically find our Organization ID & Network ID.

In our getClients function, we create an empty Python dictionary to hold our list of client operating systems - and we also create a total variable which we’ll increment for every client in the list.

The HTTP GET request should look fairly similar to what we used previously. The big difference is that we’re creating a dictionary called q to hold our perPage & timespan query parameters. Then we include that in our GET request by adding params=q to the request.

Next - we convert the JSON response into a Python object, and walk through every device in that list. For each device in the list, we look at the “os” value to determine the operating system detected by Meraki. We then use a try/except block to see if we can increment the counter for that operating system. If we get a KeyError, then we know the OS isn’t currently on the list & we can just add it with a new value of 1.

After all that has been completed, we return our clientCount dictionary - which our primary function passes to the printReport function. This just prints out a header, then iterates through our clientCount dictionary and prints each operating system & count.

Let’s take a look at that output below:

matt@DESKTOP:~/postman-python$ python getOScount.py
Count of clients by operating system:
None: 9
Sailfish OS: 2
Nokia: 1
Windows 10: 2
Raspberry Pi: 2
Android: 4
Meraki OS: 1
Total Devices: 21

In the list above, we can see that we have a total of 21 devices in our network - and 7 different operating systems were found as well.

That output may not be the prettiest of reports, but it was accomplished with ~50 lines of Python & takes less than a few seconds to run. If we wanted to format the data in another way, or include data from a non-Meraki source, we absolutely could.

That’s part of what’s exciting about using Python for network automation - most anything we could think of doing is possible.

TIP: Use Postman to Generate Python Code

Okay - so I wanted to save this bit for last. Now that you’ve seen examples in both tools, I wanted to make sure we cover a feature in postman that can save some time.

So over in the right-hand side of your Postman window, you’ll see an icon that looks like this: </>

If you click that, you’ll see a dropdown menu of various languages & tools. Select one of those options and Postman will auto-generate code you can use. This auto-generated code will execute the same request you have built in the Postman GUI.

For example, our last Postman request we used to get Meraki clients:

I wanted to save this for last, because I feel like it’s important to understand how to write the code manually first - then take advantages of shortcuts after having a good understanding of what the code is doing.

That’s about all I had for this example. Again, my intent here wasn’t to create an all-inclusive resource for how to use Postman & Python - but rather to give some examples for each one & show where/why each would be used.

I’ve met a handful of people over the years who have seen many API demos using Postman, but aren’t sold yet on the value of learning Python & getting into network automation.

Hopefully these examples help bridge that gap a little bit 😄

This post has been on my backlog for a while… I’ve been intermittently trying out the IOS-XE guestshell feature for a few different projects, and never feeling like any of them were good enough to write about.

So why not just write about guestshell itself? It’s such a nifty tool.

What is Guestshell?

Now that Cisco’s Catalyst platform has standardized on IOS-XE, we can take advantage of some of the features of the Linux-based platform. One of which being Linux Containers (LXC).

Most of the latest Catalyst routers, switches, and access points support what Cisco calls Application Hosting - which is a fancy way of just saying it can run containers on-box. Another acronym to be aware of is IOx - which is what Cisco calls their IOS-XE/Linux appliction framework.

Guestshell is a specific feature within IOS-XE, where a dedicated pre-built container is enabled for on-box access to a Linux shell.

What Hardware Supports Guestshell?

Okay - so for this example, I’ll be using the new Catalyst 8000V platform (a virtual Catalyst router). I do also have a Catalyst 9200L on hand, but unfortunately it’s one of the few Catalyst platforms that does not support Guestshell (due to lower-end HW specs).

You can also use the Catalyst 8000V to test this in a lab, or you could use most of the Catalyst 8000 / 9000 series platforms if you had them available (or the CSRv & some ISR routers!).

You can find a list of supported platforms & other hardware requirements here.

All that being said - let’s get started!

Enabling IOx

So before we can actually use the guestshell feature, there is some pre-configuration to be done.

First we’ll need to ensure that the IOx application framework is enabled & running. We can check this by using the show iox command:

0x8KV01# show iox

IOx Infrastructure Summary:
---------------------------
IOx service (CAF)              : Not Running
IOx service (HA)               : Not Supported
IOx service (IOxman)           : Not Running
IOx service (Sec storage)      : Not Supported
Libvirtd 5.5.0                 : Running

And as we see above - most components are listed as “Not Running” or “Not Supported”.

So we’ll enter config mode, and use the iox command to enable these services:

0x8KV01# conf t
Enter configuration commands, one per line.  End with CNTL/Z.
0x8KV01(config)# iox 
0x8KV01(config)#
0x8KV01(config)# exit
0x8KV01# show iox

IOx Infrastructure Summary:
---------------------------
IOx service (CAF)              : Running
IOx service (HA)               : Not Supported
IOx service (IOxman)           : Running
IOx service (Sec storage)      : Not Supported
Libvirtd 5.5.0                 : Running

Configuring Guestshell Networking

There’s a good chance we’ll want our container to have access to the outside world, so let’s take a quick look at the network configuration.

Note: The networking config syntax will differ if you are using a Catalyst router or a Catalyst switch. Since I am using a Catalyst 8000V - we will look at the config for a Catalyst router first.

In order to allow external access to our container, we’ll need to configure a gateway interface and NAT translations. Then we can provide a full network configuration to our container:

## Enable NAT on our external interface - in my case, gigabitEthernet1
0x8KV01(config)# interface gigabitEthernet 1
0x8KV01(config-if)# ip nat outside

## Create a virtual interface for the guestshell container
0x8KV01(config-if)# int virtualportgroup0
0x8KV01(config-if)# ip address 192.168.100.1 255.255.255.0
0x8KV01(config-if)# ip nat inside

## Create an ACL to match traffic from guestshell & Enable NAT
0x8KV01(config)# ip access-list standard IOX_NAT
0x8KV01(config-std-nacl)# permit 192.168.100.0 0.0.0.255
0x8KV01(config)# ip nat inside source list IOX_NAT interface gigabitEthernet 1 overload

## Assign network configuration to our guestshell container
0x8KV01(config)#app-hosting appid guestshell
0x8KV01(config-app-hosting)# app-vnic gateway0 virtualportgroup 0 guest-interface 0
0x8KV01(config-app-hosting-gateway0)# guest-ipaddress 192.168.100.5 netmask 255.255.255.0
0x8KV01(config-app-hosting-gateway0)# app-default-gateway 192.168.100.1 guest-interface 0
0x8KV01(config-app-hosting)# name-server0 8.8.8.8

Now, as I mentioned before - this config will look different if you’re using a switch vs a router.

So let’s take a quick look at what this would look like, if we were on a Catalyst Switch instead:

Cat9k(config)# interface AppGigabitEthernet 1/0/1
Cat9k(config-if)# switchport mode trunk

Cat9k(config)# app-hosting appid name
Cat9k(config-app-hosting)# app-vnic AppGigabitEthernet trunk
Cat9k(config-app-hosting-trunk)# vlan 10 guest-interface 0
Cat9k(config-app-hosting-vlan-access-ip))# guest-ipaddress 192.168.100.1 netmask 255.255.255.0

Cat9k(config-app-hosting)# app-default-gateway 192.168.100.1 guest-interface 0
Cat9k(config)# name-server 8.8.8.8 

Once all that config is done - Let’s move on to getting our container started!!

Managing the Guestshell Process

In order to start a container on our Catalyst device, we’ll need to go through a process of deploying the app, activating it, then starting it.

For guestshell, there is a shortcut command that will perform all of these steps for you - and make managing the guestshell process much easier.

So let’s go ahead and spin up our guestshell container with the command guestshell enable:

0x8KV01# guestshell enable
Interface will be selected if configured in app-hosting
Please wait for completion
guestshell installed successfully
Current state is: DEPLOYED
guestshell activated successfully
Current state is: ACTIVATED
guestshell started successfully
Current state is: RUNNING
Guestshell enabled successfully

0x8KV01# show app-hosting list
App id                                   State
---------------------------------------------------------
guestshell                               RUNNING

And as you can see above, everything gets automatically deployed & started. We can verify using the show app-hosting list command to see that our container has been started.

If we need to, we can also stop & deactivate our container using the command guestshell disable.

We could also use the commands below if we wanted to perform these steps manually:

0x8KV01# app-hosting activate appid guestshell
0x8KV01# app-hosting start appid guestshell

0x8KV01# app-hosting stop appid guestshell
0x8KV01# app-hosting deactivate appid guestshell

Before we move onto accessing the guestshell interface, I also wanted to show where you can get more detail about the guestshell container.

Using the show app-hosting detail appid guestshell command, we can see details around the container version, current MAC/IP config, and resource consumption:

0x8KV01# show app-hosting detail appid guestshell
App id                 : guestshell
Owner                  : iox
State                  : RUNNING
Application
  Type                 : lxc
  Name                 : GuestShell
  Version              : 3.2.0
  Description          : Cisco Systems Guest Shell XE for x86_64
  Path                 : /guestshell/:guestshell.tar
  URL Path             :
Activated profile name : custom

Resource reservation
  Memory               : 256 MB
  Disk                 : 1 MB
  CPU                  : 800 units
  CPU-percent          : 3 %
  VCPU                 : 1

Attached devices
  Type              Name               Alias
  ---------------------------------------------
  serial/shell     iox_console_shell   serial0
  serial/aux       iox_console_aux     serial1
  serial/syslog    iox_syslog          serial2
  serial/trace     iox_trace           serial3

Network interfaces
   ---------------------------------------
eth0:
   MAC address         : 52:54:dd:d:bf:da
   IPv4 address        : 192.168.100.5
   IPv6 address        : ::
   Network name        : VPG0

Port forwarding
  Table-entry  Service  Source-port  Destination-port
  ---------------------------------------------------

Accessing the Guestshell CLI

Now for the fun part! Let’s get into our guestshell container.

We’ll just need to use the guestshell command, and we’ll be dropped into the Linux shell:

0x8KV01# guestshell
[guestshell@guestshell ~]$
[guestshell@guestshell ~]$ uname -a
Linux guestshell 5.4.40 #1 SMP Tue Oct 6 17:57:00 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux

Let’s also make sure our network & NAT configuration worked:

[guestshell@guestshell ~]$ ping 8.8.8.8
PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
64 bytes from 8.8.8.8: icmp_seq=1 ttl=64 time=3.57 ms
64 bytes from 8.8.8.8: icmp_seq=2 ttl=64 time=2.64 ms
64 bytes from 8.8.8.8: icmp_seq=3 ttl=64 time=2.54 ms
^C
--- 8.8.8.8 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 4ms
rtt min/avg/max/mdev = 2.543/2.916/3.567/0.465 ms

If needed, we can also run commands on our Catalyst device CLI without leaving the guestshell interface by using the dohost utility:

[guestshell@guestshell ~]$ dohost "show app-hosting list"
App id                                   State
---------------------------------------------------------
guestshell                               RUNNING

[guestshell@guestshell ~]$

Just a note, the reverse is also possible. Using the guestshell run command from our Catalyst CLI, we can run commands in our container:

0x8KV01# guestshell run uname -a
Linux guestshell 5.4.40 #1 SMP Tue Oct 6 17:57:00 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux

0x8KV01#

It’s also worth reiterating, that the guestshell container is a full Linux container (It runs CentOS). So if we need to install additional Linux packages, we can use our Linux package manager (YUM) to do so.

Anyways - Let’s wrap this up by looking at the built-in Python modules & capabilities

Using Python in Guestshell

One of the more appealing use cases for guestshell is the ability to run native Python scripts & code directly on your Catalyst device.

A couple of possible use cases could be:

• Troubleshoot intermittent issues - Automatically collect device state (routes, MAC changes, etc) on a regular basis to log locally or send via email
• Automated resolution - If a certain type of state change is observed, we could run a pre-set list of commands to try and automatically fix the issue
• Local monitoring / troubleshooting - We could run a series of ping, web page load tests, etc from a python script to help monitor performance from the switch’s perspective
• Change management / notification - A script could be written to monitor the device configuration for any changes made, then send an automated email when something was detected
• Have a risky change that might sever your connection to a remote device? A script could execute the change for you, and if unsuccessful, revert to a working configuration (without doing a reload after)

These are just a handful of ideas that came to mind while writing this blog post… But there are many more possibilities!

Within the guestshell container, there is a special cli python module that comes pre-loaded. This module allows us to run CLI commands on our catalyst device directly from a python script & receive the command output for parsing.

Let’s look at a quick example using the Python interactive interpreter to save the device configuration:

[guestshell@guestshell ~]$ python3
Python 3.6.8 (default, Aug 24 2020, 17:57:11)
[GCC 8.3.1 20191121 (Red Hat 8.3.1-5)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> 
>>> import cli
>>> status = cli.execute("write memory")
>>> if "OK" in status: print("Device configuration was saved!")
...
Device configuration was saved!

The example above uses the cli.execute Python function, which will run commands in Cisco’s exec mode.

What if we wanted to make configuration changes? In that case we would use the cli.configure function:

>>> config_data = """interface loopback200
... ip address 172.16.99.10 255.255.255.0
... """
>>>
>>> cli.configure(config_data)
'Line 1 SUCCESS:  interface loopback200\nLine 2 SUCCESS:  ip address 172.16.99.10 255.255.255.0\n'
>>>
>>> cli.execute("show run interface loopback200")
'Building configuration...\nCurrent configuration : 68 bytes\n!\ninterface Loopback200\n ip address 172.16.99.10 255.255.255.0\nend\n'

In the above example, we used a multi-line comment to provide the list of commands to enter. The cli.configure function also supports a Python list - so we could provide the commands in that format as well.

You’ll notice that the Python interpreter returns a status for each command that we attempted to run. This should allow us to error-check & ensure that all of our intended configuration was accepted.

Lastly, we used the cli.execute command again to validate that our running configuration looks correct.

There’s a bit more functionality built into the cli Python module, but I just wanted to cover some of the common use cases. More details can be found here

A Few Common Questions

Does this give me access to the underlying IOS-XE Linux shell?

Nope, anything running in guestshell is running in a container - which runs on-top of the IOS-XE image.

What about resource conflicts?

The linux containers running on the IOS-XE platform are given their own dedicated resources. Any resource constraints that affect the containers will not impact normal network functions.

In the last post, I covered a simple project that I’m working on while studying for the Cisco DevNet certifications. This is part two of a series, which will continue on while I work through this project.

As a brief summary - I started using a combination of Scrapli & Cisco Genie for a short network automation script. This script connects to a list of network switches & outputs a spreadsheet of interface statistics. This provides a quick snapshot view into the current port capacity within your network.

In this post, I’ll be showing off a bit of how to build a simple web frontend - which I’ll put together using Flask and Bootstrap.

Getting Started with Flask

Okay so I have a bad habit of making a lot of Python scripts which are essentially just command-line utilities.

In theory, this isn’t necessarily problem. But what if I want to share some of the tools I build? Maybe not everyone wants to compile config files & figure out what command-line arguments are needed. For some, they may prefer to have an easy-to-use web interface instead.

So for this project I opted to venture a little outside my typical comfort zone & build a web dashboard. I’ll admit I’ve done this once or twice before, but certainly not something I would claim proficiency in!

The good thing is - building a web interface doesn’t have to be complex. My intent with this post is to try & break it down a bit - and hopefully encourage you to try it yourself!

Installing Flask & Hello World

Installing Flask is much like any other python module - we’ll use pip:

pip install flask

Once installed, we can import the module into our python script:

from flask import Flask

Simple enough!

Now let’s look at how easy it is to set up the web server & return a simple web page:

app = Flask(__name__)

@app.route('/')
def main():
    return "Hello there!"

if __name__ == '__main__':
    app.run()

First we create a new instance of Flask, using the syntax app = Flask(name).

Next, we just create a quick python function to return the text Hello there! You’ll notice that there is a decorator above the function - this is used by Flask to route incoming HTTP requests.

In this example, we use @app.route(’/’). This tells Flask to register this python function for any HTTP calls to http://<url>/. If we wanted a function for any HTTP requests to http://<url>/networking, we would modify the decorator to @app.route(’/networking’).

Lastly, we need to start the Flask web server when the script is run. This is accomplished using app.run()

Let’s go ahead and try to run the script - which should start the Flask server:

In the above screenshot, you’ll see that by default Flask will start on http://127.0.0.1:5000. You may also notice that Flask will print out real-time logging of incoming HTTP requests.

If we visit our page, we’ll see pretty much what we might expect:

Before we move onto the next section, I did want to show one more example.

Let’s say that we have a python variable (or dictionary, etc). Could we pass that as part of our web page function?

Let’s look at this modified example:

web_page_text = {"Hello": "There!"}

@app.route('/')
def main():
    return web_page_text

If we reload our local web page, we’ll now see the following:

Keep this in mind - We’ll use this later!

Making life easier with HTML templates

Now then - you could build all of your HTML in python, then return the entire HTML page as a response to the function call. That being said, just because you can doesn’t mean you should 🙃

Let’s take a quick look at how we can use HTML templates to help build our web page.

First we’ll create a new directory called templates, and create an HTML file. In this case, I named my template main.html:

To start with, we’ll just add some simple text into the HTML file:

<body>
    Hello There - From the template!
</body>

On the Flask side, we’ll have to modify our imports to include the render_template module. We’ll also update what we’re returning when an HTTP request is received:

from flask import Flask, render_template

app = Flask(__name__)

@app.route('/')
def main():
    return render_template('main.html')

if __name__ == '__main__':
    app.run()

So now instead of returning plain text, we’ll return render_template(‘main.html’).

Flask uses Jinja2 for templating, which we’ll get into shortly. The above function call tells our app to use main.html as a base template for the content that is returned to the end user.

Let’s check out the page:

Awesome - we receive our HTML file as a response this time.

Extending functionality with Jinja2

Now we can start getting into the fun stuff.

Manually writing out a bunch of HTML is fun and all - but what if we could auto-generate everything programmatically?

Jinja2 allows for exactly that. We’ll be able to insert variables, if/then statements, and looping logic directly into our HTML template.

As an example, let’s say we had the following python dictionary - which we wanted to display on a web page:

switchList = [
        {
        "name": "C9200",
        "serial": "ABCD00010",
        "ip": "192.168.1.1",
        "check": True,
        "total": 28,
        "up": 10,
        "down": 5,
        "disabled": 13,
        "capacity": 35       
    },
    {
        "name": "C9300",
        "serial": "ABCD00011",
        "ip": "172.168.44.2",
        "check": False,
        "total": 48,
        "up": 32,
        "down": 6,
        "disabled": 10,  
        "capacity": 67       
    },
        {
        "name": "C9400",
        "serial": "ABCD00012",
        "ip": "172.33.44.2",
        "check": True,
        "total": 48,
        "up": 40,
        "down": 6,
        "disabled": 2,  
        "capacity": 82       
    }
]

This dictionary is an example from the scrapli script I’ve been working on (more detail in my last post).

One way for us to present this using an HTML template would be the following:

<body>
    {% block content %}
    
    {% for switch in switches %}
    Switch Name: {{ switch.name }} 
      - Serial: {{ switch.serial }} 
      - Reachable at: {{ switch.ip }} 
      
    {% endfor %}
    
    {% endblock %}
</body>

As you can see - that’s a bit of a change from what we were using in our template before.

The Jinja2 syntax above uses a combination of curly braces & percentage signs to indicate which parts of our template are logic that should be processed before returning content to the user. Variables are represented with double curly braces.

Once our template receives the switchList dictionary, we can iterate through it similar to how we might in python. Using the {% for switch in switches %} syntax, we can iterate through each item - and pull out relevant data.

Within our for loop, we can reference the individual values of each item in the dictionary. Using the double braces, we can insert a placeholder for where a piece of content should be inserted. For example, in the above template we have a spot where we want to insert the name of the switch. We use {{ switch.name }} as a placeholder, where the value from the dictionary will be inserted once our template is processed.

Okay - so before we test this, we have one minor modification to our python function:

@app.route('/')
def main():
    return render_template('main.html', switches=switchList)

We’ve changed our function render_template, but also include the python object that we’ll be passing to our template.

Let’s test this out:

Now there’s some magic! Using a combination of python & our Jinja2 templates - we can drastically reduce the amount of HTML code that we need to write.

Okay, but that’s not pretty

Yes I know. But we needed to get the basics done first!

Here’s where Bootstrap comes in.

I went out to Google and searched for good CSS templates. I’m not a web developer, nor am I good at design - so I’ll leave that work to someone else.

In my searching, I found quite a bunch of free templates… but I fell in love with one called Lux by Bootswatch.

They provide a great sample page for the template, which shows off different variations. But the best part is that it also includes code samples!

After we pick & download our CSS template, we’ll place it in a new directory named static:

To get started, we’ll need to install one additional python module:

pip install flask_bootstrap

Then we’ll also need a quick modification to our base Flask app:

from flask_bootstrap import Bootstrap

... code omitted ...

if __name__ == '__main__':
    Bootstrap(app)
    app.run()

I removed some code to focus on just the two parts that change.

First, we need to import our new module. Second, we need to inject our bootstrap plugin into the Flask app. We do this with Bootstrap(app) prior to app.run().

Let’s move back over to our HTML template, since this is where the most of our changes will be.

First, we’ll need to include a few things to make sure our CSS file is loaded:

{%- extends "bootstrap/base.html" %}

<head>
    {% block styles %}
    {{super()}}
    <link rel="stylesheet"
            href="{{url_for('static', filename='bootstrap.css')}}">
    {% endblock %}

</head>

I won’t dive in too deep on this piece, as it’s fairly straightforward. First, we’ll need to include the base/default bootstrap template. Next, we’ll include a reference to where our CSS file is located & it’s name - so that it gets loaded when our page is rendered.

Okay, now for the body of the page:

<body>
    {% block content %}
    <table class="table table-hover">
        <thead>
          <tr>
            <th scope="col">Name</th>
            <th scope="col">Current Capacity</th>
          </tr>
        </thead>
        <tbody>
          {% for switch in switches %}
            {% if switch.capacity > 75 %}
                <tr class="table-danger">
            {% else %}
                <tr class="table-success">
            {% endif %}
            <th scope="row">{{ switch.name }}</th>
            <td>{{ switch.capacity }}%</td>
          </tr>
          {% endfor %}
        </tbody>
      </table> 
    {% endblock %}
</body>

Now instead of just returning a plain-text list of all three switches, we’ll use our CSS template to generate a colorful table. For the purpose of this example, I kept the data to just showing the switch name & it’s current capacity.

Most of the template is fairly simple. First we build our table header using the <thead> tags. Next we’ll build the rows of our table using <tbody> and <tr>.

For the Jinja2 logic - We’ll iterate through our list of switches, and add a new table row (<tr>) for each device. I also added logic to check the current capacity of the switch. If the switch capacity is greater than 75%, we create the table row using <tr class=“table-danger”> - which is a reference in our CSS stylesheet that will color the row red. If capacity is less than 75%, we use table-success for a green color.

Let’s go ahead and check out what this looks like:

And as we expect - we get our nicely formatted table & the correct colors on each row.

Bringing it all together

Now that we’ve gotten some background on how to use Flask & Bootstrap, let me show you a bit of what I’ve been working on.

I won’t cover much code in this section, but you can check out the GitHub repo if you’re interested in seeing the details.

The scrapli script that I wrote previously has been extended a little. The biggest change is that instead of writing its output to a spreadsheet, it will insert the data into a sqlite database.

The web frontend has been assembled using the same basic ideas covered in this blog (plus a lot of banging my head against the desk, trying to figure out why things don’t format or align properly 🙂). Whenever a request is made to the web dashboard, it will query the sqlite database for the requested information.

So, without further delay - here it is!

I currently have one physical device running, plus a handful of virtual nexus 9k & CSRv devices running in Cisco Modeling Labs. So all of the data shown in this dashboard is being pulled from real(ish) equipment - no mock data.

This was one of those projects where I started off thinking my dashboard was going to be really simple… but then I kept having new ideas and getting carried away with the design & functionality.

The table above shows each switch, it’s serial number, management IP, current software version, and the port inventory. Similar to the example earlier in this post, I have a small progress bar that shows switch capacity - and will change color depending on percentage of in-use ports.

If you click on any of the switch names, you’ll be taken to a page with additional detail on that particular device:

On this first tab, you’ll see some quick info - mostly the same that is on the main page of the dashboard. However, I added two additional tabs here - one for a detailed port breakdown & one for a dump of the raw CLI output.

If we click on the port info:

We have a breakdown of how many ports are currently in use vs down, as well as our breakdown of port media & operational speed. Since I account for switches that are anywhere from 10M up to 100G, the data for operational speeds will only show the speeds that are actually in-use on the switch.

Just in case it’s needed, I added a tab to show the raw CLI output from the switch:

This could be a quick way to check port counters & errors, or any other information that isn’t already presented via the dashboard.

Lastly, I built a separate page to provide statistics on ALL devices in the network:

This page will show port count & availability network-wide. However, I also added some spaces to show the top 5 hardware models & software versions that are in-use across the network.

I went into this project a bit worried because frontend development isn’t my strength. That being said, I really enjoyed working on this project. It was a different challenge than I’m normally used to - and it gave me a creative way to try and format & display the data I am collecting.

I hope this post was useful to you. Please leave a comment below - and check out my Github repo for the full code.

So I just scheduled an upcoming attempt at the Developing Applications using Cisco Core Platforms and APIs (DEVCOR 350-901) exam.

It’s coming up quick in two weeks here & I’m starting to do some review / final prep before taking the exam.

Why does this matter? Well - I plan on doing a few write-ups & videos on some of the content I’m studying. There are a lot of people diving into the DevNet exams, and I want to do what I can to help other people succeed.

All that being said, check back here over the next few weeks - or subscribe on YouTube - to see the additional content that will follow. While this specific blog doesn’t cover much from the exam blueprint, it’s the beginning a simple project I’ll be using in the further content.

Getting Started with Scrapli

For this project I opted to start with scrapli, and possibly migrate to using RESTCONF later on in the process. Mostly this was an excuse for me to try out scrapli, as I’ve heard a few people using it recently & was interested.

Scrapli is a screen scraping module for Python. If you’re not familiar with screen scraping, it’s the process of connecting to something via telnet/ssh/etc, then literally scraping or dumping the contents of the screen. There are other modules that do this as well, like paramiko, netmiko, or expect scripting.

In networking, too many of our devices still rely on CLI and don’t have proper API endpoints. We’re working on it, but yet still a ways from having it everywhere. So in the meantime, we still need screen scraping for automation.

On the whole, this isn’t necessarily a bad thing. For example, most network engineers are very familiar and competent with the CLI of any network operating system. It’s easier to jump into the world of automation if you can start with something you know, the CLI. It’s harder to force someone to start their automation journey by giving up everything they know and shoving REST APIs at them.

Okay - enough rambling. Let’s get scrapli installed and see what it can do.

Installing the module

Easiest part of the whole project. Install with pip:

pip install scrapli

Next we’ll go ahead & import into our script.

Scrapli supports quite a handful of operating systems (including a few non-Cisco platforms as well!). In the case of my project though, I’m only using Cisco IOS-XE switches - so we’ll only import the scrapli driver for that.

from scrapli.driver.core import IOSXEDriver

Connecting to a Device

Okay - now that we’re all setup with the module, it’s time to get working!

First thing, we need to authenticate to our device. Building off of the example code from the scrapli page - we’ll create a short dictionary of authentication parameters first:

switch = {
    "host": "10.1.1.1",
    "auth_username": "net_api",
    "auth_password": "net_api_pass",
    "auth_strict_key": False
}

cli = IOSXEDriver(**switch)
cli.open()

Once we build out dictionary, we’ll use **switch to unpack our key/value pairs into the IOSXEDriver object & assign it to a variable called cli. Then, all we need to do is call cli.open() and scrapli will open a connection to our target device.

Now we can run any command we want by calling cli.send_command():

sh_int = cli.send_command("show interface")
print(sh_int.output)

So in the above example, I want to issue a show interface - then print the output.

What we get is shown below:

GigabitEthernet1/0/1 is up, line protocol is up (connected)
  Hardware is Gigabit Ethernet, address is 78bc.1a81.e101 (bia 78bc.1a81.e101)
  Description: Test Port
  MTU 1500 bytes, BW 1000000 Kbit/sec, DLY 10 usec,
     reliability 255/255, txload 1/255, rxload 1/255
  Encapsulation ARPA, loopback not set
  Keepalive set (10 sec)
  Full-duplex, 1000Mb/s, media type is 10/100/1000BaseTX
  input flow-control is off, output flow-control is unsupported
  ARP type: ARPA, ARP Timeout 04:00:00
  Last input 00:00:11, output 00:00:03, output hang never
  Last clearing of "show interface" counters never
  Input queue: 0/2000/0/0 (size/max/drops/flushes); Total output drops: 198
  Queueing strategy: fifo
  Output queue: 0/40 (size/max)
  5 minute input rate 9000 bits/sec, 11 packets/sec
  5 minute output rate 2066000 bits/sec, 221 packets/sec
     2647548 packets input, 371883264 bytes, 0 no buffer
     Received 6985 broadcasts (6757 multicasts)
     0 runts, 0 giants, 0 throttles
     0 input errors, 0 CRC, 0 frame, 0 overrun, 0 ignored
     0 watchdog, 6757 multicast, 0 pause input
     0 input packets with dribble condition detected
     50905390 packets output, 60134059101 bytes, 0 underruns
     0 output errors, 0 collisions, 2 interface resets
     0 unknown protocol drops
     0 babbles, 0 late collision, 0 deferred
     0 lost carrier, 0 no carrier, 0 pause output
     0 output buffer failures, 0 output buffers swapped out

[**Output Truncated**]

What’s that look like? Exactly the same output we would get if we entered show interface on the command line ourselves! (Only Gig1/0/1 shown here to keep this short & clean)

Using Cisco Genie to Parse CLI Output

So what if we wanted to pull a list of every interface on the switch? Maybe tally how many ports are connected vs down vs admin disabled? Or even check operational speeds & media types?

Well that’s what I’m looking to do for this project.

Now at first it may seem like we have to use regular expressions to try & match the content we need from the output. However, there is an easier way!

Cisco Genie is an open source project, and part of the larger PyATS automated network testing suite. If you haven’t looked at any of that yet, I would highly recommend you check it out.

So what’s Genie do? It’s a utility that handles all the output parsing for us. There are a ton of pre-existing parsers written, which handle all the hard work so we don’t have to.

Best yet - scrapli has native integration into Genie. All we have to do is install one additional component:

pip install scrapli[genie]

And to make use of the power of Genie, we just need to pass our raw output to it.

So our new code will look like this:

sh_int = cli.send_command("show interface")
sh_int_parsed = sh_int.genie_parse_output()
print(sh_int_parsed)

That’s it. And now, instead of that raw output - we get a native Python dictionary that’s ready to consume by our script:

{
   "GigabitEthernet1/0/1":{
      "port_channel":{
         "port_channel_member":False
      },
      "enabled":True,
      "line_protocol":"up",
      "oper_status":"up",
      "connected":True,
      "type":"Gigabit Ethernet",
      "mac_address":"78bc.1a81.e101",
      "phys_address":"78bc.1a81.e101",
      "description":"Test Port",
      "delay":10,
      "mtu":1500,
      "bandwidth":1000000,
      "reliability":"255/255",
      "txload":"1/255",
      "rxload":"1/255",
      "encapsulations":{
         "encapsulation":"arpa"
      },
      "keepalive":10,
      "duplex_mode":"full",
      "port_speed":"1000mb/s",
      "media_type":"10/100/1000BaseTX",
      "flow_control":{
         "receive":False,
         "send":False
      },
      "arp_type":"arpa",
      "arp_timeout":"04:00:00",
      "last_input":"00:00:05",
      "last_output":"00:00:08",
      "output_hang":"never",
      "queues":{
         "input_queue_size":0,
         "input_queue_max":2000,
         "input_queue_drops":0,
         "input_queue_flushes":0,
         "total_output_drop":198,
         "queue_strategy":"fifo",
         "output_queue_size":0,
         "output_queue_max":40
      },
      "counters":{
         "rate":{
            "load_interval":300,
            "in_rate":8000,
            "in_rate_pkts":11,
            "out_rate":1868000,
            "out_rate_pkts":205
         },
         "last_clear":"never",
         "in_pkts":2658450,
         "in_octets":372811780,
         "in_no_buffer":0,
         "in_multicast_pkts":6783,
         "in_broadcast_pkts":6783,
         "in_runts":0,
         "in_giants":0,
         "in_throttles":0,
         "in_errors":0,
         "in_crc_errors":0,
         "in_frame":0,
         "in_overrun":0,
         "in_ignored":0,
         "in_watchdog":0,
         "in_mac_pause_frames":0,
         "in_with_dribble":0,
         "out_pkts":51057453,
         "out_octets":60309072263,
         "out_underruns":0,
         "out_errors":0,
         "out_interface_resets":2,
         "out_collision":0,
         "out_unknown_protocl_drops":0,
         "out_babble":0,
         "out_late_collision":0,
         "out_deferred":0,
         "out_lost_carrier":0,
         "out_no_carrier":0,
         "out_mac_pause_frames":0,
         "out_buffer_failure":0,
         "out_buffers_swapped":0
      }
   }
}

This format makes our lives a lot easier. For example, let’s say we wanted to determine the operational state of a port. Without the Genie integration, we would need to write some regex to comb through the raw output & find what we needed.

However, with Genie involved - its as easy as this:

print(sh_int_parsed['GigabitEthernet1/0/1']['oper_status'])

Collecting the Useful Bits

Now that we have everything in an easy-to-use format, all we need to do is write a few loops to run through our interface list & collect data.

The purpose of my script is to automate the collection of port utilization. For example, think about performing a switch refresh or some form of capacity planning scenario. You might need to inventory how many switches you have, how many ports are utilized vs how many are available, or count the number of copper vs fiber ports.

For this first iteration, we’ll just collect the data then dump it out to a CSV file. As I mentioned earlier, this is just the start of a small project I’ll be using to study for the DEVCOR exam - so this will be evolving into a web service later on.

The full script can be found here. But I’ve posted just a snippet of how we count the different interface characteristics:

# Count all Ethernet interfaces
interfaceStats['total'] += 1
# Count admin-down interfaces
if not sh_int_parsed[iface]['enabled']:
    interfaceStats['intdisabled'] += 1
# Count not connected interfaces
elif sh_int_parsed[iface]['enabled'] and sh_int_parsed[iface]['oper_status'] == 'down':
    interfaceStats['intdown'] += 1
# Count up / connected interfaces - Then collect current speeds
elif sh_int_parsed[iface]['enabled'] and sh_int_parsed[iface]['connected']:
    interfaceStats['intup'] += 1
    speed = sh_int_parsed[iface]['bandwidth']
    if speed == 10_000:
        interfaceStats['intop10m'] += 1
    if speed == 100_000:
        interfaceStats['intop100m'] += 1
    if speed == 1_000_000:
        interfaceStats['intop1g'] += 1
    if speed == 10_000_000:
        interfaceStats['intop10g'] += 1
# Count number of interfaces by media type
try:
    media = sh_int_parsed[iface]['media_type']
    if '1000BaseTX' in media:
        interfaceStats['intmedcop'] += 1
    else:
        interfaceStats['intmedsfp'] += 1
except KeyError:
    interfaceStats['intmedsfp'] += 1

Once all that runs, we create a CSV file to dump all of the data to.

For example, running the complete script against my lab Catalyst 9200 switch would output the following:

And that’s it! Using the combination of scrapli & genie made this script very quick and easy to write - which means now I can focus more time on the next steps.

As I’ve mentioned a few times, this is hopefully the start of a short series of blog posts & videos as I wrap up studying for the DEVCOR exam.

If you found this content helpful - or you’re interested in the future content - please check back soon! Or consider subscribing to my YouTube channel, where new content will be coming shortly.

In a recent post, I walked through setting up a Netgear LTE cellular modem with Google Fi. Might seem random - but I had a plan for this!

In trying to ensure I keep a stable internet connection for work, I eventually led myself down the path of buying a cellular modem. That was part one. The next step was being able to somewhat-intelligently monitor my home internet connection, and then fail over to the cell modem when connectivity was poor (think lazy SDWAN).

At first I figured this would be easy…. but of course nothing is :)

I currently have a Cisco FirePower 1010 appliance that I’m using for a home firewall. Unfortunately, while this thing does support IP SLA - It wouldn’t quite accomplish what I wanted to do. And to be fair, this box is intended to be a security appliance - not SDWAN.

Anyways - I talked myself into just writing some Python automation to monitor my home internet, and dynamically inject/remove static routing entries. I needed a new project anyways

For those of you wanting to jump straight to the code, the GitHub repo is here

Part 1 - Monitoring Packet Loss & Latency

So first thing - I regularly experience both complete internet outages (always at the worst times), as well as very high latency. Packet loss seems to be less common with my ISP - but hey, it happens sometimes too.

I opted to use the pythonping module as an easy way to collect some of the info I needed.

After importing the module, it’s as easy as specifying a destination, packet size, and number of ICMP messages to send:

from pythonping import ping
result = ping('8.8.8.8', size=2, count=10, verbose=True)

To simplify at least one part of the operation, pythonping has a built in function to return the average round trip:

>>> print(result.rtt_avg_ms)
74.23

The actual contents of our ping results are going to be in the following format: Reply from 8.8.8.8, 10 bytes in 43.82ms

So a quick way for me to figure out packet loss was to simply search for the “Reply from” text in each response:

lost = 0
for packet in result:
    if "Reply from" in str(packet):
        pass
    else:
        lost += 1

Easy enough - and we can use that to calculate the amount of packet loss against the 10 total packets sent:

lossperc = 100 * lost / 10

Once all that is figured out, we can use a simple expression to determine whether or not the loss or latency thresholds have been exceeded:

if response >= MAX_LATENCY or loss >= MAX_LOSS:
    print("Loss/Latency violate thresholds.")
    return True
else:
    print("Loss/Latency within thresholds.")
    return False

The code I wrote then takes one of two paths.

• If the loss and latency is ABOVE our thresholds, call to the FirePower module to inject a static default route over the LTE modem
• If the loss and latency is BELOW our thresholds, call to the FirePower module to delete the static default route - which returns traffic to the primary internet

These functions within the FirePower module were written so that each change will only be made once. For example, if the script checks and finds that the loss/latency is bad, but the static route towards the LTE modem already exists - then no additional changes are made.

So next - Let’s take a look at the FirePower module.

Part 2 - Authenticating to FDM & Initial Checks

This was my first time getting into the FirePower FDM APIs - but they ended up being fairly straightforward to use.

Turns out that FDM has built-in API documentation, which is extremely helpful. This can be found at https://<FDM IP>/#/api-explorer

Okay - So first thing’s first. Authenticating to the firewall:

oauth_data = {
    "grant_type": "password",
    "username": "admin",
    "password": "Cisco1234!"
}
headers = {
          "Content-Type": "application/json",
          "Accept": "application/json"
}
baseurl = "https://" + FDM + "/api/fdm/latest"

authurl = baseurl + "/fdm/token"
print("Posting AUTH request to FDM")
# POST request to FDM with headers / oauth data
resp = self.s.post(authurl, headers=headers,
                   data=json.dumps(oauth_data),
                   verify=False)
# If success - only pull out & return the auth token
if resp.status_code == 200:
    print("Auth success - got token.")
    return json.loads(resp.text)['access_token']
else:
    print("Authentication Failed.")
    print(resp.text)

In the code above - we take the headers and some basic authentication info (username, password, grant type) and send it in an HTTP POST request to https://<FDM IP>/api/fdm/latest/fdm/token

This returns an authentication token, which we’ll need to include in any further HTTP request to the firewall. This can be done by sending a new set of headers in the future:

headers = {
          "Content-Type": "application/json",
          "Accept": "application/json",
          "Authorization": "Bearer " + self.token
}

Next we need to figure out which routing table to insert the route into. Since I am only using the default routing table, the script will just grab the UID for the default global routing table:

vr_url = baseurl + "/devices/default/routing/virtualrouters"
routing_table = requests.get(vr_url, headers=headers)

I mentioned earlier that the script will not make any changes if the firewall is already in the desired state. So we will take time now to check what state the firewall is in, before attempting to make any changes.

This is accomplished by making our first primary action scanning the routing table to see if our route already exists:

route_url = baseurl + "/devices/default/routing/virtualrouters/" + \
            self.globalVR + "/staticrouteentries"
route_data = requests.get(route_url, headers=headers)

# Convert returned JSON object
current_routes = json.loads(route_data)['items']
# Run through each route returned and see if it matches the one we're looking for
for route in current_routes:
    # For each route, we need to manually go look up the uid of our gateway & network objects
    gateway = self.getNetworkObject(route['gateway']['id'])
    dest_network = self.getNetworkObject(route['networks'][0]['id']).split('/')[0]
    # Match based on route prefix & upstream next hop gateway
    if gateway == GATEWAY and dest_network == ROUTE.split('/')[0]:
        print("Found route to %s via %s" % (dest_network, gateway))
        return route

Depending on whether we were looking to add or remove a route, the script may proceed with doing so - or just quit if the action has already been taken previously.

Part 3 - Failover (Add Static Route)

Assuming that we need to Add a route, we need to sent a POST request to https://<FDM IP>/api/fdm/latest/devices/default/routing/virtualrouters/<Virtual Router ID>/staticrouteentries with some required information (like subnet info, next-hop, etc)

Unfortunately, we can’t just send a POST with the target subnet & gateway. Those need to be created as network objects on the FirePower box beforehand. For each network object, we need to build a quick JSON object with the required info:

host_data = {}
host_data['name'] = name
host_data['description'] = "Created by ISP Failover automation"
host_data['subType'] = subtype
host_data['value'] = address
host_data['type'] = "networkobject"

Then we can send a POST to the FDM API to create the object with our supplied parameters:

posturl = baseurl + "/object/networks"
requests.post(posturl, headers=headers, json=host_data)

Once we have those objects created, we can compile all of that info into a JSON object with all the components needed to create a static route entry:

routeobject = {}
routeobject['name'] = "route_BACKUP"
routeobject['description'] = "Created by ISP Failover automation"
routeobject['iface'] = {}
routeobject['iface']['id'] = iface_ID
routeobject['iface']['type'] = "physicalinterface"
routeobject['iface']['name'] = iface_name
routeobject['networks'] = [{}]
routeobject['networks'][0] = {}
routeobject['networks'][0]['id'] = network_ID
routeobject['networks'][0]['type'] = "networkobject"
routeobject['networks'][0]['name'] = network_name
routeobject['gateway'] = {}
routeobject['gateway']['id'] = gateway_ID
routeobject['gateway']['type'] = "networkobject"
routeobject['gateway']['name'] = gateway_name
routeobject['metricValue'] = 1
routeobject['ipType'] = "IPv4"
routeobject['type'] = "staticrouteentry"

Then pass all that into a POST request to create the route object:

add_url = baseurl + "/devices/default/routing/virtualrouters/" + self.globalVR + "/staticrouteentries
requests.post(add_url, headers=headers, json=routeobject)

Success? Well not quite yet.

FirePower requires all changes to be deployed (or applied) to the system before they take effect.

So next we need to initiate a deployment task - and periodically check on it. Deployments can take a while to complete, depending on number of changes, processing power of the appliance, etc.

# First send a POST to the deployment endpoint:
deploy_url = baseurl + "/operational/deploy"
deploy_response = requests.post(deploy_url, headers=headers)
# Grab the deployment task UID:
deploymentID = json.loads(deploy_response.text)['id']

# Loop while deployment is running:
while deployed is False:
    # Sleep for a few seconds:
    sleep(5)
    # Get list of all deployment tasks:
    tasklist = json.loads(requests.get(deploy_url).text)
    for task in taskList['items']:
        if task['id'] == deploymentID and task['state'] == 'DEPLOYED':
            print("Deployment status is: " + task['state'])
            deployed = True
            return True
        elif task['id'] == deploymentID and task['state'] != 'DEPLOYED':
            # If changes not yet deployed, check again momentarily
            print("Deployment status is: " + task['state'])
            deployed = False

So in the above block, we POST a request to deploy changes. The response of that POST request contains our deployment ID, which we keep to check the status later.

Then the script waits a few seconds, and pulls a list of all deployment tasks. Search through that list for our deployment ID - and check to see if it has been completed yet. If not, wait and run the loop again.

And that’s it! Once we get confirmation that our changes have been deployed - we’ve now routed traffic over the secondary connection (an LTE modem, in my case).

Part 4 - Fail-Back (Delete Static Route)

Okay - this section will be fairly quick. We’ve already looked at authenticating, checking if our route already exists, and how to add a new route. So the only thing remaining is removing our route if we wanted to migrate traffic back to the primary connection.

Same logic applies as earlier. If our path monitoring script runs and finds that loss & latency are within the thresholds we set, then we make a call to the firepower module. First we check to ensure there is a route for us to delete, and if so - proceed with deleting it.

Adding a route is a little more work, since we may need to create network objects. However, when we delete the route - we’ll just leave those objects on the FirePower box. They’ll be there for the next time we need them (which also speeds up deployment times).

To get started, we just need the UID for the route we want to delete.

Remember that code I showed above, where we check to see if the static route exists? And match on our intended subnet / gateway pair? Well, I just made that into a function that will return the UID of the route if it finds it. Easy enough!

Next, we just send an HTTP DELETE to the static routing endpoint - and reference that UID:

del_url = baseurl + "/devices/default/routing/virtualrouters/" + \
          self.globalVR + "/staticrouteentries/" + route['id']
requests.delete(del_url, headers=headers)

Once that succeeds - we use the same logic as earlier to deploy the changes.

After that, our route is removed & traffic should be flowing over our primary connection again.

If it helps anyone - I also threw together a quick diagram to explain the flow of operations here:

Well - that’s it. This was a fun side project to work on over the past week or two. I hadn’t spent much time with the FirePower/FDM APIs just yet. While there was a bit of work in creating all the necessary network objects, the overall process was fairly simple.

It helped tremendously that the FDM API explorer exists, and is available on-box. This utility allows you to see all the available API calls, what parameters they require, and even run test calls from the web UI. This greatly reduced the time needed to figure this out.

Hope this was interesting. If you would like to see the whole project - check out the repo on my GitHub page.

The future is APIs! SD-EVERYTHING! Automation! Orchestration! Artificial Intelligence and Machine Learning! Sound familiar? It’s all part of the messaging going around in just about everything IT-related. With as much as you keep hearing about it, you might think that it’s all anyone is doing anymore. Yet it still just seems like not a whole lot of people are really getting into it in my area. Every vendor event I’ve gone to this year has asked attendees the same questions: “How many of you are leveraging the APIs in your network hardware/software?”. And every time the same answer - maybe two or three people in a room of 40 raise their hands.

So where is the problem? Is all of this just marketing fluff or am I just talking to the wrong people?

Let’s think about this from a typical network admin’s perspective. Shifting from traditional CLI to automation and APIs can seem difficult or overwhelming. Let’s say I want to automate a new VLAN deployment. Oh, you’re telling me I need to stop and learn vendor APIs… but before that I need to understand how to write scripts. But I’ve never even programmed something before. There are dozens of languages - how do I pick one? How much fundamental programming knowledge do I really need to have before starting? I don’t want to be a developer!

Okay, okay - just stop there for a second. No one is asking you to drop networking and write code for a living. The end goal of all this programmability stuff isn’t to turn networkers into developers - It’s to enable network/systems admins to be more efficient at their jobs. Why  copy/paste the same config change to 100+ devices, if you can mass-deploy the change via an API? That’s a lot of time savings that could be used toward educating yourself on new products, planning other projects, or thinking about your ideal network design.

I’ve heard a lot of the same things over the past few years:

“Programming is difficult” or “I don’t know where to start”

Try learning Python. It’s simple to get started and you can build from there.

“I don’t know what an API is or how to use it”

Don’t worry about that yet - start with learning the basics and APIs will make sense later.

“I’m not a developer”

No one is asking you to be one! But learning the basics of scripting and automation gives you a whole new toolset to solve problems.

For me personally - I would never want to be a developer. I can’t stand the thought of coming into work every day and just writing code. Some people might enjoy that, but for me it doesn’t sound like fun. However - I enjoy writing scripts to solve problems, especially when it ends up making my job easier. I think that’s the part where some people tend to get stuck though. A lot of automation sounds like I need to be able to develop a huge 10,000+ line application to pull data from 15 sources and aggregate it to make intelligent network changes. Ehhh… Nope, not really. But what about just a quick script that runs every 5 minutes to check an interface statistic, and email you when a particular threshold is exceeded? Realistically that could be done in less than 50-100 lines of a script and maybe 30 minutes worth of work.

Still not interested? That’s okay too. Traditional networking isn’t going away any time soon, and over time the vendors will write all of that automation for you. They will package it up in a pretty GUI and sell it off to companies that want it. In fact, this has already happening and has been for quite some time. This isn’t a bad thing - vendors need to make money, and not all companies will have the time or skilled resources to automate all the things. However, a network admin who can write their own scripts/automation won’t be exclusively tied to a vendor to help them - and instead they will be empowered to solve more problems themselves.

Where do you get started? I already wrote a bit earlier this year on a few resources for learning Python - which you can find here. I also wanted to point out some other great resources that are a bit more specific to using those skills for network automation:

• Python For Network Engineers - Don’t know anything about Python yet? Start here! This is a free course provided by Kirk Byers for anyone who is interested in using Python for network automation. Once a week you’ll get an email with all the great free content, but it will be up to you to spend time going through it. Go sign up, and set aside an hour or two each week to practice.

• Cisco DevNet - There is a ton of great content here. While DevNet does offer some tutorials on basic Python fundamentals,  the real value here is examples on how to use some network APIs (NX-OS, Meraki, UCS, etc). Also - one of the best parts about DevNet is the sandboxes they offer. Want to write scripts against the FirePower Management Center, but you don’t have one to test with? Well with DevNet you can get access to one!  Get familiar with your Python basics, then come here to see where you can start using those skills with your existing infrastructure.

• Network Programmability and Automation - This is a fantastic book. Not free, but it is well worth the ~$30. Once you have a good handle on how to write some basic network automation with Python, I highly recommend picking this up. While Python is covered here, the book does a great job of introducing you to all of the other toolsets available. Curious about how Linux or Ansible fit into network automation? You can find out here - and learn about APIs and source control systems too!

So - What are you waiting for? Go get started, and see what you can accomplish. Learn the basics - and keep an open mind for opportunities to use those skills.

Have suggestions on where else to learn? Comment below!

I have always said that I’m not sure I could write code for a living, but I do really enjoy writing scripts that make my life easier. Today’s post is a great example of that. The ease of use offered by the Juniper SRX firewalls and JunOS is something that I wish I had in all of my networking infrastructure. Even better, a brand new SRX 300 can be purchased on Amazon for less than $300 - which made a great addition to my home lab. Now I have a place to develop and test automation without breaking production 🙂

Anyways - I had a requirement to monitor my SRX clusters for route changes. Specifically I’m using this with devices where I have implemented customer peering via BGP. The SRXs don’t natively offer any form of monitoring and alerting for this, and the current monitoring applications at my disposal don’t either. So I decided to write something myself, which took significantly less time than I had assumed.

Code has been posted up to my GitHub - but I’m going to walk through some of it here. This script is intended to run as a cron job on a 5 or 10 minute interval.

# Imports
from jnpr.junos import Device
from jnpr.junos.op.routes import RouteTable

On my initial research to see how easy this would be to pull off, I found a nifty thing in the JunOS PyEZ package. Turns out they already offer a module literally called RouteTable that can pull the information I need.

Originally, I spent a bit of time trying to figure out how to use the standard device API to pull this info, but this module made everything 10x easier.

#################
# Required values
#################
deviceName = 'SRXFirewall'
deviceIP = '0.0.0.0'
apiuser = 'username'
apipassword = 'password'
SMTP = 'smtp-alias'
fromName = 'BGP Monitor'
fromAddr = 'bgpmonitor@domain.com'
toName = 'contactName'
toAddr = 'contact@domain.com'
prefixDict = {
        "FriendlyName": "Prefix",
        "Route-to-Inet": "0.0.0.0/0"
    }
################

The section above contains a list of the required variables for this script to function. A lot of them are going to be self-explanatory - but I wanted to take a moment to look at the prefixDict. This is a Python dictionary that maps a friendly name to a route prefix, which is used when we check our routing table. For example, if you wanted to monitor the SRX device for a route for 10.10.10.0/24 which belongs to Customer1, then we would just add and entry in this dictionary for “Customer1”: “10.10.10.0/24”

Alright - now let’s skip to the good stuff:

# Function to check received BGP routes
def checkBGP():
    try:
        # Open SRX session
        dev.open()
    except:
        sys.exit(0)

    # Pull device routing table, then keep only BGP originated routes
    allroutes = RouteTable(dev)
    bgp = allroutes.get(protocol="bgp").keys()

    # Close SRX session
    dev.close()

The section above is the beginning of the checkBGP function. Simple enough - just open an API session to the SRX and grab the entire routing table. That module I was talking about earlier makes it super easy! Next, we pull only the routes originating from BGP and assign them to a variable called bgp.

So in order to run this script repeatedly as a cron, I needed a place to persistently store the last retrieved routing info. For the time being, this is done by simply writing a temp file with the information:

    if not os.path.isfile(tempfile):
        with open(tempfile, 'w+b') as a:
            a.write(str(bgp))
        sys.exit(0)

    # Local file used to keep track of BGP learned routes
    with open(tempfile, 'ab') as a:
        lastroutes = a.readlines()
        # Compare if routes are different
        if str(bgp) == str(lastroutes[0]):
            sys.exit(0)
        if str(bgp) != str(lastroutes[0]):
            pass
    # Delete file, then re-create with new route list
    #os.remove(tempfile)
    with open(tempfile, 'w+b') as a:
        a.write(str(bgp))

The logic in the comparison is simple enough. If the current string of routes pulled from the SRX equals what is in the temp file (from the last run), then we assume no changes have occurred - and the script ends. Otherwise, if they don’t match then something has changed.

Once we know something has changed, we’ll go ahead and find out exactly which route entry is missing:

    # Create Status list, by checking received routes in bgp object
    status = []
    for name,prefix in prefixDict.items():
        if prefix in bgp:
            status.append("%s - RECEIVED" % name)
        if not prefix in bgp:
            status.append("%s - MISSING" % name)

This is where our prefixDict from earlier comes into play. We’ll look at every BGP prefix that we defined in that dictionary, and see if it exists in the current SRX routing table. All of this information (both routes received and missing) get added to an alert email.

Lastly, we’ll go ahead and compose our alert email to send out:

    # Send alert message
    sendMail(str(lastroutes[0]), str(bgp), status)

I’m not going to cover the email function here, since it’s pretty straightforward.

That’s it! The existence of the JunOS RouteTables module made creating this script a piece of cake. I’m considering adding onto this later with some additional functionality, so be sure to check my GitHub repo if you’re interested.

Hope this is useful to someone else out there - Let me know in the comments!

A lot of people take the beginning of the year to make new resolutions and goals for the coming months. So this year, I’m urging you to add one more to your list: Try and automate something that will make your life easier.

Where to Start

What you choose to automate doesn’t need to be extremely complex or elaborate, just anything that will save you a little bit of time. Never used a scripting language? I can’t recommend enough using Learn Python The Hard Way to start learning. This site is what I used about five years ago to get into scripting. Another great resource is CodeAcademy, where they have web-based interactive tutorials (also check out their specific module on Python and APIs).

Once you get a good handle on the basics, start thinking about repeatable tasks that are great candidates for automation. Start with something simple - maybe a script that prompts the user for information, then generates the command-line entries to configure new switch ports. Then someone can easily copy and paste the commands from the script output to achieve their desired configuration. Something like this might not immediately seem like a huge time savings, but it gives you a place to start and get familiar with what is possible. Once you get something like that working, it’s not too difficult to extend the script later and actually include calls to the switch APIs to automate the changes.

Is Python/scripting your only option? Not at all. There are also automation toolsets like Ansible, which can abstract the code layer a bit. For quite a number of systems that I deploy to an average datacenter, I already have Ansible playbooks written to handle that work. My actual time involved in deploying standard network monitoring applications and tools to a new datacenter went from hours to less than five minutes. For the purposes of this post, I’ll be speaking more to the Python/Scripting side. However, the important point is not necessarily which toolset you choose - it’s the fact that you try to use any one of these tools or others to automate something.

Stick with it

Learning a scripting language at first might seem like a very unnecessary and time consuming task. However, this is something that will pay off in the long run. When I started learning Python, all I wanted to do was parse data from several CSV files and combine the necessary data into one large file. Stupid simple script, but it saved me half an hour each day for a previously manual task.

I’m not at all a fantastic developer by any means, nor would I want to write code for a profession. I just really enjoy problem solving, and sometimes the best way to solve a problem is with a bit of custom scripting. What gets me excited is the process of finding something that wouldn’t normally be possible and knowing that I have the skills and ability to make it happen. Over the past five years, my basic level Python abilities have enabled me to work my way through a number of problems - or write various scripts to make my job easier.

You’ll need to dedicate some time and put in the effort up front to learn a new skill, but trust me it will be worth it.

Look for New Opportunities

Once you have learned the basics, start looking for ways to use your new skills. It’s a different way of thinking in some cases, and will likely take a bit of adjustment. Whats that? Your load balancer doesn’t have built-in reporting functionality to tell you how many server pools you have (and how many are actually fully functioning vs degraded)? Yep, they probably have an API which would be easy enough to pull that data from.

Over the years, I’ve built scripts to automate load balancer configurations, generate reports, alert on BGP peering changes, auto-remediate IPSec VPN disconnects, and even a full IPSec VPN dashboard (since the vendor doesn’t supply one). As a network administrator, having the automation skills in Python has allowed me to accomplish many tasks that my co-workers have stated aren’t possible (solely based on the functionality not being native to a product). Sure, I spend a bit of time up front writing and testing out scripts - but it not only saves me time/effort, but also my peers who I share the scripts with. For example, my team used to have a maintenance task that would take a full hour to complete on a monthly basis. About a week worth of my own effort to write a script, and all of that work is now automated into a 30 second process.

Think about how automation can help not just you, but your whole team.

The Future of Networking

If you follow practically any news source for computer networking, I’m sure you’ve heard this already. Over the next few years the role of a traditional network administrator can and will change. Businesses are evolving more rapidly to meet customer demands, and we need to ensure that our networks can keep up. The only way this is going to be possible is through automation, or hiring an ridiculous number of people.

Practically all major networking vendors are integrating APIs into the new iterations of their device platforms. Some are fantastic, and some are less than ideal - but they’re all working on it. In some way or another these new APIs will become a part of your job - whether you’re writing the code to perform tasks or just using a script written by someone else. Does this mean we have an end to our careers in the future? No - the CLI will take a while to completely disappear. Even if it does go away completely, the role of a network admin will not be replaced, but evolve into something a bit different from what we know today. Even today, having the skills to automate tasks out of your daily job can allow you to spend your time on more important things (like a new network design, or that big project you haven’t had time to look at yet).

You can probably get away with not learning scripting and automation for quite some time yet - but don’t you want to make your life easier and be prepared for the future of your career? I know I do.

• Part 1 - Initial Thoughts
• Part 2 - Leaning Django
• Part 3 - Creating the Dashboard

Alright - We’re finally at the last step to this project. We already have Django running with a somewhat decent-looking web dashboard. Now the only thing that remains is polling our SRX firewalls for VPN connections, then populating this information into the database.

For this to happen, I built a custom management command for Django - the cool thing here is that we can easily use this within a cron job to automatically schedule updates at regular intervals. So within our application (the vpn folder), we’re going to create a management folder then a commands folder within that. In here you can name your script whatever you want, so I went with cronpoller.py.

The script that I wrote is extremely simplistic and could probably use quite a number of improvements - which I will slowly make over time. But for now, it is what it is - and it does exactly what I need it to.

First thing we need to do is import a few things we will need:

from django.core.management.base import BaseCommand, CommandError
from vpn.models import Firewall, Datacenter
from jnpr.junos import Device
from lxml import etree

We have some Django modules for treating this as a management command - and we’re also importing our existing models into this script. This part is really cool to me, because it means that this cron script can just reference the existing objects that we created to get their attributes. Next, we import the JunOS stuff from their pyEZ packages (don’t forget to install pyEZ!). The last one is going to be used to parse the responses from our SRX into something we can use.

Alright - so in order to build a management command, we have to create a class called Command, then define our functions within that. Within the Command class, Django will look for a function called handle to execute. In my final script, I have that function plus one called getVPNStatus. Let’s start with putting together getVPNStatus:

# This function will poll the device for status 
def getVPNStatus(self, fw, dc):
    connectedlist = []
    # So we generate a JunOS pyEZ device connection using the information about the 
    # firewall that we gather from the database object
    device = Device(fw.firewall_manageip,
                    user=fw.firewall_user,
                    password=fw.firewall_pass)
    # Try to open a connection out to the target device
    try:
        dev.open()
    except:
        # If for some reason this doesn't work, just return UNREACHABLE - which
        # we'll assume means the device is down
        return "UNREACHABLE"
 
    # Here is where we poll the SRX for a list of all IPSec Security Associations.
    # The equivalent of the 'show security ipsec sa' command
    response = etree.tostring(dev.rpc.get_security_associations_information())
    # The SRX returns a response in XML, which we'll need to dig through
    # Credit to the guys over at <a href="http://packetpushers.net/parsing-junos-xml-python/" target="_blank" rel="noopener">Packet Pushers</a> for a great post explaining how to
    # parse these responses
    with open(response) as a:
        xmldoc = etree.parse(a)
        docroot = xmldoc.getroot()
        rootchildren = docroot.iter()
        for child in rootchildren:
            # For each IPSec SA returned, we need to find the remote gateway IP, which 
            # we use to tie the connection back to the connected datacenter
            if child.tag == "sa-remote-gateway":
                connectedlist.append(child.text)
   
    # Once we've built our list, send it back!
    return connectedlist

That already is major part of our script. It will connect out to each device, grab a list of every connected IPSec tunnel, then return back a list of connected gateways. Now we just need to write our handle function, which will do all of the remaining work.

def handle(self, *args, **options):
    # Let's quickly create two lists - based on our firewall and datacenter models
    # This actually polls the database for anything that's been created
    dclist = Datacenter.objects.order_by('datacenter_code')
    fwlist = Firewall.objects.order_by('firewall_name')
 
    # This will loop through each firewall, then call the getVPNStatus function
    for fw in Firewall.objects.order_by('firewall_name'):
        statuslist = self.getVPNStatus(fw, dclist)


    # Once we have our response, we're going to check the returned list of connected
    # gateways against our list of datacenters from the database
    for dc in dclist:
        for remoteFW in fwlist:
            # If we find another datacenter in the connected gateway list, add 
            # that datacenter to the vpnstatus list as "VPNUP", otherwise assume it's down
            if remoteFW.firewall_vpnip in statuslist:
                vpnstatus[dc.datacenter_code] = "VPNUP"
                break
            else:
                vpnstatus[dc.datacenter_code] = "VPNDOWN"
 
    # After all that is done - we just save the new vpnstatus list to the firewall_vpnstatus
    # field in the database
    fw.firewall_vpnstatus = vpnstatus
    fw.save(update_fields=["firewall_vpnstatus"])

I’ve said this before, but I think it’s worth noting again - This probably isn’t the best or most efficient/reliable way of doing this. I think that over time I would like to revisit this and refine it a bit - but this is what I’ve put together so far. In fact, I think it’s worth stating that this will probably break in a fantastically horrific manner. This isn’t a finished product, but pretty much just version 0.1 - the base functionality works, but it’s in desperate need of refinement.

Alright - so now we just have to add a cron job in our system to call this script and run it. Depending on how many firewalls you have and how the latency is, you might need a different interval than I am using - but I went ahead and set mine to run once every 10 minutes. I would like to get this down to 5 minutes or less, but I might need to figure out a way to potentially multi-thread the cronpoller.py script. So here is what I did in /etc/cron.d/vpnstatuspoller:

*/10  * * * * * python /root/junos-dashboard/manage.py cronpoller

After letting the script poll my firewalls - I ended up with a dashboard that looks like this:

Future improvements

Of course, I still have a few things I would like to add or improve on. I’ve been keeping a list of some ideas that I’ve had, which I’ll share here:

• Add a timestamp to each firewall that contains the last poll time (in case something gets missed or hasn’t updated yet)
• Possibly add ability to click a ‘down’ VPN cell to force clear SA
• Set up email alerts from the cronpoller to automatically notify me of a failure
• Ability to click on any VPN cell and get additional info - like VPN uptime, subnets routed across it, or maybe the IKE/IPSec negotiation parameters
• Ability to click on any firewall name and get additional info - like uptime, JunOS version, CPU/Memory

I finally got around to getting myself a GitHub account, so I might put the final code up there once I’m done. I also have a number of other JunOS scripts that are probably worth posting up there as well.

Well, I hope you enjoyed reading about this project - because I certainly enjoyed working on it. This was one of my first real projects using the JunOS pyEZ libraries, and I got to pick up and learn how to use Django as well. The experience of building this has given me ideas for other JunOS automation projects - so look out for some of those in the future!

• Part 1 - Initial Thoughts
• Part 2 - Leaning Django

In the last post, we got Django working well enough to start serving up web requests. That’s a great start - So now it’s on to actually building the project. We’re going to cover this in two parts: the front-end dashboard, and the back-end scripts. In this post, I’m going to show you how I began putting everything together to assemble the front-end HTML dashboard.

As a quick refresher note, we created a project in the last post called junos-dashboard. Within that project, we created our app named vpn. This folder is primarily where we’ll be spending our time today. There are two files in our app folder that will need a few edits:

views.py - This is where we originally created our basic index page, which currently just spits out a message. So we’ll need to add code in here to render our dashboard instead.

models.py - In here we will define our objects and the characteristics about those objects that we want to store/retrieve in the sqlite database.

Let’s go ahead and open up our models.py file. For my dashboard, I have two objects I want to track - Firewalls (the SRX hosting the VPN) and Datacenter (as a location tracking). So in order to create those objects, we just have to add two classes into the models.py file:

from __future__ import unicode_literals
from django.db import models

class Datacenter(models.Model):
    def __str__(self):
        return self.datacenter_code

class Firewall(models.Model):
    def __str__(self):
        return self.firewall_name

Easy enough, right? So here is the really cool thing about Django (or probably any web framework really) - These model objects are now something that we can reference in our code to change or query attributes about them. Even cooler is that Django automatically builds an admin page to our site, where we can create new instances of each model right there (which I’ll cover later). So this means that all I have to do is define these two models and their attributes, then anyone on my team can log into the dashboard admin page and add new firewalls or datacenters.

Okay, so in order to actually make these models useful, we need to add our attributes. For the datacenter object, I only care about two things - What is the datacenter code (identifier), and is the datacenter an active location. So here is where we add those options under our datacenter class:

class Datacenter(models.Model):
    datacenter_code = models.CharField('Datacenter Code', max_length=10)
    datacenter_active = models.BooleanField('Datacenter Active?', default=True)

The firewall object gets a little more complicated because I want to be able to define quite a few things. The obvious attributes are: the firewall name, which datacenter it belongs to, and whether or not it is an active firewall. I’ll also need to collect this firewall’s VPN peer IP, so that I can compare it against other devices to check the connection. But wait - how am I actually checking that VPN status? Oh, I guess I’ll also need to collect a username/password for the SRX API, as well as a valid management IP to reach the API.

Let’s take a moment though - because I stopped here and realized that I’ll need to collect user/password data in a form, then it’s going to be stored in a sqlite database. Oh, and of course it will be unencrypted. I didn’t really like that idea - so I did some research on how to encrypt one of the object attributes. Turns out, it’s actually pretty easy since someone has already created a module to do exactly that.

So let’s grab that module real quick:

[root@0x2142-Centos vpn]# pip install django-encrypted-fields

Once we have the module, it requires us to generate some keys which will be used for encrypting our data. The following is based on the steps listed on the GitHub page for django-encrypted-fields:

[root@0x2142-Centos junos-dashboard]# mkdir fieldkeys
[root@0x2142-Centos junos-dashboard]# keyczart create --location=fieldkeys --purpose=crypt
[root@0x2142-Centos junos-dashboard]# keyczart addkey --location=fieldkeys --status=primary --size=256

Next, we just need to add this keyfile into our settings.py:

ENCRYPTED_FIELDS_KEYDIR = '/root/junos-dashboard/fieldkeys'

Alright - back to actually creating the attributes we need for our firewalls. Since we’re using this new module, we’ll need to add an additional import statement - otherwise, we are just adding the fields I covered earlier:

from encrypted_fields import EncryptedCharField

class Firewall(models.Model):
    firewall_name = models.CharField('Firewall Name', max_length=50)
    firewall_location = models.ForeignKey('Datacenter', on_delete=models.CASCADE)
    firewall_active = models.BooleanField('Firewall Active?', default=True)
    firewall_manageip = models.GenericIPAddressField('Management IP')
    firewall_vpnip = models.GenericIPAddressField('VPN Interface IP')
    firewall_user = models.CharField('API User', max_length=50, blank=True)
    firewall_pass = EncryptedCharField('API Pass', max_length=50, blank=True)
    firewall_vpnstatus = models.TextField(editable=False, blank=True)

A few things to note here - The firewall_location attribute will actually query the table of datacenter objects - so we’re not creating any data twice. You might also notice that I added a firewall_vpnstatus text field, which is going to be hidden in the administrative console. Because I’m a terrible programmer, I’ll be storing all of the VPN status info in this text field in the database. Yes, there is probably a much more elegant way of handling this - but again, I’m a network admin not a professional coder. For what I need, this gets the job done. If you have a better way of accomplishing this - let me know! I would be very interested in another method.

I also found out later that just because I encrypted the field doesn’t mean that Django knows the field is a password. I wanted the field to be treated like a password input, so the data wasn’t visible to anyone who just logged in. I found out that you can create a forms.py file within the vpn directory, and pretty much override the field type to account for this.

So here is what I threw into the forms.py file to handle password input:

from django.forms import ModelForm, PasswordInput
from .models import Firewall

class FirewallForm(ModelForm):
    firewall_pass = CharField(widget=forms.PasswordInput)
    class Meta:
        model = Firewall
        fields = ['firewall_pass']

That was actually way easier than I had anticipated.

Awesome, now our work on the models is completely done - why don’t we log into the administrative  web interface and take a look at how it all turned out?

Here is a view of the datacenter page - where we can add a new location:

And now for the firewall objects - with all the fields we need to get the job done:

Looks pretty good, huh? And we didn’t even need to do any work to get the free admin functionality! This is honestly my favorite part of Django. Without posting a ton of additional screenshots, the admin page also provides audit logs - so we can see who changed what objects. Very helpful.

Alright - now let’s start work on our views.py file, so we can actually start putting all this together in our dashboard!

Within our views.py file, we already had our index function, which just returned a string of text. We’ll be adding to that in a moment - but first I created a separate function called buildrows, which does exactly what you think. This function will pull each firewall and it’s status, and build our little HTML table. I’m not going to go into great detail on this - but check out the comments for more information on what’s going on here:

# This is our function to build the HTML table - We're going to be expecting this function
# to be fed a list of firewalls and datacenters
def buildrows(firewall_list, datacenter_list):
    firewallstatus = []
    # We will iterate through each firewall and compile each row for our table
    for fw in firewall_list:
        # The first cell in our row is going to be the firewall name and it's own VPN peer IP
        onerow = "<td><b>%s</b><i>%s</i></td>" % (fw.firewall_name, fw.firewall_vpnip)
        # Now we iterate through every datacenter, in order to see which ones we have a
        # connection to from this firewall
        for dc in datacenter_list:
            # First thing is first - If this firewall contains the name of the datacenter
            # then we'll print N/A, since we wouldn't expect a VPN to itself 
            if str(dc.datacenter_code) in str(fw.firewall_name):
                onerow += ("<td>N/A</td>")
                continue
            # Also, if there is no VPN status in the database, then just print 'No Status'
            if not fw.firewall_vpnstatus:
                onerow += ("<td>No Status</td>")
                continue
     
            # This portion is pretty self-explanatory - We parse the vpnstatus field in the
            # database. If the state of the connection is 'VPNUP', then we print a cell for
            # that datacenter with the text 'UP'. If the state is 'VPNDOWN', then we print
            # 'DOWN'. And if nothing matches, print 'No Status'
            statuslist = ast.literal_eval(fw.firewall_vpnstatus)
            try:
                status = statuslist[dc.datacenter_code]
                if status == "VPNUP":
                    onerow += ("<td class=\"vpnup\">")
                    onerow += ("UP")
                elif status == "VPNDOWN":
                    onerow += ("<td class=\"vpndown\">")
                    onerow += ("DOWN")
                else:
                    onerow += ("<td>")
                    onerow += ("No Status")
                    onerow += ("</td>")
            except KeyError:
                onerow += ("<td>")
                onerow += ("No Status")
                onerow += ("</td>")
        # Once complete, we append this row to the status list
        firewallstatus.append(onerow)
    
    # All done! Return our list of statuses!
    return firewallstatus

That block might not make a ton of sense at the moment - but it will shortly. Essentially I have a script that is connecting to each firewall via the SRX API and polling the VPN status for each peer. The script is then writing all of this information to a field in the database called vpnstatus in one long string, which kinda looks like this:

{u'US-1': 'VPNUP', u'US-2': 'VPNUP', u'EU-1': 'VPNUP', u'EU-2': 'VPNUP', u'CN-1': 'VPNDOWN'}

The buildrows function is then just grabbing each firewall and then parsing this data to figure out what it has connections to - then generates a row in our table.

With that done, our index function within views.py needs a little work to start displaying our table. You’ll also notice we’re importing the models we created, as well as a template loader - which I’ll get to in a moment. So here is what that function will look like when we’re done:

from .models import Firewall, Datacenter
from django.template import loader
import sys, ast

def index(request):
    firewall_list = []
    datacenter_list = []
    firewall_status = []
    # This will grab each datacenter object (if they're marked active) from the 
    # database and add them to a list
    for each in Datacenter.objects.order_by('datacenter_code'):
        if each.datacenter_active == True: datacenter_list.append(each)
    # Same thing here - grab our firewalls and append to a list
    for each in Firewall.objects.order_by('firewall_name'):
        if each.firewall_active == True: firewall_list.append(each)
    # Now we pass those lists to the buildrows function to assemble our HTML table
    firewall_status = buildrows(firewall_list, datacenter_list)
    # We're also going to apply a template to make the page look fancy
    template = loader.get_template('web/index.html')
    # This is taking all of our lists, and passing them into our HTML template
    # so that it can build the page semi-automatically
    context = {
        'datacenter_list':datacenter_list,
        'firewall_list': firewall_list,
        'firewall_status':firewall_status,
    }
    return HttpResponse(template.render(context,request))

Alright - our views.py file is now complete. I wanted to keep the index function kind of simple, so we just have it pull data from the database, pass it to another function for processing, then return it to the browser for display.

So in the code above, you might have noticed that I was using an HTML template to make the page look fancier. I did this by going out to Google and finding a free CSS template for HTML tables. I won’t post the CSS here, but there are plenty of free templates out there - just find whatever suits your taste. Once you have that CSS file, create a directory (within our app folder) called static and place the CSS file in there.

Then, it’s one simple template HTML file to load our CSS and render our table. Within the app directory, I created a templates folder, then a folder called web within that. I added a new file called index.html - which looks like this:

<title>SRX VPN Dashboard</title>
<div align="center">
    {% load static %}
    <!-- Load the CSS template here -->
    <link rel="stylesheet" type="text/css" href="{% static 'style.css' %}" />
    <!-- Add a header to the table -->
    <div class="table-title">
        <h3>SRX VPN Dashboard</h3>
    </div>

    <!-- Create our first row, which will be a list of each data center location -->
    {% if firewall_list %}
        <table class="container">
        <tr>
        <th></th>
        {% for datacenter in datacenter_list %}
            <th>{{ datacenter.datacenter_code }}</th>
        {% endfor %}
        </tr>

        <!-- Then we add a row for each firewall, followed by its status 
             for each datacenter -->
        {% for firewall in firewall_status %}
            <tr>
            {{firewall|safe}}
            </tr>
        {%endfor%}

        </table>
        <!-- If something goes wrong, we just print an error -->
    {% else %}
        No firewalls were found.
    {% endif %}
</div>