PAM-modules Manual (split by chapter):   Section:   Chapter:FastBack: sql   Up: Top   FastForward: umotd   Contents: Table of ContentsIndex: Concept Index

7 pam_ldaphome

The pam_ldaphome facilitates maintenance of a centralized LDAP user database. It can be installed as a part of authentication or session management stack. When invoked, it creates the user home directory, if it does not already exist, and ensures his .ssh/authorized_keys is in sync with the database.

Apart from common options, this module understands only one implementation-specific option:


Read configuration from file. Default is pam_ldaphome.conf in sysconfdir.

Actual module configuration is read from the configuration file.

7.1 Configuration file for pam_ldaphome

Pam_ldaphome reads its configuration from two files: the configuration file supplied with the config command line option and the system-wide LDAP configuration file /etc/ldap.conf.

The syntax of the former is described in SQL configuration file. Allowed keywords are discussed below.

The syntax of the /etc/ldap.conf configuration file is described in LDAP configuration file in ldap.conf(5) manpage. Its parsing can be suppressed using the ldap-config statement (see below).

From /etc/ldap.conf, the following statements are used: ‘base’, ‘binddn’, ‘bindpw’, ‘tls_cacert’, ‘uri’. The ‘ssl’ statement is understood if its value is ‘start_tls’ or ‘off’. Other values are silently ignored.

In general, all statements defined below can appear in both files. However, since /etc/ldap.conf is read by other system utilities as well, we do not recommend using pam_ldaphome-specific keywords in it.

The values read from pam_ldaphome configuration file override those obtained from the standard LDAP configuration file.

LDAP configuration

pam_ldaphome config: base searchbase

Use searchbase as the starting point for the search instead of the default, e.g.:

base dc=gnu,dc=org,dc=ua
pam_ldaphome config: binddn dn

Use the Distinguished Name dn to bind to the LDAP directory. Example:

binddn cn=Manager,dc=gnu,dc=org,dc=ua
pam_ldaphome config: bindpw password

If binddn statement is used, this statement supplies the password for simple authentication.

pam_ldaphome config: bindpwfile file

Read password for simple authentication from file.

pam_ldaphome config: filter expr

Sets the LDAP filter expression to return a user profile. The expr should conform to the string representation for search filters as defined in RFC 4515.

pam_ldaphome config: ldap-config file

Read LDAP configuration from file (default – /etc/ldap.conf). Special value ‘none’ disables this feature.

pam_ldaphome config: ldap-version v

Sets the LDAP version to use. Valid values for v are ‘2’ and ‘3’ (the default).

pam_ldaphome config: pubkey-attr text

Defines the name of the attribute which holds the user public key.

pam_ldaphome config: tls val

Controls whether TLS is desired or required. If val is ‘no’ (the default), TLS will not be used. If it is ‘yes’, the module will issue the ‘StartTLS’ command, but will continue anyway if it fails. Finally, if val is ‘only’, TLS is mandatory, and the module will not establish LDAP connection unless ‘StartTLS’ succeeds.

pam_ldaphome config: tls-cacert val
pam_ldaphome config: tls_cacert val

Full pathname to the CA certificate file. Used if TLS is enabled. The second form (‘tls_cacert’) is for use in /etc/ldap.conf file.

pam_ldaphome config: uri arg

Sets the URI of the LDAP server to consult for the user profile. Example:

uri ldap://

Home directory creation

pam_ldaphome config: allow-home-dir path

If present, this option controls where pam_ldaphome should try to create home directories. Its value is a list of directories separated by colons. The user’s home directory will be created only if the directory part of its name is listed in path.

pam_ldaphome config: copy-buf-size n

Sets the size of the buffer used to copy files from the skeleton directory to the newly created home. The default size is 16384 bytes.

pam_ldaphome config: home-dir-mode mode

Sets the mode (octal) for the created user directories.

pam_ldaphome config: skel dir

Supplies the name of a skeleton directory. The contents of this directory is copied to the newly created user home directory. The file modes and permissions are preserved.

Authorized keys file

pam_ldaphome config: authorized_keys name

Sets the pathname (relative to the home directory) for the authorized keys file. The default is ‘.ssh/authorized_keys’. For normal operation, this value must be the same as the value of ‘AuthorizedKeysFile’ variable in sshd_config. Unless you change the latter, there’s no need to edit it.

pam_ldaphome config: import-public-keys bool

When set to ‘no’, disables importing public keys from LDAP. You may wish to use this option if you are using openssh 6.1 or later with ldappubkey as ‘AuthorizedKeysCommand’.

pam_ldaphome config: keyfile-mode mode

Sets the mode (octal) for the created authorized keys file.

pam_ldaphome config: user-keys-boundary string

User key files can contain both keys managed by pam_ldaphome and added by the user. These two groups of keys must be separated by a special comment line, which informs the module that all keys below it must be retained.

This feature is enabled by the user-keys-boundary setting. The delimiting comment is formed as ‘#string’. E.g. if the configuration file contains:

