
[[backup-script]]
= Configure Backup Script
:description: How to use the SSH scripting engine for device configuration backup and details about vendor TFTP support in {page-component-title}.

{page-component-title} uses an SSH scripting engine to run the commands on devices to upload their configuration settings.
You must create a script for each device type whose configuration you want to back up, and save the scripts in `$\{OPENNMS_HOME}/etc/device-config`.
Each script simulates an interactive session with the network device, and tells the device to create a backup of its configuration.
The backup is then sent to a TFTP server which is operated by either {page-component-title} or a Minion.

NOTE: Some devices may distinguish between different types of configuration settings (for example, startup configuration versus running configuration).
{page-component-title} treats configuration types as arbitrary strings, and uses `default` when no configuration type is specified.

You will reference these scripts when you xref:deep-dive/device-config-backup/dcb-requisition.adoc[create a requisition] for a device of each type.

== SSH scripting engine

The scripting engine supports the following commands:

* `send: ...`: Sends the given string to the device.
* `await: ...`: Waits for a response from the device that matches the given string.
* `capture:`: Marks the current position in the device's output as the start of the configuration to capture.
  When an `await:` command matches after a `capture:`, the matched line is automatically excluded from the captured output.
  No TFTP server or file transfer is involved; the captured bytes are stored directly.
* `capture: <string>`: Same as `capture:`, but first waits for `<string>` to appear in the output before setting the capture start point.
  Use this form to skip the device's echo of the preceding `send:` command.

Scripts can reference the following variables by using `$\{varname}` notation:

[caption=]
.SSH scripting variables
[options="autowidth"]
|===
| Name  | Description

| tftpServerIp
| TFTP server's IP address

| tftpServerPort
| TFTP server's port number

| filenameSuffix
| Suffix that must be appended to the file name before uploading.
{page-component-title} uses this additional suffix to identify incoming uploads.

| configType
| Configuration type.
If not specified, this is set to `default`.
|===

NOTE: Uploaded configuration files should include filename extensions like `.zip` or `.gz` that specify their file type.
You must also append the script variable `filenameSuffix` to the file name; this indicates that the file is set to upload.

=== Example

This example script is for a Juniper SRX firewall.
You will need to modify it to configure other device types.

[source, script]
----
await: >
send: start shell
await: %
send: cd /config
await: %
send: tftp ${tftpServerIp}
await: tftp>
send: put juniper.conf.gz juniper.conf.gz${filenameSuffix}
await: tftp>
send: exit
----

=== Inline capture example

Some devices support retrieving configuration output directly from the SSH session without a separate file transfer.
The following example retrieves the running configuration from a Cisco IOS device using inline capture.

[source, script]
----
await: #
send: terminal length 0
await: #
send: show running-config
capture: show running-config
await: #
----

`terminal length 0` disables paging so the full configuration is returned in a single output block.
`capture: show running-config` waits for the device to echo the command back, then starts recording the output.
The final `await: #` waits for the prompt that signals the end of the output; the prompt line is excluded from the stored configuration.

NOTE: The `filenameSuffix`, `tftpServerIp`, and `tftpServerPort` variables are not used in capture-based scripts.
The `configType` variable is still used to identify the configuration type that is stored.

== Vendor TFTP support

See your device manufacturer's official documentation for details on their TFTP support.
The following are links to popular device manufacturers:

* https://www.arubanetworks.com/techdocs/ArubaOS_63_Web_Help/Content/ArubaFrameStyles/Management_Utilities/Managing_Files_on_the_.htm[Aruba]
* https://www.cisco.com/c/de_de/support/docs/ios-nx-os-software/ios-software-releases-122-mainline/46741-backup-config.html[Cisco]
* https://supportportal.juniper.net/s/article/Manually-transfer-a-configuration-file-or-text-file-from-EX-Switch-to-TFTP-server?language=en_US[Juniper]
* https://knowledgebase.paloaltonetworks.com/KCSArticleDetail?id=kA10g000000ClJ9CAK[Palo Alto]

There are several example scripts available in `$\{OPENNMS_HOME}/etc/examples/device-config`:

.Example scripts for Aruba devices
[options="autowidth"]
|===
| Script    | Target Device | Description

| aruba-cx-cli.dcb
| Aruba OS-CX
| Retrieves configuration from an ArubaOS-CX device in CLI format.

| aruba-cx-json.dcb
| Aruba OS-CX
| Retrieves configuration from an ArubaOS-CX device in JSON format.

| aruba-os.dcb
| Aruba OS
| Retrieves configuration from an ArubaOS device.

| cisco-ios-running.dcb
| Cisco IOS
| Retrieves `running-config` from a Cisco IOS device.

| cisco-ios-startup.dcb
| Cisco IOS
| Retrieves `startup-config` from a Cisco IOS device.

| juniper-junos-config-gz.dcb
| Juniper JunOS
| Retrieves compressed configuration from a Juniper JunOS device.

| juniper-junos-config-set.dcb
| Juniper JunOS
| Retrieves configuration from a Juniper Junos device in `set-format`.

| juniper-junos-config-txt.dcb
| Juniper JunOS
| Retrieves uncompressed configuration from a Juniper Junos device.

| paloalto-panos-config.dcb
| Palo Alto PanOS
| Retrieves configuration from a Palo Alto PAN-OS device.
|===

=== Configure DCB user accounts

We recommend that you limit the privileges of any user accounts used for configuration retrieval.
The following examples demonstrate how to configure a `dcb` user account, specify its password (`Pa55w0rd`), and limit its privileges to only configuration retrieval commands.

[{tabs}]
====
ArubaOS::
+
--
include::dcb-accounts/aruba-os.adoc[]
--

ArubaOS-CX::
+
--
include::dcb-accounts/aruba-oscx.adoc[]
--

Cisco IOS::
+
--
include::dcb-accounts/cisco-ios.adoc[]
--

Juniper Junos::
+
--
include::dcb-accounts/juniper.adoc[]
--
====

