Setting up and running the LDAP server

The LDAP server must be run as a started task. To do this, you must define the started task for the LDAP server and then you can run the LDAP server by using JCL. The LDAP server can be run in 31-bit mode or 64-bit mode.

Defining the started task for the LDAP server

After you create the LDAPSRV user ID (described in Requirements for a user ID that runs the LDAP server), you must define the DSSRV started task. The examples and the sample startup procedure use the name DSSRV for this task, but you can use any name for it.

To define the started task for the user ID you created, you can use the following RACF® commands.

RDEFINE STARTED DSSRV.** STDATA(USER(LDAPSRV))
SETROPTS RACLIST(STARTED) REFRESH
Note: When using dsconfig to configure the LDAP server, the started task is already defined.

Running the LDAP server using the sample JCL

The JCL needed to run the LDAP server as a started task is provided with the product as a procedure. This JCL can be found in the DSSRV member of GLDHLQ.SGLDSAMP on the system where the LDAP server is installed. If you are using the Start of changez/OSMF portable software instance (ServerPac)End of change for installation, GLDHLQ is GLD. Use DSSRV for starting the LDAP server in 31-bit or 64-bit mode. The JCL procedure can be started in the System Display and Search Facility (SDSF) or from the operator's console after the sample JCL is placed into the installation-specific library for procedures.

The JCL must be tailored before it can be run. In particular, you must change the program name to GLDSRV31 to run the LDAP server in 31-bit mode or GLDSRV64 to run in 64-bit mode. When you are using 31-bit mode, make sure the REGION= parameter is the appropriate size. When you are using 64-bit mode with one or more LDBMs, make sure the MEMLIMIT= parameter is coded with the appropriate size. If it is too small, then the server might not start and the following messages are issued:
GLD1106E LDBM backend initialization failed for backend named LDBM-0001.
GLD1101A Unable to load the database backends.
GLD1007I LDAP server is stopping.
See LDBM performance considerations for size estimates.

For 64-bit mode, the MEMLIMIT= parameter should be coded such that if an LDBM (or more) is included, then the MEMLIMIT size needs to be considered.

To start the LDAP server in SDSF, enter:

/s dssrv

To start the LDAP server from the operator’s console, enter:

s dssrv

The LDAP server has the following optional command-line parameters. One or more of these might be specified when starting the LDAP server.

-f pathname
Name of LDAP server configuration file to be read. The file name is case-sensitive unless it refers to a data set or DD statement. A data set is indicated by //'dataset-name' while a DD statement is indicated by //DD:dd-name. The configuration data set specified by the CONFIG DD statement is used if the -f parameter is not specified. The /etc/ldap/ds.conf configuration file is used if the -f parameter is not specified and the CONFIG DD statement is not defined.
-l ldap_URL
Hostname or IP address and port number on which the LDAP server binds and listen for incoming requests. See the listen parameter at listen ldap_URL for information about the ldap_URL parameter. The -l parameter can be specified multiple times to add more ldap_URL values. The values that are specified using the -l command line parameter override the values that are specified for the listen option in the LDAP server configuration file.

You should reserve the port number or numbers that are chosen here in your TCP/IP profile data set. Port numbers less than 1024 might require additional specification. For more information, see z/OS Communications Server: IP Configuration Guide.

