Home » How to Install Oxidized for Network Config Backup

How to Install Oxidized for Network Config Backup

  • by

Oxidized is an open-source project started by Saku Ytti and Samer Abdel-Hafez as an alternative to the very popular RANCID software. With this article, I Will show How to Install Oxidized for Network Config Backup


Oxidized is a network device configuration backup tool. It’s a RANCID replacement!

Light and extensible, Oxidized supports over 130 operating system types.


Feature highlights:

    • Automatically adds/removes threads to meet configured retrieval interval
    • Restful API to a move node immediately to head-of-queue (GET/POST /node/next/[NODE])
    • Syslog udp+file example to catch config change events (IOS/JunOS) and trigger a config fetch
    • Will signal which IOS/JunOS user made the change, can then be used by output modules (via POST)
    • The git output module uses this info – ‘git blame’ will show who changed each line, and when
    • Restful API to reload list of nodes (GET /reload)
    • Restful API to fetch configurations (/node/fetch/[NODE] or /node/fetch/group/[NODE])
    • Restful API to show list of nodes (GET /nodes)
    • Restful API to show list of version for a node (/node/version[NODE]) and diffs

I did this on Debian 11 following their installation instructions. I wanted things simple — no git repo, no docker, no sql databases. Just read from a list of switches and dump their configs to a directory.

After the first reboot, update the system, install a few tools. I use vim when I have to, but prefer nano. Of course, use the editor of your choice.


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

  • Oxidized – 0.28.0
  • Oxidized Host – Debian 11
  • Mikrotik – (I’m Using CCR, MAP Lite, RB450 and more)
  • Cisco – C2960G
  • Dell Force10 – S60

Install Dependencies

add-apt-repository universe
apt-get install ruby ruby-dev libsqlite3-dev libssl-dev pkg-config cmake libssh2-1-dev libicu-dev zlib1g-dev g++
gem install oxidized
gem install oxidized-script oxidized-web # If you don't install oxidized-web, ensure "rest" is removed from your Oxidized config.

create user & environment

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
echo "OXIDIZED_HOME=/opt/oxidized" | sudo tee --append /etc/environment


touch /opt/oxidized/.config/oxidized/config
touch /opt/oxidized/.config/oxidized/router.db

Oxidized Config File

fill the file /opt/oxidized/.config/oxidized/config that you have create before and this my tested script. this script will give output for your local server and auto sync to your git repo (I’m using github)

log: /opt/oxidized/.config/oxidized/logs/oxidized.log
  default: ssh, telnet
  debug: false
    secure: false
  default: csv
    file: "/opt/oxidized/.config/oxidized/router.db"
    delimiter: !ruby/regexp /:/
      name: 0
      ip: 1
      model: 2
      group: 3
    vars_map: {}
  juniper: junos
  cisco: ios
  mikrotik: routeros
  force10: dnos
  enable: <your secret>
  remove_secret: true
    username: oxidized
    password: <your password>
    username: oxidized
    password: <your password>
    username: oxidized
    password: <your password>
models: {}
    directory: /var/lib/oxidized/configs

on the script above, I have use remove_secret: true to remove the secret/password on backup configuration. It’s better secure for me

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

    • 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.

and then fill the file /opt/oxidized/.config/oxidized/router.db that you have create before too

# name:ip:model:group

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

Create 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
Description=Oxidized - Network Device Configuration Backup Tool
After=network-online.target multi-user.target



Start and enable the oxidized service.

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


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/devninja.git/

├── cisco
│   └── devninja-SW
├── force10
│   └── devninja-MMR
├── mikrotik
│   ├── miko-devninja
│   └── R1-devninja
└── README.md

3 directories, 5 files

Because I configured the groups config parameter, Oxidized creates a folder for each group of devices.


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

another docs from oxidized can found here. setup for auto sync for git repo will be found in the next post 🙂


Leave a Reply

Your email address will not be published.

nine − five =