Oxidized Quickstart

Oxidized is a "RANCID replacement" that has taken on a life of it's own.  Designed to automatically store, compare, and log configuration files from network based equipment.

I've never used RANCID, or rConfig, or Sweet, but I wanted to more than a fileshare of all the latest configs of our devices, which is what we were doing.

Oxidized the seemed the easiest to setup.

Here is how I setup one up from scratch.


  1. Setup an Ubuntu server.  I used 16.04.2, the LTS version available at the time.
    • When asked to create a user, make it oxidized
    • Set the timezone as UTC
    • Run apt-get update and get everything current.
  2. Install dependancies
    sudo apt-get install ruby ruby-dev libsqlite3-dev libssl-dev pkg-config cmake libssh2-1-dev
  3. Install oxidized.
    sudo gem install oxidized
  4. Install oxidized web front endsudo gem install oxidized-script oxidized-web
  5. run oxidized with no args.  This will create all the required directories, with a sample config in it.


  1. Edit the /home/oxidized/.config/oxidized/config to customize your system.
I've inserted comments with the // before them.  This is not a valid operator, so don't attempt to use them. This is more to identify the places that you need to replace the defaults.  I'm not pretending to know what all of these settings mean, but I'm identifying the ones to change.  I don't recommend changing the other defaults unless you have a good reason. (for example, the thread counts)

  1. Copy the oxidized.services file from extras to /lib/systemd/system/
    sudo cp /var/lib/gems/2.3.0/gems/oxidized-0.19.0/extra/oxidized.service /lib/systemd/system
  2. Set the service to start at boot
    sudo systemctl enable oxidized.service
That should give you a fully functional Oxidized instance running. You can only access it from localhost.

Wait...  What?  You want authentication?  HTTPS?  Oxidized doesn't support that natively.  The preferred suggestion seems to be:
  • Run an NGINX instance on the same host, configured for HTTPS and authentication
  • Configure Oxidized to only answer queries. (This is Oxidized's default configuration)

Setup a NGINX forward proxy to enable SSL

  1. Add nginx-extras
    apt-get install nginx-extras
  2. Remove the default site, and copy the example oxidized configuration to NGINX
    sudo rm /etc/nginx/sites-enabled/default
    sudo cp /var/lib/gems/2.3.0/gems/oxidized-0.19.0/extra/oxidized.nginx /etc/nginx/sites-enabled/default
  3. Edit the site config, and enable SSL
    sudo vi  /etc/nginx/sites-enabled/default
  4. Create the directory to hold the SSL certs
    sudo mkdir /etc/nginx/ssl
  5. Create the SSL certificates
    sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/ssl/nginx.key -out /etc/nginx/ssl/nginx.crt
  6. sudo systemctl reload nginx
Your site show be available to both http and https connections now.

Configure NGINX to enable LDAP auth

  1. Install Prereq's
    sudo apt-get install nodejs npm
    sudo apt install nodejs-legacy
  2. Create unprivelged user
    useradd --shell /sbin/nologin -m nginx-auth
  3. Clone the nginx-auth repository
     sudo -u nginx-auth -H git clone https://github.com/justinjahn/nginx-auth.git
  4. Installing NPM Packages
    cd /home/nginx-auth/nginx-auth
    sudo -u nginx-auth -H npm install
    (Note, i had issues with NPM, had it install it twice)
  5. Copy and edit the configuration file
    sudo -u nginx-auth -H cp config/default.json.dist config/default.json
    sudo -u nginx-auth -H vi config/default.json

  1. Install the LDAP Pam module
    sudo apt-get install libpam-ldapd
  2. Create the LDAP config File
    sudo vi /etc/pam.d/nginx_restricted

    auth    required     /lib/x86_64-linux-gnu/security/pam_listfile.so onerr=fail item=user \                     sense=allow file=/etc/nginx/restricted_users
    auth    required     /lib/x86_64-linux-gnu/security/pam_ldap.so
    account required     /lib/x86_64-linux-gnu/security/pam_ldap.so
  3. Create the list of allowed groups
    sudo vi /etc/nginx/restricted_users


Popular posts from this blog

WPAD does not resolve in DNS