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
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 z/OSMF portable software instance (ServerPac) 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.
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,
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.s dssrv,parms='-d -ERROR'
- 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:
- Only one server can be started and running with transition mode in the whole sysplex.
- 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.
- 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.
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.
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
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.
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.