You must meet the following requirements to install and run the TS agent on your system.

Note	To avoid potential issues and to make sure you're using the most up-to-date software, Cisco recommends using the latest released version of the TS agent. To find the latest version, go to the Cisco Support site.

Server Requirements

Install the TS agent on one of the following 64-bit Microsoft Windows Terminal Server versions:

• Microsoft Windows Server 2019

• Microsoft Windows Server 2016

• Microsoft Windows Server 2008 R2

• Microsoft Windows Server 2012

• Microsoft Windows Server 2012 R2

Note	The TS agent installation requires 653KB of free space on your server.

Note	If the TS agent server uses anti-virus software that proxies web traffic, user traffic is typically assigned to the System user and the management center sees those users as Unknown. To avoid the issue, disable web traffic proxying.

The TS agent is compatible with any of the following terminal services solutions installed on your server:

• Citrix Provisioning

• Citrix XenDesktop

• Citrix XenApp

• Xen Project Hypervisor

• VMware vSphere Hypervisor/VMware ESXi 6.0

• Windows Terminal Services/Windows Remote Desktop Services (RDS)

This version of the TS agent supports using a single network interface controller (NIC) for port translation and server-system communications. If two or more valid NICs are present on your server, the TS agent performs port translation only on the address you specify during configuration. A valid NIC must have a single IPv4 or IPv6 address, or one of each type; a valid NIC cannot have multiple addresses of the same type.

Note	If router advertisements are enabled on any devices connected to your server, the devices can assign multiple IPv6 addresses to NICs on your server and invalidate the NICs for use with the TS agent.

System Requirements

This version of the TS agent supports connecting to standalone or high availability management centers running Version 6.4 or later of the System.

See the following sections for information about troubleshooting management center issues with the TS agent.

For information about known and fixed issues in this release, see Resolved Issues.

Management Center does not display user information for System processes

Traffic generated by a service running in the System context is not tracked by the TS agent. In particular, note the following:

• The TS agent does not identify Server Message Block (SMB) traffic because SMB traffic runs in the System context.

• Some anti-virus applications proxy web traffic to an on-premises or cloud gateway to catch viruses before they reach a client computer. However, this means that the anti-virus software typically uses the System account; in this case, the management center sees the users as Unknown. To resolve the issue, disable web traffic proxying.

TS Agent user timeouts do not occur when expected

You must synchronize the time on your server with the time on the management center.

TS Agent does not translate user session ports

The TS agent does not perform port translation in the following cases:

• A user session exceeds the set Max User Sessions value. For example, if the Max User Sessions is set to 29, the TS agent does not perform port translation on the 30th user session.

• All available ports are in use. For example, if your User Ports Range value designates 1000 ports per user session, the TS agent does not perform port translation on the 1001st TCP/UDP connection until the user ends another TCP/UDP connection and releases a port.

• A user session does not have an associated domain. For example, if a server administrator's session is authenticated by the local system and not by an external Active Directory server, the server administrator logs in to the server but cannot access the network and the TS agent does not assign ports to the user session.

TS Agent port translation is not performed as expected

If you manually edit the IP address of the server, you must edit the Server NIC on the TS agent. Then, save your TS agent configuration and reboot your server.

TS Agent reports users as Unknown and rules not matched

If other vendors' Terminal Services agents are running on the same server as the Cisco Terminal Services (TS) Agent, port numbers for user connections might not be in the assigned User Ports range. As a result, users can be identified as Unknown and therefore identity rules do not match for users.

To resolve this issue, disable or uninstall the other Terminal Services agents running on the same server as the Cisco TS agent.

User sessions are not reported to the Management Center as expected

If you update the TS agent configuration to connect to a different management center, you must end all current user sessions before saving the new configuration. For more information, see Ending a Current User Session.

Client application traffic is reported to the Management Center as user traffic

If there is a client application installed on your server and the application is configured to bind to a socket that uses a port that falls outside of your System Ports, you must use the Exclude Port(s) field to exclude that port from translation. If you do not exclude the port and it falls within your User Ports, the TS agent may report traffic on that port as unrelated user traffic.

To prevent this, configure your client application to bind to a socket that uses a port that falls within your System Ports.

Server application timeout, browser timeout, or TS Agent-Management Center connection failure

If an application on the TS agent server ends a TCP/UDP connection but incompletely closes the associated port, the TS agent cannot use that port for translation. If the TS agent attempts to use the port for translation before the server closes the port completely, the connection fails.

Note	You can use the netstat command (for summary information) or the netstat -a -o -n -b command (for detailed information) to identify incompletely closed ports; these ports have a state of TIME_WAIT or CLOSE_WAIT.

If you see this issue, increase the TS agent port range affected by the issue:

• Server application or browser timeout occurs if an incorrectly closed port falls within the User Ports range.

