Jun 9 ’09

Configuring Linux to Authenticate to the z/VM LDAP Server

by Editor in z/Journal

Starting with z/VM Version 5.3, IBM delivered a lightweight directory access Protocol (LDAP) server as a component of tCP/IP. It’s based on the LDAP server provided with z/oS, IBM Tivoli Directory Server (ITDS). on z/VM 5.3, the LDAP server is equivalent to that running on z/OS Version 1.8; on z/VM 5.4, it’s based on the package running on z/OS Version 1.10.

This article discusses how to configure the LDAP server on z/VM and how to integrate it into a Linux security infrastructure. Refer to the references for additional information about LDAP itself. We’ll get right into LDAP on z/VM.

The LDAP server for z/VM has several outstanding features. It provides multiple database back-ends and allows for version 2 or 3 LDAP clients. Multiple authentication methods are available, including CRAM-MD5, Digest-MD5, and simple authentication. Secure transmissions can be handled with Secure Sockets Layer (SSL) and Transport Layer Security (TLS). The LDAP server also supports referrals, aliases, directory access controls, and change logging. Password and password phrase verification can optionally be performed by the z/VM RACF security server.

LDAP on z/VM provides multiple “back-ends,” which is essentially a database manager, not in the traditional sense, but typically a high-performance method to access the data the LDAP server needs to store. The back-ends available are:

• Lightweight Database Manager (LDBM) is the easiest to set up and use. It stores directory information in the z/VM Byte File System (BFS) and keeps the LDAP data in memory during its operation for very fast access, writing it to disk when necessary.

• Secure Database Manager (SDBM) provides a more comprehensive interface to RACF. In addition to LDAP functionality, RACF Security server operations can actually be performed via LDAP, adding, altering, and deleting users or groups, connecting users to groups, removing users from groups, and searching the RACF database.

• The GNU Database Manager (GDBM) back-end is used for auditing changes to the LDAP server.

The LDAP server on z/VM is implemented as a virtual machine called LDAPSRV. It runs under control of the TCP/IP virtual machine, which means TCP/IP can start it. It also requires certain definitions in PROFILE TCPIP and the DTCPARMS files, both of which are delivered with the sample files. LDAPSRV uses TCP/IP port 389 for regular data transfer and port 636 for secure data transfer.

Figure 1 shows the parts of the IBM DTCPARMS file from z/VM that relate to the LDAP server. You can probably leave it intact unless you’re running multiple LDAP servers. Of special note in the file are the mount statement and External Security Manager (ESM) parameters. The mount statement puts various parts of the byte file system into directory structures for use by the LDAP server (like the mount command on Linux). The ESM_Enable tag is used to indicate that RACF is to be used with LDAP.


Multiple LDAP servers can be configured. If you do this, each additional LDAP server will minimally need its own separate mount point in the DTCPARMS file. Also required is a directory entry for the new LDAP server, a new BFS file space, and appropriate permissions. The port number that additional servers will listen on can be specified as a parameter to the server or in the configuration file.

Since the LDAP server uses the byte file system, the associated shared file system server must be started before TCP/IP.

The LDAP server uses two configuration files. Samples of the two files are distributed on TCPMAINTs 591 disk. The sample files are called LDAP-DS SCONFIG and LDAP-DS SENVVAR. Copy LDAP-DS SCONFIG to TCPMAINTs 198 disk as DS CONF. This is the LDAP server’s primary configuration file. Copy LDAP-DS SENVVAR to TCPMAINTs 198 disk as DS ENVVAR. This file contains environment variables for the LDAP server.

You won’t need to change much in the DS ENVVARs file, which is primarily used to set message logging, debugging, and trace output options. The timezone for LDAP reported messages also is set in this file.

Most configuration for the LDAP server occurs in the DS CONF file. If you’re going to use a different name for this file, you will need to indicate this to the LDAP server on the PARMS tag in the DTCPARMS file.

The configuration file includes a global section and a section for each of the three database back-ends. A back-end is activated by uncommenting its associated keyword in the configuration file.

To configure the LDAP server, start by editing the DS CONF file. In the global section, set the adminDN and adminPW keywords as follows:

adminDN "cn=admin"

adminPW secret

