Provided by:
libpam-mount_0.41-1_i386 
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, but these three symbols are unlikely to be seen
often anyway.
Do not use comments inside elements taking verbatim text, like
<lsof></lsof> - 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, davfs, smbfs, ncpfs, fuse and truecrypt are
overriden by pam_mount and we call the respective helpers
directly without going thorugh mount(8), to have access to more
options of the helper programs.
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.
fskeycipher="ciphertype"
Cipher type for use with the crypt fstype (dm-crypt and LUKS).
fskeypath="path"
Path to the filesystem key.
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 user logging in. This is useful
in conjunction with the uid= or gid= mount options, e.g. <volume
options="uid=%(USERUID)" />.
%(FSTYPE)
The fstype as given by the <volume fstype="..."> attribute.
%(SERVER)
The source server as given by the <volume server="...">
attribute.
%(VOLUME)
The source volume as given by the <volume path="..."> attribute.
%(MNTPT)
The target mountpoint as given by the <volume mountpoint="...">
attribute.
%(CIPHER)
%(KEYBITS)
Various options related to dm-crypt/LUKS crypto.
%(OPERATION)
This is for internal-use between pam_mount and pmvarrun(8) only.
When the user logs in, it expands to 1, on logout, it expands to
-1.
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.
<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
configuration file by the presence of the <luserconf> element.
With it, users may mount and unmount any volumes they specify.
The mount operation is executed under the user account, not with
root permissions. You also need at least an allow or deny option
list (see <mntoptions>).
<mntoptions allow="options,..." />
The <mntoptions> elements determine which options may be
specified in per-user configuration files (see <luserconf>). It
does not apply to the master file.
<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.)
<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
<fsckloop device="/dev/loop7" />
Specify the device used when checking loopback mounts. (This
seems unused.)
<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.
<lsof>program...</lsof>
lsof is used for debugging only, to show what processes hold
which files open on logout thus preventing successful unmounting
of the volume when pam_mount would normally close the
filesystem. (I.e. when the last login session is closed.)
<mntcheck>mntcheck ...</mntcheck>
Originally intended for use on BSD to check if a volume was
mounted. Currently unused.
<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
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.
<losetup>losetup ...</lsof>
<unlosetup>losetup -d ...</unlosetup
<cifsmount>mount.cifs ...</cifsmount>
<cryptmount>mount.crypt ...</cryptmount>
Mount helper for dm-crypt and LUKS volumes.
<davmount>mount.davfs ...</davmount>
<fusemount>mount.fuse ...</fusemount>
<fuseumount>fuserumount ...</fuseumount>
<ncpmount>ncpmount ...</ncpmount>
<ncpumount>ncpumount ...</ncpumount>
<nfsmount>mount %(SERVER):%(VOLUME) ...</nfsmount>
<smbmount>smbmount ...</smbmount>
<smbumount>smbumount ...</smbumount>
<truecryptmount>truecrypt ...</truecryptmount>
<truecryptumount>truecrypt -d ...</truecryptumount>
Messages
<msg-authpw>pam_mount password:</msg-authpw>
When pam_mount is not used with "use_first_pass" or
"try_first_pass" keywords in the PAM configuration files
(/etc/pam.d/), it will have to ask for a password. This is also
the case if pam_mount is the first auth module in the block.
<msg-authpw> allows you to customize that prompt.
<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</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).
FUSE mounts
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="encfs#/crypto/%(USER)" mountpoint="~" />
NFS mounts
<volume fstype="nfs" server="fileserver" path="/home/%(USER)"
mountpoint="~" />
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" />
DAVFS
<volume fstype="davfs" server="https://inkscape.svn.sourceforge.net/"
path="/svnroot/inkscape/trunk" mountpoint="/projects/inkscape" />
Bind mounts
This may come useful in conjunction with pam_chroot:
<volume path="/bin" mountpoint="~/bin" options="bind" />
Encrypted mounts
Section unsorted.
<volume path="/home/%(USER).img" mountpoint="~"
fskeycipher="aes-256-cbc" fskeypath="/etc/ehd/%(USER)" />
pam_mount.conf(5)