Poller Configuration

OpenNMS backs up device configuration through the Device Config Monitor.

You may have to configure the TFTP port before OpenNMS can back up device configurations.

Configure TFTP Port

By default, the TFTP server uses non-privileged port 6969 on both Minion and Horizon.

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 port 10069
config:update
Some devices (for example, Juniper) may allow TFTP upload on non-default port. For such devices there is no need to change default port.

The OpenNMS Horizon core services run as an unprivileged user and can’t bind on port numbers < 1024 without escalated privileges. For this reason, the default port for the TFTP listener is set to port number 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 the OpenNMS instance or on a Minion. Normally the IP address to use is determined by picking the interface address that the operating system will use to reach the destination device. In the case of a Dockerized Minion running not in host networking mode, the IP address cannot be automatically determined. In this case, you need to configure the IP Address as below:

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.sshscripting
config:property-set tftpServerIPv4Address 192.168.1.123
config:property-set tftpServerIPv6Address ::1
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 both Horizon and all Minions as below:

Configure SSH session I/O collection
config:edit org.opennms.features.deviceconfig.sshscripting
config:property-set disableIOCollection true
config:update

(optional) Enable push-based configuration upload

Devices may also push configuration through TFTP manually whenever their configuration changes. This is not enabled by default; you must enable the sink for device configuration.

Configure device config sink feature via Karaf shell on Horizon
ssh -p 8101 admin@localhost
Configure device config sink feature via Karaf shell on Minion
ssh -p 8201 admin@localhost
Configure opennms-deviceconfig-sink feature (Horizon/Minion)
feature:install opennms-deviceconfig-sink

  1. To make the device config sink start automatically on future service starts, add the line opennms-deviceconfig-sink to the file $\{OPENNMS/MINION_HOME}/etc/featuresBoot.d/device-config.boot. (Create the file if it does not exist.)

  2. To make the device config sink start now, log in to the Karaf shell and run the following command to load the feature: feature:install opennms-deviceconfig-sink

Events associated with device config backup

Pollerd can generate the following events in Horizon for device config backup.

Event name Description

uei.opennms.org/deviceconfig/configBackupStarted

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

uei.opennms.org/deviceconfig/configBackupFailed

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

uei.opennms.org/deviceconfig/configBackupSucceeded

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

Additional Parameters

  • controlProtocol - The name of the control-plane protocol OpenNMS uses to initiate the backup ("cron", "REST").

  • dataProtocol - The name of the data-plane protocol by which OpenNMS received the backup contents ("TFTP").

  • eventReason - If the backup failed, contains a short description of the issue.

Back up device configuration on demand

You can manually back up devices from the OpenNMS UI under Info>Device Configs. You can also use the REST API to trigger device configuration retrieval outside of a monitor schedule. (See Device Config Rest API.)

Poller thread pool adjustments

Device configuration backup shares resources with Poller, particularly poller threads. If too many backups are running in parallel that take too long, Poller may not have sufficient threads to schedule other monitors. As a rough estimate, start with the number of devices you expect will ever be simultaneously backed up and multiply by the time (in minutes). Increase the existing thread pool size by the resulting value. For example, with 50 devices and each backup running for 1 minute, you should increase pool size by 50.

Changes to the poller thread pool size take effect the next time OpenNMS is restarted.

Trigger/retrieve device config from Karaf shell

You can also use the Karaf shell to manually trigger and retrieve a device configuration backup for test purposes.

ssh -p 8101 admin@localhost

Once in the shell, you can print show the commands help as follows:

Get Device Config Backup from a specific Interface
admin@opennms()> opennms:dcb-get --help
DESCRIPTION
        opennms:dcb-get

	Get device config from a specific Interface

SYNTAX
        opennms:dcb-get [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
        -t, --timeout
                Timeout for device config retrieval in msec
                (defaults to 60000)
        -s, --service
                Device Config Service
                (defaults to DeviceConfig)
        -e, --encoding
                Encoding format
                (defaults to UTF-8)
        -p, --persist
                Whether to persist config or not
Trigger device config 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
The previous Karaf commands will not persist configuration by default. Use the -p option to persist configuration in the Horizon database.