Skip to main content

Ansible installation method for Windows agents

This topic describes how to install the DigiCert​​®​​ agent application on your Windows servers using Ansible in silent mode. Silent-mode installations typically require a companion application to authenticate and provision the agent. However, the Ansible installation method described in this topic doesn’t require the companion application.

Before you begin

DigiCert software downloads

  • DigiCert TLM Agent.exe: Download the latest agent executable (.exe) from the Discovery & automation tools > Agents page in DigiCert​​®​​ Trust Lifecycle Manager. The .exe installer is the recommended installer for agent deployments and is used in this procedure.

    Note

    Agent version 3.1.7 and later is supported.

  • Ansible deployment package (.zip): Download the Ansible deployment package provided here. The .zip file contains the helper script, example playbook files, and configuration templates referenced in this procedure.

Ansible control node requirements

  • Ansible version 2.9 and later

  • Python version 3.6 and later

  • Install the WinRM Python library by running the pip install pywinrm command

Environment variables

  • Set these environment variables on the Ansible server so the playbook can activate the agent without hard-coding secrets:

    • Windows

      # Windows PowerShell  
$env:DC_API_KEY = "your-digicert-api-key"  
$env:TLM_BUSINESS_UNIT = "your-business-unit-id"

    • Linux/macOS

      # Linux/Mac  
export DC_API_KEY="your-digicert-api-key"  
export TLM_BUSINESS_UNIT="your-business-unit-id"

  • (Optional) To securely store the API key using Ansible vault instead of environment variables, follow the steps in the Use Ansible vault to secure the API key section.

  • DigiCert ONE production environment is supported by default. To use demo and non-production environments, include the DCONE_HOST parameter.

    • Windows

      $env:DCONE_HOST= "demo.one.digicert.com"

    • Linux/macOS

      export DCONE_HOST="demo.one.digicert.com"

Target Windows hosts

  • Network connectivity to DigiCert services or a proxy configured

  • Administrator access

  • Windows Server 2012 R2 and later or Windows version 10 and later

  • PowerShell version 5.1 and later

WinRM

WinRM must be enabled to accept remote connections, and configured securely on each target Windows host. Ansible uses WinRM to connect to Windows hosts and execute the agent installation commands remotely.

  1. Ensure that your Ansible inventory is configured to use WinRM over HTTPS (port 5986) with NTLM on Windows.

    ansible_connection=winrm
ansible_winrm_transport=ntlm
ansible_winrm_scheme=https
ansible_port=5986
ansible_winrm_server_cert_validation=validate

  2. Run the following commands on each host to enable and configure WinRM:

    # Enable WinRM with basic configuration
Enable-PSRemoting -Force

# Do NOT enable AllowUnencrypted (leave default: false)
# Do NOT enable Basic authentication (NTLM is used)

# Restrict WinRM access to the Ansible network or host
Set-Item WSMan:\localhost\Client\TrustedHosts -Value "10.160.xx.0/24" -Force

# Restart WinRM service
Restart-Service WinRM

    Replace 10.160.xx.0/24 with the network shared with the Ansible control node or a specific IP address of your Ansible node. This ensures that the Ansible node or a trusted network can connect to WinRM on the target host.

  3. Configure an HTTPS listener.

    The HTTPS listener must be bound to a valid certificate.

    # Create the HTTPS listener bound to the certificate
