How to Install and Configure Oxidized Backup Tool Using Docker Step-by-Step

Introduction

Network devices are the foundation of modern IT infrastructure. Routers, switches, firewalls, wireless controllers, load balancers, and security appliances all rely on configuration files that define how they operate. Losing these configurations due to hardware failure, accidental changes, security incidents, or operational mistakes can result in significant downtime and lengthy recovery efforts.

This is why automated network configuration backup solutions have become an essential component of network operations, disaster recovery planning, compliance initiatives, and configuration management strategies.

Among the available tools, Oxidized has emerged as one of the most popular open-source network configuration backup platforms. Designed as a modern replacement for legacy solutions such as RANCID, Oxidized automates the collection, versioning, and tracking of network device configurations while supporting a wide range of vendors including Cisco, Juniper, Arista, Fortinet, Palo Alto Networks, MikroTik, and many others.

Running Oxidized in Docker further simplifies deployment by providing portability, consistency, easier upgrades, and streamlined management. Instead of manually installing dependencies and maintaining application environments, administrators can deploy Oxidized within a containerized environment and begin backing up devices within minutes.

In this comprehensive guide, you’ll learn how to install and configure Oxidized using Docker, understand its architecture, prepare a production-ready environment, and establish the foundation for automated network configuration backups.

What Is Oxidized?

Quick Definition

Oxidized is an open-source network configuration backup and change-tracking platform that automatically connects to network devices using protocols such as SSH and Telnet, retrieves their running configurations, stores them in a version-controlled repository, and provides visibility into configuration changes over time.

Unlike manual backup methods, Oxidized continuously monitors devices and creates configuration snapshots automatically.

Why Network Configuration Backups Matter

Network devices contain critical operational information, including:

• Routing protocols
• VLAN assignments
• Firewall rules
• Access control lists (ACLs)
• VPN settings
• Interface configurations
• Security policies
• Quality of Service (QoS) configurations

Without regular backups, organizations face several risks:

Risk	Impact
Hardware failure	Complete loss of configuration
Human error	Accidental deletion of settings
Unauthorized changes	Security and compliance issues
Failed upgrades	Difficult rollback process
Disaster recovery events	Extended downtime

Automated backups significantly reduce these risks by maintaining a continuously updated repository of device configurations.

How Oxidized Works

At its core, Oxidized follows a simple workflow:

1. Retrieve device inventory.
2. Connect to devices using SSH or Telnet.
3. Execute vendor-specific commands.
4. Collect configuration output.
5. Process and normalize configuration data.
6. Save configurations to storage.
7. Track changes through Git version control.
8. Display backup status through a web interface.

The process runs automatically based on configurable polling intervals.

Key Features of Oxidized

Feature	Description
Automated Backups	Scheduled configuration retrieval
Multi-Vendor Support	Supports hundreds of device models
Git Integration	Tracks configuration history
Web Interface	Provides visibility into backups
Docker Support	Simplifies deployment
REST API	Enables automation workflows
SSH & Telnet Support	Flexible connectivity options
Change Tracking	Detects configuration modifications
Open Source	No licensing costs

Why Oxidized Replaced RANCID for Many Organizations

Historically, many organizations used RANCID (Really Awesome New Cisco Configuration Differ) for network backups.

While RANCID remains functional, Oxidized introduced several improvements.

Feature	Oxidized	RANCID
Modern Architecture	Yes	Limited
REST API	Yes	No
Docker Deployment	Easy	Manual
Git Integration	Native	Limited
Web Interface	Built-in	External
Vendor Support	Extensive	Extensive
Community Development	Active	Moderate
Configuration Tracking	Advanced	Basic

For organizations adopting network automation and Infrastructure as Code principles, Oxidized often aligns better with modern operational practices.

Supported Network Vendors

One of Oxidized’s strongest advantages is broad vendor compatibility.

Commonly supported platforms include:

Vendor	Operating System
Cisco	IOS
Cisco	IOS-XE
Cisco	NX-OS
Cisco	ASA
Cisco	IOS-XR
Juniper	JunOS
Arista	EOS
Fortinet	FortiOS
Palo Alto Networks	PAN-OS
MikroTik	RouterOS
Dell	OS10
HPE	Comware
Extreme Networks	EXOS

This broad compatibility makes Oxidized suitable for heterogeneous enterprise environments.

Oxidized Architecture Overview

Before deployment, it is important to understand the major components.

