Terminal Server Agent (TSA) Advanced Configuration using Windows Registry
39494
Created On 01/26/21 16:05 PM - Last Modified 12/01/22 09:11 AM
Symptom
Palo Alto Terminal Server Agent (TSA) is a User-ID software installed on compatible Windows Terminal Servers to solve a challenge associated with identifying user to IP address mapping on PAN firewalls. The challenge with user to IP address mapping on Terminal-Servers is as follows:
- By definition, user to IP address mapping identifies one user located at a specific IP address; and by design, Terminal Servers are used by multiple users at any given moment. Hence, the firewall can no longer associate the Terminal Server IP with one User.
- All logged-on users are monitored and individual users are assigned with a specific set of ports - This is called User Source-Port Range
- When a firewall is configured to establish a connection with TSA on TCP port 5009, firewall learns about every logged-on user on the Terminal Server and his/her User Source-Port Range
- When a user initiates any network traffic, the user application requests the Windows Kernel to create a TCP/IP socket, which is mainly a combination of Source-IP:Source-Port + Destination-IP:Destination-Port. TaService collaborates with TAD to intervene in this socket creation and allocate the Source-Port from the User Source-Port Range.
- When the firewall receives this network traffic from the Terminal Server, it identifies the User based on the User's Source-Port
https://knowledgebase.paloaltonetworks.com/KCSArticleDetail?id=kA10g000000ClFdCAK
Environment
Windows Servers
Compatibility matrix can be found in the following document:
https://docs.paloaltonetworks.com/compatibility-matrix/terminal-services-ts-agent/terminal-services-ts-agent-table.html
Cause
Basic TSA configuration caters to most of the deployments, however, depending on the need and the environment, we may need to customise TSA configuration. The following is an exhaustive list of all the Windows registry keys supported by TSA.
Note: Please consult with TAC if additional clarification is needed. Exercise caution when performing Windows registry modifications.
Resolution
| HKEY_LOCAL_MACHINE\SOFTWARE\Palo Alto Networks\TS Agent\Conf |
| Registry Key | Type | Value | Description |
|---|---|---|---|
| EnableTws | DWORD | 0 : disable (default) 1 : enable | When this is enabled, TSA will avoid choosing a port for a new connection, if that port is in Timed-Wait-State. Note: TSA Service (TaService) must be restarted for this registry key to take effect. |
| FreePortBlockDelay | DWORD | 0 : disable (default) N : value in seconds - Enables the Timer | When this is enabled, a function with periodic timer is started within TSA that runs every N seconds - This function scans User Source-Port Range blocks and free all those ports that are no longer in Timed-Wait-State. Note 1: This feature is effective if EnableTws is enabled Note 2: Recommended value of N is the same as that of the registry key that controls the Timed-Wait-State timer assigned to a port. See TwsTimeout below. |
| TwsTimeout | DWORD | 0 : default N : value in seconds | When this is disabled by default, Timed-Wait-State timeout assigned to a port is 240 seconds by default. It can be customized using the Windows TCP/IP registry setting, which is a system-wide setting: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\TcpTimedWaitDelay When N is set, TSA uses this value to assign Timed-Wait-State timeout to a port, which was previously assigned to a socket by TSA and is now being released. When both TcpTimedWaitDelay and TwsTimeout are defined, then TSA uses the value that is the maximum of the two. Note: This feature is effective if EnableTws is enabled |
| HKEY_LOCAL_MACHINE\SOFTWARE\Palo Alto Networks\TS Agent\Log |
| Registry Key | Type | Value | Description |
|---|---|---|---|
| IgnoreDrvLog | DWORD | 0 : disable (default) 1 : enable | When this is enabled, TSA Driver (TAD) logs are not written into TSA Log file i.e. debug.log. Driver logs, the log lines which start with "Drv", are verbose level logs, which may fill up debug.log file and make it difficult to catch non-driver related logs. This need not be enabled, unless advised by TAC. |
| LogPath | String | Windows file-system path to a folder | This can be used to write the log file i.e. debug.log into a different directory. Default Folder: TSA Installation Directory at C:\Program Files\Palo Alto Networks\Terminal Server Agent |
| HKEY_LOCAL_MACHINE\SOFTWARE\Palo Alto Networks\TS Agent\Adv |
| Registry Key | Type | Value | Description |
|---|---|---|---|
| HonorSrcPortRequest | DWORD | 0 : default 1 2 | When a User application tries to create a socket, TSA cares about the Source-Port of the connection. And there are 3 possibilities: a. The application may request for a specific source-port to be allocated to the socket and this Source-port may lie within the configured User Source-Port Range b. The application may request for a specific source-port to be allocated to the socket and this Source-port may lie outside the configured User Source-Port Range. c. The application may NOT request for a specific source-port to be allocated to the socket and let the system (i.e TSA) allocate a source-port for the socket - When HonorSrcPortRequest is set to 0, which is default, TSA will ignore all the above and allocate a source-port from the User's port-range. - When HonorSrcPortRequest is set to 1, TSA will honor the source-port request made by the application in Scenario (b) i.e. When the source-port requested by the application lies outside the configured User Source-Port Range. - When HonorSrcPortRequest is set to 2, TSA will honor the source-port request by the application in Scenario (a) and (b) i.e. TSA will honor every explicit source-port request made by the application. |
| MonitorInterval | DWORD | 1440000 : default N : value in minutes | TSA can be configured to monitor for user-logout events on a periodic basis. Setting this value to 1 would result in TSA checking its Monitored User List for logged off users every minute. |
| DelayStart | DWORD | 0 : default N : value in seconds | When Windows Server boots up, TSA can delay the TSA Driver (TAD) activation for the configured number of seconds. This can be used to avoided any conflict with Anti-Virus Software - This should be discussed specific Anti-Virus vendors that flag such conflicts. |
| DelayAtShutdown | DWORD | N : value in seconds | When Windows Server is shutdown or rebooted, TSA can delay the shutdown operation for the configured number of seconds. When this value is enabled, any value more than 15 defaults to 15 seconds since Windows does not allow delaying the shutdown operation for more than 15 seconds. By default, TSA delays the shutdown by 3 seconds. |
| EnableDetachFilter | DWORD | 0 : default 1 | This setting is recommended to be enabled in Citrix PVS Environment. When this is enabled, TS-Agent activates PVS-specific feature-set (see related registry keys below) to avoid issues such as Non-Responsive Windows Server following PVS Shut-Down or Failover |
| PvsHbInterval | DWORD | N : value in milliseconds | This is used to detect PVS Failover events. And this value is by default set to 500 ms. This value defines the interval at which TSA should send heartbeat messages to TSA Driver. Shorter the interval, faster the failover detection. |
| PvsDetectMode | DWORD | 1 : default 2 3 | This value dictates the PVS Failover detection mechanism in TSA. 1 - heartbeat detection (default) - TSA sends heartbeat messages to TAD in Windows Kernel. 2 - source-port detection - TSA tries to detect if PVS Failover has been initiated by checking if the PVS Failover Port is used in an active socket 3 - hybrid of 1 and 2 |
| PvsHbSuspendTimes | DWORD | 0 : default N : number | When PvsDetectMode is set to 3, this value must be non-zero. When PvsDetectMode is set 3, and PVS failover is detected using heartbeat messages, then TSA delays re-attaching TSA Driver for X seconds, where X is PvsHbInterval multiplied by PvsHbSuspendTimes. For example, X will be 100 seconds when PvsHbInterval = 500 ms and PvsHbSuspendTimes = 200 Note: When PvsDetectMode is set to 3, and PVS failover is detected using source-port detection method, then TSA delays re-attaching TSA Driver for 60 seconds, which is hard-coded. But PVS failover might be detected using heartbeat messages and attempt to reattach the driver right away, while TSA is waiting for 60 seconds for driver reattachment - In such a scenario, to distinguish the failover trigger and to avoid reattaching the driver too soon, PvsHbSuspendTimes should be non-zero. |
| PvsHbFailureTimes | DWORD | N : number | When PVS Failover detection using lost heartbeat messages is used (PvsDetectMode is either 1 or 3), TSA detaches TSA driver when the number of lost heartbeat messages reach the value of PvsHbFailureTimes. The default value is 4 |
| PvsFailoverPort | DWORD | N : number | When PVS Failover detection is performed using source-port, TSA looks for active sockets using this source port. Default value is 6901. This is the port number used by PVS Client Windows Server to communicate with PVS Streaming Server during Failover. |
| PvsNumPattern | DWORD | N : number | When TSA finds PvsFailoverPort in an active socket, the value of PvsNumPattern dictates how many such sockets using PvsFailoverPort should be detected before declaring PVS Failover event. Setting this value to 1 accelerates PVS failover detection. The default value is 2. |