Adding or editing device agents

A device agent helps manage devices. You can add or remove TrueSight Network Automation remote device agents at any time after you install the Network Automation application server. You can only edit the local device agent. This topic provides instructions on adding and editing device agents.

To understand device agents and their communication with the application server, see Device-agent-architecture.

Adding a device agent

On the Admin > Network Admin > Device Agent page, click Add, and do the following:

1. Enter information in the following fields:

   Field	Description
   Name	Enter a unique name for the device agent.
   Address	Enter a resolvable DNS host name or the IP address of the remote device agent. This is the server-facing address which the Network Automation application server uses to communicate with this agent.
   Port	Enter the port used to communicate with the device agent. If you are using the default port (1099) on the device agent server, ensure that you specify a non-conflicting port when installing the device agent and when assigning the port.
   Enabled	(Optional) Select this option to enable the device agent (default) or clear the option to disable it. When a device agent is disabled, no device actions are performed on the network devices associated with that device agent, and no syslog messages are received.
   Name Resolution Enabled	(Optional) Select this option to control whether Network Automation should attempt to perform host name resolution as needed at the agent, both when connecting to devices the agent manages and when parsing syslog messages received from those devices. By default, this option is selected.
   New in 20.02.02 Use Secondary NAT Address For Devices	(Optional) Select to use the secondary NAT address instead of the primary NAT address to be used by the devices to access this device agent or proxy file server. If secondary NAT address is disabled, primary NAT address is used.
   Local	(Read-only) Identifies the agent as the local device agent. All installations include a local device agent that resides on the Network Automation application server.

2. In the Device Facing NICs section, click Add, and enter information about one or more agent NICs that can be used for communication with devices. The NICs defined here can be selected from the device editor, to control which NIC will be used by the agent to communicate with a device.

   Notes

   • The address value of the device-facing NIC used to communicate with a NIC is used to populate the "%address%" connection property references in the device adapter. Typically, this property is used in file transfer commands within adapters.
   • The mask values specified are CIDR values in the case of an IPv4 NIC, and prefix lengths in the case of an IPv6 NIC.
     
   • The table must contain at least one default NIC. If the agent only has one NIC, then the default NIC address is the same as the server-facing address.
   • You can specify only one IPv4 and one IPv6 default NIC. However, you can specify multiple non-default NICs.
   • You cannot delete a device-facing NIC that is still specified as the NIC to use when communicating with a particular device. To delete the NIC, you must first edit the device to specify that it uses a different NIC. You can use the device filter to help find which devices are still using a particular NIC.
   • Similarly, you cannot edit a device-facing NIC to change it from non-default to default, if the NIC is still specified as the NIC to use when communicating with a particular device.

