Oxidized quickstart tutorial howto

Oxidized is a “RANCID replacement” — a system for automatically extracting, storing, and comparing configuration files from network devices. I have no experience with RANCID or anything else, and I am most certainly not a programmer, so I struggled to follow their instructions. I wrote up my notes in case they’re helpful to anyone else.

I did this on CentOS 7 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. 

1. yum install cmake sqlite-devel openssl-devel libssh2-devel ruby gcc ruby-devel 

2. gem install oxidized

3. gem install oxidized-script oxidized-web

4. useradd oxidized

5. su - oxidized

6. Run oxidized with no args. This creates a /home/oxidized/.config/oxidized/ directory with a sample config in it.

6.5 mkdir /home/oxidized/deviceconfigs to store the configs it will download.

7. Edit /home/oxidized/.config/oxidized/config as per the following (I added the //comments here, not sure how to properly comment within the config file itself.)

// Our environment is mostly ProCurve switches.
// We use the same username (manager) and
// same password (f00bar) on all of them.
// Global defaults. Can be overridden on a per-device basis 
// by specifying different model, username, or password in router.db.
username: manager
password: f00bar
model: procurve
// How often it grabs the configs, in seconds
interval: 600
// Other defaults
log: ~/.config/oxidized/log
use_syslog: false
debug: false
threads: 30
timeout: 20
retries: 3
prompt: !ruby/regexp /^([\w.@-]+[#>]\s?)$/
pid: /home/oxidized/.config/oxidized/pid

// Procurve gear doesn't need the "enable" pwd 
// because we ssh in directly as manager, but this is 
// where we'd specify it.
  enable: v3ry5ecur3
  // This removes/obscures cleartext passwords 
  // before saving the config.
  remove_secret: true

// IP and port for http listener (view all nodes, download, etc.)
// Set to zeroes to bind to all IP addresses,
// and I needed to change the default port.

// No idea how to use this yet, I think we're
// a small enough environment that who cares.
groups: {}

// Try ssh first, telnet second.
  default: ssh, telnet
  debug: false
    // I think this means, don't care about ssh key warnings.
    secure: false
  default: file
    directory: /home/oxidized/deviceconfigs

  default: csv
  // Format:
  // hostname:modelname:username:password:enablepassword
  // sw-edge3.example.org:procurve:manager:s3cr3t:SuP3rSecr3t
  // Only name (hostname) and model are required, the other things
  // will use global values from this config file if left blank.
    file: /home/oxidized/.config/oxidized/router.db
    delimiter: !ruby/regexp /:/
    // Tell it which field is which in the csv.
      name: 0
      model: 1
      username: 2
      password: 3
      enable: 4

// I *think* that this just lets you write "cisco" 
// when you MEAN "ios", but I dunno.
  cisco: ios
  juniper: junos

8. Run firewall-cmd --permanent --zone=public --add-port=8787/tcp followed by firewall-cmd —reload to let me view the webpage. Im including this stupid step because I ALWAYS forget to do it, and waste time trying to figure out why [thing] doesnt work.

9. Create /home/oxidized/.config/oxidized/router.db and make it look something like this:


10: Run oxidized again (no args) and browse to


and you should see a list of nodes (devices). Wait a few seconds/minutes to give it a chance to fetch the configs. 

The Actions buttons are, left to right: View config, compare versions, and update now.

If we had one switch with a different set of credentials, we’d add it to router.db like this:


If we had one Cisco switch amidst all the Procurves, we’d do something like


Here’s another reference which helped, mainly for his config file diffs (I dont use Docker):



- Daemonize oxidized so it starts automatically when the server restarts

- Set up some kind of alerting for if a node is unreachable, or if a config has changed. I’m sure this is easy to accomplish IF you understand all their references to RESTful APIs and stuff, but I so totally don’t.

- integrate with LibreNMS somehow???? Well, that was actually kinda stupidly easy:

In LibreNMS, go to gear icon -> Global Settings -> External Settings and plug in the URL to Oxidized:

Then, go to LibreNMS’s Devices view, find one of the switches, and click Config. If all is well, it should look something like this:

If it throws an error, make sure that the devices name in LibreNMS EXACTLY matches the devices name in Oxidized. I got tripped up because in LibreNMS things were just sw-edge1 but in Oxidized they were sw-edge1.example.org, oops. Use LibreNMSs rename.php to fix that:

cd /opt/librenms
./renamehost.php sw-edge3 sw-edge3.example.org

(With help from http://docs.librenms.org/Extensions/Oxidized/ AND especially https://www.reddit.com/r/networking/comments/5cw9op/oxidized_or_rancid_vs_other_for_config_backup/