ALTER LDAP SERVER statement

Alters an LDAP server configuration object.

Syntax

ALTER LDAP SERVER ldapua-server-name
[ ldapua-server-attribs ... ]
[ WITH { SUSPEND | ACTIVATE | REFRESH } ]

ldapua-server-attribs :
SEARCH DN search-dn-attributes ...
| AUTHENTICATION URL { 'url-string' | NULL }
| CONNECTION TIMEOUT timeout-value
| CONNECTION RETRIES retry-value
| TLS { ON | OFF }

search-dn-attributes :
URL { 'url-string' | NULL }
| ACCESS ACCOUNT { 'dn-string' | NULL }
| IDENTIFIED BY ( 'password' | NULL }
| IDENTIFIED BY ENCRYPTED { encrypted-password | NULL }

Parameters

SEARCH DN clause
There is no default value for any parameter in the SEARCH DN clause.
- URL
  Use this clause to specify the host (by name or by IP address), port number, and search to be performed to do the lookup of the LDAP Distinguished Name (DN) for a given user ID. url-string is validated for correct LDAP URL syntax before it is stored in ISYSLDAPSERVER. The maximum size for this string is 1024 bytes.
  
  The format of url-string must comply with the LDAP URL standard. See The LDAP Standard Specification.
- ACCESS ACCOUNT
  Use this clause to specify the LDAP Distinguished Name (DN) used by the database server to connect to the LDAP server. This is not a SQL Anywhere user, but a user created in the LDAP server specifically for logging in to the LDAP server. This user must have permissions within the LDAP server to search for DNs by user ID in the locations specified in the SEARCH DN URL clause. The maximum size for this string is 1024 bytes.
- IDENTIFIED BY
  Use this clause to specify the password associated with the user identified by ACCESS ACCOUNT. The maximum size is 255 bytes, and cannot be set to NULL.
- IDENTIFIED BY ENCRYPTED
  Use this clause to specify the password associated with the user identified by ACCESS ACCOUNT, provided in encrypted form, and is a binary value stored somewhere on disk. The maximum size of the binary is 289 bytes, and cannot be set to NULL. IDENTIFIED BY ENCRYPTED allows the password to be retrieved and used, without it becoming known.
AUTHENTICATION URL clause
Use this clause to specify the host by name or IP address, and the port number of the LDAP server to use to authenticate a user. The DN of the user obtained from a prior DN search and the user password are used to bind a new connection to the authentication URL. A successful connection to the LDAP server is considered proof of the identity of the connecting user. There is no default value for this parameter.
CONNECTION TIMEOUT clause
Use this clause to specify the connection timeout, in milliseconds, to the LDAP server, both for searches for the DN and for authentication. The default value is 10 seconds.
CONNECTION RETRIES clause
Use this clause to specify the number of retries for connections to the LDAP server, both for searches for the DN and for authentication. The valid range of values is 1-60. The default is 3.
TLS clause
Use this clause to specify the use of the TLS protocol on connections to the LDAP server, both for the DN searches, and for authentication. The valid values are ON or OFF. The default is OFF. Use the Secure LDAP protocol by specifying ldaps:// to begin the URL instead of ldap://. The TLS option must be set to OFF when using Secure LDAP.
WITH clause
- WITH SUSPEND
  Sets the state of the LDAP server communications to SUSPENDED (maintenance mode). The connections to the LDAP server are closed and authentication with the LDAP server is no longer performed.
- WITH ACTIVATE
  Activates the LDAP server for immediate use. This changes the state of the LDAP server communications to READY.
- WITH REFRESH
  Reinitializes LDAP user-authentication. This command does not change the state of the LDAP server if it is in the SUSPENDED state. When WITH REFRESH is specified for an LDAP server in the READY or ACTIVE state, connections to the LDAP server are closed. Then, the server option values are reread from the ISYSLDAPSERVER system table and are applied to new connections to the LDAP server and to incoming authentication requests to the database server.

Remarks

ALTER LDAP SERVER...WITH REFRESH is often used on an LDAP server that is in the ACTIVE or READY state to release any resources that may be held, or to reread changes made to files outside of the server, such as a change to the contents of the file specified by the trusted_certificates_file database option.

For other states, ALTER LDAP SERVER...WITH REFRESH has no effect.

If you use this statement in a procedure, do not specify the password (IDENTIFIED BY clause) as a string literal because the definition of the procedure is visible in the SYSPROCEDURE system view. For security purposes, specify the password using a variable that is declared outside of the procedure definition.

Privileges

You must have the MANAGE ANY LDAP SERVER system privilege.

Side effects

Automatic commit.

Standards

ANSI/ISO SQL Standard
Not in the standard.

Example

The following example suspends the fictitious LDAP server named apps_primary.

ALTER LDAP SERVER apps_primary WITH SUSPEND;

The following example changes the LDAP server named apps_primary to use a different URL for authentication on host fairfax, port number 1066, sets connection retries to 10, and activates it.

ALTER LDAP SERVER apps_primary
 AUTHENTICATION URL 'ldap://fairfax:1066/'
 CONNECTION RETRIES 10
 WITH ACTIVATE;