Before we get into what SuzieQ is, let’s start with a common scenario for Network Engineers. Imagine you’re putting together this OSPF topology. The usual steps involve configuring IP addresses, loopbacks, router IDs, and OSPF parameters. Then you’d run several show commands to verify that neighbors are up and running correctly.

If something is not as expected, you need to find the problem and troubleshoot further. Even if everything seems to be in order, it’s important to confirm that the configurations are applied as intended. This process can frequently lead to errors because it requires coordinating various configuration elements across multiple pairs of devices.

A simple lab network showing three devices connected serially

In this lab environment, I have three Arista devices connected as shown in the above diagram. Router r1 connects to r2 and r2 connects to r3. Each router has a P2P interface that connects to its peers. The routers also have a stub network (172.16.0.x) and a loopback interface (10.0.0.x)

Once I finished configuring the devices, I ran some show commands on each of the routers to make sure the neighbourship was up and they were learning the routes. But now imagine you have tens of or even hundreds of devices from different vendors and you want to constantly validate to make sure they are functioning as intended. It would take hours and hours to do this manually or even using a custom Python script or an Ansible playbook. That’s where SuzieQ comes in and makes your life easier.

To validate that the OSPF configuration is applied correctly in our example, you only need to run a couple of commands using SuzieQ CLI. This command provides confirmation on whether OSPF has been set up correctly.

Screenshot showing SuzieQ CLI displaying errors in OSPF lab setup

The ospf show command provides a snapshot of our network's OSPF status. It lists out details like each router's hostname, the interfaces, the OSPF areas they belong to, and the adjacency state among routers. It even provides some helpful information such as the peer’s hostname which we don’t see in the normal CLI outputs. From this output, we notice that the loopback interfaces are marked as 'fail'. Please note that you can use query filters to reduce the output you see on the CLI. We will cover them in a separate blog post.

Moving on to the ospf assert command, it performs checks to confirm the OSPF configuration is as it should be. In our case, it’s again flagging issues with the loopback interfaces. The 'assertReason' column clearly tells us 'No Peer Found', indicating these interfaces don't have any neighbors. This is a hint that I should have configured the loopback interfaces as OSPF passive interfaces, preventing them from attempting to establish adjacency with other OSPF routers.

These examples illustrate one of SuzieQ's use cases in pinpointing where our configuration may be going wrong. With such insights, you can quickly identify and rectify configuration errors. I’m going to make loopback0 as an ospf passive interface on r1 and re-test to see what SuzieQ shows now. As you can see, it doesn’t show up as ‘fail’ anymore. In the next sections, we will look at what SuzieQ is and how to get it up and running in your environment.

SuzieQ CLI screenshot showing OSPF working

SuzieQ Introduction

SuzieQ is an open-source multi-vendor network observability platform that is focused on improving your understanding of your network. We define observability as the ability of a system to answer either trivial or complex questions that you pose as you go about operating your network.

How does it work?

After seeing SuzieQ in action with the OSPF example, you might be wondering how to bring this tool into your network environment. Let's break down how SuzieQ works and the steps to get it up and running.

SuzieQ needs read-only access to your network devices. It logs into each device, runs a series of "show" commands and takes a detailed snapshot of your network's current state.

With this data in hand, you can begin to ask SuzieQ questions. Simple ones, like "Is my OSPF configuration, correct?" or more specific queries, such as "What are the MAC addresses for devices in VLAN 10?"

SuzieQ Installation

Installing SuzieQ is a straightforward process. You've got two options, use pre-built Docker containers or install it as a Python package. For now, we'll focus on the Python package method, and I'll get to the Docker approach in a future post.

For this example, I'm using an Ubuntu machine with Python version 3.9.11. SuzieQ works with Python versions 3.8/3.9.

Before installing any Python package, it's always a good idea to use a virtual environment. A virtual environment, or venv for short, is a tool that helps keep dependencies required by different projects separate by creating isolated Python environments for them. It's like giving each project its own unique space on your machine, so they don't interfere with each other. Here's how you set one up and install SuzieQ.