Core Components

Component	Function
Oxidized Engine	Main backup service
Device Source	Inventory provider
Input Module	SSH/Telnet connectivity
Model Library	Vendor-specific commands
Output Module	Storage backend
Git Repository	Version tracking
Web Interface	Monitoring and access
Docker Container	Runtime environment

Backup Lifecycle

Stage	Description
Discovery	Device inventory loaded
Authentication	Login to device
Collection	Execute backup commands
Processing	Normalize output
Storage	Save configuration
Versioning	Commit changes to Git
Monitoring	Display status

This architecture enables scalable and reliable network configuration management.

Benefits of Running Oxidized in Docker

Why Use Docker Instead of Native Installation?

Although Oxidized can be installed directly on Linux, Docker offers several operational advantages.

Organizations increasingly standardize applications using containers because they simplify deployment, upgrades, portability, and maintenance.

Portability

A Docker container packages:

• Oxidized application
• Dependencies
• Runtime environment
• Configuration structure

As a result, deployments behave consistently across:

• Ubuntu
• Debian
• Rocky Linux
• AlmaLinux
• Virtual Machines
• Cloud Instances
• On-Premises Servers

This consistency reduces troubleshooting effort and deployment variability.

Simplified Deployment

Traditional installations often require:

• Ruby dependencies
• Gem packages
• System libraries
• Manual updates

Docker abstracts these complexities.

Instead of installing numerous packages, administrators can deploy a single container image.

Easier Upgrades

Updating Oxidized natively may involve:

• Package upgrades
• Dependency conflicts
• Service interruptions

Docker upgrades are simpler:

1. Pull latest image.
2. Stop old container.
3. Start new container.
4. Retain persistent data volumes.

This approach minimizes operational risk.

Isolation and Security

Containers isolate applications from the host operating system.

Benefits include:

• Reduced dependency conflicts
• Better resource control
• Simplified rollback procedures
• Improved operational consistency

Infrastructure as Code Compatibility

Docker Compose files can be stored in:

• GitHub
• GitLab
• Bitbucket
• Internal Git repositories

This enables:

• Version-controlled deployments
• Automated rebuilds
• Repeatable infrastructure

Docker Benefits Summary

Benefit	Operational Value
Portability	Consistent deployments
Isolation	Reduced conflicts
Upgrades	Faster maintenance
Automation	CI/CD friendly
Recovery	Faster restoration
Scalability	Easier expansion

Prerequisites Before Installing Oxidized

Proper preparation helps avoid installation issues later.

Hardware Requirements

Oxidized is lightweight compared to many network management platforms.

Recommended baseline:

Environment Size	CPU	RAM	Storage
Lab	1 Core	1 GB	10 GB
Small Business	2 Cores	2 GB	20 GB
Medium Enterprise	4 Cores	4 GB	50 GB
Large Enterprise	8+ Cores	8+ GB	100+ GB

Storage requirements increase when:

• Managing thousands of devices
• Retaining long configuration history
• Storing backups in Git

Software Requirements

The following software should be available:

Component	Version Recommendation
Ubuntu	22.04 LTS or newer
Docker Engine	Latest stable
Docker Compose	Latest stable
Git	Latest stable
OpenSSH	Latest stable

Network Requirements

Oxidized must communicate with devices using management connectivity.

Required access may include:

Protocol	Default Port
SSH	22
Telnet	23
HTTPS	443
SNMP (optional)	161

Best practice is to use SSH whenever possible.

Device Access Requirements

Ensure the backup account has:

• Read-only access where appropriate
• Permission to display running configuration
• Access to required show commands
• SSH connectivity

Typical Cisco commands include:

show running-config
show version

The exact commands vary by vendor model.

Security Best Practices Before Deployment

Before installation:

• Create dedicated backup accounts.
• Use SSH keys whenever possible.
• Restrict management network access.
• Implement role-based access control.
• Protect Git repositories.
• Store secrets securely.

These practices improve operational security and compliance.

Oxidized Deployment Architecture

Understanding deployment architecture simplifies configuration and troubleshooting.

Components Overview

A typical Docker-based deployment contains the following layers.

Layer	Component	Purpose
Infrastructure	Linux Server	Host platform
Container Runtime	Docker Engine	Executes containers
Application	Oxidized	Backup automation
Connectivity	SSH/Telnet	Device communication
Storage	Volumes	Persistent data
Version Control	Git	Change tracking
Monitoring	Web Interface	Operational visibility

