sysadmin ldap

Configures or lists an LDAP URL, specifies the access accounts for LDAP user authentication, or verifies an LDAP URL or login-related parameters.

Syntax

sysadmin ldap [<operation> [,<parameter1>, [,<parameter2>]]]

Valid <operation> [,<parameter1>, [,<parameter2>]] options are:

set_primary_url, '<ldapurl>'
set_access_acct, '<account_distinguished_name>', '<account_password>'
list_urls
list_access_acct
check_url, '<ldapurl>' [,'<tls>'] [,'<dn>', '<pwd>']
check_login, '<login_name>'
set_secondary_url, '<ldapurl>'
set_secondary_access_acct,'<account_distinguished_name>',<account_password>
starttls_on_primary, 'true|false'
starttls_on_secondary, 'true|false'
set_timeout, timeout_in_milliseconds    
set_retry_limit, retry_number   
set_cacert_file, 'full/path/to/CARootCertFile'
refresh_ldapua_module

Parameters

set_primary_url, '<ldapurl>'

specifies the primary LDAP URL search filter. The syntax for <ldapurl> is:

ldapurl:=ldap://host:port/node?attributes?base | one |sub?filter

where:

host: Is the host name of the LDAP server.
port: Is the port number of the LDAP server.
node: Specifies the node in the object hierarchy at which to start the search.
attributes: Is a list of attributes to return in the result set. Each LDAP server can support a different list of attributes.
base: Qualifies the search criteria, specifying a search of the base node.
one: Qualifies the search criteria, specifying a search of node and a sublevel below node.
sub: Specifies a search of node and all node sublevels.
filter: Specifies the attribute or attributes to be authenticated. The filter can be simple, for example, "uid=*", or compound, for example, "&(uid=*)(ou=group)". The standard attribute for a login name is "uid" on an OpenLDAP or "samaccountname" on Microsoft Active Directory.

Note The URL syntax is specific to the LDAP server and uses a wildcard (*) to describe the login name.

set_access_acct, '<account_distinguished_name>', '<account_password>'

Specifies the distinguished name (DN) and password of an LDAP server user account that Replication Server uses to conduct search and administrative functions.

If you do not specify the administrative DN and password, Replication Server uses anonymous binding to LDAP server for searching the user account.

list_urls

Displays LDAP URL search filters.

list_access_acct

Displays the LDAP server access account DN, which is set in the "set_access_account" parameter.

check_url, '<ldapurl>' [,'<tls>'] [, '<dn>', '<pwd>']

Verifies an LDAP URL search filter. Verifies whether the connection to the LDAP server is running.

check_login, '<login_name>'

Verifies the existence of a user account in the LDAP server, but does not authenticate the user.

set_secondary_url, '<ldapurl>'

Specifies the secondary LDAP URL search filter.

Note

A null URL string or failed connection to the primary LDAP URL causes Replication Server to attempt failover to a secondary LDAP URL if specified. Replication Server does not fail over to the secondary URL for failures returned by LDAP search operations.

set_secondary_access_acct, 'account_distinguished_name', 'account_password'

Specifies the secondary DN, and password of an LDAP server user account that Replication Server uses to conduct search and administrative functions.

If you do not specify a search filter, Replication Server uses anonymous binding to LDAP server for searching the user account.

starttls_on_primary, 'true|false'

Specifies whether to start or stop the Transport Layer Security (TLS) connection on a primary LDAP server.

starttls_on_secondary, 'true|false'

Specifies whether to start or stop the TLS connection on a secondary LDAP server.

set_timeout

Specifies timeout value, in milliseconds, Replication Server to wait for a response from the LDAP server before rejecting the request. The default value for set_timeout is 10,000 milliseconds (10 seconds). Valid range is between 1 to 3,600,000 (one hour).

retry_limit

Specifies the number of retry attempts limit after transient errors. The default value is 3. Valid range for retry_limit is between 1 to 60.

set_cacert_file, 'full/path/to/CARootCertFile'

Configures the full path to the trusted certificate authority (CA) root file, which accepts the PEM-format files for Secure Sockets Layer (SSL) communication. For example, the default file location is '$SYBASE/config/trusted.txt'

See Replication Server Administration Guide: Volume 1> Manage Replication Server Security > Manage SSL Security > SSL Overview.

refresh_ldapua_module

Reintializes the entire LDAP user authentication module.

Do not restart the Replication Server for the reinitialization to take effect. This parameter releases any resources that may be held by LDAP user authentication module, or rereads changes made to files outside of Replication Server, such as a change to the contents of CA root file.

Examples

Example 1

Configures an LDAP URL search filter in Replication Server using the sublevel criteria:

sysadmin ldap, set_primary_url, 
'ldap://myhost:389/dc=mycompany,dc=com?distinguishedName?sub?uid=*?'

Example 2

Specifies an LDAP server login name and password for authentication:

sysadmin ldap 
set_access_acct, 'cn=Manager, dc=mycompany, dc=com', 'password'

Example 3

Verifies an LDAP server connection:

sysadmin ldap, check_url, 'ldap://myhost:389'

sysadmin ldap, check_url, 
'ldap://myhost;389', 'cn=Manager,dc=mycompany,dc=com', 'password'

sysadmin ldap, check_url, 'ldaps://myhost:636'

sysadmin ldap, check_url, 'ldap://myhost:389', 'tls'

Example 4

Starts TLS connection on a primary LDAP server:

sysadmin ldap, starttls_on_primary, 'true'

Example 5

Sets the CA root file path of the target LDAP server for SSL connection:

sysadmin ldap, set_cacert_file, 'user/sybase/config/trusted.txt'

Example 6

Sets timeout value for Replication Server to wait before rejecting the request in milliseconds:

sysadmin ldap, set_timeout, 3000

Example 7

Sets the number of retry attempts limit after a transient error:

sysadmin ldap, set_retry_limit, 6

Usage

The LDAP vendor determines the syntax of the search filter. In all cases, the search filter specifies the attribute name that uniquely identifies the user in the form “<attribute> = wildcard” as in “cn=*.”
The first attribute with a wildcard in a compound filter must define the relative distinguished name ; Otherwise, authentication fails. For example, if "uid = ray, dc=sybase, dc=com" is the user DN, then its parent DN is "dc=sybase, dc=com" and its relative DN is "uid = ray"
When a search filter is added, Replication Server verifies that it uses valid LDAP URL syntax and has references to an existing node. To ensure that the valid string returns expected values, choose the search filter carefully, and verify it when you configure Replication Server.
You can use SSL or TLS for LDAP user authentication in Replication Server, either by:
- Setting the CA root file path and entering the "ldaps://" scheme to specify the LDAP URL, or,
- Enabling TLS using the sysamdin ldap on the target LDAP URL. The LDAP URL scheme must be "ldap://" with no "s".

Permissions

sysadmin ldap requires "sa" permission.