Provided by: libpam-mount_2.20-3build2_amd64 bug

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