Poller Configuration

Horizon backs up device configuration through the DeviceConfigMonitor. You may have to configure the TFTP port before Horizon can back up device configurations.

Configure TFTP port

By default, the TFTP server uses non-privileged port 6969 on Horizon and Minions. Follow the steps below to configure the TFTP port if you want to use a different port:

Connect to Karaf shell on Horizon
ssh -p 8101 admin@localhost
Connect to Karaf shell on Minion
ssh -p 8201 admin@localhost
Configure TFTP port
config:edit org.opennms.features.deviceconfig.tftp
config:property-set port 10069 (1)
config:update
1 If you have set CAP_NET_BIND_SERVICE on the service unit, you can set the port to the TFTP default of 69 and skip the firewall port redirect steps below.
Some devices (for example, Juniper) may allow TFTP upload on a non-default port. In these cases, you do not need to change the default port.

The Horizon core services run as an unprivileged user and cannot bind on port numbers lower than 1024 without escalated privileges. For this reason, the default port for the TFTP listener is set to 6969/udp instead of the IANA-registered port number 69/udp. The following example shows how to configure the local firewall daemon to forward port 69/udp to 6969/udp:

  • CentOS/RHEL 7/8

  • Debian/Ubuntu

Enable Masquerade to allow port forwarding
sudo firewall-cmd --permanent --add-masquerade
Forward TFTP UDP port 69 to 6969
sudo firewall-cmd --permanent --add-port=69/udp
sudo firewall-cmd --permanent --add-port=6969/udp
sudo firewall-cmd --permanent --add-forward-port=port=69:proto=udp:toport=6969
sudo systemctl reload firewalld
Enable Masquerade to allow port forwarding
sudo vi /etc/ufw/before.rules
For TFTP forwarding, add the following lines at the top before the *filter section
*nat
:PREROUTING ACCEPT [0:0]
-A PREROUTING -p udp --dport 69 -j REDIRECT --to-port 6969
COMMIT
Apply the firewall changes
sudo ufw allow in 69/udp
sudo ufw allow in 6969/udp
sudo ufw reload

Configure TFTP IP address

The device configuration backup feature allows the retrieval of network device configurations using TFTP. To achieve this, a TFTP server needs to be started on your Horizon instance or on a Minion.

Usually, the IP address is determined by selecting the interface address that the operating system uses to reach the destination device. In the case of a Minion running in Docker outside of host networking mode, the IP address cannot be automatically determined; you need to configure it manually:

Connect to Karaf shell on Horizon
ssh -p 8101 admin@localhost
Connect to Karaf shell on Minion
ssh -p 8201 admin@localhost
Configure TFTP IP address
config:edit org.opennms.features.deviceconfig.sshscripting
config:property-set tftpServerIPv4Address 192.168.1.123
config:property-set tftpServerIPv6Address ::1
config:update

Configure maximum backup file size

By default, the maximum file size the internal TFTP server will accept when Horizon receives a backup is 50,000 bytes. We recommend that you increase that size.

Connect to Karaf shell on Horizon
ssh -p 8101 admin@localhost
Connect to Karaf shell on Minion
ssh -p 8201 admin@localhost
Configure TFTP port (Minion/Horizon)
config:edit org.opennms.features.deviceconfig.tftp
config:property-set maximumReceiveSize 100000000
config:update

SSH session I/O collection

By default, the SSH scripting service collects all SSH session output for debugging, and stores it in the poller’s status. To disable this behavior, configure the scripting service on Horizon and all Minions:

config:edit org.opennms.features.deviceconfig.sshscripting
config:property-set disableIOCollection true
config:update

Enable push-based configuration upload

Devices may push configuration information through TFTP manually whenever their configuration settings change. This is an optional setting, and is not enabled by default; you must enable the sink for device configuration:

Connect to Karaf shell on Horizon
ssh -p 8101 admin@localhost
Connect to Karaf shell on Minion
ssh -p 8201 admin@localhost
Configure opennms-deviceconfig-sink feature
feature:install opennms-deviceconfig-sink

To set the deviceconfig-sink feature to start automatically upon future service starts, add opennms-deviceconfig-sink to $\{OPENNMS/MINION_HOME}/etc/featuresBoot.d/device-config.boot. If the file does not exist, create it. To make the feature start immediately, log into the Karaf shell and run feature:install opennms-deviceconfig-sink.

Device configuration backup events

Pollerd can generate the following device configuration backup events in Horizon:

Event Name Description

uei.opennms.org/deviceconfig/configBackupStarted

Configuration backup started on a given service during the last poll on a given interface.

uei.opennms.org/deviceconfig/configBackupFailed

Failed to back up configuration settings associated with a given service during the last poll on a given interface.

uei.opennms.org/deviceconfig/configBackupSucceeded

Configuration backup succeeded on a given service during the last poll on a given interface.

Device configuration backup parameters

Additional parameters associated with device configuration backup
Parameter Description

controlProtocol

Name of the control-plane protocol that Horizon uses to initiate a backup (cron, REST).

dataProtocol

Name of the data-plane protocol through which Horizon receives backup contents (TFTP).

eventReason

If a backup failed, this contains a short description of the issue.

Manually back up device configuration

You can manually back up device configuration settings via the web UI:

  1. In the top menu bar, click Info  Device Configs.

  2. Click Backup and follow the instructions.

You can also use the REST API to run device configuration retrieval outside of a schedule (see Device Config REST API).

Pollerd thread pool adjustments

The device configuration backup process shares resources with pollerd—​particularly, the threads. If too many backup processes are running in parallel, or they take too long, pollerd may not have sufficient threads available to schedule other monitors. For a rough estimate, start with the number of devices that you expect might be backed up simultaneously, and multiply by the expected time, in minutes; increase your existing thread pool size by the resulting value. For example, if you have 50 devices and each backup process takes 1 minute, you should increase the thread pool size by 50.

Changes to the thread pool size take effect the next time that Horizon restarts.

You can also back up and retrieve device configuration settings manually via the Karaf shell:

Connect to Karaf shell on Horizon
ssh -p 8101 admin@localhost
In the shell, use opennms:dcb-get --help to view the command’s help information.
Run device configuration backup from a specific interface
admin@opennms()> opennms:dcb-trigger --help
DESCRIPTION
        opennms:dcb-trigger

	Trigger device config backup from a specific Interface

SYNTAX
        opennms:dcb-trigger [options] host

ARGUMENTS
        host
                Hostname or IP Address of the system to poll
                (required)

OPTIONS
        -l, --location
                Location
                (defaults to Default)
        --help
                Display this help message
        -s, --service
                Device Config Service
                (defaults to DeviceConfig)
        -p, --persist
                Whether to persist config or not
By default, these commands do not persist configuration settings. To persist configuration settings in the Horizon database, use the -p flag.