VSI OpenLDAP ACME Agent for OpenVMS

This is a mandatory directive.

Specify the DNS host names or IP addresses of one or more LDAP directory servers. Use one or more space characters between the server names or IP addresses (do not use commas or tabs to delimit).

For example:

server = dc1.corp.com dc2.corp.com 10.1.11.111

The OpenLDAP ACME agent tries to connect to the first server in the list. If the target server is unreachable, the next server is attempted. This process repeats until the list is exhausted.

If the list contains more than one server, note the following:

This is a mandatory directive.

Specify the LDAP TCP port number that the directory servers listen on. Default value is 389 (the standard, insecure LDAP port).

Set the value to 636 to use the standard, secure LDAP port (LDAPS).

Specify the minimum level of encryption required for communications over the LDAP port specified by the "port" directive. If a stronger encryption method than the one specified can be negotiated with the server, the stronger method will be used.

Possible values are:

• NONE - Clear text mode; all requests, responses, and data (including passwords) are transmitted in clear text.
• The "port" directive must be set to 389 (port = 389).
• Recommended only for troubleshooting purposes.

Values for LDAPS options (when using "port = 636"):

• SSLTLS - Negotiate TLS encryption with the server.
• SSLTLS12 - Select only TLSV1.2 encryption.

Values for StartTLS options (when using "port = 389"):

• StartTLS - Negotiate TLS encryption with the server.
• StartTLS12 - Select only TLSV1.2 encryption.

This is a mandatory directive.

Specify the distinguished name (DN) of an LDAP directory server account that is created for and used by the OpenLDAP ACME agent to bind to and search the directory server.

The "bind_dn" and "bind_password" directives provide the credentials used to bind (authenticate) to the directory servers.

If the directory server is an Active Directory domain controller, a domain administrator may obtain the distinguished name of an OpenLDAP ACME agent user account using either of the following methods:

Set the "bind_dn" directive to the distinguished name displayed.

This is a mandatory directive.

Specify the password for the account specified by the "bind_dn" directive. Specify the password using the correct case, but do not enclose it in quotes.

Specify a timeout value in seconds, which defines the maximum number of seconds the OpenLDAP ACME agent will wait for a response to a bind request before abandoning the attempt.

By default, if the target directory server is not reachable, each bind request to a directory server can take as long as 75 seconds to timeout (TCPIP default connection establishment timeout). If multiple servers are specified in the "server" directive value, the user login session (i.e., a TELNET session) may expire before the OpenLDAP ACME agent is able to contact a working directory server.

Use the "bind_timeout" directive when listing multiple servers in the "server" directive. For example, if the "server" directive list consists of 3 servers and the "bind_timeout" directive is set to three seconds, the overall timeout period is approximately 9 seconds.

This is a mandatory directive.

Specify the LDAP schema attribute that contains the username for login purposes. For Active Directory LDAP servers, this must be set to "samaccountname". For OpenLDAP servers, the attribute name is often "uid" but may be different in your configuration.

This is a mandatory directive.

Specify the distinguished name of an LDAP directory element on the directory server where the search for a user account begins.

The LDAP users are stored in a tree structure in the directory server. The user entries must be present under the specified "base_dn" tree element as sub-tree elements. The OpenLDAP ACME agent will search for matching entries based on the attribute specified by the "login_attribute" directive. To search the entire directory tree, specify the distinguished name of the domain. For example, if the domain name is CORP.COM:

base_dn = DC=corp,DC=com

Indicates the set of entries at or below the LDAP directory location specified by the "base_dn" directive that may be considered potential matches for a search request. Valid keywords? are:

Specify an LDAP search filter. The default value is no filter.

Specify the number of seconds before an LDAP search request times out. The default is 20 seconds. Use the "search_timeout" directive when listing multiple servers in the "server" directive (see the "bind_timeout" directive for more information).

Specify the username mapping mechanism to use. There are three options (more information, see Section 3, ''Username Mapping''):

This directive is applicable only for global username mapping. Specify the name of the schema attribute on the LDAP directory server that will be used to specify username mapping data. For example, to use the Description field of user accounts, specify mapping_attribute = description.

A newly created attribute on the directory server may also be created to store the username mapping data. This attribute should be an IA5 multi-valued string.

