Installing and configuring Oxidized on CentOS 7

I was recently asked to look at learning a bit about Oxidized for an upcoming project. If you've found this blog you already know what Oxidized is so I won't bother explaining it.

I thought it would be worth documenting what I found as there are a few considerations and issues to deal with on CentOS 7.

First, the version of Ruby available in the official CentOS 7 repositories is Ruby v2.0.0, Oxidized will fail to install under Ruby 2.0.0 as dependencies of Oxidized require a version of Ruby greater than 2.2/2.3.

ERROR: Error installing oxidized-web:
     puma requires Ruby version >= 2.2.

ERROR: Error installing oxidized-web:
     net-telnet requires Ruby version >= 2.3.0.

There are a couple of ways to deal with this, install older versions of puma and net-telnet that work with Ruby 2.0.0 or install a newer version of Ruby via rvm (Ruby Version Manager).

NOTE: The version of rdoc included with Ruby 2.0.0 will throw several errors during documentation parsing, it is recommended to use a newer version of Ruby which resolves these errors. Example of errors:

unable to convert "\x90" from ASCII-8BIT to UTF-8 for lib/oxidized/web/public/fonts/glyphicons-halflings-regular.eot, skipping
unable to convert "\xA1" from ASCII-8BIT to UTF-8 for lib/oxidized/web/public/fonts/glyphicons-halflings-regular.woff, skipping

Install dependencies
At this point the decision needs to be made to either upgrade Ruby or stick with version 2.0.0 in the CentOS repositories.

If using Ruby v2.0.0:

# yum install ruby ruby-devel make cmake which sqlite-devel openssl-devel libssh2-devel gcc libicu-devel gcc-c++

If you've decided to use a newer version of Ruby it will be installed via rvm so it won’t be necessary to install ruby and ruby-devel via yum.

# yum install make cmake which sqlite-devel openssl-devel libssh2-devel gcc libicu-devel gcc-c++

Install older versions of puma and net-telnet gems
Only do this if using Ruby v2.0.0
Before installing oxidized via gem install older versions of puma and net-telnet manually.

Install puma

# gem install puma -v 3.11.4

Install net-telnet

# gem install net-telnet -v 0.1.0

Install a newer version of ruby using Ruby Version Manager (rvm)
Skip this if using Ruby v2.0.0
RVM is a command-line tool which allows you to easily install, manage, and work with multiple ruby environments from interpreters to sets of gems.

Install rvm

# curl -sSL https://rvm.io/mpapis.asc | gpg --import -
# curl -L get.rvm.io | bash -s stable
# source /etc/profile.d/rvm.sh

Install Ruby 2.4 via rvm

# rvm reload
# rvm requirements run
# rvm install 2.4
# rvm list

Installing Oxidized as a Ruby "Gem"
RubyGems provides a repository of Ruby Libraries, the gem command allows search, list, install and uninstall of gems from the RubyGems repository.

The below packages (and their dependencies) will be installed as ruby gems:
oxidized - oxidized core
oxidized-script - oxidized cli and Library
oxidized-web - oxidized web interface and rest api

Install oxidized

# gem install oxidized oxidized-script oxidized-web

Create oxidized user

# useradd oxidized

Configure oxidized
Run oxidized to create config dirs, running Oxidized for the first time will create the necessary directory structure and a base configuration file.

# su - oxidized
$ oxidized
Exit Oxidized with ctrl+c

Device configs directory
This directory is used to store the configs from devices, it is advisable to store these on a separate volume group or if the host has limited disk space an NFS share.

Create directory to store plain file device configurations, if using plain file configs create a directory for the configs

$ mkdir -p /var/lib/oxidized/configs

If using git instead of plain files create a different directory

$ mkdir -p /var/lib/oxidized/devices.git

Edit configuration file
The below covers basic configuration of web interface, output location and an input source.

# su - oxidized
$ nano /home/oxidized/.config/oxidized/config

To allow the web interface to be accessible from computers other than localhost change the rest entry, if the web interface won’t be used this can be set to false.

Replace:

rest: 127.0.0.1:8888

With:

rest: 0.0.0.0:8888

Add to "source:" section:

  default: csv
  csv:
    file: "/home/oxidized/.config/oxidized/router.db"
    delimiter: !ruby/regexp /:/
    map:
      name: 0
      ip: 1
      model: 2
      username: 3
      password: 4
    vars_map:
      enable: 5

If using plain files add the below to the "output:" section:

  file:
    directory: "/var/lib/oxidized/configs"

Alternatively, and recommended Oxidized can use a local git repository providing version control:

  default: git
  git:
    user: oxidized
    email: bircoe@gmail.com
    repo: "/var/lib/oxidized/devices.git"

More information on git output: https://github.com/ytti/oxidized/blob/master/docs/Outputs.md#output-git

Now we need to create a database of devices

$ nano /home/oxidized/.config/oxidized/router.db

Format of db is as follows:

Hostname:IP:OS:username:password

Example:

Heimdall:192.168.1.1:opnsense:username:password

More information on CSV Source:
https://github.com/ytti/oxidized/blob/master/docs/Sources.md#source-csv

A list of supported OSes can be found at the below link:
https://github.com/ytti/oxidized/blob/master/docs/Supported-OS-Types.md

Testing Oxidized
At this point Oxidized should start successfully, Oxidized can be tested by starting it manually, example of successful start:

# su - oxidized
$ oxidized
I, [2018-08-08T19:28:12.697453 #876]  INFO -- : Oxidized starting, running as pid 876
I, [2018-08-08T19:28:12.698238 #876]  INFO -- : lib/oxidized/nodes.rb: Loading nodes
I, [2018-08-08T19:28:12.772161 #876]  INFO -- : lib/oxidized/nodes.rb: Loaded 1 nodes
Puma starting in single mode...
* Version 3.12.0 (ruby 2.4.4-p296), codename: Llamas in Pajamas
* Min threads: 0, max threads: 16
* Environment: development
* Listening on tcp://0.0.0.0:8888
Use Ctrl-C to stop
I, [2018-08-08T19:28:14.165742 #876]  INFO -- : Configuration updated for /192.168.1.1

Configure auto start
The Oxidized gem provides a prebuilt service file for systemd, pay attention to the path, it will change with the Ruby version and the version of Oxidized.

# sudo cp /usr/local/rvm/gems/ruby-2.4.4/gems/oxidized-0.24.0/extra/oxidized.service /lib/systemd/system/

Copy wrapper script to the location specified in the oxidized.service file

# cp /usr/local/rvm/gems/ruby-2.4.4/wrappers/oxidized /usr/local/bin/oxidized

Enable Oxidized to start at boot

# systemctl enable oxidized

Start Oxidized

# systemctl start oxidized

Confirm that Oxidized has started correctly

# systemctl status oxidized

Troubleshooting
Run oxidized manually to check for error messages.

# su - oxidized
$ oxidised

I, [2018-08-08T19:23:36.288017 #32734] INFO -- : Oxidized starting, running as pid 32734
F, [2018-08-08T19:23:36.291134 #32734] FATAL -- : Oxidized crashed, crashfile written in /home/oxidized/.config/oxidized/crash
no source csv config, edit ~/.config/oxidized/config

In the above exampled there is no source configured in the config file, rectify any errors until Oxidized starts without errors.

I hope someone finds this helpful, please leave a comment if I helped you or you have a suggestion.