1pam_mount(8)                    pam_mount 2.18                    pam_mount(8)
2
3
4

Name

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

Overview

9       This  module  is aimed at environments with central file servers that a
10       user  wishes  to  mount  on  login  and  unmount  on  logout,  such  as
11       (semi-)diskless  stations  where  many users can logon and where stati‐
12       cally mounting the entire /home from a server is a  security  risk,  or
13       listing all possible volumes in /etc/fstab is not feasible.
14
15       •   Users can define their own list of volumes without having to change
16           (possibly non-writable) global config files.
17
18       •   Single sign-on feature - the user needs to type the  password  just
19           once (at login)
20
21       •   Transparent mount process
22
23       •   No stored passwords
24
25       •   Volumes  are  unmounted on logout, freeing system resources and not
26           leaving data exposed.
27
28       The module also supports mounting local filesystems  of  any  kind  the
29       normal  mount  utility  supports,  with extra code to make sure certain
30       volumes are set up properly because often they need more  than  just  a
31       mount  call,  such  as encrypted volumes. This includes SMB/CIFS, FUSE,
32       dm-crypt and LUKS.
33
34       If you intend to use pam_mount to protect volumes on your computer  us‐
35       ing  an  encrypted  filesystem  system, please know that there are many
36       other issues you need to consider in order to protect  your  data.  For
37       example,  you  probably  want to disable or encrypt your swap partition
38       (the cryptoswap can help you do this). Do not assume a system is secure
39       without carefully considering potential threats.
40

Configuration

42       The   primary   configuration   file   for   the  pam_mount  module  is
43       pam_mount.conf.xml.  On most platforms this file is read from  /etc/se‐
44       curity/pam_mount.conf.xml. On OpenBSD pam_mount reads its configuration
45       file from /etc/pam_mount.conf.xml.  See  pam_mount.conf(5)  documenting
46       its use.
47
48       Individual  users  may define additional volumes to mount if allowed by
49       pam_mount.conf.xml (usually ~/.pam_mount.conf.xml). The volume  keyword
50       is the only valid keyword in these per-user configuration files. If the
51       luserconf parameter is set in pam_mount.conf.xml, allowing user-defined
52       volume,  then  users  may  mount and unmount any volume they own at any
53       mount point they own. On some filesystem configurations this may  be  a
54       security  flaw  so  user-defined volumes are not allowed by the example
55       pam_mount.conf.xml distributed with pam_mount.
56

PAM configuration

58       In addition, you must include two entries in  the  system's  applicable
59       /etc/pam.d/service config files, as the following example shows:
60
61                  auth     required  pam_securetty.so
62                  auth     required  pam_pwdb.so shadow nullok
63                  auth     required  pam_nologin.so
64              +++ auth     optional  pam_mount.so
65                  account  required  pam_pwdb.so
66                  password required  pam_cracklib.so
67                  password required  pam_pwdb.so shadow nullok use_authtok
68                  session  required  pam_pwdb.so
69                  session  optional  pam_console.so
70              +++ session  optional  pam_mount.so
71
72       When "sufficient" is used in the second column, you must make sure that
73       pam_mount is added before this entry. Otherwise pam_mount will not  get
74       executed  should  a  previous  PAM module succeed. Also be aware of the
75       "include" statements. These make PAM look into the specified  file.  If
76       there is a "sufficient" statement, then the pam_mount entry must either
77       be in the included file before the "sufficient" statement or before the
78       "include" statement.
79
80       If  you use pam_ldap, pam_winbind, or any other authentication services
81       that make use of PAM's sufficient keyword, model your configuration  on
82       the following order:
83
84              •••
85              account sufficient  pam_ldap.so
86              auth    required    pam_mount.so
87              auth    sufficient  pam_ldap.so use_first_pass
88              auth    required    pam_unix.so use_first_pass
89              session optional    pam_mount.so
90              •••
91
92       This allows for:
93
94       1.  pam_mount,  as  the first "auth" module, will prompt for a password
95           and export it to the PAM system.
96
97       2.  pam_ldap will use the password from the PAM system to try  and  au‐
98           thenticate  the  user. If this succeeds, the user will be authenti‐
99           cated. If it fails, pam_unix will try to authenticate.
100
101       3.  pam_unix will try to authenticate the user if pam_ldap  failed.  If
102           pam_unix fails, then the authentication will be refused (due to the
103           "required").
104
105       Alternatively, the following is possible (thanks to Andrew  Morgan  for
106       the hint!):
107
108              auth [success=2 default=ignore] pam_unix2.so
109              auth [success=1 default=ignore] pam_ldap.so use_first_pass
110              auth requisite pam_deny.so
111              auth optional pam_mount.so
112
113       It  may  seem  odd,  but  the first three lines will make it so that at
114       least one of pam_unix2 or pam_ldap has to  succeed.  As  you  can  see,
115       pam_mount  will  be run after successful authentication with these sub‐
116       systems.
117

