1pam_mount.conf(5) pam_mount 2.18 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 options="..."
110 Specifies the mount options. If omitted and /etc/fstab is used
111 (see mountpoint), the options will also be sources from fstab.
112 ssh="0" or ssh="1"
114 The ssh option enables an input hack wrapper (zerossh, see
115 fd0ssh(1)) for this volume to hand the password to ssh over an
116 ssh-specific mechanism. Enable this option for any mount involv‐
117 ing the SSH binary, e.g. ccgfs or sshfs. Do not enable it for
118 anything else or the login will most likely hang.
119 cipher="cipher"
121 Cryptsetup cipher name for the volume. To be used with the crypt
122 fstype.
123 fskeycipher="ciphertype"
125 OpenSSL cipher name for the fskey. Use with the crypt fstype
126 (dm-crypt and LUKS). The special cipher keyword "none" may be
127 used to directly pass the file's contents to cryptsetup without
128 decryption by OpenSSL.
129 fskeyhash="hash"
131 OpenSSL hash name for the fskey.
132 fskeypath="path"
134 Path to the filesystem key.
135
137 Within attributes and commands (see later section), specific placehold‐
138 ers or variables, identified by %(name) may be used. These are substi‐
139 tuted at command invocation time.
140 %(USER)
142 Expands to the username of the user logging in.
143 %(DOMAIN_NAME), %(DOMAIN_USER)
145 Winbind has special UNIX usernames in the form of "domain\user‐
146 name", and %(DOMAIN_NAME) and %(DOMAIN_USER) provide the split
147 parts of it. This is useful when a sharename on an MSAD server
148 is the same as the username, e.g. <volume fstype="cifs"
149 server="fsbox" path="%(DOMAIN_USER)" />.
150 %(USERUID), %(USERGID)
152 The numeric UID and GID of the primary group of the user logging
153 in. This is obtained via getpw*(), not getuid(). It is useful
154 in conjunction with the uid= or gid= mount options, e.g. <volume
155 options="uid=%(USERUID)" />. Note that you do not need to spec‐
156 ify uid=%(USERUID) for smbfs or cifs mounts because this is al‐
157 ready done automatically by pam_mount.
158 %(GROUP)
160 The name of the group for %(USERGID).
161 All other variables you might find in the source code are internal to
163 pam_mount, and are likely not to be expanded when you would expect it.
164
166 Besides volumes, there are other elements allowed in pam_mount.conf.xml
167 that control pam_mount's own behavior.
168 General tunables
170 <debug enable="1" />
171 Enables verbose output during login to stderr and syslog. Some
172 programs do not cope with output sent on stderr, see
173 doc/bugs.txt for a list. 0 disables debugging, 1 enables
174 pam_mount tracing, and 2 additionally enables tracing in
175 mount.crypt. The default is 0. As the config file is parsed lin‐
176 early, the <debug> directive takes effect once it is seen - it
177 it thus advised to put it near the start of the file, before any
178 <volume> definitions.
179 <logout wait="microseconds" hup="yes/no" term="yes/no" kill="yes/no" />
181 Programs exist that do not terminate when the session is closed.
182 (This applies to the "final" close, i.e. when the last user ses‐
183 sion ends.) Examples are processes still running in the back‐
184 ground; or a broken X session manager that did not clean up its
185 children, or other X programs that did not react to the X server
186 termination notification. pam_mount can be configured to kill
187 these processes and optionally wait before sending signals.
188 <luserconf name=".pam_mount.conf.xml" />
190 Individual users may define additional volumes in a file by the
191 specified name relative to their home directory. The presence of
192 <luserconf> in the master config file enables this feature. If
193 turned on, users may mount and unmount any volumes they specify
194 and that they have ownership of (in case of local mounts). The
195 mount process is executed as superuser. This may have security
196 implications, so this feature is disabled by default. Lusercon‐
197 figs are parsed after any volumes from the global configuration
198 file have been mounted, so that first mounting home directories
199 with a global config and then mounting further volumes from
200 luserconfigs is possible.
201 <mntoptions allow="options,..." />
203 The <mntoptions> elements determine which options may be speci‐
204 fied in <volumes> in per-user configuration files (see <luser‐
205 conf>). It does not apply to the master file. Specifying <mntop‐
206 tions> is forbidden and ignored in per-user configs. The default
207 allowed list consists of "nosuid,nodev", and this default is
208 cleared when the first allow="..." attribute is seen by the con‐
209 fig parser. All further allow="..." are additive, though.
210 <mntoptions deny="options,..." />
212 Any options listed in deny may not appear in the option list of
213 per-user mounts. The default deny list is empty.
214 <mntoptions require="options,..." />
216 All options listed in require must appear in the option list of
217 per-user mounts. The default require list consists of "no‐
218 suid,nodev", and like allow="", is cleared when first encoun‐
219 tered by the parser, and is otherwise additive.
220 <path>directories...</path>
222 The default for the PATH environmental variable is not consis‐
223 tent across distributions, and so, pam_mount provides its own
224 set of sane defaults which you may change at will.
225 Volume-related
227 <mkmountpoint enable="1" remove="true" />
228 Controls automatic creation and removal of mountpoints. If a
229 mountpoint does not exist when the volume is about to be
230 mounted, pam_mount can be instructed to create one using the en‐
231 able attribute. Normally, directories created this way are re‐
232 tained after logout, but remove may be set to true to remove the
233 mountpoint again, but only if it was automatically created by
234 pam_mount in the same session before.
235 Auxiliary programs
237 Some mount programs need special default parameters to properly func‐
238 tion. It is good practice to specify uid= for CIFS for example, because
239 it is mounted as root and would otherwise show files belonging to root
240 instead of the user logging in.
241 <fd0ssh>program...</fd0ssh>
243 fd0ssh is a hack around OpenSSH that essentially makes it read
244 passwords from stdin even though OpenSSH normally does not do
245 that.
246 <fsck>fsck -p %(FSCKTARGET)</fsck>
248 Local volumes will be checked before mounting if this program is
249 set.
250 <ofl>ofl -k%(SIGNAL) %(MNTPT)</ofl>
252 The Open File Lister is used to identify processes using files
253 within the given subdirectory, and optionally send a signal to
254 those processes.
255 <pmvarrun>pmvarrun ...</pmvarrun>
257 pmvarrun(8) is a separate program to manage the reference count
258 tracking user sessions.
259 Mount programs
261 Commands to mount/unmount volumes. They can take parameters, as shown.
262 You can specify either absolute paths, or relative ones, in which case
263 $PATH will be searched. Since login programs have differing default
264 PATHs, pam_mount has its own path definition (see above).
265 <lclmount>mount -t %(FSTYPE) ...</lclmount>
267 The regular mount program.
268 <umount>umount %(MNTPT)</umount>
270 Unless there is a dedicated umount program for a given filesys‐
271 tem type, the regular umount program will be used.
272 Linux supports lazy unmounting using `/sbin/umount -l`. This may
274 be dangerous for encrypted volumes because the underlying device
275 is not unmapped. Loopback devices are also affected by this (not
276 being unmapped when files are still open). Also, unmount on SMB
277 volumes needs to be called on %(MNTPT) and not %(VOLUME).
278 Commands for various mount programs. Not all have a dedicated umount
280 helper because some do not need one.
281 <cifsmount>mount.cifs ...</cifsmount>
283 <cryptmount>mount.crypt ...</cryptmount>
285 <cryptumount>umount.crypt %(MNTPT)</cryptumount>
287 Mount helpers for dm-crypt and LUKS volumes.
288 <fusemount>mount.fuse ...</fusemount>
290 <fuseumount>fuserumount ...</fuseumount>
292 <ncpmount>ncpmount ...</ncpmount>
294 <ncpumount>ncpumount ...</ncpumount>
296 <nfsmount>mount %(SERVER):%(VOLUME) ...</nfsmount>
298 <smbmount>smbmount ...</smbmount>
300 <smbumount>smbumount ...</smbumount>
302 Messages
304 <msg-authpw>pam_mount password:</msg-authpw>
305 When pam_mount cannot obtain a password through PAM, or is con‐
306 figured to not do so in the first place, and is configured to
307 ask for a password interactively as a replacement, this prompt
308 will be shown.
309 <msg-sessionpw>reenter...:</msg-sessionpw>
311 In case the 'session' PAM block does not have the password (e.g.
312 on su from root to user), it will ask again. This prompt can
313 also be customized.
314
316 Sometimes, the simple user control attributes for the <volume> element
317 are not sufficient where one may want to build more complex expressions
318 as to whom a volume applies. Instead of attributes, extended user con‐
319 trol is set up using additional elements within <volume>, for example
320 <volume path="/dev/shm" mountpoint="~"> <and> <sgrp>students</sgrp>
322 <not> <sgrp>profs</sgrp> </not> </and> </volume>
323 Which translates to (students && !profs).
325 Logical operators
327 <and><elements>*</and>
328 All elements within this one are logically ANDed. Any number of
329 elements may appear.
330 <or><elements>*</or>
332 All elements within this one are logically ORed. Any number of
333 elements may appear.
334 <xor><elements>{2}</xor>
336 The two elements within the <xor> are logically XORed.
337 <not><element></not>
339 The single element within the <not> is logically negated.
340 User selection
342 <user>username</user>
343 Match against the given username.
344 <uid>number</uid> or <uid>number-number</uid>
346 Match the UID of the user logging in against a UID or UID range.
347 <gid>number</gid> or <gid>number-number</gid>
349 Match the primary group of the user logging in against a GID or
350 GID range.
351 <pgrp>groupname</pgrp>
353 Check if the user logging in has groupname as the primary group.
354 <sgrp>groupname</sgrp>
356 Check if the user logging in is a member of the group given by
357 name (i.e. it is either a primary or secondary group).
358 Attributes
360 icase="yes" or icase="no"
361 The icase attribute may be used on <user>, <pgrp> and <sgrp> to
362 enable case-insensitive matching (or not). It defaults to "no".
363 regex="yes" (or no)
365 The regex attribute may be used on <user>, <pgrp> and <sgrp> to
366 enable interpreting the text content of the tag as a Perl-com‐
367 patible regular expression pattern. This attribute may be com‐
368 bined with "icase" (see above). Example: <user
369 regex="yes">joe</user> matches any user who has the letter se‐
370 quence "joe" anywhere in their username. Therefore, use the
371 regex feature cautiously and consider adding ^ and $ anchors to
372 limit security surprises. Example: <user
373 regex="yes">^.*joe.*$</user> if you really wanted to match the
374 sequence at any position.
375
377 Remember that ~ can be used in the mountpoint attribute to denote the
378 home directory as retrievable through getpwent(3).
379 sshfs and ccgfs
381 Not specifying any path after the colon (:) uses the path wherever ssh
382 will put you in, usually the home directory. With fd0ssh (package hx‐
383 tools) installed:
384 <volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~"
386 ssh="1" />
387 Without fd0ssh:
389 <volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~"
391 options="nosuid,nodev,noatime,reconnect,nonempty,allow_other,de‐
392 fault_permissions,password_stdin" ssh="0" noroot="0" />
393 <volume fstype="fuse" path="ccgfs-ssh-pull#%(USER)@host:directory"
395 mountpoint="~" />
396 Note that sshfs's "password_stdin" option tries to locate a string
398 "assword" on ssh's output, while fd0ssh is rather using the "askpass"
399 API, which might also work with passphrase-protected SSH keys whose
400 prompt is quite different.
401 encfs 1.4.x and up
403 <volume fstype="fuse" path="encfs#/crypto/%(USER)" mountpoint="~" op‐
404 tions="nonempty" />
405 (encfs 1.3 is no longer supported.)
407 NFS mounts
409 <volume fstype="nfs" server="fileserver" path="/home/%(USER)" mount‐
410 point="~" />
411 CIFS/SMB mounts
413 <volume user="user" fstype="smbfs" server="krueger" path="public"
414 mountpoint="/home/user/krueger" />
415 NCP mounts
417 <volume user="user" fstype="ncpfs" server="krueger" path="public"
418 mountpoint="/home/user/krueger" options="username=user.context" />
419 Bind mounts
421 This may come useful in conjunction with pam_chroot:
422 <volume path="/bin" mountpoint="~/bin" options="bind" />
424 tmpfs mounts
426 Volatile tmpfs mount with restricted size (thanks to Mike Hommey for
427 this example):
428 <volume user="test" fstype="tmpfs" mountpoint="/home/test" op‐
430 tions="size=10M,uid=%(USER),mode=0700" />
431 dm-crypt volumes
433 Crypt mounts require a kernel with CONFIG_BLK_DEV_DM and CON‐
434 FIG_DM_CRYPT enabled, as well as all the ciphers that are going to be
435 used, e.g. CONFIG_CRYPTO_AES, CONFIG_CRYPTO_BLOWFISH, CON‐
436 FIG_CRYPTO_TWOFISH.
437 <volume path="/home/%(USER).img" mountpoint="~" cipher="aes-cbc-es‐
439 siv:sha256" fskeycipher="aes-256-cbc" fskeyhash="sha1" fskey‐
440 path="/home/%(USER).key" />
441 LUKS volumes
443 <volume path="/home/%(USER).img" mountpoint="~" cipher="aes-cbc-es‐
444 siv:sha256" />
445 cryptoloop volumes
447 cryptoloop is not explicitly supported by pam_mount. Citing the Linux
448 kernel config help text: "WARNING: This device [cryptoloop] is not safe
449 for journal[l]ed filesystems[...]. Please use the Device Mapper [dm-
450 crypt] module instead."
451 OpenBSD encrypted home
453 OpenBSD encrypted home directory example:
454 <volume path="/home/user.img" mountpoint="/home/user" options="svnd0"
456 />
457pam_mount 2.18 2021-01-04 pam_mount.conf(5)