Data Flow Workflow

The following sequence illustrates how backups occur.

1. Device inventory is loaded.
2. Oxidized selects a target device.
3. SSH session is established.
4. Authentication is performed.
5. Device-specific commands execute.
6. Configuration output is collected.
7. Output is normalized.
8. Configuration is stored.
9. Git commits changes.
10. Web UI updates status.

This workflow repeats continuously according to configured intervals.

Typical Production Architecture

Component	Example
Host OS	Ubuntu Server 24.04
Container Runtime	Docker Engine
Application Container	Oxidized
Storage Volume	Persistent Docker Volume
Repository	GitHub or GitLab
Monitoring	LibreNMS Integration
Inventory Source	CSV or NetBox

Storage Considerations

Persistent storage is critical.

Important directories include:

Directory	Purpose
Configurations	Device backups
Git Repository	Version history
Logs	Troubleshooting
Configuration Files	Application settings

Without persistent volumes, backups may be lost when containers are recreated.

High Availability Considerations

For larger environments:

• Use redundant storage.
• Back up Git repositories.
• Protect Docker host snapshots.
• Monitor backup success rates.
• Maintain configuration documentation.

These practices support business continuity objectives.

Installing Docker and Docker Compose

Before deploying Oxidized, Docker must be installed.

The examples in this guide use Ubuntu Server.

Update the System

Begin by updating package repositories.

sudo apt update
sudo apt upgrade -y

This ensures the operating system is current.

Install Required Packages

Install supporting dependencies.

sudo apt install -y \
ca-certificates \
curl \
gnupg \
lsb-release

These packages support repository management and secure downloads.

Add Docker Repository Key

Create the keyring directory.

sudo mkdir -p /etc/apt/keyrings

Download Docker’s signing key.

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Add Docker Repository

Add the Docker package source.

echo \
"deb [arch=$(dpkg --print-architecture) \
signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine

Update repositories again.

sudo apt update

Install Docker.

sudo apt install -y docker-ce docker-ce-cli containerd.io

Verify Docker Installation

Check Docker version.

docker --version

Example output:

Docker version 27.x.x

Verify service status.

sudo systemctl status docker

You should see the Docker service running.

Enable Docker at Boot

Ensure Docker starts automatically.

sudo systemctl enable docker

Install Docker Compose Plugin

Install the Compose plugin.

sudo apt install docker-compose-plugin -y

Verify installation.

docker compose version

Expected output resembles:

Docker Compose version v2.x.x

Test Docker Functionality

Run a test container.

sudo docker run hello-world

Successful output confirms Docker is functioning correctly.

Allow Non-Root Docker Usage (Optional)

Add your account to the Docker group.

sudo usermod -aG docker $USER

Apply changes.

newgrp docker

Verify access.

docker ps

You should be able to execute Docker commands without sudo.

Key Takeaways

At this stage, you have learned:

• What Oxidized is and why it is widely used.
• How Oxidized automates network configuration backups.
• The advantages of deploying Oxidized with Docker.
• Hardware, software, and network prerequisites.
• Core Oxidized architecture and workflow.
• Production deployment considerations.
• How to install Docker Engine and Docker Compose on Ubuntu.
• How to verify a container-ready environment.

Creating the Oxidized Project Structure

With Docker and Docker Compose installed, the next step is creating a structured and maintainable project layout for Oxidized. Proper organization makes upgrades, troubleshooting, backups, and Git integration significantly easier.

Why Directory Structure Matters

Many first-time deployments place all files in a single directory. While this may work in a lab environment, it quickly becomes difficult to manage in production.

A well-designed structure provides:

• Easier backups
• Cleaner configuration management
• Simplified upgrades
• Better Git organization
• Faster troubleshooting
• Clear separation of data and application components

Recommended Directory Layout

Create a dedicated project directory:

mkdir -p ~/oxidized-docker
cd ~/oxidized-docker

Create the required subdirectories:

mkdir -p oxidized/config
mkdir -p oxidized/devices
mkdir -p oxidized/output
mkdir -p oxidized/logs
mkdir -p oxidized/git

Recommended structure:

oxidized-docker/
├── docker-compose.yml
├── oxidized/
│   ├── config/
│   ├── devices/
│   ├── output/
│   ├── logs/
│   └── git/

Directory Purpose

