Important This version of the product has reached end of support. The documentation is available for your convenience. However, you must be logged in to access it. You will not be able to leave comments.

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 TrueSight Network Automation application server. You can only edit the local device agent.

To add or edit a device agent

  1. Open the Device Agents page by navigating to Admin > Device Agent.
  2. Click Add in the menu to create a new device agent, or select the Edit action to modify an existing device agent.
    AddDeviceAgent.png

  3. Enter or edit 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 TrueSight 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.

    New in 8.9.03Name Resolution Enabled

    (Optional) Select this option to control whether TrueSight 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.

    Local

    (Read-only) Identifies the agent as the local device agent. All installations include a local device agent that resides on the TrueSight Network Automation application server.

  4. (Applicable for versions 8.9.03 and later) In the Device Facing NICs section, 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.

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

    Agent IPv4 Address
    (Not applicable for versions 8.9.03 and later)

    Enter the IPv4 address of the device agent, if the agent has an IPv4 address (for example, 12.34.56.78). For important information, see the note following these fields.

    Agent IPv4 Subnet Mask (CIDR)
    (Not applicable for versions 8.9.03 and later)

    For an IPv4 address, enter the Classless Inter-Domain Routing (CIDR) mask of the device agent (for example, 24).

    Agent IPv6 Address
    (Not applicable for versions 8.9.03 and later)

    Enter the IPv6 address of the device agent, if the agent has an IPv6 address
    (for example, 123:abcd:4567:ef89:0:a1b2:c3d4:e5f6 or fe80::202:b3ff:fe1e:8329).

    Agent IPv6 Prefix Length (Not applicable for versions 8.9.03 and later)

    For an IPv6 address, enter the prefix length of the device agent (for example, 64).

    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 Username

    (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 CopSSH, 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 Username

    (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 Username

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

  6. Enter or edit information in the following fields to define the syslog information for the device agent:

    Note

    TrueSight 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 TrueSight 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: TrueSight 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 directly (for 8.9.02 or earlier versions) or to the device agent via the specified device facing NIC (for 8.9.03 and later versions). 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 TrueSight Network Automation during agent initialization.

  7. Enter a description for any user defined dynamic field for the device agent.
  8. Click Save.

To add 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

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

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*