1pam_mount.conf(5) pam_mount 2.19 pam_mount.conf(5)
2
6 pam_mount.conf - Description of the pam_mount configuration file
7
9 The pam_mount configuration file defines soft defaults for commands
10 pam_mount will be executing, the messages it will show, and which vol‐
11 umes to mount on login. Since pam_mount 0.18, the configuration file is
12 written in XML so as to simplify the pam_mount code base while giving
13 formatting freedom to the end-user. Special characters like <, > and &
14 that are used by XML itself must be encoded as <, > and &,
15 respectively; additionally, " must be encoded as " within a ""
16 area, but these three/four symbols are unlikely to be seen often any‐
17 way.
18 Do not use comments inside elements taking verbatim text, like <fuser‐
20 mount></fusermount> - this is not handled by the pam_mount XML tree
21 parser.
22
24 Volumes are defined with the <volume> element, which primarily takes
25 the parameters as attributes, such as
26 <volume user="joe" fstype="nfs" server="fsbox" path="/home/%(USER)"
28 mountpoint="/bigdisk/%(USER)" />
29 and define to mount what for whom and how. There are a lot of tunables,
31 which are described in this section.
32 Simple user control
34 The following attributes control whether the volume is going to get
35 mounted once the user logs in. By default, volumes apply to all users,
36 and specifying attributes limits it to the given conditions, i.e. they
37 are logically ANDed. There is a more powerful and verbose mechanism
38 for specifying complex conditions, described further below in the sec‐
39 tion "Extended user control".
40 user="username"
42 Limit the volume to the specified user, identified by name
43 uid="number" or uid="number-number"
45 Limit the volume to the specified user(s), identified by UID or
46 UID range.
47 pgrp="groupname"
49 Limit the volume to users which have the group identified by
50 name as their primary group.
51 gid="number" or gid="number-number"
53 Limit the volume to users which have the group(s) given by GID
54 or GID range as a primary group.
55 sgrp="groupname"
57 Limit the volume to users which are a member of the group iden‐
58 tified by name (either as primary or secondary group).
59 Volume configuration
61 The following attributes select volume source, destination, options and
62 so on.
63 fstype="type"
65 The filesystem type, which can be anything your kernel,
66 userspace and pam_mount understand. If the fstype specifies a
67 pam_mount-special type, pam_mount will handle it. Otherwise, the
68 fstype is passed to mount(8) which then in turn looks for a
69 userspace helper /sbin/mount.fstype and runs that if it exists,
70 and in any other case, mount(8) would call mount(2) to cause the
71 kernel to directly mount it. mount(8) knows of an auto fstype,
72 which might be helpful in some cases. Not specifying the fstype
73 attribute implies fstype="auto". Note that mounting with auto
74 may fail if the filesystem kernel module is not loaded yet,
75 since mount(8) will check /proc/partitions.
76 The fstypes cifs, smbfs, ncpfs, fuse, nfs and nfs4 are overrid‐
78 den by pam_mount and we run the respective helper programs di‐
79 rectly instead of invoking mount(8) with the basic default set
80 of arguments which are often insufficient for networked filesys‐
81 tems. See this manpage's section "Examples" below for more de‐
82 tails.
83 noroot="1"
85 Call the mount program without root privileges. It defaults to
86 yes for the fuse fstype, because FUSE volumes must be mounted as
87 the user that logs in to get access to the files by default.
88 server="name"
90 Defines the server to which to connect in case of cifs, smbfs
91 and ncpfs and nfs fstypes. For all other fs types, this attri‐
92 bute is ignored. You can also specify the server in the path at‐
93 tribute instead, but need to adhere to the specific syntax that
94 is a particular fstype requires. (E.g. CIFS uses
95 "//server/path", whereas NFS uses "server:path", etc.)
96 path="path"
98 This mandatory attribute specifies the location of the volume,
99 relative to the server (if specified).
100 mountpoint="directory"
102 This specifies the destination directory onto which the volume
103 is mounted. "~" expands to the user's home directory as present
104 in the passwd database, according to sh semantics. "~name" is
105 not supported. If this attribute is omitted, the location is
106 read from /etc/fstab, which also requires path to be a device or
107 a source directory of an fstab entry.
108 header="path"
110 This specifies a detached (separated) metadata file where the
111 LUKS header is stored. This correlates with the `cryptsetup
112 --header` option. If this attribute is omitted, the detached
113 LUKS header feature is not used.
114 options="..."
116 Specifies the mount options. If omitted and /etc/fstab is used
117 (see mountpoint), the options will also be sources from fstab.
118 ssh="0" or ssh="1"
120 The ssh option enables an input hack wrapper (zerossh, see
121 fd0ssh(1)) for this volume to hand the password to ssh over an
122 ssh-specific mechanism. Enable this option for any mount involv‐
123 ing the SSH binary, e.g. ccgfs or sshfs. Do not enable it for
124 anything else or the login will most likely hang.
125 cipher="cipher"
127 Cryptsetup cipher name for the volume. To be used with the crypt
128 fstype.
129 fskeycipher="ciphertype"
131 OpenSSL cipher name for the fskey. Use with the crypt fstype
132 (dm-crypt and LUKS). The special cipher keyword "none" may be
133 used to directly pass the file's contents to cryptsetup without
134 decryption by OpenSSL.
135 fskeyhash="hash"
137 OpenSSL hash name for the fskey.
138 fskeypath="path"
140 Path to the filesystem key.
141
143 Within attributes and commands (see later section), specific placehold‐
144 ers or variables, identified by %(name) may be used. These are substi‐
145 tuted at command invocation time.
146 %(USER)
148 Expands to the username of the user logging in.
149 %(DOMAIN_NAME), %(DOMAIN_USER)
151 Winbind has special UNIX usernames in the form of "domain\user‐
152 name", and %(DOMAIN_NAME) and %(DOMAIN_USER) provide the split
153 parts of it. This is useful when a sharename on an MSAD server
154 is the same as the username, e.g. <volume fstype="cifs"
155 server="fsbox" path="%(DOMAIN_USER)" />.
156 %(USERUID), %(USERGID)
158 The numeric UID and GID of the primary group of the user logging
159 in. This is obtained via getpw*(), not getuid(). It is useful
160 in conjunction with the uid= or gid= mount options, e.g. <volume
161 options="uid=%(USERUID)" />. Note that you do not need to spec‐
162 ify uid=%(USERUID) for smbfs or cifs mounts because this is al‐
163 ready done automatically by pam_mount.
164 %(GROUP)
166 The name of the group for %(USERGID).
167 All other variables you might find in the source code are internal to
169 pam_mount, and are likely not to be expanded when you would expect it.
170
172 Besides volumes, there are other elements allowed in pam_mount.conf.xml
173 that control pam_mount's own behavior.
174 General tunables
176 <debug enable="1" />
177 Enables verbose output during login to stderr and syslog. Some
178 programs do not cope with output sent on stderr, see
179 doc/bugs.txt for a list. 0 disables debugging, 1 enables
180 pam_mount tracing, and 2 additionally enables tracing in
181 mount.crypt. The default is 0. As the config file is parsed lin‐
182 early, the <debug> directive takes effect once it is seen - it
183 it thus advised to put it near the start of the file, before any
184 <volume> definitions.
185 <logout wait="microseconds" hup="yes/no" term="yes/no" kill="yes/no" />
187 Programs exist that do not terminate when the session is closed.
188 (This applies to the "final" close, i.e. when the last user ses‐
189 sion ends.) Examples are processes still running in the back‐
190 ground; or a broken X session manager that did not clean up its
191 children, or other X programs that did not react to the X server
192 termination notification. pam_mount can be configured to kill
193 these processes and optionally wait before sending signals.
194 <luserconf name=".pam_mount.conf.xml" />
196 Individual users may define additional volumes in a file by the
197 specified name relative to their home directory. The presence of
198 <luserconf> in the master config file enables this feature. If
199 turned on, users may mount and unmount any volumes they specify
200 and that they have ownership of (in case of local mounts). The
201 mount process is executed as superuser. This may have security
202 implications, so this feature is disabled by default. Lusercon‐
203 figs are parsed after any volumes from the global configuration
204 file have been mounted, so that first mounting home directories
205 with a global config and then mounting further volumes from
206 luserconfigs is possible.
207 <mntoptions allow="options,..." />
209 The <mntoptions> elements determine which options may be speci‐
210 fied in <volumes> in per-user configuration files (see <luser‐
211 conf>). It does not apply to the master file. Specifying <mntop‐
212 tions> is forbidden and ignored in per-user configs. The default
213 allowed list consists of "nosuid,nodev", and this default is
214 cleared when the first allow="..." attribute is seen by the con‐
215 fig parser. All further allow="..." are additive, though.
216 <mntoptions deny="options,..." />
218 Any options listed in deny may not appear in the option list of
219 per-user mounts. The default deny list is empty.
220 <mntoptions require="options,..." />
222 All options listed in require must appear in the option list of
223 per-user mounts. The default require list consists of "no‐
224 suid,nodev", and like allow="", is cleared when first encoun‐
225 tered by the parser, and is otherwise additive.
226 <path>directories...</path>
228 The default for the PATH environmental variable is not consis‐
229 tent across distributions, and so, pam_mount provides its own
230 set of sane defaults which you may change at will.
231 Volume-related
233 <mkmountpoint enable="1" remove="true" />
234 Controls automatic creation and removal of mountpoints. If a
235 mountpoint does not exist when the volume is about to be
236 mounted, pam_mount can be instructed to create one using the en‐
237 able attribute. Normally, directories created this way are re‐
238 tained after logout, but remove may be set to true to remove the
239 mountpoint again, but only if it was automatically created by
240 pam_mount in the same session before.
241 Auxiliary programs
243 Some mount programs need special default parameters to properly func‐
244 tion. It is good practice to specify uid= for CIFS for example, because
245 it is mounted as root and would otherwise show files belonging to root
246 instead of the user logging in.
247 <fd0ssh>program...</fd0ssh>
249 fd0ssh is a hack around OpenSSH that essentially makes it read
250 passwords from stdin even though OpenSSH normally does not do
251 that.
252 <fsck>fsck -p %(FSCKTARGET)</fsck>
254 Local volumes will be checked before mounting if this program is
255 set.
256 <ofl>ofl -k%(SIGNAL) %(MNTPT)</ofl>
258 The Open File Lister is used to identify processes using files
259 within the given subdirectory, and optionally send a signal to
260 those processes.
261 <pmvarrun>pmvarrun ...</pmvarrun>
263 pmvarrun(8) is a separate program to manage the reference count
264 tracking user sessions.
265 Mount programs
267 Commands to mount/unmount volumes. They can take parameters, as shown.
268 You can specify either absolute paths, or relative ones, in which case
269 $PATH will be searched. Since login programs have differing default
270 PATHs, pam_mount has its own path definition (see above).
271 <lclmount>mount -t %(FSTYPE) ...</lclmount>
273 The regular mount program.
274 <umount>umount %(MNTPT)</umount>
276 Unless there is a dedicated umount program for a given filesys‐
277 tem type, the regular umount program will be used.
278 Linux supports lazy unmounting using `/sbin/umount -l`. This may
280 be dangerous for encrypted volumes because the underlying device
281 is not unmapped. Loopback devices are also affected by this (not
282 being unmapped when files are still open). Also, unmount on SMB
283 volumes needs to be called on %(MNTPT) and not %(VOLUME).
284 Commands for various mount programs. Not all have a dedicated umount
286 helper because some do not need one.
287 <cifsmount>mount.cifs ...</cifsmount>
289 <cryptmount>mount.crypt ...</cryptmount>
291 <cryptumount>umount.crypt %(MNTPT)</cryptumount>
293 Mount helpers for dm-crypt and LUKS volumes.
294 <fusemount>mount.fuse ...</fusemount>
296 <fuseumount>fuserumount ...</fuseumount>
298 <ncpmount>ncpmount ...</ncpmount>
300 <ncpumount>ncpumount ...</ncpumount>
302 <nfsmount>mount %(SERVER):%(VOLUME) ...</nfsmount>
304 <smbmount>smbmount ...</smbmount>
306 <smbumount>smbumount ...</smbumount>
308 Messages
310 <msg-authpw>pam_mount password:</msg-authpw>
311 When pam_mount cannot obtain a password through PAM, or is con‐
312 figured to not do so in the first place, and is configured to
313 ask for a password interactively as a replacement, this prompt
314 will be shown.
315 <msg-sessionpw>reenter...:</msg-sessionpw>
317 In case the 'session' PAM block does not have the password (e.g.
318 on su from root to user), it will ask again. This prompt can
319 also be customized.
320
322 Sometimes, the simple user control attributes for the <volume> element
323 are not sufficient where one may want to build more complex expressions
324 as to whom a volume applies. Instead of attributes, extended user con‐
325 trol is set up using additional elements within <volume>, for example
326 <volume path="/dev/shm" mountpoint="~"> <and> <sgrp>students</sgrp>
328 <not> <sgrp>profs</sgrp> </not> </and> </volume>
329 Which translates to (students && !profs).
331 Logical operators
333 <and><elements>*</and>
334 All elements within this one are logically ANDed. Any number of
335 elements may appear.
336 <or><elements>*</or>
338 All elements within this one are logically ORed. Any number of
339 elements may appear.
340 <xor><elements>{2}</xor>
342 The two elements within the <xor> are logically XORed.
343 <not><element></not>
345 The single element within the <not> is logically negated.
346 User selection
348 <user>username</user>
349 Match against the given username.
350 <uid>number</uid> or <uid>number-number</uid>
352 Match the UID of the user logging in against a UID or UID range.
353 <gid>number</gid> or <gid>number-number</gid>
355 Match the primary group of the user logging in against a GID or
356 GID range.
357 <pgrp>groupname</pgrp>
359 Check if the user logging in has groupname as the primary group.
360 <sgrp>groupname</sgrp>
362 Check if the user logging in is a member of the group given by
363 name (i.e. it is either a primary or secondary group).
364 Attributes
366 icase="yes" or icase="no"
367 The icase attribute may be used on <user>, <pgrp> and <sgrp> to
368 enable case-insensitive matching (or not). It defaults to "no".
369 regex="yes" (or no)
371 The regex attribute may be used on <user>, <pgrp> and <sgrp> to
372 enable interpreting the text content of the tag as a Perl-com‐
373 patible regular expression pattern. This attribute may be com‐
374 bined with "icase" (see above). Example: <user
375 regex="yes">joe</user> matches any user who has the letter se‐
376 quence "joe" anywhere in their username. Therefore, use the
377 regex feature cautiously and consider adding ^ and $ anchors to
378 limit security surprises. Example: <user
379 regex="yes">^.*joe.*$</user> if you really wanted to match the
380 sequence at any position.
381
383 Remember that ~ can be used in the mountpoint attribute to denote the
384 home directory as retrievable through getpwent(3).
385 sshfs and ccgfs
387 Not specifying any path after the colon (:) uses the path wherever ssh
388 will put you in, usually the home directory. With fd0ssh (package hx‐
389 tools) installed:
390 <volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~"
392 ssh="1" />
393 Without fd0ssh:
395 <volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~"
397 options="nosuid,nodev,noatime,reconnect,nonempty,allow_other,de‐
398 fault_permissions,password_stdin" ssh="0" noroot="0" />
399 <volume fstype="fuse" path="ccgfs-ssh-pull#%(USER)@host:directory"
401 mountpoint="~" />
402 Note that sshfs's "password_stdin" option tries to locate a string
404 "assword" on ssh's output, while fd0ssh is rather using the "askpass"
405 API, which might also work with passphrase-protected SSH keys whose
406 prompt is quite different.
407 encfs 1.4.x and up
409 <volume fstype="fuse" path="encfs#/crypto/%(USER)" mountpoint="~" op‐
410 tions="nonempty" />
411 (encfs 1.3 is no longer supported.)
413 NFS mounts
415 <volume fstype="nfs" server="fileserver" path="/home/%(USER)" mount‐
416 point="~" />
417 CIFS/SMB mounts
419 <volume user="user" fstype="smbfs" server="krueger" path="public"
420 mountpoint="/home/user/krueger" />
421 NCP mounts
423 <volume user="user" fstype="ncpfs" server="krueger" path="public"
424 mountpoint="/home/user/krueger" options="username=user.context" />
425 Bind mounts
427 This may come useful in conjunction with pam_chroot:
428 <volume path="/bin" mountpoint="~/bin" options="bind" />
430 tmpfs mounts
432 Volatile tmpfs mount with restricted size (thanks to Mike Hommey for
433 this example):
434 <volume user="test" fstype="tmpfs" mountpoint="/home/test" op‐
436 tions="size=10M,uid=%(USER),mode=0700" />
437 dm-crypt volumes
439 Crypt mounts require a kernel with CONFIG_BLK_DEV_DM and CON‐
440 FIG_DM_CRYPT enabled, as well as all the ciphers that are going to be
441 used, e.g. CONFIG_CRYPTO_AES, CONFIG_CRYPTO_BLOWFISH, CON‐
442 FIG_CRYPTO_TWOFISH.
443 <volume path="/home/%(USER).img" mountpoint="~" cipher="aes-cbc-es‐
445 siv:sha256" fskeycipher="aes-256-cbc" fskeyhash="sha1" fskey‐
446 path="/home/%(USER).key" />
447 LUKS volumes
449 <volume path="/home/%(USER).img" mountpoint="~" cipher="aes-cbc-es‐
450 siv:sha256" />
451 volume path="/home/%(USER).img" mountpoint="~"
453 header="/home/%(USER)-header.img" />
454 cryptoloop volumes
456 cryptoloop is not explicitly supported by pam_mount. Citing the Linux
457 kernel config help text: "WARNING: This device [cryptoloop] is not safe
458 for journal[l]ed filesystems[...]. Please use the Device Mapper [dm-
459 crypt] module instead."
460 OpenBSD encrypted home
462 OpenBSD encrypted home directory example:
463 <volume path="/home/user.img" mountpoint="/home/user" options="svnd0"
465 />
466pam_mount 2.19 2022-07-06 pam_mount.conf(5)