Directory	Purpose
config	Oxidized configuration files
devices	Device inventory files
output	Configuration backups
logs	Application logs
git	Git repository storage

Persistent Storage Design

One of the most important considerations when running applications in containers is data persistence.

Containers are designed to be disposable. If a container is removed and no persistent storage exists, all collected configurations may be lost.

Always map the following to persistent volumes:

Data Type	Persist?
Device inventory	Yes
Oxidized configuration	Yes
Backup repository	Yes
Logs	Recommended
Git history	Yes

This approach ensures backups remain intact even after upgrades or container recreation.

Creating the Docker Compose File

Docker Compose simplifies deployment by defining services, storage, networking, and runtime settings in a single file.

Why Docker Compose Is Recommended

Instead of manually starting containers with lengthy commands, Docker Compose allows infrastructure to be managed as code.

Benefits include:

• Reproducibility
• Version control
• Simplified upgrades
• Easier troubleshooting
• Team collaboration

Creating docker-compose.yml

Create the file:

nano docker-compose.yml

Add the following configuration:

services:
  oxidized:
    image: oxidized/oxidized:latest
    container_name: oxidized
    restart: unless-stopped

    ports:
      - "8888:8888"

    volumes:
      - ./oxidized/config:/home/oxidized/.config/oxidized
      - ./oxidized/output:/home/oxidized/output
      - ./oxidized/logs:/home/oxidized/logs

    environment:
      CONFIG_RELOAD_INTERVAL: 600

Save and exit.

Docker Compose Configuration Breakdown

Image

image: oxidized/oxidized:latest

Specifies the Oxidized container image.

Container Name

container_name: oxidized

Provides predictable container identification.

Restart Policy

restart: unless-stopped

Automatically restarts Oxidized after:

• Host reboot
• Service interruption
• Container crash

Port Mapping

ports:
  - "8888:8888"

Exposes the Oxidized web interface.

Volumes

volumes:

Mounts persistent data locations from the host.

Production Compose Enhancements

For enterprise environments, consider:

Setting	Purpose
Resource Limits	Prevent excessive CPU usage
Dedicated Networks	Improve isolation
Read-Only Filesystems	Enhance security
Logging Drivers	Centralized logging
Health Checks	Improve monitoring

A production-ready deployment should evolve as operational requirements grow.

Configuring Oxidized

After creating the deployment structure, the next step is configuring Oxidized itself.

Generate Initial Configuration

Start the container temporarily:

docker compose up -d

Access the container:

docker exec -it oxidized bash

Generate a default configuration:

oxidized

The default configuration file will be created inside:

/home/oxidized/.config/oxidized/config

Exit the container:

exit

Understanding the Oxidized Configuration File

The configuration file controls:

• Device sources
• Authentication
• Storage methods
• Polling intervals
• Logging
• Web interface settings

A simplified example:

---
username: backupuser
password: StrongPassword

model: ios

interval: 3600

use_syslog: false

threads: 10

timeout: 20

retries: 3

rest: 0.0.0.0:8888

Core Parameters Explained

Parameter	Purpose
username	Login account
password	Device password
model	Device platform
interval	Backup frequency
timeout	Connection timeout
retries	Retry attempts
threads	Parallel connections
rest	Web interface binding

Backup Interval Best Practices

Environment	Recommended Interval
Lab	1 Hour
Small Business	4 Hours
Enterprise	12 Hours
Compliance-Driven	1 Hour

Excessively aggressive polling can generate unnecessary load.

Configuring Sources

A source defines where Oxidized obtains its device inventory.

Supported source types include:

• CSV
• SQLite
• HTTP
• LibreNMS
• NetBox
• SQL Databases

For simplicity, this guide starts with CSV.

Configure CSV Source

Add the following section:

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

How CSV Source Works

Oxidized reads device information from a text file.

Each line represents:

hostname:model

Example:

R1:ios
R2:ios
SW1:nxos
FW1:asa

This method is simple and reliable for small and medium environments.

Configuring Outputs

Outputs determine where collected configurations are stored.

File-Based Output

Most deployments begin with file output.

output:
  default: file
  file:
    directory: /home/oxidized/output

Benefits:

• Simplicity
• Easy troubleshooting
• Local storage

Git Output

For production environments, Git is strongly recommended.

Example:

output:
  default: git
  git:
    user: Oxidized
    email: oxidized@example.com
    repo: /home/oxidized/output/configs.git

