
[[poller-config]]
= Poller Configuration
:description: Device Configuration Backup feature poller configuration in {page-component-title}: TFTP port and IP address, events, parameters, thread pool adjustments.

{page-component-title} backs up device configuration through the xref:reference:service-assurance/monitors/DeviceConfigMonitor.adoc[].
You may have to configure the <<tftp-port-configure, TFTP port>> before {page-component-title} can back up device configurations.

[[tftp-port-configure]]
== Configure TFTP port

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

.Connect to Karaf shell on {page-component-title}
[source, console]
ssh -p 8101 admin@localhost

.Connect to Karaf shell on Minion
[source, console]
ssh -p 8201 admin@localhost

.Configure TFTP port
[source, karaf]
----
config:edit org.opennms.features.deviceconfig.tftp
config:property-set port 69 <1>
config:update
----
<1> {page-component-title} ships with the `CAP_NET_BIND_SERVICE` capability set in the systemd service unit, in most cases you can set the port to the IANA-assigned default port `69` and skip the firewall port redirect steps below.

NOTE: Some devices (for example, Juniper) may allow TFTP upload on a non-default port.
In these cases, you may not need to change the default port.

{page-component-title} runs as a non-privileged user with the `CAP_NET_BIND_SERVICE` capability and can bind to IANA-registered TFTP port number `69/udp`.
However, if you prefer the TFTP listener bind to the default non-privileged port `6969/udp` instead of port number `69/udp`, the following example shows how to configure the local firewall daemon to forward port `69/udp` to `6969/udp`:

[{tabs}]
====
CentOS/RHEL 7/8::
+
--
include::centos-rhel/firewall-core.adoc[]
--

Debian/Ubuntu::
+
--
include::debian-ubuntu/firewall-core.adoc[]
--
====

== 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 {page-component-title} 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 {page-component-title}
[source, console]
ssh -p 8101 admin@localhost

.Connect to Karaf shell on Minion
[source, console]
ssh -p 8201 admin@localhost

.Configure TFTP IP address
[source, karaf]
----
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 {page-component-title} receives a backup is 50,000 bytes.
We recommend that you increase that size.

.Connect to Karaf shell on {page-component-title}
[source, console]
----
ssh -p 8101 admin@localhost
----

.Connect to Karaf shell on Minion
[source, console]
----
ssh -p 8201 admin@localhost
----

.Configure TFTP port (Minion/{page-component-title})
[source, karaf]
----
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 {page-component-title} and all Minions:

[source, karaf]
----
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 {page-component-title}
[source, console]
ssh -p 8101 admin@localhost

.Connect to Karaf shell on Minion
[source, console]
ssh -p 8201 admin@localhost

.Configure `opennms-deviceconfig-sink` feature
[source, karaf]
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 {page-component-title}:

[cols="2,3"]
|===
| 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.

| uei.opennms.org/deviceconfig/configChanged
| Configuration backup on a given service has changed from the last poll on a given interface.
|===

== Device configuration backup parameters

[caption=]
.Additional parameters associated with device configuration backup
[options="autowidth"]
|===
| Parameter     | Description

| controlProtocol
| Name of the control-plane protocol that {page-component-title} uses to initiate a backup (`cron`, `REST`).

| dataProtocol
| Name of the data-plane protocol through which {page-component-title} 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:

. In the top menu bar, click menu:Info[Device Configs].
. Click *Backup* and follow the instructions.

You can also use the REST API to run device configuration retrieval outside of a schedule (see xref:development:rest/device_config.adoc[]).

== 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.

NOTE: Changes to the thread pool size take effect the next time that {page-component-title} restarts.

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

.Connect to Karaf shell on {page-component-title}
[source, karaf]
ssh -p 8101 admin@localhost

NOTE: In the shell, use `opennms:dcb-get --help` to view the command's help information.

.Run device configuration backup from a specific interface
[source, console]
----
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
----

NOTE: By default, these commands do not persist configuration settings.
To persist configuration settings in the {page-component-title} database, use the `-p` flag.
