pam_mount.conf - Description of the pam_mount configuration file
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.
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.
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).
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.
-
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.
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.
Besides volumes, there are other elements allowed in pam_mount.conf.xml that
control pam_mount's own behavior.
- <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.
- <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.
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.
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>
-
<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.
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).
-
<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>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).
-
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.
Remember that
~ can be used in the mountpoint attribute to denote the
home directory as retrievable through
getpwent(3).
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.
<volume fstype="fuse" path="encfs#/crypto/%(USER)"
mountpoint="~" options="nonempty" />
(encfs 1.3 is no longer supported.)
<volume fstype="nfs" server="fileserver"
path="/home/%(USER)" mountpoint="~" />
<volume user="user" fstype="smbfs"
server="krueger" path="public"
mountpoint="/home/user/krueger" />
<volume user="user" fstype="ncpfs"
server="krueger" path="public"
mountpoint="/home/user/krueger"
options="username=user.context" />
This may come useful in conjunction with pam_chroot:
<volume path="/bin" mountpoint="~/bin"
options="bind" />
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" />
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" />
<volume path="/home/%(USER).img" mountpoint="~"
cipher="aes-cbc-essiv:sha256" />
volume path="/home/%(USER).img" mountpoint="~"
header="/home/%(USER)-header.img" />
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 directory example:
<volume path="/home/user.img" mountpoint="/home/user"
options="svnd0" />