Benefits include:

• Version tracking
• Historical analysis
• Rollback capability
• Compliance reporting

We will implement Git fully later in this guide.

Configuring Authentication

Authentication is critical because Oxidized must access network devices automatically.

Username and Password Authentication

Basic configuration:

username: backupuser
password: StrongPassword

This approach works but has limitations.

SSH Key Authentication

For production deployments, SSH keys are preferred.

Benefits:

• Improved security
• Reduced password exposure
• Better compliance alignment
• Easier credential rotation

SSH keys are covered in detail later in the guide.

Per-Device Credentials

Large environments may require unique credentials per device group.

Examples include:

• Core routers
• Data center switches
• Firewalls
• Customer-managed devices

This can be implemented through advanced source integrations.

Configuring Git Repository Support

One of Oxidized’s most valuable capabilities is Git integration.

Why Git Matters

Without Git:

• Only current backups exist
• Historical visibility is limited

With Git:

• Every change is tracked
• Configuration drift is visible
• Rollbacks become easier
• Auditing improves significantly

Git Workflow

Oxidized performs:

1. Backup collection
2. Change detection
3. Git commit
4. History retention

This effectively creates a configuration timeline.

Example Git Output Configuration

output:
  default: git

  git:
    user: Oxidized
    email: oxidized@example.com
    repo: /home/oxidized/output/configs.git

Each configuration update generates a commit when changes are detected.

Adding Network Devices to Oxidized

Now that the source configuration exists, devices must be added.

Create router.db

Create the inventory file:

nano oxidized/config/router.db

Add sample devices:

core-rtr01:ios
edge-rtr01:ios
dc-sw01:nxos
branch-fw01:asa

Save the file.

Device Inventory Fields

At minimum:

Field	Purpose
Hostname	Device address
Model	Vendor platform

Advanced inventories may include:

Additional Field	Purpose
Username	Override credentials
Password	Device-specific login
Group	Device categorization
Port	Custom SSH port

Cisco Router Example

Example inventory:

10.10.10.1:ios

Model:

model: ios

Oxidized automatically executes Cisco IOS-specific commands.

Cisco Nexus Example

10.10.20.1:nxos

Oxidized loads NX-OS commands automatically.

Cisco ASA Example

10.10.30.1:asa

Firewall configurations are collected using ASA-specific logic.

Multi-Vendor Inventory Example

10.10.10.1:ios
10.10.20.1:nxos
10.10.30.1:asa
10.10.40.1:junos
10.10.50.1:eos
10.10.60.1:fortios

This demonstrates the flexibility of Oxidized in heterogeneous environments.

Starting the Oxidized Container

After configuration is complete, launch the service.

Start Deployment

docker compose up -d

Verify:

docker ps

Expected output:

CONTAINER ID
oxidized
Up

Check Logs

Review startup logs:

docker logs -f oxidized

Look for:

• Successful startup
• Device inventory loading
• SSH connections
• Backup operations

Common Startup Messages

Message	Meaning
Configuration Loaded	Success
Node Added	Inventory recognized
Configuration Saved	Backup completed
Git Commit Created	Version tracked

Logs provide immediate visibility into deployment health.

Verifying Container Health

Check Running Status

docker inspect oxidized

Verify:

State: Running

Resource Monitoring

Monitor resource consumption:

docker stats oxidized

Useful metrics include:

• CPU
• Memory
• Network activity
• Disk I/O

Restart Testing

Test restart behavior:

docker restart oxidized

Verify data remains intact.

This confirms persistent storage is functioning correctly.

Accessing the Oxidized Web Interface

The built-in web interface provides operational visibility.

Open the Dashboard

Navigate to:

http://SERVER-IP:8888

Example:

http://192.168.1.100:8888

Dashboard Functions

The web interface displays:

• Device inventory
• Backup status
• Configuration history
• Recent activity
• Device models

Why the Web Interface Matters

Benefits include:

• Quick verification
• Operational visibility
• Troubleshooting assistance
• Backup confirmation

Many administrators use the dashboard as their primary operational view.

Verifying Successful Backups

After initial polling completes:

1. Open the dashboard.
2. Select a device.
3. View collected configuration.
4. Verify command output.
5. Confirm latest backup timestamp.

Successful retrieval confirms:

• Connectivity
• Authentication
• Model mapping
• Storage functionality

Understanding Backup Operations

