This is a guide for integrating Oxidized with LibreNMS. This guide also addresses the installation of a newer version of Ruby on CentOS 7.

 

The first step is to verify the removal of the default version of Ruby (2.0.0), and installing Ruby 2.4.5 from source.

Remove Ruby:

sudo yum remove ruby ruby-devel

Install development tools:

sudo yum groupinstall "Development Tools"

Verify/install the following dependencies:

sudo yum install openssl-devel wget cmake libicu-devel

Fetch Ruby 2.4.5 via wget:

wget http://he.ruby-lang.org/pub/ruby/2.4/ruby-2.4.5.tar.gz

Unpackage gunzip:

tar -zxvf ruby-2.4.5.tar.gz

Build!

cd ruby-2.4.5
./configure
make
sudo make install

We can now verify Ruby version:

ruby --version

Install Oxidized via Ruby:

gem install oxidized oxidized-web oxidized-script

 

Copy Oxidized service

Find the service:

sudo find / -name "oxidized.service"

Notate the path, and move to systemd based on the location discovered from “find”; the oxidized service file contains notes on the correct path to copy per flavor of linux:

mv /usr/local/lib/ruby/gems/2.4.0/gems/oxidized-0.24.0/extra/oxidized.service /etc/systemd/system/

Change user from “oxidized” to “root” within the oxidized.service file:

nano /etc/systemd/system/oxidized.service

Verify that oxidized starts:

oxidized

The initial output should refer to “edit ~/.config/oxidized/config”; this is the location of the default config file generated by oxidized. We will refer to the full path in references (i.e. /root/.config/oxidized/config) for all future references.

Oxidized will pull information via the LibreNMS API; the API can be generated through the LIbreNMS web interface at:

Settings -> API -> API Settings

After generating the token, test the token with the following command:

curl -H ‘X-Auth-Token: 1234567890’ http://127.0.0.1/api/v0/oxidized

We have implemented SSL; use the full url name if you have implemented a certificate for the curl.

Once we have verified that Oxidized has started, we can set the service to run and add a firewall exception.

Start the service, add firewall exception for correct zone; note we changed to port within oxidized to 8843:

sudo systemctl daemon-reload
sudo systemctl enable oxidized.service
sudo systemctl start oxidized
sudo systemctl status oxidized
sudo firewall-cmd --zone=public --permanent --add-port=8843/tcp

Once devices have been added to LibreNMS, test the API to verify models, OS types etc:

curl -H 'X-Auth-Token: 1234567890' http://127.0.0.1/api/v0/oxidized

The curl to the API helps to provide important information; it will reveal how LibreNMS interprets existing devices so you can create model maps that help Oxidize interpret the pulled information. For example, for a UniFi access point, LibreNMS identifies the device as having the OS “unifi”, put per the Oxidized forums, we want Oxidized to map out to “airos”. The Cisco SMB switches are another example I discovered and mapped out below. If the OS types match per the API pull, do not map them.

Once setting your URL and port within the Oxidzed settings page, allow access via your firewall. We use firewalld, with the following command to allow port 8843 TCP access to allow access to the localhost interface:

firewall-cmd --permanent --zone=trusted --add-interface=lo
firewall-cmd --permanent --zone=trusted --add-port=8843/tcp
firewall-cmd --reload

 

Oxidized Configuration Example:

# /root/.config/oxidized/config
username: oxidized
password: securepasswordforoxidized
model: juno
interval: 3600
use_syslog: false
threads: 30
timeout: 20
retries: 3
prompt: !ruby/regexp /^([\[email protected]]+[#>]\s?)$/
rest: 0.0.0.0:8843
next_adds_job: false
vars: {}
models: {}
pid: "/root/.config/oxidized/pid"

input:
  default: ssh, telnet
  ssh:
    secure: false

output:
  default: git
  git:
    user: root
    email: [email protected]
    repo: "/root/.config/oxidized/devices.git" 
  
source:
  default: http
  http:
    url: https://librenms.yourdomain.com/api/v0/oxidized
    map:
      name: hostname
      model: os
      group: group
    headers:
      X-Auth-Token: 'randomAPIstringhere-fromLibreNMS'

model_map:
  cisco: ios
  juniper: junos
  unifi: airos
  ciscosb: ciscosmb

groups:
  Cisco_SMB:
    username: oxidized
    password: securepasswordforoxidized
  pfSense:
    username: oxidized
    password: securepasswordforoxidized
  UniFi_APs:
    username: oxidized
    password: securepasswordforoxidized
  UniFi_Switch:
    username: oxidized
    password: securepasswordforoxidized


hooks:
  post-commit:
    type: exec
    events: [node_success, post_store]
    cmd: 'cd /root/.config/oxidized/devices.git && git push -f -q /root/.config/oxidized/devices.git master'