-m
Start the server in maintenance mode rather than normal mode. Maintenance mode severely restricts access to the server. See Basic replication maintenance mode or Advanced replication maintenance mode for more information.
-p port
Note: The port option is deprecated when the listen option is specified. See listen ldap_URL for information about the listen option.
Port number where the LDAP server listens for nonsecure communications. If you specify this parameter, it overrides the port value that might be in the LDAP server configuration file if there are not any listen values that are specified in the configuration file or -l parameters on the command line.
-s secureport
Note: The secureport option is deprecated when the listen option is specified. See listen ldap_URL for information about the listen option.
Port number where the LDAP server listens for secure communications. If you specify this parameter, it overrides the secureport value that might be in the LDAP server configuration file if there are not any listen values specified in the configuration file or -l parameters on the command line.
-d debug_level
The debug level is a mask that might be specified as follows:
  • A decimal value (for example, 32)
  • A hexadecimal value (for example, x20 or X20)
  • A keyword (for example, FILTER)
  • A construct of those values using plus and minus signs to indicate inclusion or exclusion of a value. For example:
    • '32768+8' is the same as specifying 'x8000+x8', or 'ERROR+CONNS'
    • '2147483647-16' is the same as specifying 'x7FFFFFFF-x10' or 'ANY-BER'
    • By beginning the debug level with a minus sign, you can deactivate debug collection for a debug level. For example, "-CONNS" modifies an existing debug level by deactivating connection traces.
    • By beginning the debug level with a plus sign, you can activate debug collection for a debug level. For example, "+CONNS" modifies an existing debug level by activating connection traces.
    Note: Specifying the debug level by using decimal or hex values with a plus or minus sign is not necessarily the same as specifying the sum or difference as the debug level. For example, specifying '7+1' activates the 'TRACE', 'PACKETS', and 'ARGS' debug levels, while specifying '8' activates only the 'CONNS' debug level. Similarly, specifying '16-1' activates only the 'BER' debug level, while specifying '15' activates 'TRACE', 'PACKETS', ARGS', and 'CONNS'.
Table 1 lists the debug levels and related decimal, hexadecimal, and keyword values. Keywords can be abbreviated using the uppercase characters for each keyword.
Table 1. LDAP debug levels
Keyword Decimal Hexadecimal Description
OFF 0 0x00000000 No debugging
TRACe 1 0x00000001 Entry and exit from routines
PACKets 2 0x00000002 Packet activity
ARGS 4 0x00000004 Data arguments from requests
CONNs 8 0x00000008 Connection activity
BER 16 0x00000010 Encoding and decoding of data, including ASCII and EBCDIC translations, if applicable
FILTer 32 0x00000020 Search filters
MESSage 64 0x00000040 Messaging subsystem activities and events
ACL 128 0x00000080 Access Control List activities
STATs 256 0x00000100 Operational statistics
THREad 512 0x00000200 Threading activities
REPLication 1024 0x00000400 Replication activities
PARSe 2048 0x00000800 Parsing activities
PERFormance 4096 0x00001000 Performance statistics
SDBM 8192 0x00002000 Backend activities (SDBM)
REFErral 16384 0x00004000 Referral activities
ERROr 32768 0x00008000 Error conditions
SYSPlex 65536 0x00010000 Sysplex/WLM activities
MULTIServer 131072 0x00020000 Multi-server activities
LDAPBE 262144 0x00040000 Connection between a frontend and a backend
STRBuf 524288 0x00080000 UTF-8 support activities
TDBM 1048576 0x00100000 Backend activities (TDBM)
SCHEma 2097152 0x00200000 Schema support activities
BECApabilities 4194304 0x00400000 Backend capabilities
CACHe 8388608 0x00800000 Cache activities
INFO 16777216 0x01000000 General processing information
LDBM 33554432 0x02000000 Backend activities (LDBM)
PLUGin 67108864 0x04000000 Plug-in extension activities
ANY 2147483647 0x7FFFFFFF All levels of debug
ALL 2147483647 0x7FFFFFFF All levels of debug
Note: The minimum abbreviation for each keyword is shown in uppercase letters.
The debug level for the server can be set at a number of different times.
  • The initial debug level is OFF.
  • Before you start the server, the LDAP_DEBUG environment variable might be set. The server uses this value first. For example,
    export LDAP_DEBUG='ERROR+TRACE'
  • When you start the server, the -d parameter might be specified. The debug level that is specified on this parameter replaces, adds to, or deletes from the preceding debug level. For example,
    • s dssrv,parms='-d ERROR'
      replaces the current debug level that is off or was set by the LDAP_DEBUG environment variable with the new debug level of only ERROR.
    • s dssrv,parms='-d +ERROR'
      adds the ERROR debug level to the current debug level that is off or was set by the LDAP_DEBUG environment variable.
    • s dssrv,parms='-d -ERROR'
      removes the ERROR debug level from the current debug level that is off or was set by the LDAP_DEBUG environment variable.
  • It is possible to change the debug level when the server is running. See Dynamic debugging for more information.