Before moving into advanced integrations and production hardening, it is important to understand how Oxidized performs ongoing backups.

Polling Mechanism

Oxidized continuously cycles through devices according to the configured interval.

Example:

interval: 3600

This instructs Oxidized to poll devices every hour.

Configuration Collection Process

For each device:

1. Establish SSH connection.
2. Authenticate.
3. Execute model-specific commands.
4. Capture output.
5. Normalize configuration.
6. Compare with previous version.
7. Save changes.
8. Commit to Git if modified.

Change Detection

Oxidized avoids unnecessary storage growth.

If no configuration changes occur:

• No new commit is created.
• Existing backup remains valid.

If changes are detected:

• New backup generated.
• Git commit created.
• Historical version retained.

Configuration History Benefits

Organizations gain:

• Change visibility
• Rollback capability
• Compliance evidence
• Audit support
• Troubleshooting context

These capabilities are among the primary reasons engineers adopt Oxidized over manual backup methods.

Key Takeaways

At this point, you have:

• Built a production-ready project structure.
• Created a Docker Compose deployment.
• Configured Oxidized settings.
• Configured device inventory sources.
• Added network devices.
• Started and verified the container.
• Accessed the web interface.
• Understood backup workflows.
• Enabled the foundation for Git-based version control.

Configuring Git Version Control

One of the biggest advantages of Oxidized is its native integration with Git. While storing configuration files locally provides backup protection, Git transforms Oxidized into a complete configuration management and change-tracking platform.

Why Git Integration Matters

Network environments constantly change due to:

• Maintenance activities
• Security updates
• Routing modifications
• VLAN additions
• Firewall rule updates
• Infrastructure upgrades

Without version control, identifying who changed what and when becomes difficult.

Git provides:

Benefit	Description
Change Tracking	Tracks configuration modifications
Rollback Capability	Restore previous versions
Audit History	Review historical changes
Compliance Support	Demonstrate configuration control
Collaboration	Multiple administrators can review changes

Initializing a Local Git Repository

Access the Oxidized container:

docker exec -it oxidized bash

Navigate to the output directory:

cd /home/oxidized/output

Initialize Git:

git init

Verify:

git status

Oxidized will automatically create commits whenever configuration changes are detected.

GitHub Integration

Many organizations store configuration backups in private GitHub repositories.

Create a repository in GitHub and configure remote access:

git remote add origin git@github.com:organization/network-backups.git

Verify:

git remote -v

Push configurations:

git push -u origin main

GitLab Integration

GitLab provides similar functionality.

Example:

git remote add origin git@gitlab.com:organization/network-backups.git

Benefits include:

• Private repositories
• CI/CD pipelines
• Merge requests
• Access controls
• Self-hosted options

Viewing Configuration History

Useful Git commands:

View commit history:

git log

Compare changes:

git diff

View specific commit:

git show COMMIT_ID

These capabilities make troubleshooting configuration drift significantly easier.

Integrating Oxidized with LibreNMS

Many organizations already use LibreNMS for monitoring. Integrating Oxidized allows device inventory to be automatically synchronized.

Benefits of LibreNMS Integration

Benefit	Value
Dynamic Inventory	Automatically imports devices
Reduced Manual Work	No duplicate inventory management
Centralized Operations	Monitoring and backups work together
Scalability	Supports large environments

Integration Workflow

1. LibreNMS discovers devices.
2. Oxidized retrieves inventory.
3. Device information is synchronized.
4. Backups begin automatically.
5. Configuration changes are tracked.

Example LibreNMS Source Configuration

source:
  default: http

  http:
    url: https://librenms.example.com/api/v0/oxidized
    scheme: https

Operational Advantages

Using LibreNMS as a source eliminates the need to maintain:

• CSV files
• Manual inventory lists
• Duplicate device records

This improves operational efficiency and reduces administrative overhead.

Integrating Oxidized with NetBox

NetBox has become one of the most popular sources of truth for network infrastructure.

Combining NetBox with Oxidized creates a highly automated network management workflow.

Why Integrate with NetBox?

NetBox stores:

• Devices
• Interfaces
• Sites
• IP addresses
• Racks
• Roles
• Platforms

Oxidized can leverage this inventory automatically.

Integration Benefits

Feature	Benefit
Dynamic Inventory	Automatic device updates
Single Source of Truth	Consistent infrastructure data
Reduced Errors	Less manual entry
Automation Friendly	Supports Infrastructure as Code

