Provided by: libpam-mount_0.41-1_i386 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,  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)