Oxidized

Oxidized is a network device configuration backup tool. It's a RANCID replacement!

It is light and extensible and supports over 130 operating system types.

Feature highlights:

• Automatically adds/removes threads to meet configured retrieval interval
• Restful API to a move node immediately to head-of-queue (GET/PUT /node/next/[NODE])
• Syslog udp+file example to catch config change events (IOS/JunOS) and trigger a config fetch
  • Will signal which IOS/JunOS user made the change, can then be used by output modules (via POST)
  • The git output module uses this info - 'git blame' will show who changed each line
• Restful API to reload list of nodes (GET /reload)
• Restful API to fetch configurations (/node/fetch/[NODE] or /node/fetch/group/[NODE])
• Restful API to show list of nodes (GET /nodes)
• Restful API to show list of version for a node (/node/version[NODE]) and diffs

Check out the Oxidized TREX 2014 presentation video on YouTube!

:warning: Maintainer Wanted! :warning:

Is your company using Oxidized and has Ruby developers on staff? I'd love help from an extra maintainer!

Index

1. Supported OS Types
2. Installation
   • Debian and Ubuntu
   • Rocky Linux, Red Hat Enterprise Linux
   • FreeBSD
   • Build from Git
   • Docker & Podman
3. Initial Configuration
4. Configuration
   • Debugging
   • Privileged mode
   • Disabling SSH exec channels
   • Sources
     • Source: CSV
     • Source: SQL
     • Source: SQLite
     • Source: Mysql
     • Source: HTTP
   • Outputs
     • Output: GIT
     • Output: GIT-Crypt
     • Output: HTTP
     • Output: File
     • Output types
   • Advanced Configuration
   • Advanced Group Configuration
   • Hooks
     • Hook: exec
     • Hook: githubrepo
     • Hook: awssns
     • Hook: slackdiff
     • Hook: xmppdiff
     • Hook: ciscosparkdiff
5. Creating and Extending Models
6. Help
7. Help Needed
8. Ruby API
   • Input
   • Output
   • Source
   • Model

Installation

Debian and Ubuntu

Debian 12 "bookworm" or newer and Ubuntu 22.04 (Jammy Jellyfish) or newer are recommended. On Ubuntu, begin by enabling the universe repository (required for libssh2-1-dev):

add-apt-repository universe

Install the dependencies:

apt install ruby ruby-dev libsqlite3-dev libssl-dev pkg-config cmake libssh2-1-dev libicu-dev zlib1g-dev g++ libyaml-dev libzstd-dev

Finally, install Oxidized:

gem install oxidized

You can also install one or both of the optional gems. They are not required to run Oxidized:

gem install oxidized-web    # Web interface and rest API
gem install oxidized-script # Script-based input/output extensions

Rocky Linux, Red Hat Enterprise Linux

These instructions has been verified on Rocky Linux 9, Rocky Linux 10 and Fedora.

On Rocky Linux 9, you need to install/enable EPEL, CRB and Ruby 3.1:

dnf install epel-release
dnf config-manager --set-enabled crb
dnf module enable ruby:3.1

Then you need the required packages for oxidized:

dnf -y install ruby ruby-devel sqlite-devel openssl-devel pkgconf-pkg-config  cmake libssh-devel libicu-devel zlib-devel gcc-c++ libyaml-devel which

Finally, install Oxidized:

gem install oxidized

You can also install one or both of the optional gems. They are not required to run Oxidized:

gem install oxidized-web    # Web interface and rest API
gem install oxidized-script # Script-based input/output extensions

FreeBSD

:warning: These installation instructions have been tested on FreeBSD 14.2, but oxidized itself has not been tested on it.

First install ruby and rubyXX-gems (Find out the name of the package with pkg search gems):

pkg instal ruby
pkg instal ruby32-gems

Then install the dependencies of oxidized an oxidized-web:

pkg install ruby ruby-gems git sqlite3 libssh2 cmake pkgconf gmake
pkg install libyaml icu   # Dependencies for oxidized-web

Finally, install Oxidized:

gem install oxidized

You can also install one or both of the optional gems. They are not required to run Oxidized:

gem install oxidized-web    # Web interface and rest API
gem install oxidized-script # Script-based input/output extensions

Oxidized is also available via FreeBSD ports:

pkg install rubygem-oxidized rubygem-oxidized-script rubygem-oxidized-web

Build from Git

git clone https://github.com/ytti/oxidized.git
cd oxidized/
gem install bundler
rake install

Running with Docker or Podman

See docs/Docker.md

Configuration

Oxidized configuration is in YAML format. Configuration files are subsequently sourced from /etc/oxidized/config then ~/.config/oxidized/config. The hashes will be merged, this might be useful for storing source information in a system wide file and user specific configuration in the home directory (to only include a staff specific username and password). Eg. if many users are using oxs, see Oxidized::Script.

It is recommended practice to run Oxidized using its own username. This username can be added using standard command-line tools:

useradd -s /bin/bash -m oxidized

It is recommended not to run Oxidized as root. After creating a dedicated user, switch to the oxidized user using su oxidized to ensure that Oxidized is run under the correct user context.

To initialize a default configuration in your home directory ~/.config/oxidized/config, simply run oxidized once. If you don't further configure anything from the output and source sections, it'll extend the examples on a subsequent oxidized execution. This is useful to see what options for a specific source or output backend are available.

You can set the env variable OXIDIZED_HOME to change its home directory.

OXIDIZED_HOME=/etc/oxidized

$ tree -L 1 /etc/oxidized
/etc/oxidized/
├── config
├── log-router-ssh
├── log-router-telnet
├── pid
├── router.db
└── repository.git

Source

Oxidized supports CSV, SQLite, MySQL and HTTP as source backends. The CSV backend reads nodes from a rancid compatible router.db file. The SQLite and MySQL backends will fire queries against a database and map certain fields to model items. The HTTP backend will fire queries against a http/https url. Take a look at the Configuration for more details.

Outputs

Possible outputs are either File, GIT, GIT-Crypt and HTTP. The file backend takes a destination directory as argument and will keep a file per device, with most recent running version of a device. The GIT backend (recommended) will initialize an empty GIT repository in the specified path and create a new commit on every configuration change. The GIT-Crypt backend will also initialize a GIT repository but every configuration push to it will be encrypted on the fly by using git-crypt tool. Take a look at the Configuration for more details.

Maps define how to map a model's fields to model model fields. Most of the settings should be self explanatory, log is ignored if use_syslog is set to true.

First create the directory where the CSV output is going to store device configs and start Oxidized once.

mkdir -p ~/.config/oxidized/configs
oxidized

Now tell Oxidized where it finds a list of network devices to backup configuration from. You can either use CSV or SQLite as source. To create a CSV source add the following snippet:

source:
  default: csv
  csv:
    file: ~/.config/oxidized/router.db
    delimiter: !ruby/regexp /:/
    map:
      name: 0
      model: 1

Now lets create a file based device database (you might want to switch to SQLite later on). Put your routers in `~/.config/oxidize