Example Workflow

1. Device added to NetBox.
2. NetBox inventory updates.
3. Oxidized discovers device.
4. Backup process begins.
5. Configuration history tracked.

This creates a modern network automation ecosystem.

Securing Oxidized in Production

Security should never be an afterthought.

Because Oxidized stores network configurations and device credentials, hardening is critical.

SSH Key Authentication

SSH keys are strongly recommended over passwords.

Generate a key pair:

ssh-keygen -t ed25519

Copy public key to devices:

ssh-copy-id backupuser@router-ip

Benefits include:

• Stronger security
• Reduced credential exposure
• Easier automation
• Better compliance alignment

Credential Protection

Avoid:

• Shared accounts
• Hardcoded passwords
• Weak passwords
• Excessive privileges

Instead:

Best Practice	Purpose
Dedicated Backup Accounts	Accountability
Strong Passwords	Security
SSH Keys	Improved Authentication
Role-Based Access	Least Privilege

Docker Security Best Practices

Production deployments should include:

• Updated images
• Minimal exposed ports
• Regular vulnerability scans
• Secure volume permissions
• Non-root execution where possible

Network Segmentation

Place Oxidized in a dedicated management network.

Benefits:

• Reduced attack surface
• Improved access control
• Better monitoring visibility

Repository Security

Protect Git repositories using:

• Private repositories
• MFA
• Access control policies
• Audit logging

Network configurations often contain sensitive operational information.

Monitoring and Logging

Operational visibility is essential for long-term reliability.

Log Analysis

View logs:

docker logs oxidized

Follow logs in real time:

docker logs -f oxidized

Common Log Events

Event	Meaning
Node Added	Device recognized
Connection Established	Authentication successful
Config Saved	Backup completed
Git Commit Created	Change tracked
Timeout Error	Connectivity issue

Health Monitoring

Important metrics include:

Metric	Why It Matters
Backup Success Rate	Operational reliability
Failed Devices	Problem identification
Authentication Failures	Security visibility
Polling Duration	Performance monitoring
Storage Growth	Capacity planning

Backup Validation

Do not assume backups are valid.

Regularly verify:

1. Device configurations exist.
2. Files are readable.
3. Git commits are being generated.
4. Inventory synchronization works.
5. Recent changes appear correctly.

Validation should be part of operational procedures.

Common Oxidized Issues and Troubleshooting

Even well-designed deployments encounter occasional problems.

Authentication Failures

Common causes:

• Incorrect credentials
• Expired passwords
• SSH key issues
• Access restrictions

Troubleshooting steps:

ssh backupuser@device-ip

Verify manual login succeeds before troubleshooting Oxidized.

SSH Timeout Errors

Possible causes:

• Firewall restrictions
• Routing issues
• ACLs
• Device load

Verify connectivity:

ping DEVICE_IP

Test SSH:

ssh DEVICE_IP

Device Model Issues

Symptoms:

• Empty backups
• Incomplete configurations
• Command failures

Verify:

router.db

contains the correct model identifier.

Example:

10.10.10.1:ios

instead of:

10.10.10.1:cisco

Docker Permission Problems

Symptoms:

• Missing files
• Volume mount failures
• Startup issues

Verify permissions:

ls -la

Correct ownership if necessary.

Git Synchronization Failures

Possible causes:

• Authentication problems
• Incorrect repository URL
• Network restrictions

Verify:

git remote -v

Test connectivity manually.

Troubleshooting Matrix

Problem	Likely Cause	Solution
Login Failed	Incorrect Credentials	Verify Account
SSH Timeout	Connectivity Issue	Check Network
Empty Config	Wrong Model	Correct Model Mapping
No Git Commits	Output Configuration	Verify Git Settings
Container Stops	Docker Error	Review Logs

Oxidized Best Practices

Successful deployments share several characteristics.

Use Dedicated Backup Accounts

Avoid using administrator accounts.

Benefits:

• Better accountability
• Reduced risk
• Easier auditing

Implement Git from Day One

Organizations frequently delay Git integration and later regret it.

Version control should be enabled immediately.

Group Devices Logically

Examples:

• Core
• Distribution
• Access
• Firewalls
• Data Center

Grouping improves scalability and management.

Monitor Backup Success Rates

Regularly review:

• Failed devices
• Authentication issues
• Configuration changes

Do not wait until an outage occurs.

Secure Configuration Data

