pam_mount.conf(5) pam_mount 2.1 pam_mount.conf(5)Namepam_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 vol‐
umes 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 any‐
way.
Do not use comments inside elements taking verbatim text, like <fuser‐
mount></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 sec‐
tion "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 iden‐
tified 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, encfs13, smbfs, ncpfs, fuse, nfs and nfs are
overriden 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 filesys‐
tems. 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 encfs13 and fuse fstypes, 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.
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.
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
pmt-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.
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).
fskeyhash="hash"
OpenSSL hash name for the fskey.
fskeypath="path"
Path to the filesystem key.
Variables
Within attributes and commands (see later section), specific placehold‐
ers or variables, identified by %(name) may be used. These are substi‐
tuted 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\user‐
name", 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 spec‐
ify 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 lin‐
early, 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 ses‐
sion ends.) Examples are processes still running in the back‐
ground; 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 (usually in
~/.pam_mount.conf.xml) to mount if allowed by the master config‐
uration file by the presence of the <luserconf> element. With
it, users may mount and unmount any volumes they specify that
they have ownership of (in case of local mounts) - the mount
process is called as superuser. On some filesystem configura‐
tions this may be a security risk so user-defined volumes are
not allowed by the default pam_mount.conf.xml distributed with
pam_mount. Luserconfigs are parsed after any volumes from the
global configuration file are mounted, so mounting home directo‐
ries with a global config and then mounting further volumes from
luserconfigs is possible.
<mntoptions allow="options,..." />
The <mntoptions> elements determine which options may be speci‐
fied in per-user configuration files (see <luserconf>). It does
not apply to the master file. Specifying <mntoptions> is for‐
bidden and ignored in per-user configs. It defaults to
allow="nosuid,nodev", and the default is cleared when the first
<mntoptions allow="..."> tag is seen. All further <mntoptions>
are additive, though.
<mntoptions deny="options,..." />
Any options listed in deny may not appear in the option list of
per-user mounts. (Does not apply to the master file.)
<mntoptions require="options,..." />
All options listed in require must appear in the option list of
per-user mounts. (Does not apply to the master file.) It
defaults to nosuid,nodev, and the default is cleared when the
first <mntoptions require="..."> tag is seen. All further
<mntoptions> are additive, though.
<path>directories...</path>
The default for the PATH environmental variable is not consis‐
tent 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 func‐
tion. 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.
<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 -p0 -t %(FSTYPE) ...</lclmount>
The regular mount program.
<umount>umount %(MNTPT)</umount>
Unless there is a dedicated umount program for a given filesys‐
tem 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 con‐
figured 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 con‐
trol is set up using additional elements within <volume>, for example
<volume path="/dev/shm" mountpoint="~"> <and> <sgrp>students</user>
<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".
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 whereever ssh
will put you in, usually the home directory.
<volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~"
/>
<volume fstype="fuse" path="ccgfs-ssh-pull#%(USER)@host:directory"
mountpoint="~" />
encfs 1.4.x and up
<volume fstype="fuse" path="encfs#/crypto/%(USER)" mountpoint="~"
options="nonempty" />
encfs 1.3.x
encfs 1.3.x did not support option passthrough, which is why a separate
helper (/sbin/mount.encfs13, installed by pam_mount) is needed. This
variant also supports 1.4.x, but it is encouraged to use fstype=fuse in
that case.
<volume fstype="encfs13" path="/crypto/%(USER)" mountpoint="~"
options="nonempty" />
NFS mounts
<volume fstype="nfs" server="fileserver" path="/home/%(USER)" mount‐
point="~" />
CIFS/SMB mounts
<volume user="user" fstype="smbfs" server="krueger" path="public"
mountpoint="/home/user/krueger" />
NCP mounts
<volume user="user" fstype="ncpfs" server="krueger" path="public"
mountpoint="/home/user/krueger" options="user=user.context" />
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 CON‐
FIG_DM_CRYPT enabled, as well as all the ciphers that are going to be
used, e.g. CONFIG_CRYPTO_AES, CONFIG_CRYPTO_BLOWFISH, CON‐
FIG_CRYPTO_TWOFISH.
<volume path="/home/%(USER).img" mountpoint="~"
cipher="aes-cbc-essiv:sha256" fskeycipher="aes-256-cbc" fskey‐
hash="sha1" fskeypath="/home/%(USER).key" />
LUKS volumes
<volume path="/home/%(USER).img" mountpoint="~"
cipher="aes-cbc-essiv:sha256" />
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"
/>
pam_mount 2.1 2010-05-02 pam_mount.conf(5)