python3 -m venv venv 
source venv/bin/activate 
pip install suzieq

And that's pretty much it for the installation part. To check if everything's in order, just run suzieq-cli version command, and it should confirm the successful installation of SuzieQ on your system by printing out the version.

(venv) suresh@ubuntu-desktop:~/Documents/projetcs/suzieq$ suzieq-cli version 
0.22.0

SuzieQ Terminology

Now that SuzieQ is installed, let’s get it ready to use. There are a couple of key files and directories you need to set up before diving in that are a configuration file and an inventory file. Both are written in YAML, which is a human-friendly data serialization standard. You also need to create a couple of directories to save the snapshots and any temporary files.

The configuration file is where you'll define the settings SuzieQ needs to function correctly in your environment. The inventory file, on the other hand, lists all the devices in your network that SuzieQ will pull information from, along with the necessary credentials to access them.

In the next section, I’ll dive into the details of each file, showing you how to create them and explaining what each part does. We will also look at the poller and suzieq-cli which are essential for using SuzieQ as a whole.

Configuration File

For those of you familiar with Ansible, you know that ansible.cfg is where you configure Ansible's configuration parameters. Similarly, the configuration file for SuzieQ is where you define how SuzieQ operates and interacts with your network devices. This file includes various settings and parameters that tell SuzieQ about aspects such as where to collect data from, where to store it, and how to process it.

By default, SuzieQ looks for the configuration file in one of these locations in the following order:

./suzieq-cfg.yml (the same folder where the SuzieQ component is started)
$HOME/.suzieq/suzieq-cfg.yml
The configuration file can also be explicitly set as an argument using -c flag (sq-poller -c suzieq-config.yml)

Here is a sample configuration file created in the current working directory.

#suzieq-cfg.yml 
 
data-directory: ./parquet 
temp-directory: ./tmp/ 
 
rest: 
  API_KEY: 656257e6rt56cb24a6f6d847b2245a 
  logging-level: WARNING 
  address: 127.0.0.1 
  port: 8000 
 
poller: 
  logging-level: DEBUG 
  period: 30 
  connect-timeout: 15 
  logfile: ./tmp/sq-poller.log 
  max-cmd-pipeline: 1 
  inventory-file: ./inventory.yml 
  chunker: 
	policy: sequential 
 
coalescer: 
  period: 1h 
  logging-level: WARNING 
 
analyzer: 
 timezone: Europe/London

data-directory - This is where SuzieQ saves the data it gathers from your network devices, in a big data format 'parquet', which is optimized for fast reading and writing of large datasets.
temp-directory - A place to save temporary files used during SuzieQ's operation.
rest - This section configures the REST API settings.

API_KEY - A unique key for securing access to your API.
logging-level - Sets the threshold for what level of details you want to log.

address and port - These specify where the REST API service will listen for incoming requests.

poller - Controls how SuzieQ collects data.

period - How often, in seconds, SuzieQ will poll your devices to gather data.
logfile - Where to save log files from the polling process.
inventory-file - The location of the file listing all devices SuzieQ should gather data from.
chunker - This determines how data collection tasks are distributed, with 'sequential' meaning the inventory is divided into 'n' equal chunks, where 'n' represents the number of workers. For instance, if you have 100 devices and specify 2 workers (using sq-poller -w 2), the list is split into two groups: the first 50 devices go to worker 1, and the remaining 50 are assigned to worker 2.
coalescer -This is for internal housekeeping and coalescing multiple data into a smaller set of files for better performance.

We will cover each of these options in detail in a future post but if you want to dive deep, feel free to check out the comprehensive explanation here in the official documentation - https://suzieq.readthedocs.io/en/latest/config_file/.

Inventory File

The inventory file is where you list all the network devices that SuzieQ will monitor and gather data from. For each device, you'll include details such as the device type, its hostname or IP address, and the credentials SuzieQ should use to access the device.

The inventory file is structured in 4 major pieces

sources - a list of sources to gather the list of devices
devices - a list of default settings to be applied
auths - a list of credential sources
namespaces - where you put together all the above. A namespace is defined by a source, an auth and a device