-t transition mode
Starts the server in transition mode. Transition mode is used to update the server compatibility level, or to add or remove shared backends in a sysplex configuration without incurring a complete LDAP service outage. The server running in transition mode provides uninterrupted LDAP services while other servers are being updated and are unavailable.
Notes:
  1. Only one server can be started and running with transition mode in the whole sysplex.
  2. Transition mode is a temporary work mode used during sysplex level configuration updates. Transition mode is removed and changed to normal work mode automatically when this server becomes sysplex owner and the configuration updates complete.
  3. Transition mode is supported for z/OS® Version 2 Release 2 and later. See Updating LDAP configurations settings in a sysplex without server outage for more information.
When the LDAP server is started and is ready, GLD1004I is displayed:
GLD1004I LDAP server is ready for requests.

Running the LDAP server using data sets contains information about using a data set for the LDAP server configuration file. To specify the configuration file as a data set name or a DD name in SDSF, some special syntax is necessary.

To specify a full data set name, it might be necessary to be in the expanded input screen for SDSF. This is accomplished by entering a slash (/) in SDSF. On the expanded screen, it is then possible to specify a data set name for the configuration file. Assuming that the configuration file has been established in data set MYUSERID.DS.CONF, the start command for the LDAP server in expanded input SDSF or the console is:

s dssrv,parms='-f //''''MYUSERID.DS.CONF''''' 

or, if more parameters are needed:

s dssrv,parms='-f //''''MYUSERID.DS.CONF'''' -l ldap://:999' 

If a DD name, CONFIG, was established in the DSSRV procedure, as follows:

CONFIG DD DSN=MYUSERID.DS.CONF,DISP=SHR

the LDAP server can be started from expanded input SDSF or the console by entering:

s dssrv,parms='-f //DD:CONFIG’

To stop the LDAP server in SDSF, enter:

/p dssrv

To stop the LDAP server from the operator's console, enter:

p dssrv

This command causes the LDAP server to shut down.

Restriction: Start of change If the PC callable service is configured with the z/OS LDAP server, you cannot use the REUSASID parameter when restarting the server. For more information, see PC callable support mode.End of change

LDAP server messages and debug output

The LDAP server writes messages to stdout and stderr. Messages sent to stdout and stderr appear in DD:DSOUT in the provided JCL when running the LDAP server. DSOUT appears in the started task log for the LDAP server and can be viewed through SDSF. For information about how to use SDSF, see z/OS SDSF Operation and Customization.

Output from the LDAP server debug facility is directed to the file specified by the LDAP_DEBUG_FILENAME environment variable. If this environment variable is not set, the output is sent to stdout, which is redirected to DSOUT as explained above.

Running the LDAP server using data sets

Note: Using the LDAP configuration utility (dsconfig) to configure your server creates all the necessary files in a partitioned data set.

The LDAP server accepts several of its files as data sets. Data set versions of the configuration file and the environment variables file are not shipped with the LDAP server, but can be created by using the OGET command to copy the file system versions of the files into data sets. For information about the OGET command, see OGET - Copy z/OS UNIX files into an MVS data set in z/OS UNIX System Services Command Reference.

The default data set characteristics for record format and record length (V 255) which OGET uses when creating a new data set are not acceptable for JCL when submitting for batch processing. In order to avoid this, allocate the MYUSER.DSNTIJCL sequential data set to be fixed block 80 before performing the OGET operation.

A data set version of the DSNAOINI file needed for the TDBM and GDBM (when Db2-based) backends can be created by copying and editing the default file provided by Db2. See step 4. The DSNAOINI file name can be specified in the dsnaoini option in the LDAP server configuration file, in a DSNAOINI DD statement in the DSSRV procedure, or in a DSNAOINI environment variable. The DD statement takes precedence, followed by the environment variable, and then the configuration option.

Note: Be sure that use of sequence numbers is turned off when editing this data set.

When the data set versions of these files are available, they can be specified in the DSSRV procedure. The configuration file can be specified by using the CONFIG DD statement, the environment variables file can be specified by using the ENVVAR DD statement, and the DSNAOINI file can be specified by using the DSNAOINI DD statement.