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 SMB (Samba or Windows NT) or
       NCP (Netware or Mars-NWE) servers that Unix users wish to access trans‐
       parently. It facilitates access to private volumes of these types well.
       The module also supports  mounting  home  directories  using   loopback
       encrypted filesystems. The module was originally written for use on the
       GNU/Linux operating system but has since been modified to work on  sev‐
       eral flavors of BSD.

       ·   Every user can access his own volumes

       ·   The user needs to type the password just once (at login)

       ·   The mounting process is transparent to the users

       ·   There is no need to keep the login passwords in any additional file

       ·   The  volumes  are  unmounted  upon  logout,  so  it  saves   system
           resources, avoiding the need of listing every every possibly useful
           remote  volume in /etc/fstab or in an  automount/supermount  config
           file. This is also necessary for securing encrypted filesystems.

       pam_mount  can  mount  any filesystem the kernel supports, and has sup‐
       ports the userspace helpers for SMB, CIFS, NCP, davfs, FUSE, and crypto
       mounts.

       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 use_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 then model your configuration
       on the following:


              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 the following:

       1.  pam_mount  will prompt for a password and export it to the PAM sys‐
           tem.

       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  fails.  If
           pam_unix fails, then the authentication will be refused.

       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  theses
       subsystems.

       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   and   check   the   lsof   variable   in
       pam_mount.conf.xml.  This causes pam_mount to run lsof upon logging out
       and write lsof's output to the system's logs.

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

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



                                                                  pam_mount(8)