The cn, in LDAP terms, stands for Common Name, and is frequently used. In the LDBM section of the file, there’s a database keyword you will need to uncomment to activate the LDBM backend. Additionally, you will need to specify a suffix for the LDAP server; this identifies the LDAP server to any LDAP clients or servers with which it may communicate. For example:

suffix "ou=vm,dc=VMAssist,dc=com"

For initial LDAP server configuration, that’s about all that’s needed. It’s time to start the LDAP server virtual machine. It can be XAUTOLOGged, or you can directly log on to it. It starts up just like the other TCP/IP service virtual machines. When the LDAP process is started, it will issue several messages, some of which appear in Figure 2. Note the values coded in the configuration file and the message indicating the LDAP server is ready to accept requests.


If you use the TCP/IP NETSTAT command, you will see the LDAP server listening on port 389; this indicates the LDAP server is running properly.

LDAP implementations typically provide command line tools to maintain the back-end database(s). LDAP on z/VM is no different. The names are slightly different to fit into the CMS eight-character name standard. The tools are equivalent to those found on other platforms and work similarly.

Here are the commands typically used to maintain the LDAP back-end and their shorter CMS equivalents:

• ldapsearch: LDAPSRCH

• ldapadd: LDAPADD

• ldapmodify: LDAPMDFY

• ldapcompare: LDAPCMPR

• ldapdelete: LDAPDLET

• ldapmodrdn: LDAPMRDN.

These LDAP commands are located on the TCPMAINT 592 disk. Make sure you link to and access it before trying to execute any of the commands.

Some of the LDAP command parameters entered in CMS may require certain special characters that the z/VM Control Program (CP) intercepts. Specific special characters could be used to edit commands as they’re entered. Turn off this default CP behavior to enter LDAP commands. To turn off all line editing, use the command:


To look at information in the LDAP back-end, use the ldapsearch command; the CMS equivalent is ldapsrch.

Use the following ldapsrch command to test communication with the LDAP server:

ldapsrch -h -s base -b "ou=vm,dc=

VMAssist,dc=com" "objectclass=*"

The -h option identifies the host that you want to request information from—the local host in this case. The option -w is the password you entered in the configuration file for adminPW. The -s option is the scope of the search; you ask LDAP to search the base of the LDAP tree. The other search options are all (for the entire tree) or one (which is one level). The -b option tells the LDAP server where to start the search. Our fictional implementation has only one level, but most will have multiple levels and the search can be restricted with this option. The last parameter (without an option) is a filter. It further qualifies the entries the search returns. In this case, you’re requesting all the entries. Figure 3 shows the response and indicates the database is empty. This would be normal since you haven’t put anything into the database.


The search you just executed uses an anonymous bind, which means anyone who knows the address of your LDAP server can access it. The option that controls this feature is turned on in the configuration file. You don’t need to specify credentials on the bind (in the search parameters). This presents a security exposure that you will fix later.

Before you populate the database, you need to add a few schemas to the configuration. A schema helps define LDAP objects and their characteristics, such as what a telephone number is used for, what other fields it may depend on, and how it’s formatted.

When using the LDBM back-end, you need to add two z/VM distributed schemas, USRSCHEM LDIF and IBMSCHEM LDIF, to the LDAP server. They’re on TCPMAINTs 591 disk. The commands to add them are:

ldapmdfy -h -D "cn=Admin" -w

secret -f //USRSCHEM.LDIF -u on

ldapmdfy -h -D "cn=Admin" -w

secret -f //IBMSCHEM.LDIF -u on

The -D flag identifies the LDAP user to be used to bind (or connect) to the LDAP server. The -f flag denotes a filename where the LDIF file resides. The -u option, when turned on, will replace any existing schema items. LDIF stands for LDAP Data Interchange Format and is a standard file format for exchanging data between LDAP servers. An LDIF file can be input to an LDAP operation or output from an LDAP operation and the file can then be transported to another LDAP server.

When these commands execute, only one response is expected:

modifying entry cn=schema

Any other response should indicate an error condition.