3. In the File Transfer section, enter or edit information in the following fields to define the file transfer information for the device agent.

   Note

   • To use FTP or SCP file transfers, you must create the FTP and SCP accounts. Usually these are the same accounts, but they can be different.
   • The accounts must be local to the computer where the device agent is installed.
     • Local device agent: The FTP and SCP accounts must be on the application server. You can optionally use the BCAN_USER account.
     • Remote device agent: The FTP and SCP accounts must be on the computer where the device agent is installed.
   • Fields mentioned in the following sections specify login credentials for the existing accounts. The paths you specify are relative to the computer on which the device agent is installed.
   • When you select one of the Enabled options, other options appear. These options are indicated in the preceding figure by red rectangles.

   Field	Description
   Transfer Filename Prefix	Enter the file name prefix that is to be used while creating temporary configuration files during span action runs. For a local device agent, default prefix is ena and for a remote device agent, default prefix is agent.

   Field	Description
   Use Proxy File Server	(Optional) Enable the device agent to use proxy file server for file transfer. If you enable this option, you need to provide FTP, SCP and TFTP details of the proxy file server.
   Agent Local File Transfer Directory	(Required if proxy file server is enabled) Enter the local directory on the device agent that holds temporary files received from the proxy file server or sent to the proxy file server while performing span actions.
   Proxy File Server Address	(Required if proxy file server is enabled) Enter a resolvable DNS host name or the IP address of the proxy file server. This address is used by the device agent to communicate with the proxy file server.
   SFTP Port	(Required if proxy file server is enabled) Enter the port number on which the device agent connects to the proxy file server. Default port is 22.
   Proxy File Server IPv4 Address	(Required if proxy file server is enabled) Enter IPv4 address of the proxy file server. Device uses this address to transfer files to and from the proxy file server.
   Proxy File Server IPv6 Address	(Required if proxy file server is enabled) Enter IPv6 address of the proxy file server. Device uses this address to transfer files to and from the proxy file server.

   Notes

   • You must enter an IPv4 or IPv6 address or both. Both fields cannot be null.
   • These fields are applicable to local as well as remote agents.
   • You must enter the IPv4 (numeric) or IPV6 (hexadecimal) address before running any span action on a device using the agent. If you enter a host name, it must be resolvable on the device.

   Field	Description
   TFTP Transfer Enabled	(Optional) Enable the device agent for TFTP support.
   SFTP Transfer Account User Name	(Required if both TFTP and proxy file server are enabled) Specify the user name for the SFTP login. This user account is used by the device agent to establish an SSH connection with the proxy file server. SSH and SFTP are required on the proxy file server. The device agent uses SSH to create, monitor, and delete files on the proxy file server, and uses SFTP to transfer files to and from the proxy file server. On Linux systems, SFTP is typically bundled with the OpenSSH software package. On Windows, you can install an SSH server, where SFTP is an optional component.
   SFTP Transfer Account Password	(Required if both TFTP and proxy file server are enabled) Specify password for the SFTP login. This password is used by the device agent to establish an SSH connection with the proxy file server.
   TFTP Transfer Directory	(Required if TFTP is enabled) Specify where the system should store files temporarily when performing span actions.

   Notes

   • (Applicable only if TFTP is enabled) If the agent is installed in the default location, the typical path for Microsoft Windows is C:\Program Files\BMC Software\BCA-Networks-Agent\tmp.
   • The default TFTP location on most Linux platforms is /tftpboot.
   • (Applicable only if both TFTP and proxy file server are enabled) Device agent still logs on to the device, so any access control list on the device must allow the agent to log on to it. The device access control list does not need to allow logons from the proxy file server, as the proxy file server never makes connections to the device; the device makes connections to the proxy file server.
   • (Applicable only if both TFTP and proxy file server are enabled) While using OpenSSH on Linux, there might be permission issues with files being exchanged via TFTP. That is, when the device agent creates a temporary file in the TFTP directory on the proxy file server, the default permissions given on the file might be too restrictive and the device might not be able to overwrite the file with its configuration file. To resolve this issue, follow these steps:
     1. Log on as a root user to the proxy file server.
     2. Edit the following file: /etc/ssh/sshd_config.
     3. Find a line similar to the following:
        Subsystem sftp /usr/lib/openssh/sftp-server 
     4. Add an additional argument to this line as follows:
        Subsystem sftp /usr/lib/openssh/sftp-server -u 000 
     5. Restart the SSH services.
        Every file created by the SFTP server is assigned the rw-rw-rw- permissions.

   Field	Description
   FTP Transfer Enabled	(Optional) Enable the device agent for FTP support.
   FTP Transfer Account User Name	(Required if FTP is enabled) Specify the user name for FTP login. If proxy file server is enabled, this user name is used by the device agent to establish an SSH connection with the proxy file server.
   FTP Transfer Account Password	(Required if FTP is enabled) Specify the password for the FTP login. If proxy file server is enabled, this password is used by the device agent to establish an SSH connection with the proxy file server.
   Confirm FTP Transfer Account Password	(Required if FTP is enabled) Re-enter the password for confirmation.
   FTP Transfer Home Directory	(Required if FTP is enabled) Specify where the system should store files temporarily when performing span actions.
   FTP User Restricted to Home Directory	(Optional) Specify whether or not the FTP server that is running with this device agent is configured to restrict users to the specific home or root directory. This flag can be used in the adapter XML code. When enabled, the ftpRestrictedPathAccess property will exist. When disabled, the property will not exist. For example, IIS FTP can restrict users to accessing files within a user-defined root directory such as C:\inetpub\ftproot, or vsftpd, whose chroot_local_user setting can restrict users to accessing files within their home directories. This option controls whether or not certain path-aware devices (for example, Cisco Nexus and Juniper WX) include a full path in the FTP copy commands. If the FTP server is unrestricted: A full path is included to ensure the file lands where the agent expects to find it. If the FTP server is restricted: No full path appears in FTP commands (because files are in the relative / or root directory as restricted by the FTP server).
   SCP Transfer Enabled	(Optional) Enable the device agent for SCP support.
   SCP Transfer Account User Name	(Required if SCP is enabled) Specify the user name for the SCP login. If proxy file server is enabled, this user name is used by the device agent to connect to the proxy file server using SFTP client.
   SCP Transfer Account Password	(Required if SCP is enabled) Specify the password for the SCP login. If proxy file server is enabled, this password is used by the device agent to connect to the proxy file server using SFTP client.
   Confirm SCP Transfer Account Password	(Required if SCP is enabled) Re-enter the password for confirmation.
   SCP Transfer Account Home Directory	(Required if SCP is enabled) Specify where the system should store files temporarily when performing span actions.
   SCP Transfer Relative Home Directory	(Optional if SCP is enabled)Specifies the home directory of the SCP user from the device SCP client's perspective. That is, the SCP server might treat paths supplied by a client (a device in this case) as paths relative to some configured root directory. The SCP command for some types of devices must include this relative path (indicated by use of the %scpRelativeHomeDirectory% keyword in the adapter XML code) in place of an absolute path.

