pam_mount(8)                                                      pam_mount(8)



NAME
       pam_mount - A PAM module that can mount volumes for a user session

OVERVIEW
       This  module  is aimed at environments with central file servers that a
       user  wishes  to  mount  on  login  and  unmount  on  logout,  such  as
       (semi-)diskless  stations  where  many users can logon and where stati‐
       cally mounting the entire /home from a server is a  security  risk,  or
       listing all possible volumes in /etc/fstab is not feasible.

       ·   Users can define their own list of volumes without having to change
           (possibly non-writable) global config files.

       ·   Single sign-on feature - the user needs to type the  password  just
           once (at login)

       ·   Transparent mount process

       ·   No stored passwords

       ·   Volumes  are  unmounted on logout, freeing system resources and not
           leaving data exposed.

       The module also supports mounting local filesystems  of  any  kind  the
       normal  mount  utility  supports,  with extra code to make sure certain
       volumes are set up properly because often they need more  than  just  a
       mount  call,  such  as encrypted volumes. This includes SMB/CIFS, FUSE,
       dm-crypt and LUKS.

       If you intend to use pam_mount to  protect  volumes  on  your  computer
       using  an  encrypted filesystem system, please know that there are many
       other issues you need to consider in order to protect  your  data.  For
       example,  you  probably  want to disable or encrypt your swap partition
       (the cryptoswap can help you do this). Do not assume a system is secure
       without carefully considering potential threats.

NASTY DETAILS
       The   primary   configuration   file   for   the  pam_mount  module  is
       pam_mount.conf.xml.   On  most  platforms  this  file  is   read   from
       /etc/security/pam_mount.conf.xml.  On  OpenBSD pam_mount reads its con‐
       figuration file from /etc/pam_mount.conf.xml.  pam_mount.conf.xml  con‐
       tains many comments documenting its use.

       In  addition,  you  must include two entries in the system’s applicable
       /etc/pam.d/service config files, as the following example shows:

                  auth     required  pam_securetty.so
                  auth     required  pam_pwdb.so shadow nullok
                  auth     required  pam_nologin.so
              +++ auth     optional  pam_mount.so try_first_pass
                  account  required  pam_pwdb.so
                  password required  pam_cracklib.so
                  password required  pam_pwdb.so shadow nullok use_authtok
                  session  required  pam_pwdb.so
                  session  optional  pam_console.so
              +++ session  optional  pam_mount.so

       When "sufficient" is used in the second column, you must make sure that
       pam_mount  is added before this entry. Otherwise pam_mount will not get
       executed should a previous PAM module succeed. Also  be  aware  of  the
       "include"  statements.  These make PAM look into the specified file. If
       there is a "sufficient" statement, then the pam_mount entry must either
       be in the included file before the "sufficient" statement or before the
       "include" statement.

       If you use pam_ldap, pam_winbind, or any other authentication  services
       that  make use of PAM’s sufficient keyword, model your configuration on
       the following order:

              ···
              account sufficient  pam_ldap.so
              auth    required    pam_mount.so
              auth    sufficient  pam_ldap.so use_first_pass
              auth    required    pam_unix.so use_first_pass
              session optional    pam_mount.so
              ···

       This allows for:

       1.  pam_mount, as the first "auth" module, will prompt for  a  password
           and export it to the PAM system.

       2.  pam_ldap  will  use  the  password  from  the PAM system to try and
           authenticate the user. If this succedes, the user will be authenti‐
           cated. If it fails, pam_unix will try to authenticate.

       3.  pam_unix  will  try to authenticate the user if pam_ldap failed. If
           pam_unix fails, then the authentication will be refused (due to the
           "required").

       Alternatively,  the  following is possible (thanks to Andrew Morgan for
       the hint!):

              auth [success=2 default=ignore] pam_unix2.so
              auth [success=1 default=ignore] pam_ldap.so use_first_pass
              auth requisite pam_deny.so
              auth optional pam_mount.so use_first_pass

       It may seem odd, but the first three lines will  make  it  so  that  at
       least  one  of  pam_unix2  or  pam_ldap has to succeed. As you can see,
       pam_mount will be run after successful authentification with these sub‐
       systems.

       If  your volume has a different password than your system account, then
       encrypt the password to the volume you wish mounted using  your  system
       password  as  the  key  and  store  it somewhere on your system’s local
       filesystem. pam_mount supports transparently decrypting this filesystem
       key, as long as the cipher used is supported by openssl. Given:

       sk     system key, the key or password used to log into the system

       fsk    filesystem  key,  the  key that allows you to use the filesystem
              you wish pam_mount to mount for you

       E and D
              an openssl supported synchronous encryption/decryption algorithm

       efsk   encrypted filesystem key, efsk = E_sk (fsk), stored somewhere on
              the local filesystem (ie: /home/user.key)

       pam_mount will read efsk from the local filesystem, perform fsk =  D_sk
       (efsk)  and  use fsk to mount the filesystem. If you change your system
       password, simply regenerate efsk using efsk = E_sk (fsk). If  you  want
       to  mount  this  volume  by  hand,  use  something like ‘openssl enc -d
       -aes-256-ecb -in /home/user.key | mount -p0 /home/user‘. More  informa‐
       tion about this technique is included in pam_mount.conf.xml.

       A  script  named  mkehd  is  provided  with  pam_mount  to  help create
       encrypted home directories. If you have  an  entry  for  a  user  using
       encrypted  home  directories  in  pam_mount.conf.xml, mkehd will create
       necessary filesystem images and possibly encrypted filesystem keys.

       Individual users may define additional volumes to mount if  allowed  by
       pam_mount.conf.xml  (usually ~/.pam_mount.conf.xml). The volume keyword
       is the only valid keyword in these per-user configuration files. If the
       luserconf parameter is set in pam_mount.conf.xml, allowing user-defined
       volume, then users may mount and unmount any volume  they  own  at  any
       mount  point  they own. On some filesystem configurations this may be a
       security flaw so user-defined volumes are not allowed  by  the  example
       pam_mount.conf.xml distributed with pam_mount.

       In  general,  you will leave all the first (general) parameters as pro‐
       vided by default. You only have to provide the user/volume list in  the
       end of the file, following the examples.

       To  ensure  that  your  system and, possibly, the remote server are all
       properly configured, you should try to mount all or some of the volumes
       by  hand,  using  the  same  commands  and  mount  points  provided  in
       pam_mount.conf.xml. This will save you a lot of grief, since it is more
       difficult to debug the mounting process via pam_mount.

       If  you  can  mount  the  volumes  by  hand but it is not happening via
       pam_mount,  you  may   want   to   enable   the   "debug"   option   in
       pam_mount.conf.xml to see what is happening.

       Verify  if the user owns the mount point and has sufficient permissions
       over that. pam_mount will verify this and  will  refuse  to  mount  the
       remote volume if the user does not own that directory.

       If  pam_mount  is  having  trouble unmounting volumes upon logging out,
       enable the debug variable. This causes pam_mount to run ofl  on  logout
       and write its output to the system’s log.

AUTHORS
       W. Michael Petullo <mike@flyn.org>

       Jan Engelhardt <jengelh [at] medozas de> (current maintainer)



                                                                  pam_mount(8)