This directive is applicable only for global username mapping. The mapping_target is an arbitrary string of your choice that the OpenLDAP ACME agent uses when searching for the user's OpenVMS username in the field specified by the "mapping_attribute" value. The format of the entry is string/OpenVMS-username. For example, if the OpenLDAP ACME agent configuration file contains:

mapping = server
mapping_attribute = description
mapping_target = VMSUser

To map a user's LDAP directory account to their OpenVMS account, populate the Description field of the user's LDAP directory account with the string VMSUser/, followed by the user's OpenVMS username. For example, if the user's OpenVMS username is JDOE, specify:

VMSUser/jdoe

No extraneous text may precede the "mapping_target" directive string or follow the username in the field specified by the "mapping_attribute" directive. Neither the "mapping_target" string nor the username are case-sensitive.

This directive is applicable only for local username mapping. Specify the complete file specification of the text file used for mapping user accounts. Entries in the file use the syntax:

LDAP-username, VMS-username

where LDAP-username is the username of the user in the LDAP directory server.

Changes to a username mapping file are not dynamic; however, the username mapping file can be reloaded without restarting the ACME Server with SYS$SYSTEM:LDAP_LOAD_LOCALUSER_DATABASE.EXE (or restart ACME Server).

Comments (!) in the username mapping file are supported.

Do not include the domain name as part of the Windows username in the username mapping file, even when using a multi-domain configuration.

Enclose usernames containing spaces in quotes.

For information on how to populate and load the contents of the username mapping file, see the included template file – SYS$STARTUP:LDAP_LOCALUSER_DATABASE.TXT_TEMPLATE.

This directive is applicable for multi-domain support. The name specified here should match the short domain name of the LDAP server's domain.

The definition of the LDAPACME$INIT logical name determines the "default" domain. The domain specified in the configuration file, which corresponds to the first file in the list defined by LDAPACME$INIT, determines the "default" domain. Users in the "default" domain do not need to specify their login domain name as part of their username when logging into the OpenVMS host. However, users of the other domains must include the domain name specified by the "domain" directive as part of their username when logging into OpenVMS, using the syntax:

domain\username

For example, if the logical name LDAPACME$INIT is defined as:

$ SHOW LOGICAL LDAPACME$INIT
   "LDAPACME$INIT" = "SYS$COMMON:[SYS$STARTUP]LDAPACME$CONFIG-STD-US.INI"(LNM$SYSTEM_TABLE)
           = "SYS$COMMON:[SYS$STARTUP]LDAPACME$CONFIG-STD-EMEA.INI"

And the configuration file LDAPACME$CONFIG-STD-US.INI contains domain = us, while the configuration file LDAPACME$CONFIG-STD-EMEA.INI contains domain = emea.

When users in the EMEA domain login to the OpenVMS host, they must specify a username of EMEA\username, while users in the US domain do not need to (but may) specify the domain name (US) when logging in.

The domain name specified is not case sensitive, must not contain any special characters, and must not be longer than 25 characters.

This directive is optional.

Specify the complete specification of a file containing the PEM-format public key of the certificate authority (CA) that signed the certificate of the LDAP directory server. The OpenLDAP ACME agent needs that public key to verify the LDAP server's certificate (except when port_security = none). Verifying the server's certificate ensures that the OpenLDAP ACME agent is connecting to the intended directory server rather than an imposter. If this directive is not included, the LDAP server's certificate is not verified.

If the "server" directive lists multiple servers and the certificates of those servers were signed by different CAs, add the public key certificate information for each CA into the same file. For example:

$ TYPE CACERTS.PEM
-----BEGIN CERTIFICATE-----
.......
CA 1 public key certificate in base64 encoded format
.......
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
.......
CA 2 public key certificate in base64 encoded format
.......
-----END CERTIFICATE-----
$

Specify one of the following values ("standard" is the default):

If you are using Windows Active Directory LDAP servers, specify password_type = active-directory, otherwise any attempts to use the DCL command SET PASSWORD by externally authenticated users will fail.

Specify one of the following values ("replace" is the default):

Applies only when the "password_type" directive is set to "standard". Some directory servers require the old password to be supplied when changing the userPassword attribute; others do not.