Encrypted disks

119       pam_mount supports a few types of crypto. The most  common  are  encfs,
120       dm-crypt and dm-crypt+LUKS.
121
122       The first one uses the FUSE layer; files within the encfs container are
123       stored as single encrypted files on the host in  a  previously-existing
124       directory.  If  you  store  lots  of files, it is recommended to have a
125       lower filesystem that is strong in this area, such  as  xfs,  but  some
126       software and/or your partitioning decisions may force you to use a dif‐
127       ferent fs. The 1:1 mapping of files also allows encrypted files  to  be
128       reasonably  efficiently rsync'ed for example without having to open the
129       encrypted container. Creation is done through the encfs(1) tool.
130
131       dm-crypt provides whole-filesystem/entire-partition encryption. You can
132       also create a container file, but the idea is that it is represented as
133       a block device on which you still have to create a filesystem. In fact,
134       this  way  you  can select a filesystem of your choice. The downside is
135       that shrinking is often not possible (there is no such issue  in  encfs
136       because it uses the lower fs). Suitable dm-crypt containers (and auxil‐
137       iary files), using block devices or plain files, can be  created  using
138       the pmt-ehd(8) tool.
139
140       pmt-ehd  creates  filesystem  key  material  which is a bunch of random
141       bytes that will be used to en-/decrypt the volume. This material itself
142       is  encrypted  with  your  own  password - this is done so that you can
143       change the password without having to reencrypt all of your data.
144
145       LUKS is an extension for dm-crypt to support multi-password containers.
146       Unless  you  specifically  need  it, the above two solutions are recom‐
147       mended.
148
149       NOTE: The key file that pmt-ehd(8) will create represents the  filesys‐
150       tem  key  material  as encrypted with your password. It is thus safe to
151       store this on an unsecured filesystem.
152

Troubleshooting

154       To ensure that your system and, possibly, the  remote  server  are  all
155       properly configured, you should try to mount all or some of the volumes
156       by  hand,  using  the  same  commands  and  mount  points  provided  in
157       pam_mount.conf.xml. This will save you a lot of grief, since it is more
158       difficult to debug the mounting process via pam_mount.
159
160       If you can mount the volumes by  hand  but  it  is  not  happening  via
161       pam_mount,   you   may   want   to   enable   the   "debug"  option  in
162       pam_mount.conf.xml to see what is happening.
163
164       Verify if the user owns the mount point and has sufficient  permissions
165       over  that. pam_mount will verify this and will refuse to mount the re‐
166       mote volume if the user does not own that directory.
167
168       If pam_mount is having trouble unmounting volumes upon logging out, en‐
169       able the debug variable. This causes pam_mount to run ofl on logout and
170       write its output to the system's log.
171

Authors

173       W. Michael Petullo
174
175       Jan Engelhardt (current maintainer)
176

Community Support

178       The following two forms of communication are available. The  maintainer
179       has no preference, though you will reach more users who could answer by
180       means of the mailing list.
181
182       https://sf.net/projects/pam-mount/support
183
184
185
186pam_mount 2.18                    2021-01-04                      pam_mount(8)
Impressum