Sign in Subscribe

Setting Up Oxidized for Router Backups with Docker Compose and Git

Last updated on 

In today’s increasingly complex networking environment, regular backups of router configurations are critical. Whether you're managing a small home network or a large enterprise setup, having an automated solution for backing up router configurations can save you time and headaches. Enter Oxidized, an open-source router backup tool that supports a variety of networking devices and stores configurations using version control.

In this guide, we’ll walk you through how to deploy Oxidized using Docker Compose, making it easy to set up and maintain. We’ll use Git as the backend for storing the configurations, ensuring you can version-control and track your router backups.

Why Use Docker Compose for Oxidized?

Using Docker Compose makes setting up Oxidized a breeze. It simplifies dependencies, reduces configuration complexity, and allows you to manage the deployment with a single docker-compose.yml file. This method also ensures compatibility across systems and provides an easy way to scale or update your setup without worrying about conflicting dependencies.

With Docker Compose, you’ll have Oxidized running in isolated containers, while you manage router backups through Git, all without needing to manually install Oxidized on your Raspberry Pi or another host.

Gear List for Your Oxidized Setup

Before diving into the installation process, let’s go over the essential gear you’ll need for this setup.

1. Router Compatible with Oxidized

Oxidized supports a wide variety of routers that can be managed over SSH or Telnet. Popular models include:

  • Cisco Routers: Oxidized supports Cisco devices with IOS, including ASA firewalls.
  • Juniper Routers: For networks running Junos OS.
  • Arista Routers: Ideal for data centers or large-scale networks.
  • Ubiquiti EdgeRouters: A solid option for small to medium-sized networks or home labs.

Recommendation: The Ubiquiti EdgeRouter is a great choice for small to medium setups and home labs. It's affordable and offers great flexibility.

2. Raspberry Pi with SSD for Running Oxidized

The Raspberry Pi is a perfect host for running Oxidized. It’s affordable, low-power, and versatile. To ensure smooth operation and reliable storage, it’s recommended to use an SSD over an SD card.

  • Raspberry Pi 4 Model B (4GB RAM): Offers plenty of power for running Oxidized and other services.
  • SSD (at least 120GB): For fast and reliable storage.

Recommendation: The Raspberry Pi 4 (4GB) paired with a Kingston A400 120GB SSD is a solid, budget-friendly setup for your Oxidized deployment.

3. GitHub or GitLab Account for Storing Backups

Since Oxidized will store your router configurations in a Git repository, you need a GitHub or GitLab account for hosting the backups. Using Git allows you to track changes, manage versions, and restore previous configurations as needed.

Recommendation: Set up a private repository on GitHub or GitLab to securely store and manage your backups.

Deploying Oxidized with Docker Compose

Now that you have the gear ready, let’s dive into deploying Oxidized using Docker Compose. This method simplifies the installation process, making it much easier to manage and deploy on a Raspberry Pi or any other host system.

Step 1: Install Docker and Docker Compose

If you haven't already installed Docker and Docker Compose on your Raspberry Pi or host system, here’s how to do it:

  1. Install Docker: curl -sSL https://get.docker.com | sh
  2. Install Docker Compose:
sudo apt install -y python3-pip
sudo pip3 install docker-compose

Step 2: Create Docker Compose Configuration

Next, you need to set up the Docker Compose configuration. This will define the Oxidized container, configure Git as the backend for backups, and make sure everything runs smoothly.

  1. Create a directory for your Oxidized setup:
adduser oxidized # set the UID and GID to 30000
mkdir ~oxidized/oxidized-docker
cd ~oxidized/oxidized-docker
  1. Create the docker-compose.yml file:
---
services:
  oxidized:
    image: oxidized/oxidized:latest
    container_name: oxidized
    environment:
      # Reload hosts list once per hour
      CONFIG_RELOAD_INTERVAL: 3600
    volumes:
      - /home/oxidized/oxidized-docker/config/config:/home/oxidized/.config
      - /home/oxidized/oxidized-docker:/home/oxidized/oxidized-docker:rw
    ports:
      - 8888:8888
    restart: unless-stopped


In this configuration:

    • The Oxidized container is based on the official oxidized/oxidized image.
    • The volumes section mounts local directories for configuration, backups, and logs, ensuring persistence across container restarts.

Step 3: Configure Oxidized

Now, let’s configure Oxidized to connect to your router and fetch its configuration. We need to modify Oxidized’s configuration to tell it which routers to back up.

  1. Create the Oxidized config directory: mkdir -p ~oxidized/oxidized-docker/config
  2. Create or modify the Oxidized configuration file at ~oxidized/oxidized-docker/config/config:
  3. Save and close the file. This configuration tells Oxidized to:
    • Use Git for storing backups.
    • Back up a Ubiquiti EdgeRouter (you can modify this section to support other devices).
    • Expose a web UI on port 8888 for easy access to the logs and configurations.
