# Unimus

Integrating LibreNMS with [Unimus](https://unimus.net) brings config
viewing directly into LibreNMS: the latest backup, the full backup
history, and diffs between any two backups are all available under
the Config tab of each device.

This integration relies on you having a working Unimus deployment
which is already taking config backups of your devices. LibreNMS
reads backups through the Unimus API; it does not add or manage
devices in Unimus.

## Requirements

- Unimus with API v2 (Unimus 2.x or newer)
- An API token created in Unimus (`Settings -> User Management -> API tokens`).

## Configuration

Go to Unimus settings in the External Settings section of Global
Settings (`Settings -> Global Settings -> External -> Unimus
Integration`). Enable the integration, enter the URL of your Unimus
instance and enter your API token.

Alternatively, configure it from the CLI:

!!! setting "external/unimus"
    ```bash
    lnms config:set unimus.enabled true
    lnms config:set unimus.url http://127.0.0.1:8085
    lnms config:set unimus.token YOUR_API_TOKEN
    ```

Once enabled, users with the show config permission will see a
Config tab on devices that exist in Unimus.

## Device matching

LibreNMS matches a device to its Unimus counterpart by address,
trying the following values in order until one matches:

1. The LibreNMS hostname
1. The hostname with the domain stripped
1. The hostname with `mydomain` appended (if configured)
1. The device IP address

Successful matches are cached for one hour, so a device freshly
added to Unimus may take a few minutes to appear.

## Notes

- When Unimus support is enabled, the Unimus-backed Config tab
  takes over from the Oxidized/RANCID Config tab.
- Binary backups are listed, but their content cannot be displayed in
  LibreNMS. View those in Unimus itself.
- Diffs are generated by Unimus via its API and rendered as a unified
  diff with insertions, deletions and changes highlighted.