• TS Agent-Management Center connection failure occurs if an incorrectly closed port falls within the System Ports range.

TS Agent-Management Center connection failure

If the TS agent fails to establish a connection with the management center when you click the Test button during configuration, check the following:

• Make sure no more than 50 TS agent clients are attempting to connect to the management center at the same time.

• Confirm that the Username and Password you provided are the correct credentials for a management center user with REST VDI privileges as discussed in Creating the REST VDI Role.

  You can view the audit logs on the management center to confirm that the user authentication from the TS agent succeeded.

• If the connection to the secondary management center in a high availability configuration fails immediately after configuration, this is expected behavior. The TS agent communicates with the active management center at all times.

  If the secondary is the active management center, the connection to the primary management center fails.

System processes or applications on the server are malfunctioning

If a system process on your server is using or listening in on a port that is not within your System Ports range, you must manually exclude that port using the Exclude Port(s) field.

If an application on your server is using or listening in on your Citrix MA Client (2598) or Windows Terminal Server (3389) port, confirm that those ports are excluded in the Exclude Port(s) field.

Management Center shows Unknown users from the TS Agent

The management center shows Unknown users from the TS agent in the following situations:

• If the TS agent driver component fails unexpectedly, user sessions seen during the downtime are logged as Unknown users on the management center.

• Some anti-virus applications proxy web traffic to an on-premises or cloud gateway to catch viruses before they reach a client computer. However, this means that the anti-virus software typically uses the System account; in this case, the management center sees the users as Unknown. To resolve the issue, disable web traffic proxying.

• If the primary management center in a high availability configuration fails, logins reported by the TS agent during the 10 minutes of downtime during failover are handled as follows:

  • If a user was not previously seen on the management center and the TS agent reports user session data, the data is logged as Unknown user activity on the management center.

  • If the user was previously seen on the management center, the data is processed normally.

  After the downtime, the Unknown users are reidentified and processed according to the rules in your identity policy.

NICs are not displayed in the Server NIC list

You must disable router advertisement messages on any devices connected to your server. If router advertisements are enabled, the devices can assign multiple IPv6 addresses to NICs on your server and invalidate the NICs for use with the TS agent.

A valid NIC must have a single IPv4 or IPv6 address, or one of each type; a valid NIC cannot have multiple addresses of the same type.

Management Center test connection fails

If you are logged in to the TS agent server as a local user (as opposed to a domain user), the TS agent test connection with the management center test fails. This happens because, by default, the TS agent does not allow System processes to communicate on the network.

To work around the issue, do any of the following:

• Check Unknown Traffic Communication on the Configure tab page to allow the traffic, as discussed in TS Agent Configuration Fields.

• Log in to the TS agent computer as a domain user rather than as a local user.

TS Agent reports users as Unknown and rules not matched

If other vendors' Terminal Services agents are running on the same server as the Cisco Terminal Services (TS) Agent, port numbers for user connections might not be in the assigned User Ports range. As a result, users can be identified as Unknown and therefore identity rules do not match for users.

To resolve this issue, disable or uninstall the other Terminal Services agents running on the same server as the Cisco TS agent.

TS Agent prompts to reboot on upgrade

Sometimes, even if the machine's IP address does not change, TS agent reports an IP address change after upgrade and prompts you to reboot the server. This happens because the TS agent detects a difference between the IP address and the value of the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TSAgent\{IPv4 | IPv6}

If the key value is different from the configured primary adapter IP address, TS agent reports the change and instructs you to save the configuration and reboot the computer.

This can happen, for example, if the computer was reimaged or restored from backup and DHCP assigns a new IP address.

You can ignore the error but you must reboot the computer after upgrading anyway.

Citrix Provisioniong clients fail to boot

You must configure the TS agent to ignore the UDP port(s) you configured for the Citrix Provisioning server.

The value you specify in the TS agent Reserve Port(s) field must match one of the the Citrix Provisioning First and Last UDP port numbers ports.

Caution

Failure to specify the correct port will cause clients to fail to boot.

Exceptions when saving the TS Agent IP address

In rare circumstances, exceptions are displayed when you attempt to save the TS agent configuration with an invalid IP address. An invalid IP address can be any of the following:

• The same IP address as another device on the network.

• Changing the static IP address in Windows while the TS agent application is open.

Exceptions include the following:

• System.ArgumentException: An item with the same key has already been added.

• System.NullReferenceException: Object reference not set to an instance of an object.

Workaround: Set the TS agent server's IP address to a valid IP address, save the TS agent configuration, and reboot the server.

If you use both the TS agent and the user agent, you can avoid non-critical errors in the logs by excluding the TS agent IP address from the user agent. If the same user is detected by both the TS agent and the user agent, non-critical errors are written to logs.

To prevent this, exclude the TS agent's IP address from being logged by the user agent. For more information, see the Firepower User Agent Configuration Guide.

Resolved Issues