> For the complete documentation index, see [llms.txt](https://newdocs.keeper.io/kcm-linux-rpm-method/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://newdocs.keeper.io/kcm-linux-rpm-method/authentication/authenticating-users-with-ldap/using-multiple-ldap-servers.md).

# Using Multiple LDAP Servers

If your Active Directory or LDAP deployment spans multiple servers, Guacamole can be configured to use each of your LDAP servers using `ldap-servers.yml`, a configuration file similar to `guacamole.properties` and located within `/etc/guacamole`. When a user authenticates with a Guacamole instance configured to use multiple LDAP servers, **each configured LDAP server is tried, in order, until authentication succeeds**. Authentication fails only if none of the defined LDAP servers accept the user's provided credentials.

When `ldap-servers.yml` is used, the values within `guacamole.properties` still have meaning, but instead serve as defaults for the LDAP servers defined in `ldap-servers.yml`.

### Overview of `ldap-servers.yml` <a href="#id-.usingmultipleldapserversv2.x-overviewofldap-servers.yml" id="id-.usingmultipleldapserversv2.x-overviewofldap-servers.yml"></a>

The `ldap-servers.yml` file contains a single YAML list of LDAP servers, with each server definition consisting of a simple list of configuration properties and values. These configuration properties are identical to [the LDAP properties available within `guacamole.properties`](/kcm-linux-rpm-method/advanced-configuration/guacamole.properties/ldap-configuration-properties.md) except that the "ldap-" prefix is omitted.

For example, a simple `ldap-servers.yml` that defines two LDAP servers that may be used to authenticate users would contain the following:

```
- hostname: server1.example.net
  user-base-dn: OU=Users,DC=example,DC=net
  username-attribute: sAMAccountName
  search-bind-dn: CN=Guacamole,OU=Services,DC=example,DC=net
  search-bind-password: SomePassword!

- hostname: server2.example.net
  user-base-dn: OU=Users,DC=example,DC=net
  username-attribute: sAMAccountName
  search-bind-dn: CN=Guacamole,OU=Services,DC=example,DC=net
  search-bind-password: SomePassword! 
```

When a user attempts to log in, Guacamole will attempt to authenticate the user against the first defined LDAP server (`server1.example.net`). If that fails, Guacamole will proceed with the next (`server2.example.net`), and so on. Only if authentication fails against *all* defined LDAP servers will authentication against LDAP fail overall.

### Abbreviating common LDAP parameters <a href="#id-.usingmultipleldapserversv2.x-abbreviatingcommonldapparameters" id="id-.usingmultipleldapserversv2.x-abbreviatingcommonldapparameters"></a>

Since the only property that varies between the two servers in the above example is the hostname, and since `guacamole.properties` serves as the source of default values when `ldap-servers.yml` is used, the configuration details common to all servers would be better specified within `guacamole.properties`:

```
ldap-user-base-dn: OU=Users,DC=example,DC=net
ldap-username-attribute: sAMAccountName
ldap-search-bind-dn: CN=Guacamole,OU=Services,DC=example,DC=net
ldap-search-bind-password: SomePassword!
```

The contents of `ldap-servers.yml` can then be reduced to only the hostnames:

```
- hostname: server1.example.net
- hostname: server2.example.net
```

### Splitting users across multiple LDAP servers <a href="#id-.usingmultipleldapserversv2.x-splittingusersacrossmultipleldapservers" id="id-.usingmultipleldapserversv2.x-splittingusersacrossmultipleldapservers"></a>

LDAP servers listed within `ldap-servers.yml` may optionally be restricted to only certain users with the "`match-usernames`" option. This option accepts both a single string and an array of strings, where each string is a Perl-compatible regular expression. Additionally, if the regular expression includes a capturing group, **the contents of the first capturing group will be used as** [**the username representing the user's Guacamole identity**](/kcm-linux-rpm-method/authentication/authenticating-users-with-ldap/using-ldap-with-a-database.md).

For example, to define two LDAP servers covering distinct domains, splitting usage of those LDAP servers by whether the user enters their username as "DOMAIN1\username" or "DOMAIN2\username", you would edit your `ldap-servers.yml` to contain something like the following:

```
- hostname: domain1.example.net
  user-base-dn: OU=Users,DC=domain1,DC=example,DC=net
  match-usernames: DOMAIN1\\(.*)

- hostname: domain2.example.net
  user-base-dn: OU=Users,DC=domain2,DC=example,DC=net
  match-usernames: DOMAIN2\\(.*)
```

Each of the LDAP servers defined above will only be used if their corresponding regular expression matches the username specified by the user. Since each of the regular expressions in the above example define a capturing group around the username component of the "DOMAIN\username" format, that portion of the provided username will be used to determine the user's identity. If a user successfully authenticates as "DOMAIN1\myusername", then:

* The captured portion ("myusername") will be used to[ identify the user's corresponding account in Guacamole's database](/kcm-linux-rpm-method/authentication/authenticating-users-with-ldap/using-ldap-with-a-database.md).
* The captured portion ("myusername") will be used when [mapping the user to their fully-qualified LDAP DN.](/kcm-linux-rpm-method/authentication/authenticating-users-with-ldap.md)

If there are multiple username formats that need to be accepted by each LDAP server, multiple regular expressions may be specified. For example, to match both "MYDOMAIN\myusername" and the UPN-style "<myusername@mydomain.example.net>" formats, you would specify:

```
- hostname: domain1.example.net
  user-base-dn: OU=Users,DC=domain1,DC=example,DC=net
  match-usernames:
    - DOMAIN1\\(.*)
    - (.*)@domain1\.example\.net

- hostname: domain2.example.net
  user-base-dn: OU=Users,DC=domain2,DC=example,DC=net
  match-usernames:
    - DOMAIN2\\(.*)
    - (.*)@domain2\.example\.net
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://newdocs.keeper.io/kcm-linux-rpm-method/authentication/authenticating-users-with-ldap/using-multiple-ldap-servers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.