All servers in this configuration share one Server Name on the login screen. Each login starts at the primary. If it times out or the appliance cannot reach it, the appliance tries the enabled backups in order. A rejected password ends the attempt. The next login starts at the primary again.
Configure the primary
- Sign in as a local administrator and open System Settings → LDAP Server. Keep a local administrator session available while testing.
- Turn on Enable LDAP Server and enter Server Name, for example
corp_ldap. To add redundancy to an existing domain, keep its current name. - Enter the primary address, select LDAP Service Protocol, and set LDAP or LDAPS Service Port. Use port 389 for LDAP or LDAP with StartTLS, or 636 for LDAPS, unless your directory uses a different port. Changing the protocol leaves the port value in place. For TLS, enable Verify Server Certificate to check the server identity and trust chain on every connection.
- Set Base DN, the username attribute (for example,
uid), and the group ID attribute (for example,gidNumber). Configure the corresponding local group mapping. To assign a fallback when the directory supplies no numeric group ID, turn on Enable Default Group and choose Default User Group Name.
Add and test backup servers
- Under Backup Servers, select Add backup server. Enter the backup address and confirm its port. A new backup is enabled and starts with the primary’s port. The replica shares the primary’s LDAP protocol, certificate verification, base DN, username attributes, and group mapping.
- Add any additional backups. Backup 1 is the first choice after the primary. Use Move up or Move down to change the order. Turn off Enable backup 1 to skip that entry while retaining its settings and position. Remove deletes the selected backup.
- Under Auth. Server Test, enter a test username and password, then select Test and Apply. With the domain enabled, the appliance tests the primary and each enabled backup independently. It saves the settings when every tested endpoint accepts the credentials. Test credentials are used once and are cleared afterward. Leave the test username empty to save without a login test.
- Open a fresh login session, select the same Server Name, and sign in. Use the same login name format that the directory accepts. For example, if Base DN is
dc=example,dc=org, an account can sign in asuid=9ops.infra,ou=people,dc=example,dc=org. Withuidas the username attribute, its session name is9ops.infra.
Configure from the CLI
This example sets 192.0.2.10 as primary and 192.0.2.11 as the first backup. For this LDAPS example, substitute your directory base DN and use server addresses covered by the certificates. The example assumes a local group mapping for the directory GID.
config system auth ldap enable true name corp_ldap ip 192.0.2.10 port 636 protocol ldaps verify_server_certificate true base_dn dc=example,dc=org username_attr uid gid_attr gidNumber
config system auth ldap backup 1 ip 192.0.2.11 port 636 enable true
show system auth ldap
show system auth ldap backup
Use the next consecutive position to add a backup. Editing an existing position preserves omitted fields. For example, to pause and later re-enable backup 1 during maintenance, run the first command before maintenance and the second afterward.
config system auth ldap backup 1 enable false
config system auth ldap backup 1 enable true
| Task | Command |
|---|---|
| List domain settings and available fields | config system auth ldap ? |
| List the available backup fields | config system auth ldap backup 1 ? |
| Change only the first backup’s address | config system auth ldap backup 1 ip 192.0.2.12 |
| Move an existing second backup ahead of the first | config system auth ldap backup 2 move 1 |
| Remove the backup currently in position 2 | config system auth ldap backup 2 remove |
| Disable the whole login domain and retain its settings | config system auth ldap enable false |
Moving or removing an entry renumbers the list. Check show system auth ldap backup before making another numbered edit. Before changing an endpoint, record its address, port, position, and the shared directory and TLS settings.
Field reference
| CLI Field | UI Field | Type Or Values | Notes |
|---|---|---|---|
enable |
Enable LDAP Server | Boolean | Enables or disables LDAP authentication. |
name |
Server Name | String | Domain name users select at login. |
ip |
Server IP Address | IP address or host string | LDAP server address. |
port |
LDAP or LDAPS Service Port | Integer from 1 to 65535 |
Common values are 389 for LDAP and StartTLS, 636 for LDAPS. |
protocol |
LDAP Service Protocol | ldap, ldap_with_starttls, or ldaps |
Selects plain LDAP, StartTLS, or LDAPS. |
verify_server_certificate |
Verify Server Certificate | Boolean | Verify the TLS certificate and server identity against trusted CAs. |
base_dn |
Base DN | String | Directory search base, such as DC=example,DC=com. |
username_attr |
Attr. Name for POSIX User Name | String | Attribute list used to identify the user name. |
gid_attr |
Attr. Name for User Group ID | String | Attribute list used to identify the LDAP group ID. |
default_group_enable |
Enable Default Group | Boolean | Allows fallback to a local group. |
default_group_name |
Default User Group Name | Existing local user group | Used when LDAP group ID mapping does not find a local group. |
backup |
Backup Servers | Ordered list | Numbered from 1 in failover order. |
test_username |
Username for Test (Empty to skip) | String | Used only for this test. |
test_password |
Password for Test User | Password string | Used only for this test. |
Troubleshooting
- An endpoint fails Test and Apply. Check the address and port reported for that endpoint. Verify its directory settings and test the same user DN and password on that replica.
- A login stops at the primary. Check whether the primary rejected the credentials. Failover handles connection failures and timeouts. All enabled endpoints share a ten-second login deadline. A certificate verification error also ends an LDAP login. Check the certificate name and trust chain on the affected replica.
- Login succeeds with unexpected permissions. Check the directory group ID and its mapping to a local group. If no numeric ID is available, review the default-group setting.