---
username: username
password: password
model: junos
resolve_dns: true
interval: 600
use_syslog: true
debug: true
threads: 30
timeout: 20
retries: 3
prompt: !ruby/regexp /^([\w.@-]+[#>]\s?)$/
rest: 0.0.0.0:8888
next_adds_job: true
vars: {}
groups: {}
models: {}
use_syslog: true
log: "/home/oxidized/oxidized-docker/config/oxidized/logs/"
pid: "/home/oxidized/oxidized-docker/config/oxidized/pid"
crash:
  directory: "/home/oxidized/oxidized-docker/config/oxidized/crashes"
  hostnames: false
stats:
  history_size: 10
input:
  default: ssh, telnet
  debug: false
  ssh:
    secure: false
  ftp:
    passive: true
  utf8_encoded: true
output:
  default: git
  clean_obsolete_nodes: true
  git:
    single_repo: true
    user: <your git username>
    email: <your git email address>
    repo: "/home/oxidized/oxidized/routerconfigs.git"
    enabled: true
    auto_commit: true
hooks:
  push_to_remote:
    type: githubrepo
    events: [post_store]
    remote_repo: https://<your git repo>/routerconfigs.git # You will need to change routerconfigs.git here and above
    username: <your git username>
    password: <your git password>
source:
# Enable this as the source and comment csv for librenms to populate oxidized!
#        default: http
#        debug: false
#        http:
#          url: http://<your librenms IP>/api/v0/oxidized
#          map:
#            name: hostname
#            model: os
#            group: os
#            username: <librenms username>
#          headers:
#            X-Auth-Token: '<librenms bearer>'
  default: csv
  csv:
    file: "/home/oxidized/oxidized-docker/router.db"
    delimiter: !ruby/regexp /:/
    map:
      name: 0
      model: 1
      username: 2
      password: 3
    vars_map:
      enable: 4
    gpg: false

model_map:
  juniper: junos
  cisco: ios
groups:
  ios:
    username: <cisco username>
    password: <cisco password>
    vars:
      enable: <cisco enable>
#      ssh_kex: diffie-hellman-group1-sha1
#      ssh_hamc: aes128-cbc
    model: cisco
  iosxe:
    username: <cisco iosxe username>
    password: <cisco iosxe password>
    vars:
      enable: <cisco iosxe enable>
    model: cisco
  junos:
    username: <juniper username>
    password: <juniper password>
    model: juniper
  ubnt:
    username: <ubnt username>
    password: <ubnt password>

Step 4: Create a routerdb file

You will need to create a text file containing the following (but populated with your router(s) details:

<ip>:<model>:<username>:<password>:<enable>::

Alternatively, you could enable the lines of config for Librenms to populate oxidized for you. This would allow for a totally hands off backup system.

Step 5: Start Oxidized with Docker Compose

With everything set up, it’s time to bring up the Oxidized container using Docker Compose.

  1. From the ~/oxidized-docker directory, run:docker-compose up -d
  2. The container will start in detached mode, and Oxidized will begin backing up your router configurations automatically.

Step 6: Access the Web UI (Optional)

If you enabled the web interface, you can now access it via http://<RaspberryPi_IP>:8888 to view logs and router configurations.

Conclusion

Setting up Oxidized using Docker Compose is an easy and efficient way to automate router backups and version control using Git. With this setup, you’ll be able to regularly back up your router configurations and restore them when needed—all while keeping your setup isolated in Docker containers for easy management and scalability.

Gear List Recap:

With Oxidized running in Docker, you’ll have a reliable, automated backup system for your routers, and you can access all your configurations via Git whenever you need them.

If you have any questions or need further assistance with Docker, Oxidized, or anything else, feel free to ask!

About the author

Tim Wilkes is a UK-based security architect with over 15 years of experience in electronics, Linux, and Unix systems administration. Since 2021, he's been designing secure systems for a telecom company while indulging his passions for programming, automation, and 3D printing. Tim shares his projects, tinkering adventures, and tech insights here - partly as a personal log, and partly in the hopes that others will find them useful.

Want to connect or follow along?

LinkedIn: [phpsytems]
Twitter / X: [@timmehwimmy]
Mastodon: [@timmehwimmy@infosec.exchange]


If you've found a post helpful, consider supporting the blog - it's a part-time passion that your support helps keep alive.

⚠️ Disclaimer

This post may contain affiliate links. If you choose to purchase through them, I may earn a small commission at no extra cost to you. I only recommend items and services I’ve personally read or used and found valuable.

As an Amazon Associate I earn from qualifying purchases.