Remote Deployment of Terminal Services Agent using Ansible

Ansible is a configuration management tool typically used to enforce the state of a server in your IT infrastructure. It is used to ensure that the server is indeed in the same state as you would want it to be. It ensures the right packages are installed, the right configuration files are in place, right services are running with the right permissions ...etc. 

 

Administrators write set of rules in a simple language (YAML), in the form of playbooks. Ansible works by connecting to your nodes and pushing out small programs, called "Ansible modules" to them. More details on how Ansible works can be found here

 

Administrators could use Windows Ansible Modules (http://docs.ansible.com/ansible/latest/list_of_windows_modules.html) and remotely install and manage Terminal Services Agent (Admin Guide) 

 

Ansible by default uses SSH to manage Linux. To manage Windows, PowerShell remoting is used. For ansible to manage Windows machines, the steps documented in Ansible site needs to be followed

 

Reference: http://docs.ansible.com/ansible/latest/intro_windows.html

 

The following steps showcases some of the Windows Ansible Modules that where used to write Ansible Playbook to remotely deploy Terminal Services (TS) Agent.

  

Ansible works against multiple systems in your infrastructure at the same time. It does this by selecting portions of systems listed in Ansible’s inventory, which defaults to being saved in the location /etc/ansible/hosts

 

For example, I have defined a TS Agent server (tsagent1.palab.local) under a tag (windows)

 

[windows]
tsagent1.palab.local

 

The following module installs TS Agent on Windows Server. Details on win_package module can be found here

In the below example, the TS Agent installer (*.msi), is hosted on a network share. 

 

- hosts: windows
  tasks:
  - name: Install TS Agent
    win_package:
      path: \\DC1\Users\Administrator\Downloads\TaInstall64.x64-8.0.8-2.msi
      product_id: PAN Terminal Server Agent
      state: present
      user_name: PALAB\Administrator
      user_password: MySuperSecretPass

 

The following command would execute the playbook:

 

ansible-playbook -vvv install_ts.yml 

 

Ansible comes with a tool called as Ansible Vault (link) to encrypt secrets. These secrets can then be used in tasks.

 

Create a secret.yml file.

 

---
mysecret: MySuperSecretPass 

 

Encrypt the secret.yml file

 

# ansible-vault encrypt secret.yml
New Vault password: EnterASuperSecretPass
Confirm New Vault password: EnterASuperSecretPass

Encryption successful

 

Contents of the secret.yml file will be encrypted and will look as shown below (contents will be different in your environment)

 

cat secret.yml 

$ANSIBLE_VAULT;1.1;AES256
63303662393262633865366536333531383362633838316462313739306431656130383730303036
6433623639316439313565393430333430643930623266350a353533666432613438626331396636
32326366386361363363383335333135386364346466636533353434323261373739363533626238
3635613765383762380a306439383961336261316432376266386338643765313064376264633535
35616534613264353739333564633534353230623630653762373632323766643838

 

The variable (for example: mysecret) defined in secret.yml could now be used in the playbooks as follows:

 

- hosts: windows
  tasks:
  - name: secret
    include_vars: secret.yml

  - name: Install TS Agent
    win_package:
      path: \\DC1\Users\Administrator\Downloads\TaInstall64.x64-8.0.8-2.msi
      product_id: PAN Terminal Server Agent
      state: present
      user_name: PALAB\Administrator
      user_password: "{{mysecret}}"

 

To execute the above playbook, you would enter the folllowing command:

 

root@kali:/etc/ansible# ansible-playbook --ask-vault-pass install_ts_vault.yml
Vault password: EnterASuperSecretPass

 

Refer http://docs.ansible.com/ansible/latest/playbooks_vault.html for more details on Vault.

 

(Optional)

 

To authenticate SSL connections between firewall and the TS agent, administrators can upload custom certificates on the TS Agent. 

 

To enable mutual authentication between firewall and TS Agents, perform the following steps on a Master Windows server and use the configurations and certificates from that server and remotely push to other servers.

 

• Install TS Agent on a Windows Server
• Upload custom certificates on that server.
• Do not restart the Terminal Services Agent service
• Copy the registry values from the Windows Server and also copy the custom certificate (custom-cert.pem) from the server's TS Agent installation directory

TS Agent encrypts the certificate's passphrase and creates a registry entry (TSAgentSSL). When the TS Agent's service is restarted, the registry entry will be deleted and the encrypted passphrase will be written to the credential store. The custom certificate (custom-cert.pem) will be loaded and will be used for communication with the firewall.

 

 

 

 

 

 

 

In the following step, we will copy the "custom-cert.pem" from a Master Windows Server on which TS Agent was installed (refer previous steps) to remote TS Agent servers.

"win_copy" (link) is used to copy the custom-cert.pem file to TS Agent installation folder on the remote TS Agent Servers. For example, you will use the command "ansible-playbook -vvv copy_ts_cert.yml" to execute the following task.

 

- hosts: windows
  tasks:
  - name: Copy a single file keeping the filename
    win_copy:
      src: custom-cert.pem
      dest: C:\Program Files\Palo Alto Networks\Terminal Server Agent\

 

In the above task, custom-cert.pem file has been uploaded from Master Windows server to ansible controller and from the ansible controller, it will be copied to remote TS Agent servers

 

root@myans:/etc/ansible# ls files/custom-cert.pem 
files/custom-cert.pem

 

On the remote TS Agent Windows servers, we will update the registry keys. From the previous steps, we took note of the following registy keys:

 

• TSAgentCNEXPIRY
• TSAgentCNISSUER
• TSAgentCNNAME
• TSAgentCNSUBJECT
• TSAgentSSL

 

Using the "win_regedit" module (link), the registry keys on the remote servers will be updated

 

- hosts: windows
  tasks:
  - name: CN Expiry
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: TSAgentCNEXPIRY
      data: Mar 14 20:15:47 2019 GMT
      type: string
  - name: CN Issuer
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: TSAgentCNISSUER
      data: /CN=fw16.palab.local
      type: string
  - name: CN Name
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: TSAgentCNNAME
      data: cert_TS12Cert.pem
      type: string
  - name: CN Subject
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: TSAgentCNSUBJECT
      data: /CN=192.168.75.12
      type: string
  - name: Passphrase
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: TSAgentSSL
      data: ro6lSTTRERERERERTRRRR
      type: string

 

Using the "win_service" module (link), we can restart the Terminal Server Agent service. Once the service is restarted, the TS Agent will use the custom certificate and will move the passphrase from the registry to credential store. Once the registry key (TSAgentSSL) is moved, it will no longer be visible for viewing in the registry.

 

- hosts: windows
  tasks:
  - name: restart service
    win_service:
      name: PAN Terminal Server Agent
      state: restarted

 

On the firewall, you can note that the Connection Security has been configured under (Device > User Identification > Connection Security). In this step, the firewall verifies the CA Certificate that signed the Terminal Service Agent's certificates. 

 

 

 

It is assumed that on the TS Agent Windows Servers, the CA certificates are installed. The CA certificates can be installed via Windows Group Policy (link)

 

One can make changes to the Terminal Services Agent configurations by making modifications to the registry. The following live article (link) discusses how to tune TS Agent registry for better port allocation and handling.

 

The following screen shots show various registry entries that can be modified, which internally re-configures the TS Agents.

 

 

 

Using the "win_regedit" module, we can modify the TS Agent registries. The following tasks show few modifications that where done to TS Agent.

 

Registry values modified for following keys:

 

• StartSize
• MaxSize
• StartPort
• EndPort
• FreePortBlockDelay
• EnableTws
• TSAgentDomain
• OverrideDomainEnable
• ReservedPorts
• BlockSystemPort
• HonorSrcPortRequest

 

- hosts: windows
  tasks:
  - name: set the start size
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: StartSize
      data: 200
      type: dword

  - name: set the max size
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: MaxSize
      data: 2000
      type: dword

  - name: set the start port
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: StartPort
      data: 20001
      type: dword

  - name: set the end port
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: EndPort
      data: 39999
      type: dword

  - name: set the free port block delay
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: FreePortBlockDelay
      data: 245
      type: dword

  - name: set the time wait state
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: EnableTws
      data: 1
      type: dword

  - name: override domain
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: TSAgentDomain
      data: pm.local
      type: string

  - name: enable override domain
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: OverrideDomainEnable
      data: 1
      type: dword

  - name: Reserved Ports
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Conf
      name: ReservedPorts
      data: 
      type: string

  - name: fail port binding when available ports are used up
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Adv
      name: BlockSystemPort
      data: 1
      type: dword

  - name: Honor Source Port Request
    win_regedit:
      path: HKLM:\Software\Palo Alto Networks\TS Agent\Adv
      name: HonorSrcPortRequest
      data: 0 
      type: dword

 

After running the above playbook and after restarting the TS Agent Service, note that the TS Agent configurations got changed. Close the TS Agent User Interface and re-open the UI to take note of the updated changes on the UI

 

 

The same module that was used to install the TS Agents can be used to upgrade the agents. Reconfigure the playbook with the new TS Agent installer file and run the playbook. 

 

Please refer to the live article (XML-API Use Case to Add & Delete TS-Agents) on how to remotely add TS Agents to your firewall. 

 

Use the above guide at your own risk: The steps outlined reflect a setup we conducted in a lab environment.

Results and configuration parameters may vary depending on your environment and should be reviewed and tested before deploying in production.