Providing Teleport Desktop access to multiple Windows domains with multiple agents

[webvictim]

Edit 2026-03-13: Updated to use teleport-update enable --install-suffix ... instead of the previous manual unit file method.

---

For Windows desktops, Teleport currently has a one agent -> one domain model. If you have multiple Windows domains that you'd like to use with Teleport Desktop access, you will need to run multiple Teleport agents to provide access to each of these domains.

To avoid excess cost, it's possible to run multiple Teleport agents on one VM or physical server. In this example, we'll be provisioning access to two domains:

• example.com (EXAMPLE in NetBIOS terms)
• test.com (TEST in NetBIOS terms)

Teleport config files

Each agent needs its own config file. When you run teleport-update enable with --install-suffix, it automatically uses a config file named after the suffix — so you don't need to manually manage separate data directories or write your own systemd unit files.

example.com

Config file: /etc/teleport_example.yaml (note: this must match the format /etc/teleport_<suffix>.yaml)

version: v3
teleport:
  # this must match the format /var/lib/teleport_<suffix>
  data_dir: /var/lib/teleport_example
  log:
    output: stderr
    severity: INFO
  # use your Teleport proxy hostname here to establish a reverse tunnel
  proxy_server: example.teleportdemo.com:443
  # you'll need a join token for this cluster, created with `tctl tokens add --type=windows_desktop` or similar
  join_params:
    method: token
    token_name: 9bb4b5ebb0785d1c26e0e7e271d408b1
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
windows_desktop_service:
  enabled: true
  ldap:
    # Address of the Domain Controller for LDAP connections. Usually, this
    # address will use port 636, like: domain-controller.example.com:636.
    addr: "WIN-QD644VEFMV7.example.com:636"
    # Active Directory domain name you are connecting to, like: domain-controller.example.com.
    domain: "example.com"
    # LDAP username for authentication. This will be the user logon name you chose for the service
    # account User in step 1 (svc-teleport). This username must include the domain NetBIOS name.
    #
    # For example, if your domain is "example.com", the NetBIOS name for it is
    # likely "EXAMPLE". When connecting as the "svc-teleport" user, you should
    # use the format: "EXAMPLE\svc-teleport".
    #
    # If you are unsure of your NetBIOS name, you can find it by opening a PowerShell command prompt
    # and running:
    # ```
    # (Get-ADDomain).NetBIOSName
    # ```
    username: 'EXAMPLE\svc-teleport'
    insecure_skip_verify: false
    # DER encoded certificate.
    # This should be the path to the certificate exported in step 4 of the Windows setup docs.
    der_ca_file: /etc/teleport/teleport-cluster-ca.cer
  discovery:
    # The wildcard '*' character tells Teleport to discover all the hosts in
    # the Active Directory Domain. To refine the search, specify a custom DN.
    base_dn: '*'

test.com

Config file: /etc/teleport_test.yaml (note: this must match the format /etc/teleport_<suffix>.yaml)

version: v3
teleport:
  # this must match the format /var/lib/teleport_<suffix>
  data_dir: /var/lib/teleport_test
  log:
    output: stderr
    severity: INFO
  proxy_server: example.teleportdemo.com:443
  join_params:
    method: token
    token_name: 9bb4b5ebb0785d1c26e0e7e271d408b1
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
windows_desktop_service:
  enabled: true
  ldap:
    addr: "WIN-OE649VFEMA4.test.com:636"
    domain: "test.com"
    username: 'TEST\svc-teleport'
    insecure_skip_verify: false
    der_ca_file: /etc/teleport/teleport-cluster-ca.cer
  discovery:
    base_dn: '*'

Installing and enabling the agents

Use teleport-update with --install-suffix to set up each agent as an isolated installation. Each suffix gets its own binaries, data directory (/var/lib/teleport_<suffix>), and systemd service — no manual unit file authoring required.

example.com

sudo teleport-update --install-suffix example enable
sudo systemctl enable teleport_example --now

test.com

sudo teleport-update --install-suffix test enable
sudo systemctl enable teleport_test --now

Managing the agents

Check the status of each agent:

sudo systemctl status teleport_example
sudo systemctl status teleport_test

Check logs:

sudo journalctl -u teleport_example
sudo journalctl -u teleport_test

Check the updater status for a specific installation:

teleport-update --install-suffix example status
teleport-update --install-suffix test status

Each installation is fully independent — updating or restarting one agent has no effect on the other. Managed updates will keep each agent on the cluster-advertised version automatically.

You can run as many agents as needed by following this model — adding a config file and running teleport-update enable with a new suffix for each domain.

[webvictim]

This same approach can also be used for other Teleport protocols like ssh_service with some minor changes. This might be useful when trying to run two agents on the same machine which connect to different Teleport clusters.

[Mystikal57]

Hi,
I have an issue with this.
i have a domain A & a domain B, each domain have his proper yaml, pid & data dir
But, when i want to connect on a server in domain A, it user desktop service of domain B, and it fail at login
What can i do ?

Thanks

[webvictim]

Do the machines you're trying to connect to have the same name but in different domains? Teleport will de-duplicate and combine any machines with the same hostname.

[Mystikal57]

No they are very differents 😕 and it's for all domain machines

[Mystikal57]

Yeahhh ! i searched for 3 days, I ended up uninstalling everything and redoing everything.
Everything works now
THANKS

[zmb3]

I'm looking to make this much easier in Teleport 18: #53067

[webvictim]

When that happens, I will update and repurpose this guide as "How to run multiple independent Teleport agents on the same host" as it's often shared for that purpose too!

[loitho]

Hi,
Just to add to this thread as we faced an issue when the teleport agent is updated automatically with the new teleport-update feature.
When the teleport-updater run and updates the agent, it reloads teleport.service to use the new teleport agent version.

However, since we created one or more teleport-agent-xxxxx.service to handle the multiple domains, those service are not reloaded.
To fix this, a simple solution thank to this SO Thread is to add a new file /etc/systemd/system/teleport.service.d/override.conf
Which contains :

[Service]
ExecReload=/bin/sh -c "systemctl reload teleport-agent-*"

Run a systemctl daemon-reload and reload the main teleport.service service, and you'll see that all of the other teleport-agent-xxx.service are being reloaded too whether you triggered it, or teleport-update.

Side-note :
If you wish for the teleport-agent-xxx.service services to be Stopped/Started/Restarted with the main teleport.service service you can simply add PartOf=teleport.service to your teleport-agent-xxx.service systemd file, which would look like :

[Unit]
Description=Teleport agent for test.com
After=network.target
PartOf=teleport.service
[...]

[zmb3]

Hi @loitho - thanks for this.

@webvictim's instructions above are a bit out of date. The best way to run multiple Teleport agents on a single host with managed updates is to install them with a custom install suffix:

$ teleport update enable --install-suffix=xyz

This creates a separate namespaced install with separate systemd units and managed updates.

[loitho]

Hi !
Thanks for that, that's pretty nice and much simpler to manage !
Only thing to remember however is if you use a proxy for teleport-update, to create a new dedicated file for the newly created service as per the documentation.

[webvictim]

I've updated the guide above to use teleport update --install-suffix <name> enable instead - this should be clearer for folks in the future.