Provided by: libpam-mount_2.20-3build2_amd64 
Name
pam_mount.conf - Description of the pam_mount configuration file
Overview
The pam_mount configuration file defines soft defaults for commands pam_mount will be
executing, the messages it will show, and which volumes to mount on login. Since pam_mount
0.18, the configuration file is written in XML so as to simplify the pam_mount code base
while giving formatting freedom to the end-user. Special characters like <, > and & that
are used by XML itself must be encoded as <, > and &, respectively;
additionally, " must be encoded as " within a "" area, but these three/four symbols
are unlikely to be seen often anyway.
Do not use comments inside elements taking verbatim text, like <fusermount></fusermount> -
this is not handled by the pam_mount XML tree parser.
Volume definitions
Volumes are defined with the <volume> element, which primarily takes the parameters as
attributes, such as
<volume user="joe" fstype="nfs" server="fsbox" path="/home/%(USER)"
mountpoint="/bigdisk/%(USER)" />
and define to mount what for whom and how. There are a lot of tunables, which are
described in this section.
Simple user control
The following attributes control whether the volume is going to get mounted once the user
logs in. By default, volumes apply to all users, and specifying attributes limits it to
the given conditions, i.e. they are logically ANDed. There is a more powerful and verbose
mechanism for specifying complex conditions, described further below in the section
"Extended user control".
user="username"
Limit the volume to the specified user, identified by name
uid="number" or uid="number-number"
Limit the volume to the specified user(s), identified by UID or UID range.
pgrp="groupname"
Limit the volume to users which have the group identified by name as their primary
group.
gid="number" or gid="number-number"
Limit the volume to users which have the group(s) given by GID or GID range as a
primary group.
sgrp="groupname"
Limit the volume to users which are a member of the group identified by name
(either as primary or secondary group).
Volume configuration
The following attributes select volume source, destination, options and so on.
fstype="type"
The filesystem type, which can be anything your kernel, userspace and pam_mount
understand. If the fstype specifies a pam_mount-special type, pam_mount will handle
it. Otherwise, the fstype is passed to mount(8) which then in turn looks for a
userspace helper /sbin/mount.fstype and runs that if it exists, and in any other
case, mount(8) would call mount(2) to cause the kernel to directly mount it.
mount(8) knows of an auto fstype, which might be helpful in some cases. Not
specifying the fstype attribute implies fstype="auto". Note that mounting with auto
may fail if the filesystem kernel module is not loaded yet, since mount(8) will
check /proc/partitions.
The fstypes cifs, smbfs, ncpfs, fuse, nfs and nfs4 are overridden by pam_mount and
we run the respective helper programs directly instead of invoking mount(8) with
the basic default set of arguments which are often insufficient for networked
filesystems. See this manpage's section "Examples" below for more details.
noroot="1"
Call the mount program without root privileges. It defaults to yes for the fuse
fstype, because FUSE volumes must be mounted as the user that logs in to get access
to the files by default.
server="name"
Defines the server to which to connect in case of cifs, smbfs and ncpfs and nfs
fstypes. For all other fs types, this attribute is ignored. You can also specify
the server in the path attribute instead, but need to adhere to the specific syntax
that is a particular fstype requires. (E.g. CIFS uses "//server/path", whereas NFS
uses "server:path", etc.)
path="path"
This mandatory attribute specifies the location of the volume, relative to the
server (if specified).
mountpoint="directory"
This specifies the destination directory onto which the volume is mounted. "~"
expands to the user's home directory as present in the passwd database, according
to sh semantics. "~name" is not supported. If this attribute is omitted, the
location is read from /etc/fstab, which also requires path to be a device or a
source directory of an fstab entry.
header="path"
This specifies a detached (separated) metadata file where the LUKS header is
stored. This correlates with the `cryptsetup --header` option. If this attribute is
omitted, the detached LUKS header feature is not used.
options="..."
Specifies the mount options. If omitted and /etc/fstab is used (see mountpoint),
the options will also be sources from fstab.
ssh="0" or ssh="1"
The ssh option enables an input hack wrapper (zerossh, see fd0ssh(1)) for this
volume to hand the password to ssh over an ssh-specific mechanism. Enable this
option for any mount involving the SSH binary, e.g. ccgfs or sshfs. Do not enable
it for anything else or the login will most likely hang.
empty_pass="0" or empty_pass="1"
The empty_pass option controls behavior when an empty password is supplied or a
password is unavailable. The default value of true will try to unlock a volume
with an empty string key if no password is available. When empty_pass is false,
pam_mount will not attempt to mount the volume unless a non-empty password is
available.
cipher="cipher"
Cryptsetup cipher name for the volume. To be used with the crypt fstype.
fskeycipher="ciphertype"
OpenSSL cipher name for the fskey. Use with the crypt fstype (dm-crypt and LUKS).
The special cipher keyword "none" may be used to directly pass the file's contents
to cryptsetup without decryption by OpenSSL.
fskeyhash="hash"
OpenSSL hash name for the fskey.
fskeypath="path"
Path to the filesystem key. ignoresource="1" Ignores the source path when checking
if the volume was already mounted. This is useful in case the source path specified
in path is different to the path stored in the kernel. This could be the case when
using by-label devices files or with NFS servers.
Variables
Within attributes and commands (see later section), specific placeholders or
variables, identified by %(name) may be used. These are substituted at command
invocation time.
%(USER)
Expands to the username of the user logging in.
%(DOMAIN_NAME), %(DOMAIN_USER)
Winbind has special UNIX usernames in the form of "domain\username", and
%(DOMAIN_NAME) and %(DOMAIN_USER) provide the split parts of it. This is useful
when a sharename on an MSAD server is the same as the username, e.g. <volume
fstype="cifs" server="fsbox" path="%(DOMAIN_USER)" />.
%(USERUID), %(USERGID)
The numeric UID and GID of the primary group of the user logging in. This is
obtained via getpw*(), not getuid(). It is useful in conjunction with the uid= or
gid= mount options, e.g. <volume options="uid=%(USERUID)" />. Note that you do not
need to specify uid=%(USERUID) for smbfs or cifs mounts because this is already
done automatically by pam_mount.
%(GROUP)
The name of the group for %(USERGID).
All other variables you might find in the source code are internal to pam_mount, and are
likely not to be expanded when you would expect it.
pam_mount parameters
Besides volumes, there are other elements allowed in pam_mount.conf.xml that control
pam_mount's own behavior.
General tunables
<debug enable="1" />
Enables verbose output during login to stderr and syslog. Some programs do not cope
with output sent on stderr, see doc/bugs.txt for a list. 0 disables debugging, 1
enables pam_mount tracing, and 2 additionally enables tracing in mount.crypt. The
default is 0. As the config file is parsed linearly, the <debug> directive takes
effect once it is seen - it it thus advised to put it near the start of the file,
before any <volume> definitions.
<logout wait="microseconds" hup="yes/no" term="yes/no" kill="yes/no" />
Programs exist that do not terminate when the session is closed. (This applies to
the "final" close, i.e. when the last user session ends.) Examples are processes
still running in the background; or a broken X session manager that did not clean
up its children, or other X programs that did not react to the X server termination
notification. pam_mount can be configured to kill these processes and optionally
wait before sending signals.
<luserconf name=".pam_mount.conf.xml" />
Individual users may define additional volumes in a file by the specified name
relative to their home directory. The presence of <luserconf> in the master config
file enables this feature. If turned on, users may mount and unmount any volumes
they specify and that they have ownership of (in case of local mounts). The mount
process is executed as superuser. This may have security implications, so this
feature is disabled by default. Luserconfigs are parsed after any volumes from the
global configuration file have been mounted, so that first mounting home
directories with a global config and then mounting further volumes from
luserconfigs is possible.
<mntoptions allow="options,..." />
The <mntoptions> elements determine which options may be specified in <volumes> in
per-user configuration files (see <luserconf>). It does not apply to the master
file. Specifying <mntoptions> is forbidden and ignored in per-user configs. The
default allowed list consists of "nosuid,nodev", and this default is cleared when
the first allow="..." attribute is seen by the config parser. All further
allow="..." are additive, though.
<mntoptions deny="options,..." />
Any options listed in deny may not appear in the option list of per-user mounts.
The default deny list is empty.
<mntoptions require="options,..." />
All options listed in require must appear in the option list of per-user mounts.
The default require list consists of "nosuid,nodev", and like allow="", is cleared
when first encountered by the parser, and is otherwise additive.
<path>directories...</path>
The default for the PATH environmental variable is not consistent across
distributions, and so, pam_mount provides its own set of sane defaults which you
may change at will.
Volume-related
<mkmountpoint enable="1" remove="true" />
Controls automatic creation and removal of mountpoints. If a mountpoint does not
exist when the volume is about to be mounted, pam_mount can be instructed to create
one using the enable attribute. Normally, directories created this way are retained
after logout, but remove may be set to true to remove the mountpoint again, but
only if it was automatically created by pam_mount in the same session before.
Auxiliary programs
Some mount programs need special default parameters to properly function. It is good
practice to specify uid= for CIFS for example, because it is mounted as root and would
otherwise show files belonging to root instead of the user logging in.
<fd0ssh>program...</fd0ssh>
fd0ssh is a hack around OpenSSH that essentially makes it read passwords from stdin
even though OpenSSH normally does not do that.
<fsck>fsck -p %(FSCKTARGET)</fsck>
Local volumes will be checked before mounting if this program is set.
<ofl>ofl -k%(SIGNAL) %(MNTPT)</ofl>
The Open File Lister is used to identify processes using files within the given
subdirectory, and optionally send a signal to those processes.
<pmvarrun>pmvarrun ...</pmvarrun>
pmvarrun(8) is a separate program to manage the reference count tracking user
sessions.
Mount programs
Commands to mount/unmount volumes. They can take parameters, as shown. You can specify
either absolute paths, or relative ones, in which case $PATH will be searched. Since login
programs have differing default PATHs, pam_mount has its own path definition (see above).
<lclmount>mount -t %(FSTYPE) ...</lclmount>
The regular mount program.
<umount>umount %(MNTPT)</umount>
Unless there is a dedicated umount program for a given filesystem type, the regular
umount program will be used.
Linux supports lazy unmounting using `/sbin/umount -l`. This may be dangerous for
encrypted volumes because the underlying device is not unmapped. Loopback devices
are also affected by this (not being unmapped when files are still open). Also,
unmount on SMB volumes needs to be called on %(MNTPT) and not %(VOLUME).
Commands for various mount programs. Not all have a dedicated umount helper because some
do not need one.
<cifsmount>mount.cifs ...</cifsmount>
<cryptmount>mount.crypt ...</cryptmount>
<cryptumount>umount.crypt %(MNTPT)</cryptumount>
Mount helpers for dm-crypt and LUKS volumes.
<fusemount>mount.fuse ...</fusemount>
<fuseumount>fuserumount ...</fuseumount>
<ncpmount>ncpmount ...</ncpmount>
<ncpumount>ncpumount ...</ncpumount>
<nfsmount>mount %(SERVER):%(VOLUME) ...</nfsmount>
<smbmount>smbmount ...</smbmount>
<smbumount>smbumount ...</smbumount>
Messages
<msg-authpw>pam_mount password:</msg-authpw>
When pam_mount cannot obtain a password through PAM, or is configured to not do so
in the first place, and is configured to ask for a password interactively as a
replacement, this prompt will be shown.
<msg-sessionpw>reenter...:</msg-sessionpw>
In case the 'session' PAM block does not have the password (e.g. on su from root to
user), it will ask again. This prompt can also be customized.
Extended user control
Sometimes, the simple user control attributes for the <volume> element are not sufficient
where one may want to build more complex expressions as to whom a volume applies. Instead
of attributes, extended user control is set up using additional elements within <volume>,
for example
<volume path="/dev/shm" mountpoint="~"> <and> <sgrp>students</sgrp> <not>
<sgrp>profs</sgrp> </not> </and> </volume>
Which translates to (students && !profs).
Logical operators
<and><elements>*</and>
All elements within this one are logically ANDed. Any number of elements may
appear.
<or><elements>*</or>
All elements within this one are logically ORed. Any number of elements may appear.
<xor><elements>{2}</xor>
The two elements within the <xor> are logically XORed.
<not><element></not>
The single element within the <not> is logically negated.
User selection
<user>username</user>
Match against the given username.
<uid>number</uid> or <uid>number-number</uid>
Match the UID of the user logging in against a UID or UID range.
<gid>number</gid> or <gid>number-number</gid>
Match the primary group of the user logging in against a GID or GID range.
<pgrp>groupname</pgrp>
Check if the user logging in has groupname as the primary group.
<sgrp>groupname</sgrp>
Check if the user logging in is a member of the group given by name (i.e. it is
either a primary or secondary group).
Attributes
icase="yes" or icase="no"
The icase attribute may be used on <user>, <pgrp> and <sgrp> to enable
case-insensitive matching (or not). It defaults to "no".
regex="yes" (or no)
The regex attribute may be used on <user>, <pgrp> and <sgrp> to enable interpreting
the text content of the tag as a Perl-compatible regular expression pattern. This
attribute may be combined with "icase" (see above). Example: <user
regex="yes">joe</user> matches any user who has the letter sequence "joe" anywhere
in their username. Therefore, use the regex feature cautiously and consider adding
^ and $ anchors to limit security surprises. Example: <user
regex="yes">^.*joe.*$</user> if you really wanted to match the sequence at any
position.
Examples
Remember that ~ can be used in the mountpoint attribute to denote the home directory as
retrievable through getpwent(3).
sshfs and ccgfs
Not specifying any path after the colon (:) uses the path wherever ssh will put you in,
usually the home directory. With fd0ssh (package hxtools) installed:
<volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~" ssh="1" />
Without fd0ssh:
<volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~"
options="nosuid,nodev,noatime,reconnect,nonempty,allow_other,default_permissions,password_stdin"
ssh="0" noroot="0" />
<volume fstype="fuse" path="ccgfs-ssh-pull#%(USER)@host:directory" mountpoint="~" />
Note that sshfs's "password_stdin" option tries to locate a string "assword" on ssh's
output, while fd0ssh is rather using the "askpass" API, which might also work with
passphrase-protected SSH keys whose prompt is quite different.
encfs 1.4.x and up
<volume fstype="fuse" path="encfs#/crypto/%(USER)" mountpoint="~" options="nonempty" />
(encfs 1.3 is no longer supported.)
NFS mounts
<volume fstype="nfs" server="fileserver" path="/home/%(USER)" mountpoint="~" />
CIFS mounts
<volume user="user" fstype="cifs" server="krueger" path="public"
mountpoint="/home/user/krueger" />
Bind mounts
This may come useful in conjunction with pam_chroot:
<volume path="/bin" mountpoint="~/bin" options="bind" />
tmpfs mounts
Volatile tmpfs mount with restricted size (thanks to Mike Hommey for this example):
<volume user="test" fstype="tmpfs" mountpoint="/home/test"
options="size=10M,uid=%(USER),mode=0700" />
dm-crypt volumes
Crypt mounts require a kernel with CONFIG_BLK_DEV_DM and CONFIG_DM_CRYPT enabled, as well
as all the ciphers that are going to be used, e.g. CONFIG_CRYPTO_AES,
CONFIG_CRYPTO_BLOWFISH, CONFIG_CRYPTO_TWOFISH.
<volume path="/home/%(USER).img" mountpoint="~" cipher="aes-cbc-essiv:sha256"
fskeycipher="aes-256-cbc" fskeyhash="sha1" fskeypath="/home/%(USER).key" />
LUKS volumes
<volume path="/home/%(USER).img" mountpoint="~" cipher="aes-cbc-essiv:sha256" />
volume path="/home/%(USER).img" mountpoint="~" header="/home/%(USER)-header.img" />
cryptoloop volumes
cryptoloop is not explicitly supported by pam_mount. Citing the Linux kernel config help
text: "WARNING: This device [cryptoloop] is not safe for journal[l]ed filesystems[...].
Please use the Device Mapper [dm-crypt] module instead."
OpenBSD encrypted home
OpenBSD encrypted home directory example:
<volume path="/home/user.img" mountpoint="/home/user" options="svnd0" />