Namespaces are the way to group devices in SuzieQ. These groups allow the analysis of devices together. Namespaces also allow overlapping device names between namespaces. The most common method is to assign each site or campus to a namespace.

In this example, I’m using three Arista devices with the same user credentials. You can also pull data from external sources such as NetBox but we will cover that in a later post.

#inventory.yml

sources:
  - name: test_devices
    hosts:
      - url: ssh://192.168.100.201
      - url: ssh://192.168.100.202
      - url: ssh://192.168.100.203

devices:
  - name: default_settings
    transport: ssh
    port: 22
    ignore-known-hosts: true

auths:
  - name: default_creds
    username: admin
    password: plain:admin

namespaces:
  - name: my_ns
    source: test_devices
    device: default_settings
    auth: default_creds

Here’s a brief overview of each section

sources - Defines groups of network devices that SuzieQ will poll.

name - A label for the group, here called test_devices.
hosts - A list of device URLs that SuzieQ will access, in this case via SSH.

devices - Specifies connection settings that are common across multiple devices.

transport - The method of connecting to the device, set to SSH here.
port - The network port SuzieQ will use, typically 22 for SSH.

ignore-known-hosts - This option bypasses SSH checks against the known host file.
auths - Defines authentication methods for logging into devices. As we always recommend, never expose credentials in production environments. Instead of hardcoding the credentials, you can also use environment variables or ‘ask’ for the credentials.
namespaces - organize devices into logical groups to manage settings and access them as a single unit.

name - The label for this namespace, my_ns.
source: - Refers back to the test_devices defined in sources.
device - Connects to the default_settings defined in devices.
auth - Uses the default_creds defined in auths.

Poller

The poller is a key component of SuzieQ that is responsible for actively collecting data from your network devices. It works by periodically connecting to each device in your network as specified in the inventory file. To start the poller, you can run the command sq-poller from your current directory. As soon as you run this command, the poller will start connecting to the devices and gathering information.

Suzieq-cli

The suzieq-cli is the command-line interface for SuzieQ, offering a simple way for users to interact with SuzieQ's features directly from a terminal. This interface is especially useful for those who are comfortable using command lines to execute tasks. (We are network engineers after all working with CLI for years and years)

Through the CLI, we can enter commands to fetch data, ask questions, and analyze the overall health of our network.

You can run suzieq-cli command to initialize the CLI.

A Quick Recap

we've covered quite a bit, so it’s good to pause and review what we've learnt so far about setting up and using SuzieQ.

This is how our directory structure looks after creating all the required files and directories.

.
├── inventory.yml
├── parquet
├── suzieq-cfg.yml
├── tmp

First, we went through the installation of SuzieQ, making sure everything was set up correctly. Next, within our project directory, we created two files, a configuration file and an inventory file. These files help SuzieQ understand how to interact with our network and where to store the data it collects.

We also set up two directories, parquet and tmp, right inside our project folder, as specified in our configuration file. The parquet directory is used for storing the data SuzieQ collects in a structured format, and tmp is for temporary files that SuzieQ might need during its operations.

To start data collection, we ran the sq-poller command. This starts the process of SuzieQ gathering information from the network based on the settings we defined in the inventory and configuration files.

Finally, once the data is collected, we can use the suzieq-cli to start asking questions about our network.

Verification and Practical Use

It's time to put everything we've learnt to the test. As previously discussed, I'll run the sq-poller command from the current working directory. This will kick off SuzieQ's data collection process. Once you execute the sq-poller, you'll notice that this command will continue to run, occupying the current terminal.

Open another terminal window, in this new terminal, launch suzieq-cli and enter the command devices show. This command displays the status of the devices SuzieQ is monitoring.

Look for the word 'alive' next to your devices in the output. If you see 'alive', that means everything is set up correctly and working as expected. This confirms that SuzieQ is successfully collecting and analyzing data from your network.

Some Examples

Here is an example use of the CLI command address show to output the IP addresses, and Mac addresses of all the devices. The output also shows the hostname and the VRF.

What if I want to see just the management IP addresses from all the devices?

Getting Started with SuzieQ