LibreNMS – Integrating Oxidized on CentOS 7

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:


Unpackage gunzip:

tar -zxvf ruby-2.4.5.tar.gz


cd ruby-2.4.5
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:


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’

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'

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.

LibreNMS GUI settings for Oxidized

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?)$/
next_adds_job: false
vars: {}
models: {}
pid: "/root/.config/oxidized/pid"

  default: ssh, telnet
    secure: false

  default: git
    user: root
    email: [email protected]
    repo: "/root/.config/oxidized/devices.git" 
  default: http
      name: hostname
      model: os
      group: group
      X-Auth-Token: 'randomAPIstringhere-fromLibreNMS'

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

    username: oxidized
    password: securepasswordforoxidized
    username: oxidized
    password: securepasswordforoxidized
    username: oxidized
    password: securepasswordforoxidized
    username: oxidized
    password: securepasswordforoxidized

    type: exec
    events: [node_success, post_store]
    cmd: 'cd /root/.config/oxidized/devices.git && git push -f -q /root/.config/oxidized/devices.git master'
Posted in LibreNMS and tagged , , .

Leave a Reply

Your email address will not be published. Required fields are marked *