1pam_mount.conf(5) pam_mount 2.16 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 nfs are overriden
78 by pam_mount and we run the respective helper programs directly
79 instead of invoking mount(8) with the basic default set of argu‐
80 ments which are often insufficient for networked filesystems.
81 See this manpage's section "Examples" below for more details.
82 noroot="1"
84 Call the mount program without root privileges. It defaults to
85 yes for the fuse fstype, because FUSE volumes must be mounted as
86 the user that logs in to get access to the files by default.
87 server="name"
89 Defines the server to which to connect in case of cifs, smbfs
90 and ncpfs and nfs fstypes. For all other fs types, this
91 attribute is ignored. You can also specify the server in the
92 path attribute instead, but need to adhere to the specific syn‐
93 tax that is a particular fstype requires. (E.g. CIFS uses
94 "//server/path", whereas NFS uses "server:path", etc.)
95 path="path"
97 This mandatory attribute specifies the location of the volume,
98 relative to the server (if specified).
99 mountpoint="directory"
101 This specifies the destination directory onto which the volume
102 is mounted. "~" expands to the user's home directory as present
103 in the passwd database, according to sh semantics. "~name" is
104 not supported. If this attribute is omitted, the location is
105 read from /etc/fstab, which also requires path to be a device or
106 a source directory of an fstab entry.
107 options="..."
109 Specifies the mount options. If omitted and /etc/fstab is used
110 (see mountpoint), the options will also be sources from fstab.
111 ssh="0" or ssh="1"
113 The ssh option enables an input hack wrapper (zerossh, see
114 pmt-fd0ssh(1)) for this volume to hand the password to ssh over
115 an ssh-specific mechanism. Enable this option for any mount
116 involving the SSH binary, e.g. ccgfs or sshfs. Do not enable it
117 for anything else or the login will most likely hang.
118 cipher="cipher"
120 Cryptsetup cipher name for the volume. To be used with the crypt
121 fstype.
122 fskeycipher="ciphertype"
124 OpenSSL cipher name for the fskey. Use with the crypt fstype
125 (dm-crypt and LUKS). The special cipher keyword "none" may be
126 used to directly pass the file's contents to cryptsetup without
127 decryption by OpenSSL.
128 fskeyhash="hash"
130 OpenSSL hash name for the fskey.
131 fskeypath="path"
133 Path to the filesystem key.
134
136 Within attributes and commands (see later section), specific placehold‐
137 ers or variables, identified by %(name) may be used. These are substi‐
138 tuted at command invocation time.
139 %(USER)
141 Expands to the username of the user logging in.
142 %(DOMAIN_NAME), %(DOMAIN_USER)
144 Winbind has special UNIX usernames in the form of "domain\user‐
145 name", and %(DOMAIN_NAME) and %(DOMAIN_USER) provide the split
146 parts of it. This is useful when a sharename on an MSAD server
147 is the same as the username, e.g. <volume fstype="cifs"
148 server="fsbox" path="%(DOMAIN_USER)" />.
149 %(USERUID), %(USERGID)
151 The numeric UID and GID of the primary group of the user logging
152 in. This is obtained via getpw*(), not getuid(). It is useful
153 in conjunction with the uid= or gid= mount options, e.g. <volume
154 options="uid=%(USERUID)" />. Note that you do not need to spec‐
155 ify uid=%(USERUID) for smbfs or cifs mounts because this is
156 already done automatically by pam_mount.
157 %(GROUP)
159 The name of the group for %(USERGID).
160 All other variables you might find in the source code are internal to
162 pam_mount, and are likely not to be expanded when you would expect it.
163
165 Besides volumes, there are other elements allowed in pam_mount.conf.xml
166 that control pam_mount's own behavior.
167 General tunables
169 <debug enable="1" />
170 Enables verbose output during login to stderr and syslog. Some
171 programs do not cope with output sent on stderr, see
172 doc/bugs.txt for a list. 0 disables debugging, 1 enables
173 pam_mount tracing, and 2 additionally enables tracing in
174 mount.crypt. The default is 0. As the config file is parsed lin‐
175 early, the <debug> directive takes effect once it is seen - it
176 it thus advised to put it near the start of the file, before any
177 <volume> definitions.
178 <logout wait="microseconds" hup="yes/no" term="yes/no" kill="yes/no" />
180 Programs exist that do not terminate when the session is closed.
181 (This applies to the "final" close, i.e. when the last user ses‐
182 sion ends.) Examples are processes still running in the back‐
183 ground; or a broken X session manager that did not clean up its
184 children, or other X programs that did not react to the X server
185 termination notification. pam_mount can be configured to kill
186 these processes and optionally wait before sending signals.
187 <luserconf name=".pam_mount.conf.xml" />
189 Individual users may define additional volumes in a file by the
190 specified name relative to their home directory. The presence of
191 <luserconf> in the master config file enables this feature. If
192 turned on, users may mount and unmount any volumes they specify
193 and that they have ownership of (in case of local mounts). The
194 mount process is executed as superuser. This may have security
195 implications, so this feature is disabled by default. Lusercon‐
196 figs are parsed after any volumes from the global configuration
197 file have been mounted, so that first mounting home directories
198 with a global config and then mounting further volumes from
199 luserconfigs is possible.
200 <mntoptions allow="options,..." />
202 The <mntoptions> elements determine which options may be speci‐
203 fied in <volumes> in per-user configuration files (see <luser‐
204 conf>). It does not apply to the master file. Specifying <mntop‐
205 tions> is forbidden and ignored in per-user configs. The default
206 allowed list consists of "nosuid,nodev", and this default is
207 cleared when the first allow="..." attribute is seen by the con‐
208 fig parser. All further allow="..." are additive, though.
209 <mntoptions deny="options,..." />
211 Any options listed in deny may not appear in the option list of
212 per-user mounts. The default deny list is empty.
213 <mntoptions require="options,..." />
215 All options listed in require must appear in the option list of
216 per-user mounts. The default require list consists of
217 "nosuid,nodev", and like allow="", is cleared when first encoun‐
218 tered by the parser, and is otherwise additive.
219 <path>directories...</path>
221 The default for the PATH environmental variable is not consis‐
222 tent across distributions, and so, pam_mount provides its own
223 set of sane defaults which you may change at will.
224 Volume-related
226 <mkmountpoint enable="1" remove="true" />
227 Controls automatic creation and removal of mountpoints. If a
228 mountpoint does not exist when the volume is about to be
229 mounted, pam_mount can be instructed to create one using the
230 enable attribute. Normally, directories created this way are
231 retained after logout, but remove may be set to true to remove
232 the mountpoint again, but only if it was automatically created
233 by pam_mount in the same session before.
234 Auxiliary programs
236 Some mount programs need special default parameters to properly func‐
237 tion. It is good practice to specify uid= for CIFS for example, because
238 it is mounted as root and would otherwise show files belonging to root
239 instead of the user logging in.
240 <fd0ssh>program...</fd0ssh>
242 fd0ssh is a hack around OpenSSH that essentially makes it read
243 passwords from stdin even though OpenSSH normally does not do
244 that.
245 <fsck>fsck -p %(FSCKTARGET)</fsck>
247 Local volumes will be checked before mounting if this program is
248 set.
249 <ofl>ofl -k%(SIGNAL) %(MNTPT)</ofl>
251 The Open File Lister is used to identify processes using files
252 within the given subdirectory, and optionally send a signal to
253 those processes.
254 <pmvarrun>pmvarrun ...</pmvarrun>
256 pmvarrun(8) is a separate program to manage the reference count
257 tracking user sessions.
258 Mount programs
260 Commands to mount/unmount volumes. They can take parameters, as shown.
261 You can specify either absolute paths, or relative ones, in which case
262 $PATH will be searched. Since login programs have differing default
263 PATHs, pam_mount has its own path definition (see above).
264 <lclmount>mount -t %(FSTYPE) ...</lclmount>
266 The regular mount program.
267 <umount>umount %(MNTPT)</umount>
269 Unless there is a dedicated umount program for a given filesys‐
270 tem type, the regular umount program will be used.
271 Linux supports lazy unmounting using `/sbin/umount -l`. This may
273 be dangerous for encrypted volumes because the underlying device
274 is not unmapped. Loopback devices are also affected by this (not
275 being unmapped when files are still open). Also, unmount on SMB
276 volumes needs to be called on %(MNTPT) and not %(VOLUME).
277 Commands for various mount programs. Not all have a dedicated umount
279 helper because some do not need one.
280 <cifsmount>mount.cifs ...</cifsmount>
282 <cryptmount>mount.crypt ...</cryptmount>
284 <cryptumount>umount.crypt %(MNTPT)</cryptumount>
286 Mount helpers for dm-crypt and LUKS volumes.
287 <fusemount>mount.fuse ...</fusemount>
289 <fuseumount>fuserumount ...</fuseumount>
291 <ncpmount>ncpmount ...</ncpmount>
293 <ncpumount>ncpumount ...</ncpumount>
295 <nfsmount>mount %(SERVER):%(VOLUME) ...</nfsmount>
297 <smbmount>smbmount ...</smbmount>
299 <smbumount>smbumount ...</smbumount>
301 Messages
303 <msg-authpw>pam_mount password:</msg-authpw>
304 When pam_mount cannot obtain a password through PAM, or is con‐
305 figured to not do so in the first place, and is configured to
306 ask for a password interactively as a replacement, this prompt
307 will be shown.
308 <msg-sessionpw>reenter...:</msg-sessionpw>
310 In case the 'session' PAM block does not have the password (e.g.
311 on su from root to user), it will ask again. This prompt can
312 also be customized.
313
315 Sometimes, the simple user control attributes for the <volume> element
316 are not sufficient where one may want to build more complex expressions
317 as to whom a volume applies. Instead of attributes, extended user con‐
318 trol is set up using additional elements within <volume>, for example
319 <volume path="/dev/shm" mountpoint="~"> <and> <sgrp>students</sgrp>
321 <not> <sgrp>profs</sgrp> </not> </and> </volume>
322 Which translates to (students && !profs).
324 Logical operators
326 <and><elements>*</and>
327 All elements within this one are logically ANDed. Any number of
328 elements may appear.
329 <or><elements>*</or>
331 All elements within this one are logically ORed. Any number of
332 elements may appear.
333 <xor><elements>{2}</xor>
335 The two elements within the <xor> are logically XORed.
336 <not><element></not>
338 The single element within the <not> is logically negated.
339 User selection
341 <user>username</user>
342 Match against the given username.
343 <uid>number</uid> or <uid>number-number</uid>
345 Match the UID of the user logging in against a UID or UID range.
346 <gid>number</gid> or <gid>number-number</gid>
348 Match the primary group of the user logging in against a GID or
349 GID range.
350 <pgrp>groupname</pgrp>
352 Check if the user logging in has groupname as the primary group.
353 <sgrp>groupname</sgrp>
355 Check if the user logging in is a member of the group given by
356 name (i.e. it is either a primary or secondary group).
357 Attributes
359 icase="yes" or icase="no"
360 The icase attribute may be used on <user>, <pgrp> and <sgrp> to
361 enable case-insensitive matching (or not). It defaults to "no".
362 regex="yes" (or no)
364 The regex attribute may be used on <user>, <pgrp> and <sgrp> to
365 enable interpreting the text content of the tag as a Perl-com‐
366 patible regular expression pattern. This attribute may be com‐
367 bined with "icase" (see above). Example: <user
368 regex="yes">joe</user> matches any user who has the letter
369 sequence "joe" anywhere in their username. Therefor, use the
370 regex feature cautiously and consider adding ^ and $ anchors to
371 limit security surprises. Example: <user
372 regex="yes">^.*joe.*$</user> if you really wanted to match the
373 sequence at any position.
374
376 Remember that ~ can be used in the mountpoint attribute to denote the
377 home directory as retrievable through getpwent(3).
378 sshfs and ccgfs
380 Not specifying any path after the colon (:) uses the path whereever ssh
381 will put you in, usually the home directory.
382 <volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~"
384 />
385 <volume fstype="fuse" path="ccgfs-ssh-pull#%(USER)@host:directory"
387 mountpoint="~" />
388 encfs 1.4.x and up
390 <volume fstype="fuse" path="encfs#/crypto/%(USER)" mountpoint="~"
391 options="nonempty" />
392 (encfs 1.3 is no longer supported.)
394 NFS mounts
396 <volume fstype="nfs" server="fileserver" path="/home/%(USER)" mount‐
397 point="~" />
398 CIFS/SMB mounts
400 <volume user="user" fstype="smbfs" server="krueger" path="public"
401 mountpoint="/home/user/krueger" />
402 NCP mounts
404 <volume user="user" fstype="ncpfs" server="krueger" path="public"
405 mountpoint="/home/user/krueger" options="username=user.context" />
406 Bind mounts
408 This may come useful in conjunction with pam_chroot:
409 <volume path="/bin" mountpoint="~/bin" options="bind" />
411 tmpfs mounts
413 Volatile tmpfs mount with restricted size (thanks to Mike Hommey for
414 this example):
415 <volume user="test" fstype="tmpfs" mountpoint="/home/test"
417 options="size=10M,uid=%(USER),mode=0700" />
418 dm-crypt volumes
420 Crypt mounts require a kernel with CONFIG_BLK_DEV_DM and CON‐
421 FIG_DM_CRYPT enabled, as well as all the ciphers that are going to be
422 used, e.g. CONFIG_CRYPTO_AES, CONFIG_CRYPTO_BLOWFISH, CON‐
423 FIG_CRYPTO_TWOFISH.
424 <volume path="/home/%(USER).img" mountpoint="~"
426 cipher="aes-cbc-essiv:sha256" fskeycipher="aes-256-cbc" fskey‐
427 hash="sha1" fskeypath="/home/%(USER).key" />
428 LUKS volumes
430 <volume path="/home/%(USER).img" mountpoint="~"
431 cipher="aes-cbc-essiv:sha256" />
432 cryptoloop volumes
434 cryptoloop is not explicitly supported by pam_mount. Citing the Linux
435 kernel config help text: "WARNING: This device [cryptoloop] is not safe
436 for journal[l]ed filesystems[...]. Please use the Device Mapper [dm-
437 crypt] module instead."
438 OpenBSD encrypted home
440 OpenBSD encrypted home directory example:
441 <volume path="/home/user.img" mountpoint="/home/user" options="svnd0"
443 />
444pam_mount 2.16 2016-09-23 pam_mount.conf(5)