To perform Linux authentication with the z/VM LDAP server, an additional schema is required. It’s mentioned in the Security on z/VM Redbook (SG24- 7471). You can download the schema file from ftp://www.redbooks.ibm.com/redbooks/REDP0221/nisSchema.2.ldif. This schema provides the definition for uidnumber, gidnumber, homedirectory, and loginshell, among others important for Linux to use when logging in. After obtaining the schema, upload it to z/VM as NISSCHEM.LDIF. You should make a minor change to line 5 of the file. Change the text ‘dn:cn=schema, <suffix>’ to ‘dn: cn=schema’.

Adding the schema to the LDAP server is just like the previous two examples, except for the file name:

ldapmdfy -h -D "cn=Admin" -w

secret -f //NISSCHEM.LDIF -u on.

As before, unless there’s an error, only one response is expected.

The next step is to add the administrator to the LDAP database. On TCPMAINTs 591 disk is a sample file: SAMPSERV LDIF. It contains sample LDIF entries for various scenarios related to LDAP operations. The first two entries fit what you’re about to do. You’re going to add your top-level organization and your administrator. Based on the first two entries in the file, you’ll create a file called ADMIN LDIF (see Figure 4). Your file contains two entries; the blank line delineates the entries. The first entry adds the organization unit (ou=vm, dc=vmassist, dc=com); the second entry adds the administrator (cn=admin). Use the ldapadd command to add the entries to LDAPs LDBM database:


ldapadd -h -w secret -D

"cn=Admin" -f //admin.ldif

The responses should confirm that both entries were successfully added:

adding new entry ou=vm, dc=vmassist, dc=com

adding new entry cn=Admin, ou=vm,

dc=vmassist, dc=com

A couple of configuration changes are now needed. In the configuration file, DS CONF, you will change the adminDN parameter and comment out the adminPW parameter. Since the LDAP database now has proper entries, the configuration file doesn’t need to be used for password storage:

adminDN "cn=Admin, ou=vm, dc=VMAssist,

dc=com" #adminPW secret

For security reasons, consider turning off anonymous binds in the configuration file. The remainder of the examples won’t use anonymous binds. At this time, restart the LDAP server. The changes will be listed in the configuration summary at start-up.

The ldapsearch command can be used to list the newly added entries:

ldapsrch -h -D "cn=Admin,ou=vm,dc=

vmassist,dc=com" -w secret -b "ou=vm,dc=

vmassist,dc=com" "(cn=Admin)"

Using this command with anonymous binds turned off, you need to provide credentials to perform any operation on the LDAP database. That requires a combination of the -D (to identify who you’re going to perform the operation as) and -w flag (to prove you’re actually that person). The final item on the command line is a filter requesting the search to list only that user. Figure 5 shows the response.

If the z/VM LDAP server is set up to work in conjunction with RACF, the two packages work well together to create a comprehensive security solution. That configuration is covered in the Security on z/VM Redbook. Although RACF provides for a much more secure system, the LDAP server doesn’t require RACF to work and that’s the focus of the remainder of the article.

To use Linux with the z/VM LDAP server, you may need to install some prerequisite software. You can use SUSE Linux Enterprise Server (SLES) 10 Service Pack 2 to perform this configuration.

Start YaST, select Network Services and LDAP client. During this first use of the LDAP client screen, it may notify you that the additional packages are required. If you’re using the text mode screen, it will look something like Figure 6 when filled in. You’ve basically told the Linux LDAP client all about connecting to your z/VM LDAP server, including that when new users are being created on Linux, their home directories also should automatically be created. Clicking on “Advanced Configuration” will bring you to another screen that you can leave as-is. Just click on “Accept.” YaST essentially populates configuration files. One of the files it writes is called /etc/ldap.conf. Figure 7 shows some of the contents with comments removed.


This configuration is exactly what you want. YaST also will modify several other files, /etc/nsswitch.conf, and files in the /etc/security and /etc/pam.d directories. Unfortunately, LDAP doesn’t work the way you want it to after YaST is done modifying the files, so you need to intervene. In /etc/nsswitch.conf, modify the passwd and group lines to look like this:

passwd: files ldap

group: files ldap

The lines in /etc/nsswitch.conf that start with passwd_compat and group_compat can be removed. In the file /etc/ security/pam_unix2.conf, remove the word ‘ldap’ from the lines that start auth, account and password, but leave the lines in the file.