4. In the Syslog Listening section, enter information in the following fields to define the syslog information for the device agent:

   Note

   Network Automation has a limited syslog listener, which can be overwhelmed with a high volume of syslog messages. For large networks or networks with high syslog traffic, you should use a true syslog server and forward only those syslog messages that are needed for policy triggers to Network Automation. For details, see Configuring existing syslog servers to forward events.

   When the agent is installed on a Linux system under a non-root user, the syslog port number must be greater than 1024. Ports less than 1024 are privileged to the root user account.
   

   Field	Description
   Syslog Enabled	(Optional) Enable the device agent to receive syslog events.
   Syslog Port	(Required if syslog is enabled) Enter the syslog listening port (default is 514).
   Syslog Log Enabled	(Optional) When enabled, the device agent logs all received syslog events to the local file specified in Syslog Log File Name. Note: Network Automation does not manage this log file. If you enable this feature, you must manage this file or it will continue to grow indefinitely.
   Syslog Log File Name	(Required when Syslog Log Enabled is selected) Specify the local file name for logging received syslog events.
   Syslog Relays For	(Optional) Specify the IP address or host name of one or more relays that forward syslog events to the device agent via the specified device facing NIC. Separate IP addresses or host names by newline. For example: 121.145.67.01 121.145.67.02 Note: Default NIC is always displayed with the name, (Default), irrespective of its actual name.
   Syslog Debugging Enabled	(Optional) If you are experiencing problems receiving syslog events from a device, turn debugging on. All events are logged to the Event Log. BMC strongly recommends enabling debugging only when troubleshooting syslog problems.
   Clear Syslog Queue During Agent Initialization	(Optional) By default, a disabled or disconnected device agent queues syslog messages. Select this option if you do not want the remote device agent to send queued syslog messages to Network Automation during agent initialization.

5. Enter a description for any user defined dynamic field for the device agent.
6. Click Save.

Editing a device agent

On the Admin > Network Admin > Device Agent page, do the following:

1. From the Actions icons, click Edit.
2. Change the details provided while adding the device agent, and click Save.

Adding redundant remote device agents

You can install redundant remote device agents. Failover is done by redirecting the IP address in the remote device agent record to the snapshot remote device agent.

Related topics

Installing-the-remote-device-agent-on-Windows
Installing-the-remote-device-agent-on-Linux