user-keys-boundary :user-defined

then the line ‘#:user-defined’ can be used to delimit ldap-synchronized and user-specific keys.

Access control

pam_ldaphome config: allow-groups group [group...]

Only handle members of the listed groups.

pam_ldaphome config: min-gid n

Sets the minimal GID. For users with GIDs less than n, pam_ldaphome returns PAM_SUCCESS immediately.

pam_ldaphome config: min-uid n

Sets the minimal UID. For users with UIDs less than n, pam_ldaphome returns PAM_SUCCESS immediately. This allows you to have a set of basic users whose credentials are kept in the system database and who will not be disturbed by pam_ldaphome. See also ‘min-gid’ and ‘allow-groups’.

Initialization script

The following statements instruct pam_ldaphome to invoke an external command after initializing the user home directory. This can be used to customize the files copied from the skeleton directory according to the user.

pam_ldaphome config: exec-timeout seconds

Sets maximum time the initrc-command is allowed to run. If it runs longer than seconds, it will be terminated with a ‘SIGKILL’, and the module will return PAM_SYSTEM_ERR.

pam_ldaphome config: initrc-command command

Run command after populating the user home directory with files from the skeleton directory.

The user login name is passed to the command as its argument. Before invoking, the current working directory is changed to the user home, standard input is closed, and standard output is redirected to standard errror.

The command is run under the current user privileges, unless the variable initrc-root is set to true.

The command should exit with code 0 on success. If it exits with a non-zero code, pam_ldaphome will report ‘PAM_SYSTEM_ERR’.

pam_ldaphome config: initrc-root bool

When set to true, initrc-command will be run with root privileges. In this case, the environment variable PAM_LDAPHOME_USER will be initialized to the name of the user who is trying to log in.

pam_ldaphome config: initrc-log file

This statement redirects the standard output and error from the initrc-command to file.

pam_ldaphome config: initrc-environ env ...

Modifies the environment of initrc-command.

This statement takes one or more arguments. Each argument can be one of:

- (a dash)

Clear the environment. This is understood only when used as the first argument.


Unset the environment variable name.


Unset the environment variable name only if its value is val.


Retain the environment variable name.


Define environment variable name to have given value.


Retain variable name and append value to its existing value. If no such variable is present in the environment, it is created and value is assigned to it. However, if value begins with a punctuation character, this character is removed from it before the assignment. This is convenient for using this construct with environment variables like PATH, e.g.:


In this example, if PATH exists, ‘:/sbin’ will be appended to it. Otherwise, it will be created and ‘/sbin’ will be assigned to it.


Retain variable name and prepend value to its existing value. If no such variable is present in the environment, it is created and value is assigned to it. However, if value ends with a punctuation character, this character is removed from it before assignment.

The value part can be enclosed in single or double quotes, in which case the usual shell dequoting rules apply.

7.2 Example of pam_ldaphome configuration

This example assumes you are using GNU/Linux. The aim of this configuration is to allow remote access via sshd to users present only in the LDAP database, using ssh shared-key authentication. The exact way of achieving this depends on the version of opennsh daemon in use. The openssh version 6.2p1 introduced a possibility to obtain public keys by invoking an external command, so there are two main usage cases, as described in the subsections that follow.

7.2.1 Openssh versions prior to 6.2p1

The user public keys are kept in ‘grayPublicKey’ attribute of his LDAP entry. When a user logs in for the first time, his home directory does not exist yet and consequently sshd is not able to verify his key. Therefore it falls back to the interactive authentication (it is supposed, of course, that ‘UsePAM’ is set to ‘yes’ in the sshd configuration file). The authentication stage is supposed to create user home directory, populate his .ssh/authorized_keys with his public keys and present user with a descriptive text prompting him to cancel his current authentication attempt and retry it again. The corresponding pam.conf section looks as follows:


sshd auth [success=ok try_again=1 default=die] \ 
sshd auth [success=done ignore=ignore default=die] \
sshd auth [default=die] file=/etc/ldaphome.txt

The first line does most of the job. If succeeds in creating the user directory it will return ‘try_again’. This will cause skipping the next stack entry, so control will go to, which will print a descriptive text from /etc/ldaphome.txt and exit indicating authentication failure.

The module returns ‘success’ if the user who is trying to log in should not be handled by it (e.g. because his UID is less than the ‘min-uid’ setting, etc.). In this case, authentication will be handled by This allows normal system accounts to function as usual. This is very important, because it will allow to access the machine even when the LDAP database is not available for some reason.


The configuration handles users with uids and gids greater than or equal to 1000 and pertaining to the group ‘remote’. User home dirs are populated from the /etc/skel directory.

min-uid 1000
min-gid 1000
allow-groups remote 
skel /etc/skel
base dc=gnu,dc=org,dc=ua
filter (&(objectClass=posixAccount)(uid=$user))
pubkey-attr grayPublicKey


The LDAP schema should include an attribute to keep the user public keys. The author uses the following schema:

