Oxidized Getting Started

Intro

Oxidized is a network device configuration backup tool which was developed to be a replacement for Rancid. Oxidized is written in Ruby and is quite extensible, at the time of writing it supports collection of configuration for over 90 network operating system types.

In this post I will install and configure Oxidized enabling the collection of config from Juniper vSRX and Cisco IOSv devices. The configurations will be stored as files on the Oxidized host.

For reference the following software will be used in this post.

• Oxidized - 0.21.0
• Oxidized Host - Debian 9
• Juniper vSRX - 12.1X47-D15.4
• Cisco IOSv - vios-adventerprisek9-m.vmdk.SPA.156-1.T

Install

There are a number of installation methods available including building from source and installing a Docker container. For this blog I will install Oxidized via the Ruby gem.

First update the base system and install the dependencies.

sudo apt update
sudo apt install -y ruby ruby-dev libsqlite3-dev libssl-dev pkg-config cmake libssh2-1-dev

Now install then Oxidized gem.

sudo gem install oxidized

Configuration

Oxidized User

It is not recommended to run Oxidized as the root user, I will setup a user called oxidized to manage the Oxidized application along with the associated directories.

sudo useradd oxidized
sudo chsh -s /usr/sbin/nologin oxidized
sudo mkdir -p /opt/oxidized/{output,.config/oxidized/}
sudo usermod -m -d /opt/oxidized oxidized

Oxidized defaults to using the $HOME directory of the user that runs the application. To change this behaviour set an environment variable $OXIDIZED_HOME .

echo "OXIDIZED_HOME=/opt/oxidized" | sudo tee --append /etc/environment

Oxidized Config File

Create a file named config in the /opt/oxidized/.config/oxidized/ directory with the following contents.

# /opt/oxidized/.config/oxidized/config

---
username: vagrant
password: vagrant
model: junos
interval: 3600
use_syslog: true
log: /opt/oxidized/.config/oxidized/logs/
debug: false
rest: false
threads: 30
timeout: 20
retries: 3
prompt: !ruby/regexp /^([\w.@-]+[#>]\s?)$/
next_adds_job: false
pid: "/opt/oxidized/pid"

input:
  default: ssh
  debug: false
  ssh:
    secure: false

output:
  file:
    directory: /opt/oxidized/output/configs

source:
  default: csv
  csv:
    file: /opt/oxidized/.config/oxidized/router.db
    delimiter: !ruby/regexp /:/
    map:
      name: 0
      ip: 1
      model: 2
      group: 3
    vars_map: {}

model_map:
  juniper: junos
  cisco: ios

vars: {}

groups:
  juniper:
    username: vagrant
    password: Vagrant
  cisco:
    username: vagrant
    password: vagrant

models: {}

The Oxidized configuration file is in a yaml format. There are a number of elements in this configuration file which I will touch on.

• interval - How often to collect data (seconds).
• input - The method to get config from devices.
• output - How to store the configuration.
• source - The data source for the list of devices.
• model_map - Used to map device groups to models.
• groups - Group specific variables.
• models - Model specific variables.

Under the source section you will notice a map section. The map section defines the column number in which to find attributes such as name and ip in the data source.

Oxidized Datafile

Create a data source file named router.db in the /opt/oxidized/.config/oxidized/ directory with the following contents.

# /opt/oxidized/.config/oxidized/router.db

# name:ip:model:group
ios1:192.168.121.133:cisco:cisco
srx1:192.168.121.91:juniper:junipers

I have added a comment line to show how the map values from above align to the columns in the data source file. As you can see this follows the csv format using a colon (: ) as the column delimiter.

Finally adjust the permissions of the /opt/oxidized directory changing the ownership to the oxidized user.

sudo chown -R oxidized:oxidized /opt/oxidized

Oxidized Service

The oxidized github repo provides a number of helper scripts to manage to oxidized application. I will use the systemd service script to manage oxidized for this install. This script and others can be found here.

Create a file named oxidized.service in the /lib/systemd/system/ directory with the following contents.

# /lib/systemd/system/oxidized.service

[Unit]
Description=Oxidized - Network Device Configuration Backup Tool
After=network-online.target multi-user.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/oxidized
User=oxidized
KillSignal=SIGKILL

[Install]
WantedBy=multi-user.target

Start and enable the oxidized service.

sudo systemctl start oxidized.service
sudo systemctl enable oxidized.service

Verification

When the oxidized service is started it will attempt to fetch the configuration from all the devices in the data file. Confirm that the configuration was backed up by inspecting the output directory.

tree /opt/oxidized/output/

# output

/opt/oxidized/output/
├── cisco
│   └── ios1
└── juniper
    └── srx1

Because I configured the groups config parameter, Oxidized creates a folder for each group of devices. You can group devices based on a logical construct such as; customer, region, business function, etc... whatever makes sense for your use case.

Troubleshooting

If for some reason things are not working as expected check the following items for a clue as to what is going on.

• systemctl status oxidized.service - Confirm the oxidized service is running with no errors
• /opt/oxidized/.config/oxidized/logs/oxidized.log - Check oxidized log
• /opt/oxidized/.config/oxidized/crash - Check oxidized crash log
• /var/log/syslog - Check the system log
• debug: true - Enable debugging in the oxidized config

Outro

Oxidized is a pretty useful tool for keeping your network device configurations backed up. In future posts, I will configure Oxidized to store the device configurations in Gitlab, tighten up security by encrypting the passwords and putting a secure web server in front of the rest API.