The files in /etc/pam.d configure the Pluggable Authentication Module (PAM) and provide a way to extend the Linux security infrastructure. Change these files to work properly with your LDAP configuration. The format of the files you’re changing is similar. The files are called common-auth, common-account, common-password, and common-session. Figure 8 shows the before and after changes made to common-auth.


The first item on the line in each file must match the part of the filename after the dash. In this case, auth, which is in the filename common-auth. You must set the second item on the new line to “required” and the third item on the new line must be pam_ldap.so. Make the same changes to the other three files. These PAM files control the login, ssh, and passwd services.

You must create an LDIF file to authenticate a new user for Linux use. On CMS, you created a file called RKS1 LDIF. Figure 9 shows the file contents. This LDIF file will contain the appropriate Linux information to allow a login, uid, gid, home directory and initial shell, all of which are normally provided in /etc/passwd during login, but are mimicked here for an LDAP login.

Use the ldapadd command to add the user defined in the LDIF file to the LDAP database:

ldapadd -h -w secret -D "cn=admin

,ou=vm,dc=VMAssist,dc=US" -f //rks1.ldif

The response should indicate the user was successfully added. If you telnet or ssh to the host and login as the user rks1, you should see that the user’s home directory was automatically created, which is what was requested when you configured the LDAP client (see Figure 10). The id command shows that Linux knows user rks1 is uid 2000 and gid 100.


For FTP to work, you’ll have to change the file /etc/pam.d/vsftpd. But this time, just insert the pam_ldap.so line before pam_unix2.so in the auth and account section of the file. When you’re done, you’ll be able to log on to FTP using LDAP authentication.

The ldapsearch command is one way to view the LDAP database, but it isn’t an efficient way to view a large LDAP database. LDAP browsers provide a better method to see the database; they present it in a more intuitive format. Some LDAP browsers also provide editing capabilities. If you have the proper credentials, you can change the data in the database.

YaST contains an LDAP browser. Select Network Services and LDAP Browser from the YaST menu. You will be prompted to enter information about the LDAP server you want to connect to. The smaller window in Figure 11 shows how the LDAP server is configured for the LDAP browser; the rest of the window shows the results of the browse. If you highlight a user and select open, the details about that user will look like Figure 12.


Note that when browsing the directory the passwords are in clear text. A simple configuration change will fix this. In the DS CONF file in the LDBM section, find the pwEncryption option. The LDAP server provides multiple ways to encrypt passwords. For example, you can change the config file to read:

pwEncryption SHA

After this change, restart the LDAP server. Now, when browsing the LDAP server, the passwords are garbled.

Now that the LDAP server is properly configured, other software can be integrated with the LDAP server. All that’s needed is the hostname or IP address and bind credentials. Any software or application that requires a logon can now use z/VM as an authentication source. We’ve tested Apache, application software SugarCRM, and the Hobbit network services monitor.

Starting with version 4.2, the z/VSE operating system now delivers an optional LDAP client. Part of this support allows long userids and passwords. We have the z/VSE LDAP client configured to connect to the LDAP server for z/VM to authenticate z/VSE users. With users defined on the LDAP database on z/VM, we’re able to log on to z/VSE with long userids and passwords. For additional details about the z/VSE LDAP client, see the article by Ingo Franzki in this issue.

LDAP server operation is quite simple. It automatically starts when TCP/IP is initialized and can be shut down by an authorized user with the command SMSG LDAPSRV SHUTDOWN. It doesn’t respond to the shutdown signal.

The z/VM LDAP server is a powerful tool in the System z security arsenal. Coupled with the RACF security server, it provides an excellent way to authenticate your Linux users and other applications.


LDAP System Administration, Gerald Carter, March 2003, O’Reilly

Essential System Administration, Aeleen Frisch, 3rd Edition, August 2007, O’Reilly

Security on z/VM (Redbook): SG24-7471-00

z/VM TCP/IP User’s Guide: SC24-6124-03 (z/VM 5.3); SC24-6124-04 (z/VM 5.4)

z/VM TCP/IP LDAP Administration Guide: SC24-6140-00 (z/VM 5.3); SC24-6140-01 (z/VM 5.4).