pam_mount.conf(5)						  pam_mount 1.34						 pam_mount.conf(5)

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 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 giv-
       ing  formatting	freedom  to the end-user. Special characters like <, > and & that are used by XML itself must be encoded as &lt;, &gt; and
       &amp;, respectively; additionally, " must be encoded as &quot; 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-spe-
	      cial  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  any-
	      thing 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 placeholders or variables, identified by %(name) may be used. These are sub-
       stituted 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 "domainusername", 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 (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 that they have owner-
	      ship  of (in case of local mounts) - the mount process is called as superuser. On some filesystem configurations this may be a secu-
	      rity 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 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 per-user configuration files (see <luserconf>).  It  does  not
	      apply   to   the	 master   file.   Specifying  <mntoptions>  is	forbidden  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 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.

       <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  vol-
	      umes 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 expres-
       sions 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).

   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)" 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" />

   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"   fskey-
       path="/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 1.34							    2010-04-08							 pam_mount.conf(5)