If your monitoring system already notices when a switch reboots, a configuration changes, or an interface flaps, it can tell Oxidized to take a backup at that moment. Oxidized exposes a REST endpoint that moves a node to the front of its backup queue, and both Zabbix and Nagios can call it. Zabbix uses a webhook media type or an action. Nagios uses an event handler. For events monitoring cannot see directly, such as a configuration change on a device that only sends syslog, a small syslog bridge fills the gap.
The rest of this guide covers the architecture, the working configuration, and the security and troubleshooting issues that come up in production.
Why Scheduled Backups Are Not Enough
Most Oxidized deployments start with a polling interval of an hour or a day. That is fine for compliance snapshots, but a fixed schedule leaves you with a timing problem. An engineer commits a change at 09:05, a second engineer reverts it at 09:40, and the next scheduled run happens at 10:00. Oxidized stores a single version that shows neither change, and the audit trail loses the story.
The Gap Between Poll Intervals
Between two scheduled runs you can lose three kinds of information:
- The exact content of intermediate changes, because only the state at poll time is captured.
- The timing of the change, because the Git commit time reflects when Oxidized polled, not when the engineer worked.
- The correlation with an incident, because a configuration captured an hour after an outage tells you little about the cause.
Shortening the interval to five minutes is the obvious workaround. It works for a few dozen devices, but it multiplies SSH sessions, load on device control planes, and AAA log noise, and it still cannot match the precision of an event.
Where Event-Driven Backups Fit
Event-driven backups complement scheduled ones. They do not replace them. Keep a long interval as a safety net, and let events trigger additional runs at the moments that matter: after a configuration change, after a reboot, after a link recovers, or when a new device appears in monitoring.
Key Concepts
Before wiring anything together, it helps to agree on terminology. These are the pieces this article uses.
| Term | Meaning in this article |
|---|---|
| Oxidized | Open-source, Ruby-based tool that logs into network devices, retrieves their configuration, and stores versions, commonly in Git |
| Node | One device in the Oxidized inventory, identified by a name |
| REST API | The HTTP interface provided by the oxidized-web component, listening on the address set by the rest option |
| Next request | An API call that moves a node to the head of the queue so it is backed up as soon as a worker is free |
| Hook | An Oxidized extension that runs an action, such as a script, on events like node_success or node_fail |
| Zabbix action | A rule that runs operations when a trigger event matches its conditions |
| Webhook media type | A Zabbix media type written in JavaScript that can make HTTP requests |
| Nagios event handler | A command that Nagios runs when a host or service changes state |
What “Triggering” Actually Means
Oxidized does not execute a backup the instant you call the API. A next request reorders the queue. The backup starts when a worker thread is available, then proceeds through connection, command execution, and storage. That distinction matters later when we discuss bursts and thread limits.
Quick Answer
To trigger an Oxidized backup from an event, send an HTTP PUT request to the node’s next endpoint on the Oxidized REST API. In Zabbix, do this from a webhook media type used by a trigger action. In Nagios, do it from an event handler script. Protect the endpoint with a reverse proxy, because the Oxidized REST API has no built-in authentication.
Architecture Overview
The design has four layers, and each is replaceable.
- Event sources: the devices themselves, sending syslog messages or SNMP traps, plus the polling checks that Zabbix or Nagios run.
- Detection: Zabbix triggers or Nagios state changes that decide an event is worth acting on.
- Dispatch: a Zabbix webhook, a Nagios event handler, or a syslog bridge script that calls the Oxidized API.
- Collection: Oxidized, which logs into the device and stores the result in Git.
A typical flow looks like this:
- An engineer saves a change on a switch.
- The switch emits a configuration-change syslog message or SNMP trap.
- The monitoring platform or syslog bridge recognizes the message and extracts the device name.
- The dispatcher sends a PUT request to the Oxidized next endpoint through the reverse proxy.
- Oxidized fetches the configuration and commits it when it differs from the previous version.
- An Oxidized hook reports the result back to monitoring.
Trigger Sources at a Glance
| Event | Best detected by | Stateful? |
|---|---|---|
| Configuration change | Syslog or SNMP trap, or polling a change timestamp | No |
| Device reboot | SNMP uptime check | Yes |
| Host down then up | Ping or SNMP availability check | Yes |
| Interface flap | SNMP interface status | Yes |
| New device added | Monitoring discovery or API inventory | No |
The “stateful” column matters. Nagios event handlers fire on state transitions, so stateless events such as a configuration change do not map to them cleanly. Zabbix can generate a separate event for every matching log line, which handles stateless events better.
Choosing Between Zabbix and Nagios
Pick the platform you already run. Neither is a better fit in principle, but each has strengths for this job.
| Consideration | Zabbix | Nagios |
|---|---|---|
| Outbound HTTP | Built in through JavaScript webhooks | Requires a script using curl |
| Per-event handling of log lines | Strong, with multiple-event problem generation | Weak, because it is state based |
| Dispatch logic | Defined in the GUI and media type script | Defined in configuration files and shell |
| Inventory source for Oxidized | Rich API with tags and groups | Custom macros and generated files |
| Operational model | Central server with GUI configuration | File-based configuration, easy to version control |
If you run both, which is common after acquisitions, send both through the same Oxidized endpoint and the same debounce logic described later.
Event Sources Worth Triggering On
Not every event deserves a backup. These are the ones that consistently pay off.
Configuration Changes
This is the highest-value trigger. On Cisco IOS, the %SYS-5-CONFIG_I syslog message appears when a configuration is changed from a terminal session. For richer detail, the configuration logger under archive can record each command. Cisco also defines the ciscoConfigManEvent notification in CISCO-CONFIG-MAN-MIB for SNMP-based detection. On Junos, commit activity appears in syslog as UI_COMMIT style messages. Check the exact message format on your platform and software version, because wording varies.
Reboots and Uptime Resets
A reboot can load a different startup configuration than the one running before it. A backup shortly after boot confirms what the device is actually running. In SNMP terms, sysUpTime is in hundredths of a second, and Zabbix templates typically apply a multiplier to convert it to seconds.
Link and Availability Recovery
When a device returns after an outage, someone often fixed it by hand. Backing it up on recovery captures emergency changes that never went through your normal process.
Polling a Change Timestamp
Some platforms expose when the running configuration last changed. Cisco’s CISCO-CONFIG-MAN-MIB includes ccmHistoryRunningLastChanged for this. Polling it over SNMP and triggering on a change in its value gives you event-style behavior without any syslog infrastructure, at the cost of polling delay. Confirm that your platform supports this object before building on it.
Preparing Oxidized for API Triggers
Both integrations depend on a working Oxidized with the REST API enabled. If you have followed the earlier posts in this series on LibreNMS inventory sync, Grafana and Prometheus visualization, and Git remote webhooks, most of this will already be in place.
Installation Options
Oxidized installs either as Ruby gems (the oxidized and oxidized-web gems) or from the official container image. Container deployments are easier to reproduce and upgrade. Gem installs are easier to debug on a standalone VM. Either path ends with the same configuration file, normally under the Oxidized home directory.
A Baseline Configuration
The following configuration enables the REST interface on localhost, uses a long polling interval as a safety net, and stores versions in Git. It uses a CSV file as the inventory source for simplicity.
yaml
username: backup password: change-me model: ios interval: 86400 threads: 20 timeout: 20 retries: 3 rest: 127.0.0.1:8888 input: default: ssh, telnet ssh: secure: false output: default: git git: user: Oxidized email: oxidized@example.com repo: "/var/lib/oxidized/devices.git" source: default: csv csv: file: /var/lib/oxidized/router.db delimiter: !ruby/regexp /:/ map: name: 0 ip: 1 model: 2 group: 3 Adjust credentials and paths for your environment, and move secrets into a credential store or a restricted file rather than leaving them inline. Binding rest to 127.0.0.1 keeps the API private until you deliberately expose it through a proxy. A common pitfall is setting rest to 0.0.0.0 during testing and forgetting to revert it.
Running Oxidized as a Service
A systemd unit keeps Oxidized running and restarts it after failures. Adjust the binary path to match your installation method.
ini
[Unit] Description=Oxidized network configuration backup After=network-online.target Wants=network-online.target [Service] User=oxidized Environment=OXIDIZED_HOME=/etc/oxidized ExecStart=/usr/local/bin/oxidized Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target After saving the unit, reload systemd, enable the service, and check its journal for configuration errors. The most frequent startup failure is a YAML indentation error, so run a syntax check if the service exits immediately.
Testing the Trigger by Hand
Always prove the endpoint works with curl before involving Zabbix or Nagios. This isolates Oxidized problems from monitoring problems.
bash
curl -s "http://127.0.0.1:8888/nodes?format=json" curl -s -X PUT "http://127.0.0.1:8888/node/next/core-sw1" The first command lists nodes so you can confirm the exact name Oxidized uses. The second asks for an immediate backup of core-sw1. Watch the Oxidized log or the node status afterward. If the node name does not match, the request fails, so copy names exactly from the listing. Endpoint paths and response details can differ between releases, so compare with the API documentation for the version you run.
Putting a Reverse Proxy in Front
Because the Oxidized REST API has no authentication of its own, never expose it directly to the network. A reverse proxy lets you publish only the trigger path with credentials and TLS.
nginx
server { listen 8443 ssl; server_name oxidized.example.com; ssl_certificate /etc/ssl/certs/oxidized.crt; ssl_certificate_key /etc/ssl/private/oxidized.key; location /node/next/ { limit_except PUT { deny all; } auth_basic "Oxidized trigger"; auth_basic_user_file /etc/nginx/oxidized.htpasswd; proxy_pass http://127.0.0.1:8888; } } This configuration accepts only PUT requests under the next path and refuses everything else. The web interface stays reachable only through whatever access method you already use for it. Create the password file with htpasswd, and use a dedicated credential for monitoring, not a personal account.
Triggering Oxidized from Zabbix
Zabbix is well suited to this job because its webhook media types can make HTTP calls without any scripts on disk. The approach below was designed with Zabbix 6.0 LTS and 7.0 LTS in mind. Menu names have shifted between releases, so adapt paths to your version.
Step 1: Create the Webhook Media Type
Go to Alerts, then Media types, and create a media type with the type set to Webhook. Define these parameters:
| Parameter | Value |
|---|---|
| url | https://oxidized.example.com:8443 |
| auth | user:password for the proxy |
| node | {HOST.HOST} |
| message | {ITEM.VALUE} |
The script uses the node parameter when it is present and falls back to parsing the hostname from a syslog line otherwise. That lets one media type serve both host-based triggers and syslog-based triggers.
javascript
try { var params = JSON.parse(value); var node = params.node; if (!node || node.indexOf('{') === 0) { var m = (params.message || '').match(/^\S+\s+\d+\s+[\d:]+\s+(\S+)/); if (!m) { throw 'Cannot determine node name from event'; } node = m[1]; } var req = new HttpRequest(); req.addHeader('Content-Type: application/json'); if (params.auth) { req.addHeader('Authorization: Basic ' + btoa(params.auth)); } var url = params.url.replace(/\/+$/, '') + '/node/next/' + encodeURIComponent(node); Zabbix.log(4, '[Oxidized] PUT ' + url); var response = req.put(url, ''); var status = req.getStatus(); if (status < 200 || status >= 300) { throw 'HTTP ' + status + ': ' + response; } return 'OK'; } catch (error) { Zabbix.log(3, '[Oxidized] failed: ' + error); throw 'Oxidized webhook failed: ' + error; } This script tolerates both input styles and turns any non-2xx response into a visible failure in the Zabbix alert log. Two cautions apply. The regular expression assumes traditional syslog formatting with a timestamp followed by the hostname, so adjust it if your collector writes RFC 5424 style lines. And the extracted name must equal the node name in Oxidized, which is the most common cause of silent failures.
Step 2: Give the Media Type a User
Zabbix delivers media through users. Create a service user, for example oxidized-bot, add a media entry of the Oxidized type with any value for Send to, and place the user in a group with at least read access to the host groups that contain your network devices. Without that permission the action runs but the user never receives the message, and the failure is quiet.
Step 3: Build the Trigger
For a log-based event such as a configuration change, you need a log item on the host that receives syslog. A common design is an rsyslog server writing network device messages to a file, with a Zabbix agent log item reading it. The item key below filters for Cisco configuration messages.
text
log[/var/log/network/devices.log,"%SYS-5-CONFIG_I",,,skip] Create a trigger on that item that fires whenever a new line arrives, and set the problem event generation mode to Multiple and recovery to None. Multiple mode is the important part. Without it Zabbix would open one problem and ignore subsequent changes until recovery, so only the first configuration change would trigger a backup.
Step 4: Create the Action
Under Alerts, then Actions, then Trigger actions, create an action with a condition that matches this trigger, for example by trigger name or a tag such as oxidized with value config-change. In the operations, send a message to oxidized-bot using the Oxidized media type. Using tags to select triggers scales better than naming each trigger.
Step 5: Use Uptime for Reboot Detection
For reboots, add an SNMP item for sysUpTime on the device, convert to seconds with a multiplier of 0.01 in preprocessing, and create a trigger that fires when the value is below a threshold such as ten minutes. The same action and media type apply, and since the host is the subject, the node parameter resolves to the device name directly.
Step 6: Verify the Chain
- Trigger the event on a lab device, for example by saving a harmless change.
- Confirm the log line appears in the file and the Zabbix item receives it.
- Check that a problem event was generated in Monitoring, then Problems.
- Open Reports, then Action log, and confirm the webhook was sent without error.
- Watch the Oxidized log for the node being queued and fetched.
- Check the Git history for a new commit when the configuration actually changed.
Alternative: Remote Commands
Zabbix actions can also run a remote command on the server or an agent, which would call curl directly. It works, but it runs shell commands from the monitoring system, which broadens the attack surface, and server-side execution may need explicit enabling depending on version. Prefer the webhook unless you have a reason not to.
Triggering Oxidized from Nagios
Nagios Core and its derivatives use event handlers, which are commands executed when a host or service changes state. Event handlers run on SOFT state changes, on the first HARD problem state, and on recovery. They do not run on every check.
Understanding the State Model
This explains why configuration changes are awkward for Nagios. A passive service that reports CRITICAL on a change and stays CRITICAL will not run the handler again for the next change, because the state never moved. You could submit an OK result shortly after each CRITICAL, but that is fragile. Use Nagios event handlers for reboots, outages, and recoveries, and use the syslog bridge in the next section for configuration changes.
A Trigger Script with Debounce
This script is shared by the Nagios handler and the syslog bridge. It takes a node name, enforces a cooldown per device, and calls the Oxidized API.
bash
#!/bin/bash # trigger_oxidized.sh <node> OXIDIZED_URL="${OXIDIZED_URL:-https://oxidized.example.com:8443}" OXIDIZED_AUTH="${OXIDIZED_AUTH:-monitor:change-me}" STAMP_DIR="/var/lib/oxidized-trigger" COOLDOWN=120 node="$1" [ -z "$node" ] && exit 1 mkdir -p "$STAMP_DIR" stamp="$STAMP_DIR/${node//\//_}" now=$(date +%s) if [ -f "$stamp" ]; then last=$(stat -c %Y "$stamp") [ $((now - last)) -lt "$COOLDOWN" ] && exit 0 fi touch "$stamp" curl -fsS --max-time 10 -u "$OXIDIZED_AUTH" -X PUT \ "$OXIDIZED_URL/node/next/$node" >/dev/null \ || logger -t oxidized-trigger "request failed for $node" Install it with restricted permissions, and load the credential from a protected environment file rather than leaving a real password in the script. The cooldown prevents a flapping device or a chatty change session from queuing the same node repeatedly. Choose a value that matches how long a typical change window takes on your network.
The Event Handler Wrapper
The wrapper decides when to call the trigger script based on state.
bash
#!/bin/bash # oxidized_event_handler.sh <state> <statetype> <attempt> <hostname> state="$1"; type="$2"; host="$4" case "$state" in CRITICAL) [ "$type" = "HARD" ] && /usr/local/nagios/libexec/eventhandlers/trigger_oxidized.sh "$host" ;; OK) /usr/local/nagios/libexec/eventhandlers/trigger_oxidized.sh "$host" ;; esac exit 0 Handlers run synchronously and are subject to the event handler timeout, so keep them quick. The curl timeout above is deliberately short for that reason.
Defining the Command and Service
text
define command { command_name oxidized_event_handler command_line /usr/local/nagios/libexec/eventhandlers/oxidized_event_handler.sh $SERVICESTATE$ $SERVICESTATETYPE$ $SERVICEATTEMPT$ $HOSTNAME$ } define service { use generic-service host_name core-sw1 service_description Uptime check_command check_snmp_uptime event_handler oxidized_event_handler event_handler_enabled 1 } Make sure event handlers are enabled globally in the main configuration, and verify the configuration with the Nagios verification command before restarting. The check_snmp_uptime command above is a placeholder for whichever uptime check you use, such as check_snmp against sysUpTime. Thresholds for that plugin are in timeticks, so run it manually first and confirm the value parsing on your plugin version.
The Syslog Bridge for Configuration Changes
For stateless events, let rsyslog hand matching lines to a script. This works with Nagios, Zabbix, or neither.
text
template(name="oxidized_fmt" type="string" string="%hostname%\n") if $msg contains '%SYS-5-CONFIG_I' or $msg contains 'UI_COMMIT' then { action(type="omprog" binary="/usr/local/bin/oxidized_syslog_bridge.sh" template="oxidized_fmt") } The bridge script reads one hostname per line and passes each to the trigger script.
bash
#!/bin/bash while read -r node; do /usr/local/nagios/libexec/eventhandlers/trigger_oxidized.sh "$node" done rsyslog keeps the program running and writes each message to its standard input. Test with a captured sample message from your own devices, because the match strings depend on platform and software version. If your devices log with names that differ from the Oxidized node names, add a lookup step to the bridge.
Closing the Loop with Oxidized Hooks
Triggering is only half the story. You also want monitoring to know whether the backup worked. Oxidized hooks can execute a script on events such as node_success and node_fail, and the script receives details through environment variables such as OX_EVENT and OX_NODE_NAME.
yaml
hooks: report_status: type: exec events: [node_success, node_fail] cmd: '/usr/local/bin/oxidized_report.sh' async: true timeout: 60 For Zabbix, the script pushes a value to a trapper item with zabbix_sender.
bash
#!/bin/bash if [ "$OX_EVENT" = "node_fail" ]; then value=0; else value=1; fi zabbix_sender -z zabbix.example.com -s "$OX_NODE_NAME" \ -k oxidized.backup.status -o "$value" Create a Zabbix trapper item with that key on each device host, then add a trigger on a failing value and another using nodata to catch devices that stop reporting. The Zabbix host name must match the Oxidized node name. For Nagios, write a passive check result to the external command file with the PROCESS_SERVICE_CHECK_RESULT command, using the same node and service naming discipline.
The result is a closed loop. Monitoring tells Oxidized to back up, and Oxidized tells monitoring how it went.
Keeping the Inventory in Sync
Event triggers only work for nodes Oxidized knows about, so inventory drift defeats the design. If Zabbix is your source of truth, generate the Oxidized inventory from its API.
python
#!/usr/bin/env python3 import os, requests URL = "https://zabbix.example.com/api_jsonrpc.php" TOKEN = os.environ["ZABBIX_TOKEN"] OUT = "/var/lib/oxidized/router.db" GROUP_ID = os.environ.get("ZABBIX_GROUP_ID", "15") payload = { "jsonrpc": "2.0", "id": 1, "method": "host.get", "params": { "output": ["host"], "groupids": [GROUP_ID], "selectInterfaces": ["ip", "main"], "selectTags": ["tag", "value"], }, } r = requests.post(URL, json=payload, timeout=30, headers={"Authorization": "Bearer " + TOKEN}) r.raise_for_status() lines = [] for h in r.json()["result"]: tags = {t["tag"]: t["value"] for t in h["tags"]} model = tags.get("oxidized_model") ip = next((i["ip"] for i in h["interfaces"] if i["main"] == "1"), None) if model and ip: lines.append(f'{h["host"]}:{ip}:{model}:{tags.get("oxidized_group", "default")}') with open(OUT + ".tmp", "w") as f: f.write("\n".join(lines) + "\n") os.replace(OUT + ".tmp", OUT) Bearer authentication for the Zabbix API applies to newer releases, and older versions use a different mechanism, so check your version’s documentation. Tag each device with oxidized_model, for example the value ios, so models are explicit rather than guessed. The atomic replace avoids Oxidized reading a half-written file. For Nagios, store the model in a custom host macro and produce the same file from your object configuration. Run the script from cron or a systemd timer, and keep it independent of event triggering so inventory problems are easy to spot.
Preventing Backup Storms
An event system that can start backups can also start too many. Three controls keep it safe.
- Cooldown per node. The shell script above ignores repeat triggers within a window.
- Thread limit. Oxidized processes only as many jobs concurrently as the threads setting allows, so a burst becomes a queue instead of a flood.
- Trigger selection. Triggering on every interface flap across a large campus creates more load than value. Restrict triggers to infrastructure devices and to event types that correlate with configuration risk.
A power failure that reboots two hundred switches at once will legitimately generate two hundred triggers. That is fine with a sensible thread count, but confirm your AAA servers and device login limits tolerate it.
Some Oxidized releases include a configuration option that changes how next requests are scheduled. Check the configuration documentation for your version before relying on a particular behavior.
Security Considerations
Automation that can reach every network device deserves care.
- Treat the API as privileged. Anyone who can call it can cause logins to every node, so restrict network access and require credentials through the proxy.
- Use TLS between monitoring and the proxy, and store the proxy credential in the monitoring system’s secret facilities, not in plain script text.
- Give Oxidized a read-only device account where the platform allows it, with command authorization limited to the show commands the model needs.
- Protect the Git repository, because it contains full configurations that may include secrets. Restrict access and consider secret masking.
- Avoid shell injection. Node names taken from syslog text are untrusted input, so validate them against a safe pattern before passing them to a shell.
- Log every trigger. The logger call in the script and the Zabbix action log together give you an audit trail.
Compliance Relevance
Event-driven capture strengthens evidence for change control programs. The mappings below describe where the practice supports common frameworks, not a guarantee of compliance.
| Framework | Relevant control area |
|---|---|
| NIST SP 800-53 | Configuration management family, including baseline configuration and change control |
| ISO/IEC 27001:2022 | Annex A control on configuration management |
| PCI DSS v4.0 | Requirements covering network security control configuration and review |
| CIS Controls v8 | Secure configuration process for network infrastructure |
Verify the exact control numbers against the current published versions before citing them in an audit package.
Performance and Scalability
The practical limits are device login capacity and the number of Oxidized worker threads, not the API. Start with a conservative thread count and raise it while watching device CPU and AAA load. Large estates often partition devices into groups and run more than one Oxidized instance, each with its own inventory slice and its own trigger endpoint. When you do that, make the dispatcher choose the right instance, for instance by encoding the site in a Zabbix tag or Nagios macro.
Keep the polling interval long. Event triggers handle freshness, and a daily or longer scheduled run catches anything that never produced an event, such as a change made over a console with logging disabled.
Monitoring and Maintenance
Monitor the pipeline itself, not just the network.
- Alert on backup failures reported by the Oxidized hook.
- Alert when a node has produced no status for longer than your interval.
- Watch the Oxidized service and the proxy for availability.
- Review the Git history periodically for noise, such as timestamps or counters changing on every run, and tune the model output to remove them.
- Re-test the full chain after Zabbix, Nagios, Oxidized, or device software upgrades.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Webhook shows success but no backup | Node name mismatch | Compare the name in the event with the node listing |
| Action never fires | Service user lacks host permission | Group permissions for the oxidized-bot user |
| Only the first change triggers | Problem generation mode is single | Set multiple event generation on the trigger |
| HTTP 401 from the proxy | Wrong or missing credential | auth parameter and htpasswd entry |
| Connection refused | Oxidized bound to localhost only | Proxy target and the rest setting |
| Nagios handler never runs | Event handlers disabled | Global setting and service definition |
| Backup runs but no new commit | Configuration did not change | Expected behavior, since unchanged configs are not stored |
| Repeated triggers for one device | No cooldown | Debounce script or trigger conditions |
Work through problems in order: can curl trigger the node, does the proxy pass it, does the dispatcher build the right URL, and only then examine the event detection. Debug from the Oxidized end outward, because that stage has the least ambiguity.
Common Mistakes
- Exposing the unauthenticated API directly on the network.
- Triggering on every event type and creating load with no benefit.
- Forgetting that Nagios handlers are state driven and expecting one per configuration change.
- Mismatched names between monitoring, syslog, and Oxidized.
- Dropping the scheduled backup entirely and losing the safety net.
- Testing only the happy path and never simulating a failed login or an unreachable Oxidized server.
- Hard-coding credentials in scripts and media type parameters that many people can view.
Real-World Use Cases
Post-Incident Evidence
A branch router reboots at night and an engineer logs in to recover it. The reboot trigger captures the running configuration minutes after boot, and the configuration-change trigger captures the repair. The morning review has two precise snapshots instead of one hourly guess.
Change Window Verification
During a planned change, each committed change triggers a backup, and the diff in Git becomes the as-built record attached to the change ticket.
Unauthorized Change Detection
A configuration change at an unexpected hour triggers a backup, and the resulting commit can feed a separate alert so the network team sees what changed while it is still fresh.
Merger and Multi-Tool Estates
Two monitoring platforms feed the same Oxidized endpoint through the shared trigger script, so teams keep their tools while sharing one configuration history.
Expert Recommendations
- Start with one platform and one event type, usually configuration change, and prove it end to end before adding more.
- Keep the scheduled backup. Treat events as an accelerator.
- Put the cooldown in one place, ideally the shared script, so every source benefits.
- Use tags or macros to declare which devices participate, rather than hard-coding names in actions.
- Test the failure path by stopping Oxidized and confirming that monitoring raises a visible problem.
- Document node naming rules and enforce them in provisioning, because naming is the most common source of silent failure.
Implementation Checklist
- Oxidized runs as a service with the REST API bound to localhost.
- A reverse proxy publishes only the next path with TLS and authentication.
- Curl can trigger a test node through the proxy.
- Node names match across inventory, monitoring, and syslog.
- Zabbix webhook or Nagios handler is configured and tested.
- A cooldown protects against bursts.
- Oxidized hooks report success and failure to monitoring.
- A long scheduled interval remains as a safety net.
- Inventory sync is automated and monitored.
- The Git repository and credentials are protected.
Future Trends
Expect configuration capture to move closer to the source. Streaming telemetry and gNMI-style subscriptions let devices announce changes directly, which could replace syslog parsing for platforms that support them. NETCONF, defined in RFC 6241, already offers notifications on some systems. Meanwhile, tools such as Oxidized remain popular because they work with the large installed base of devices that only offer SSH and a command line. In practice, event-driven backup will probably stay a hybrid of device signals, monitoring detection, and a collector that speaks the device’s native language.
Frequently Asked Questions
Can Oxidized trigger backups by itself when a device changes?
Not on its own for most devices. Oxidized polls on a schedule and responds to API requests, so an external system must detect the event and call the API.
Which API call triggers a backup?
A PUT request to the node’s next endpoint on the Oxidized REST API. It moves the node to the front of the queue, and the backup starts when a worker is free. Verify the path against the documentation for your version.
Does the Oxidized REST API support authentication?
No built-in authentication is provided. Bind it to localhost and publish only what you need through a reverse proxy with TLS and credentials.
Is Zabbix or Nagios better for this?
Zabbix handles per-event log processing and outbound HTTP more naturally. Nagios works well for state changes such as reboots and recoveries, and it is easy to manage as files. Use what you already operate.
Why did only the first configuration change trigger a backup in Zabbix?
The trigger is probably using single problem event generation. Switch it to multiple so each matching log line produces an event.
Will a backup always create a new Git commit?
No. Oxidized stores a new version only when the configuration differs from the last stored one.
How do I avoid overloading devices during outages?
Use a per-node cooldown, a sensible thread limit, and selective triggers, so bursts queue instead of running at once.
Should I stop scheduled backups once events work?
No. Keep a long interval as a safety net for changes that produce no event.
Key Takeaways
- Event-driven triggers capture configuration at the moments that matter, while scheduled runs remain a safety net.
- The mechanism is a PUT to Oxidized’s next endpoint, sent by a Zabbix webhook, a Nagios event handler, or a syslog bridge.
- Nagios is state driven, so stateless events like configuration changes need a syslog bridge.
- Protect the unauthenticated REST API with a reverse proxy, TLS, and a dedicated credential.
- Node names must match everywhere, or triggers fail silently.
- Close the loop with Oxidized hooks so monitoring knows whether each backup succeeded.
Conclusion
Connecting Zabbix or Nagios to Oxidized turns configuration backup from a periodic chore into a record of what happened and when. Begin with the simplest path, a manual curl against a protected endpoint, then add one event source, a cooldown, and a status hook. Once that chain is reliable, extend it to reboots, recoveries, and inventory automation. The earlier articles in this series on LibreNMS, Grafana and Prometheus, Git remote webhooks, and Ansible deployment fit naturally alongside this setup as the rest of a complete configuration management practice.

