Man Linux: Main Page and Category List

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, 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
              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 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 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.

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  (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  ownership  of  (in case of local mounts) - the
              mount  process  is  called  as  superuser.  On  some  filesystem
              configurations  this  may  be  a  security  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
              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".

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" fskeypath="/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"
       />