bionic (5) pam_mount.conf.5.gz

Provided by: libpam-mount_2.16-3ubuntu0.1_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 nfs 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.

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

       <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 is no longer supported.)

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