Treat backups as sensitive information.

Protect:

• Device credentials
• VPN settings
• Security policies
• Infrastructure details

Regularly Test Recovery Procedures

A backup strategy is incomplete without recovery testing.

Validate that configurations can be restored when needed.

Scaling Oxidized for Enterprise Environments

As environments grow, planning becomes increasingly important.

Small Environment

Typical characteristics:

Metric	Value
Devices	Under 100
Threads	5–10
Polling Interval	1–4 Hours

Medium Environment

Metric	Value
Devices	100–1000
Threads	20–50
Polling Interval	4–12 Hours

Large Enterprise

Metric	Value
Devices	1000+
Threads	50+
Dedicated Storage	Recommended
Monitoring Integration	Required

Enterprise Recommendations

• Use NetBox inventory.
• Integrate monitoring.
• Protect repositories.
• Enable centralized logging.
• Implement backup validation.

These practices improve reliability at scale.

Oxidized vs RANCID

Many network engineers evaluate Oxidized against RANCID.

Feature Comparison

Feature	Oxidized	RANCID
Open Source	Yes	Yes
Git Support	Native	Limited
Docker Support	Excellent	Limited
REST API	Yes	No
Web Interface	Built-In	External
Modern Development	Active	Less Active
Automation Friendly	High	Moderate

Operational Comparison

Category	Oxidized	RANCID
Deployment Simplicity	Easier
Container Support	Native
Inventory Integration	Extensive
Network Automation Compatibility	Excellent

Which One Should You Choose?

For most modern environments:

• Oxidized is the preferred option.
• Docker simplifies deployment.
• Git integration improves visibility.
• API support enables automation.

RANCID remains functional but is often chosen only in legacy environments.

Frequently Asked Questions

What is Oxidized used for?

Oxidized is used to automatically back up network device configurations, track changes, and maintain version-controlled configuration history.

Is Oxidized free?

Yes. Oxidized is an open-source project and can be used without licensing costs.

Can Oxidized run in Docker?

Yes. Docker is one of the most popular deployment methods because it simplifies installation, upgrades, and maintenance.

Does Oxidized support Cisco devices?

Yes. Oxidized supports Cisco IOS, IOS-XE, NX-OS, ASA, IOS-XR, and many other platforms.

How often does Oxidized perform backups?

Backup frequency depends on the configured polling interval. Common intervals range from one hour to twelve hours.

Does Oxidized support Git?

Yes. Native Git integration is one of its most valuable features.

Can Oxidized integrate with LibreNMS?

Yes. LibreNMS can serve as an inventory source and automatically synchronize device information.

Can Oxidized integrate with NetBox?

Yes. NetBox integration enables dynamic inventory management and source-of-truth workflows.

Is SSH recommended over Telnet?

Yes. SSH provides encryption and significantly better security.

Is Oxidized suitable for enterprise environments?

Absolutely. Many enterprises use Oxidized to manage hundreds or thousands of network devices.

Final Thoughts

Network configuration backups are no longer optional. Modern networks require automated, reliable, and auditable backup processes to support operational resilience, security, compliance, and disaster recovery.

Oxidized has become one of the leading open-source solutions for network configuration management because it combines broad vendor support, Git-based version control, automation capabilities, API access, and straightforward deployment models.

Running Oxidized in Docker further enhances operational efficiency by providing portability, simplified upgrades, predictable deployments, and easier maintenance. When integrated with tools such as GitHub, GitLab, LibreNMS, and NetBox, Oxidized becomes a powerful component of a modern network automation strategy.

Whether you manage a small lab, a growing enterprise network, or a large-scale service provider environment, implementing Oxidized provides visibility into configuration changes, strengthens disaster recovery readiness, and helps establish configuration management best practices across the organization.

By following the steps in this guide, you now have the knowledge required to deploy, configure, secure, monitor, and scale Oxidized using Docker in a production-ready environment.

Key Takeaways

• Oxidized automates network configuration backups.
• Docker simplifies deployment and lifecycle management.
• Git integration provides configuration version control.
• SSH should be preferred over Telnet.
• LibreNMS and NetBox integrations improve automation.
• Security hardening is essential for production deployments.
• Monitoring and backup validation should be ongoing processes.
• Oxidized is a modern alternative to RANCID.
• The platform scales effectively from labs to enterprise environments.
• Automated configuration management significantly improves operational resilience and disaster recovery readiness.