# depends upon:
#    nis.schema

# Attribute Definitions
attributetype ( NAME 'grayPublicKey'
    DESC 'SSH public key'
    EQUALITY caseExactIA5Match
    SYNTAX )
# Object Class Definitions
objectclass ( NAME 'grayAccount'
    DESC 'Abstraction of an employee account'
    SUP posixAccount AUXILIARY
    MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory )
    MAY ( userPassword $ loginShell $ gecos $ grayPublicKey ) )


The ‘passwd’ and ‘group’ entries in /etc/nsswitch.conf file should be as follows:

passwd:         files ldap
group:          files ldap

7.2.2 Openssh versions 6.2p1 and newer

Versions of openssh starting from 6.2p1 are able to read public keys from the standard output of an external program. This can be used to improve the configuration described in the previous subsection so that the user is not required to cancel his session upon the very first connection. To that effect, pam-modules includes the utility ldappubkey, distributed in the examples subdirectory (see ldappubkey). Copy that utility to a convenient location (/usr/libexec would be a wise choice), and add the following two lines to your /etc/ssh/sshd_config file:

AuthorizedKeysCommand           /usr/libexec/ldappubkeys
AuthorizedKeysCommandUser       nobody

Two points should be observed. First, the argument to AuthorizedKeysCommand (and all its pathname components) must be owned by root and be writable only for the owner. Second, the use of AuthorizedKeysCommandUser statement is mandatory. Of course, you can chose any suitable user (not necessarily ‘nobody’).

After restarting sshd, it will invoke ldappubkeys on each log in attempt with the login name of the user as its argument. The utility will look up that user in the LDAP database, and if found, will print his piblic keys on its standard output. The sshd will then read the keys and try to authorize user against each of them. If none of the keys matches the private key supplied by the user, sshd will attempt public keys read from the user’s ~/.ssh/authorized_keys file (or another file, if overridden by the AuthorizedKeysFile statement in /etc/ssh/sshd_config).

Most of the configuration described in the previous subsection remains in effect. However, the authentication stack won’t be invoked if ldappubkeys functions successfully. The pam_ldaphome module must be invoked as a part of ‘session’ stack instead. The following example assumes it is invoked at the top of the stack:

sshd session [success=ignore try_again=ignore default=die] \

7.3 ldappubkey

The ldappubkey utility is a simple Perl program which takes user login name as its argument and produces on the standard output public ssh keys for that user, each on a separate line. The program is designed for use with openssh version 6.2p1 or higher. It is distributed in the examples subdirectory and is not installed by default. The only prerequisite for its use is the Net::LDAP module. See Use of pam_ldaphome with openssh version 6.2p1, for instructions of its use.

The utility looks up for its configuration in the following files: /etc/ldap.conf, /etc/ldap/ldap.conf and /etc/openldap/ldap.conf. These files are tried in this order and the first one of them that exists is read.

The following configuration statements are used (all keywords are case-insensitive):

ldap.conf: uri ldap[si]://[name[:port]] ...

Specifies the URI of the LDAP server (or servers) to connect to. The default is ‘ldap://’.

ldap.conf: base dn

Specifies the default base DN to use when performing LDAP operations. The base must be specified as a Distinguished Name in LDAP format.

ldap.conf: binddn dn

Specifies the default DN to bind as.

ldap.conf: bindpw password

Specifies the password to use with binddn.

ldap.conf: uid attr

Defines the name of the attribute to use instead of uid. The LDAP record is searched using the following filter:

ldap.conf: publickeyattribute attr [attr...]

List of attributes that hold the public keys. Default is ‘grayPublicKey’ (see ldap-schema).

ldap.conf: publickeyfilter filter

LDAP filter used to retrieve the objects that contain public keys. The filter string can contain the following variables:


The value of the ‘uid’ setting (see above).


First command line argument.


Full hostname of the machine.

The default value is:


7.4 usergitconfig

The examples subdirectory of the pam-modules distribution contains a program usergitconfig which is designed to customize user’s .gitconfig file using attributes from his LDAP entry.

The command reads the .gitconfig file and replaces any occurrence of ‘${attr}’ with the value of the LDAP attribute attr. Not defined attributes are replaced with empty strings.

To use this utility with pam_ldaphome, first make sure you have Perl Net::LDAP module installed. Copy usergitconfig to some location of preference (say, /usr/libexec), and add the following to pam_ldaphome configuration file:

skel /etc/skel
initrc-command /usr/libexec/usergitconfig

The /etc/skel directory should contain the file .gitconfig. Suppose its contents is as follows:

        name = ${cn}
        email = ${mail}

Then, after successful completion of pam_ldaphome, the user’s .gitconfig file will contain his real name and email set properly from the database.

For the gituserconfig LDAP configuration options, see ldap.conf statements.

PAM-modules Manual (split by chapter):   Section:   Chapter:FastBack: ldaphome   Up: ldaphome   FastForward: umotd   Contents: Table of ContentsIndex: Concept Index