authorSergey Poznyakoff <>2014-04-04 14:34:38 (GMT)
committer Sergey Poznyakoff <>2014-04-04 14:34:38 (GMT)
commit38546020318af9cee0fa36344858cb204547d11a (patch) (side-by-side diff)
parentced163f408f4ce4096855af61876796e43c8d975 (diff)
Add pam_ldaphome(8) manpage.
Diffstat (more/less context) (ignore whitespace changes)
3 files changed, 276 insertions, 7 deletions
diff --git a/doc/.gitignore b/doc/.gitignore
index 8ae6011..6ae86e7 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -2,6 +2,7 @@ Makefile
diff --git a/doc/ b/doc/
index 76df136..d42be90 100644
--- a/doc/
+++ b/doc/
@@ -27,9 +27,9 @@ endif
dist_man_MANS += pam_log.8
-# dist_man_MANS += pam_ldaphome.8
+ dist_man_MANS += pam_ldaphome.8
dist_man_MANS += pam_umotd.8
@@ -45,10 +45,10 @@ $(top_srcdir)/ $(top_srcdir)/doc/
echo ".ds ET $(sysconfdir)"; \
} >
-BUILD_MANS=pam_fshadow.8 pam_mysql.8 pam_pgsql.8
+BUILD_MANS=pam_fshadow.8 pam_mysql.8 pam_pgsql.8 pam_ldaphome.8
-pam_fshadow.8 pam_mysql.8 pam_pgsql.8:
+pam_fshadow.8 pam_mysql.8 pam_pgsql.8 pam_ldaphome.8:
@@ -59,8 +59,7 @@ pam_fshadow.8 pam_mysql.8 pam_pgsql.8:
- pam_fshadow.8in\
- pam_mysql.8in
+ $(BUILD_MANS:.8=.8in)
rm -rf manual
diff --git a/doc/pam_ldaphome.8in b/doc/pam_ldaphome.8in
new file mode 100644
index 0000000..e023942
--- a/dev/null
+++ b/doc/pam_ldaphome.8in
@@ -0,0 +1,269 @@
+.\" This file is part of PAM-Modules -*- nroff -*-
+.\" Copyright (C) 2001-2014 Sergey Poznyakoff
+.\" PAM-Modules is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\" PAM-Modules is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" GNU General Public License for more details.
+.\" You should have received a copy of the GNU General Public License
+.\" along with PAM-Modules. If not, see <>.
+.TH PAM_LDAPHOME 8 "April 4, 2014" "PAM-MODULES" "Pam-Modules User Reference"
+pam_ldaphome \- create and populate user home directories
+ [\fBconfig=\fIFILE\fR]\
+ [\fBdebug\fR[\fB=\fINUMBER\fR]]\
+ [\fBwaitdebug\fR]\
+ [\fBaudit\fR]
+For each login attempt, checks if the home directory for that user
+exists, and if not, creates it. The created directory is populated
+with files taken from a specified \fIskeleton directory\fR. The
+file \fB.ssh/authorized_keys\fR is created and populated with
+\fBSSH\fR public keys for that user, obtained from an LDAP database.
+If home directory already exists, \fBpam_ldaphome\fR checks if
+contents of the \fB.ssh/authorized_keys\fR have diverged from the
+LDAP database and synchronizes it if so.
+The configuration is kept in the file
+.BR \*(ET/pam_ldaphome.conf .
+The file is a usual UNIX-style configuration file with
+comments introduced by the \fB#\fR character. Long statements can be
+split across several physical lines of text by ending each line but
+the last with a backslash character.
+Available configuration directives are:
+.BI allow-home-dir " PATH"
+Lists directories in which it is allowed to create home directories.
+\fIPATH\fR 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 \fIPATH\fR.
+.BI skel " DIR"
+Supplies the name of a \fIskeleton directory\fR. The contents of this
+directory is copied to each newly created user home directory. The
+file modes and permissions are retained.
+.BI uri " ARG"
+Sets the URI of the LDAP server to consult for the user profile.
+.BI ldap-version " NUM"
+Sets the LDAP version to use. Valid arguments are
+.B 2
+.B 3
+(the default).
+Use \fISEARCHBASE\fR as starting point for searches.
+.BI binddn " DN"
+Use the Distinguished Name \fIDB\fR to bind to the LDAP directory.
+.BI bindpw " PASSWORD"
+Used together with \fBbinddn\fR, this statement supplies the
+password for simple authentication.
+.BI bindpwfile " FILE"
+Read password for simple authentication from \fIFILE\fR.
+.BI tls " VAL"
+Controls whether TLS is desired or required. If \fIVAL\fR is
+\fBno\fR (the default), TLS will not be used. If it is \fByes\fR,
+the module will issue the \fIStartTLS\fR command, but will continue
+anyway if it fails. Finally, if \fIVAL\fR is the word \fBonly\fR, the
+use of TLS becomes mandatory, and the module will not establish LDAP
+connection unless \fIStartTLS\fR succeeds.
+.BI min\-uid " N"
+Sets the minimal UID. For users with UIDs less than \fIN\fR,
+\fBpam_ldaphome\fR will return \fBPAM_SUCCESS\fR 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
+\fBpam_ldaphome\fR. See also \fBmin\-gid\fR and \fBallow\-groups\fR.
+.BI min\-gid " N"
+Sets the minimal GID. For users with GIDs less than \fIN\fR,
+the module will return \fBPAM_SUCCESS\fR immediately.
+\fBallow\-groups\fR \fIGROUP\fR [\fIGROUP\fR...]
+Only handle members of the listed groups.
+.BI filter " EXPR"
+Defines a LDAP filter expression which returns the user profile. The
+\fIEXPR\fR should conform to the string representation for search
+filters as defined in RFC 4515.
+.BI pubkey\-attr " TEXT"
+Defines the name of the attribute that keeps user's public SSH key.
+.BI 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 value is 16384 bytes.
+.BI home\-dir\-mode " MODE"
+Defines the file mode (octal) for creation of the user directories.
+.BI keyfile\-mode " MODE"
+Defines the file mode (octal) for creation of authorized keys files.
+.BI authorized_keys " NAME"
+Sets the pathname (relative to the home directory) for the authorized
+keys file. The default is \fB.ssh/authorized_keys\fR. For normal
+operation, this value must be the same as the value of
+\fBAuthorizedKeysFile\fR variable in
+.BR sshd_config (5).
+Unless you change the latter, there's no need to edit it.
+.BI config= FILE
+Read configuration from \fIFILE\fR instead of
+.BR \*(ET/pam_ldaphome.conf .
+Set debugging level (0 <= \fINUMBER\fR <= 100).
+Wait for \fIN\fR seconds before starting up. This option is intended
+to facilitate attaching to the module with
+.BR gdb (1).
+It is available only if the package was configured with
+the \fB\-\-enable\-debug\fR option.
+Log auditing information.
+.BR auth .
+Successful termination.
+System error or error in configuration of the module.
+The aim of this configuration is to allow remote access via \fBsshd\fR to
+users present only in the LDAP database, using ssh shared-key
+authentication. The user public keys are kept in the
+.B grayPublicKey
+attribute of his LDAP entry. When a user logs in for the first time,
+his home directory does not exist yet and consequently \fBsshd\fR is not able
+to verify his key. Therefore it falls back to the interactive
+authentication (it is supposed, of course, that \fBUsePAM\fR is set to
+\fByes\fR in the \fBsshd\fR configuration file). The authentication
+stage is supposed to create user home directory, populate the
+\fB.ssh/authorized_keys\fR file with his public keys and present user
+with a descriptive text prompting him to cancel his current
+authentication attempt and retry it again.
+.B PAM ssh stack configuration:
+auth [success=ok try_again=1 default=die]
+auth [success=done ignore=ignore default=die]
+auth [default=die] file=/etc/ldaphome.txt
+.B The configuration file (\*(ET/pam_ldaphome.conf)
+The configuration handles only users with uids and gids greater than
+or equal to 1000 and pertaining to the group \fBremote\fR. Home
+directories are populated from the
+.B /etc/skel
+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
+.B Addition to the LDAP schema:
+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
+# 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 ) )
+This manpage is a short description of \fBpam_ldaphome\fR. For a detailed
+discussion, including examples and usage recommendations, refer to the
+\fBPAM-modules Manual\fR available in texinfo format. If the \fBinfo\fR
+reader and the tar documentation are properly installed on your
+system, the command
+.RS +4
+.B info pam-modules
+should give you access to the complete manual.
+You can also view the manual using the info mode in
+.BR emacs (1),
+or find it in various formats online at
+.RS +4
+If any discrepancies occur between this manpage and the
+\fBPAM-modules Manual\fR, the later shall be considered the authoritative
+.BR pam.conf (5),
+.BR pam.d (5),
+.BR pam (8).
+Sergey Poznyakoff <>
+Report bugs to <bug\-pam\>.
+Copyright \(co 2001-2014 Sergey Poznyakoff
+License GPLv3+: GNU GPL version 3 or later <>
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:

Return to:

Send suggestions and report system problems to the System administrator.