winrm create winrm/config/Listener?Address=*+Transport=HTTPS `
    '@{Hostname="target-server.yourdomain.com"; CertificateThumbprint="<thumbprint>"}'

    Replace target-server.yourdomain.com with the target host.

  4. If you use a self-signed certificate, set the following variable:

    ansible_winrm_server_cert_validation=ignore

  5. If you trust the self-signed certificate, set these variables:

    ansible_winrm_server_cert_validation=validate
ansible_winrm_ca_trust_path=/path/to/self-signed-cert.pem

API key for DigiCert ONE

You need a DigiCert® ONE service user token ID to authenticate agents for silent mode installation. See Create a service user for detailed instructions about how to create and download an API service user token ID. Make sure the service user includes the following properties:

  • Accounts that can use this service user includes your DigiCert​​®​​ Trust Lifecycle Manager account.

  • DigiCert ONE Manager access includes Trust Lifecycle.

  • Roles and permissions includes the Infrastructure admin and User and certificate manager user roles for Trust Lifecycle Manager.

Notice

You can reuse the same service user token ID to install Windows or Linux agents in silent mode. You can disable the service user after the agents are deployed.

Step 1: Prepare the Ansible control node

  1. Create the Ansible project directory on the control node to store the agent software and installation files.

    This directory structure reflects the required files necessary to perform the deployment:

    remote-install/
  ansible.cfg
  ansible-deploy-tlm-agent.yaml
  confirm-environment.yaml
  files/
    Deploy-TLMAgent.ps1
    DigiCert TLM Agent.exe
  inventory.ini

    The following table describes the contents of the remote-install/ directory:

    Directory / File

    Location

    Description

    remote-install/

    remote-install/

    Project directory on the control node containing all configuration files, playbooks, and other installation resources for the deployment.

    ansible.cfg

    remote-install/ansible.cfg

    Ansible configuration file defining project-specific settings, inventory location, and connection parameters.

    inventory.ini

    remote-install/inventory.ini

    File listing the target hosts where the agent will be deployed.

    ansible-deploy-tlm-agent.yaml

    remote-install/ansible-deploy-tlm-agent.yaml

    Primary Ansible playbook used to deploy the agent on target systems.

    confirm-environment.yaml

    remote-install/confirm-environment.yaml

    Test Ansible playbook to validate connectivity and environment readiness before executing the main deployment.

    files/

    remote-install/files/

    Subdirectory containing the executable file and the deployment script.

    DigiCert TLM Agent.exe

    remote-install/files/DigiCert TLM Agent.exe

    Agent executable file used by the deployment script.

    Deploy-TLMAgent.ps1

    remote-install/files/Deploy-TLMAgent.ps1

    PowerShell script that is executed on the target Windows hosts to install the agent.

  2. Verify your Ansible installation by running the ansible --version command.

    Make sure your Ansible configuration file (ansible.cfg) includes the following settings:

    [defaults]
inventory = ./inventory.ini
host_key_checking = False
retry_files_enabled = False
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible_facts
fact_caching_timeout = 86400

# Logging
log_path = ./ansible.log

# Output
stdout_callback = default
result_format = yaml
bin_ansible_callbacks = True
deprecation_warnings = False


[privilege_escalation]
become = False

[ssh_connection]
pipelining = True

Step 2: Set up the Ansible inventory file

Update the inventory file (inventory.ini) stored in the project directory with the target hosts. The agent is installed on these hosts.

[windows]
target-server ansible_host=10.0.0.1
target-server ansible_host=10.0.0.2
target-server ansible_host=10.0.0.3

[windows:vars]
ansible_connection=winrm
ansible_winrm_transport=ntlm
ansible_winrm_server_cert_validation=ignore
ansible_port=5985
ansible_user=administrator
ansible_password=Jp39xxxxL

Notes:

  • The name of the hosts (windows in this example) must match what's in your Ansible playbook.

  • Use windows:vars to set any additional operational parameters that Ansible should use to access and install the agent on each host.

    Warning

    Including administrator credentials directly in the inventory file is not recommended for production environments. For improved security, we recommend storing credentials using Ansible vault or similar secret management solutions.

Use the following command syntax to test your Ansible inventory configuration:

 ansible-inventory -i {INVENTORY_FILE} --list -y

If successful, the command lists all the hosts in your Ansible inventory file.

Step 3: Create the Ansible playbook

The Ansible playbook drives the software installation process and defines all the required tasks.

Ensure that the playbook (ansible-deploy-tlm-agent.yaml) is added to the /remote-install directory on the control node (see Step 1).

Configure the playbook using the sample playbook provided in the downloadable deployment (.zip) package as a reference.

Note

  • To specify an alternate installer for upgrade, set the upgrade_installer_path variable. To use the default, leave the variable blank ("").

  • If you do not specify an agent_name, the agent will automatically register using the inventory_hostname defined in the Ansible inventory.

  • If you want to securely store the API key using Ansible Vault, follow the steps in the Use Ansible vault to secure the API key section.

Step 4: Test connectivity to Windows hosts

Before you run the Ansible playbook to deploy the agent, validate that Ansible can connect to your Windows hosts using WinRM.

Run the following command to test connectivity:

ansible-playbook -i inventory.ini confirm-environment.yaml

Step 5: Prepare the PowerShell deployment script

Ensure that the Deploy-TLMAgent.ps1 PowerShell script is in the remote-install/files/ directory on the control node. When you run the Ansible playbook, the script is automatically copied to each Windows host and is executed with the parameters based on the selected deployment_action.

The script performs the following core deployment tasks on each host:

  • Install the agent with custom parameters

  • Detect whether existing agent services exist on the node

  • Activate the agent using API key and business unit ID

  • Upgrade or uninstall the agent

  • Support proxy configuration

  • Write logs and return success or failure codes

Step 6: Deploy the agent using the Ansible playbook

Execute the playbook on the Ansible control node to run the defined tasks for installing the agent onto your Windows hosts.

Depending on the deployment (deployment_action) you want to perform, run any one of the following commands:

Note

If you are using Ansible Vault to store the API key, you will be prompted to enter the vault password after running the selected command.

  • Install and activate (default): Installs the agent and immediately activates it in Trust Lifecycle Manager.

    ansible-playbook -i inventory.ini ansible-deploy-tlm-agent.yaml

    Note

    This command is used for the deployment procedure described in this topic.

  • Install only (no activation): Installs the agent without activating it.

    ansible-playbook -i inventory.ini ansible-deploy-tlm-agent.yaml -e "deployment_action=Install"

  • Activate only (agent already installed): Activates an existing agent.

    ansible-playbook -i inventory.ini ansible-deploy-tlm-agent.yaml -e "deployment_action=Activate"

  • Upgrade: Upgrades the currently installed agent to a newer version.

    ansible-playbook -i inventory.ini ansible-deploy-tlm-agent.yaml -e "deployment_action=Upgrade"

  • Uninstall: Removes the agent and all associated data from the hosts.

    ansible-playbook -i inventory.ini ansible-deploy-tlm-agent.yaml -e "deployment_action=Uninstall"

  • Uninstall (preserves data): Removes the agent but retains data and certificates in case of a roll back.

    ansible-playbook -i inventory.ini ansible-deploy-tlm-agent.yaml -e "deployment_action=UninstallPreserveData"

Alternatively, you can use tags to execute specific phases of the playbook without running the full workflow. The playbook includes the following tags:

  • install: Copies files and runs the deployment script without verification.

    ansible-playbook -i inventory.ini ansible-deploy-tlm-agent.yaml --tags install

  • verify: Checks service status and reviews the deployment log.

    ansible-playbook -i inventory.ini ansible-deploy-tlm-agent.yaml --tags verify

  • cleanup: Removes temporary files from hosts.

    ansible-playbook -i inventory.ini ansible-deploy-tlm-agent.yaml --tags cleanup

  • report: Displays the final deployment summary.

    ansible-playbook -i inventory.ini ansible-deploy-tlm-agent.yaml --tags report

Step 7: Verify the installation

Go to Discovery & automation tools > Agents and verify that the agent has been installed on your host system and activated for use with Trust Lifecycle Manager. For more details, see View agent details.

(Optional) Use Ansible vault to secure the API key

Instead of providing the API key through the environment variables, you can securely store it using the Ansible vault. This prevents the API key from being exposed in the environment variables or stored in plain text within scripts or configuration files.

  1. Create a vault-encrypted variables file.

    1. Create a vault file in your project.

      ansible-vault create group_vars/all/vault.yml

    2. Set the vault password when prompted.

      New Vault password:
Confirm New Vault password:

    3. Add the following variable:

      vault_dc_api_key: "<YOUR API KEY>"

      Save and exit the editor.

    4. Confirm that the file is encrypted.

      cat group_vars/all/vault.yml

      You should see encrypted content beginning with: $ANSIBLE_VAULT;1.1;AES012...

  2. Reference the Ansible vault variable in the playbook.

    When you configure the playbook (in Step 3), do the following:

    1. Update the value of the api_key variable from "{{ lookup('env', 'DC_API_KEY') | default('', true) }}" to "{{ vault_dc_api_key }}".

    2. Set no_log: true to all tasks that process the API key.

      For example:

      no_log: true
tags: install
   ...
debug:
   ...
no_log: true
tags: install

  3. Enter the vault password to execute the playbook.

    When you execute the playbook (Step 6), you will be prompted to enter the vault password.

    Vault password:
In this section: