1pam_mount.conf(5) pam_mount 2.5 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, encfs13, smbfs, ncpfs, fuse, nfs and nfs are
78 overriden by pam_mount and we run the respective helper programs
79 directly 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
82 details.
83 noroot="1"
85 Call the mount program without root privileges. It defaults to
86 yes for the encfs13 and fuse fstypes, because FUSE volumes must
87 be mounted as the user that logs in to get access to the files
88 by default.
89 server="name"
91 Defines the server to which to connect in case of cifs, smbfs
92 and ncpfs and nfs fstypes. For all other fs types, this
93 attribute is ignored.
94 path="path"
96 This mandatory attribute specifies the location of the volume,
97 relative to the server (if specified).
98 mountpoint="directory"
100 This specifies the destination directory onto which the volume
101 is mounted. "~" expands to the user's home directory as present
102 in the passwd database, according to sh semantics. "~name" is
103 not supported. If this attribute is omitted, the location is
104 read from /etc/fstab, which also requires path to be a device or
105 a source directory of an fstab entry.
106 options="..."
108 Specifies the mount options. If omitted and /etc/fstab is used
109 (see mountpoint), the options will also be sources from fstab.
110 ssh="0" or ssh="1"
112 The ssh option enables an input hack wrapper (zerossh, see
113 pmt-fd0ssh(1)) for this volume to hand the password to ssh over
114 an ssh-specific mechanism. Enable this option for any mount
115 involving the SSH binary, e.g. ccgfs or sshfs. Do not enable it
116 for anything else or the login will most likely hang.
117 cipher="cipher"
119 Cryptsetup cipher name for the volume. To be used with the crypt
120 fstype.
121 fskeycipher="ciphertype"
123 OpenSSL cipher name for the fskey. Use with the crypt fstype
124 (dm-crypt and LUKS). The special cipher keyword "none" may be
125 used to directly pass the file's contents to cryptsetup without
126 decryption by OpenSSL.
127 fskeyhash="hash"
129 OpenSSL hash name for the fskey.
130 fskeypath="path"
132 Path to the filesystem key.
133
135 Within attributes and commands (see later section), specific placehold‐
136 ers or variables, identified by %(name) may be used. These are substi‐
137 tuted at command invocation time.
138 %(USER)
140 Expands to the username of the user logging in.
141 %(DOMAIN_NAME), %(DOMAIN_USER)
143 Winbind has special UNIX usernames in the form of "domain\user‐
144 name", and %(DOMAIN_NAME) and %(DOMAIN_USER) provide the split
145 parts of it. This is useful when a sharename on an MSAD server
146 is the same as the username, e.g. <volume fstype="cifs"
147 server="fsbox" path="%(DOMAIN_USER)" />.
148 %(USERUID), %(USERGID)
150 The numeric UID and GID of the primary group of the user logging
151 in. This is obtained via getpw*(), not getuid(). It is useful
152 in conjunction with the uid= or gid= mount options, e.g. <volume
153 options="uid=%(USERUID)" />. Note that you do not need to spec‐
154 ify uid=%(USERUID) for smbfs or cifs mounts because this is
155 already done automatically by pam_mount.
156 %(GROUP)
158 The name of the group for %(USERGID).
159 All other variables you might find in the source code are internal to
161 pam_mount, and are likely not to be expanded when you would expect it.
162
164 Besides volumes, there are other elements allowed in pam_mount.conf.xml
165 that control pam_mount's own behavior.
166 General tunables
168 <debug enable="1" />
169 Enables verbose output during login to stderr and syslog. Some
170 programs do not cope with output sent on stderr, see
171 doc/bugs.txt for a list. 0 disables debugging, 1 enables
172 pam_mount tracing, and 2 additionally enables tracing in
173 mount.crypt. The default is 0. As the config file is parsed lin‐
174 early, the <debug> directive takes effect once it is seen - it
175 it thus advised to put it near the start of the file, before any
176 <volume> definitions.
177 <logout wait="microseconds" hup="yes/no" term="yes/no" kill="yes/no" />
179 Programs exist that do not terminate when the session is closed.
180 (This applies to the "final" close, i.e. when the last user ses‐
181 sion ends.) Examples are processes still running in the back‐
182 ground; or a broken X session manager that did not clean up its
183 children, or other X programs that did not react to the X server
184 termination notification. pam_mount can be configured to kill
185 these processes and optionally wait before sending signals.
186 <luserconf name=".pam_mount.conf.xml" />
188 Individual users may define additional volumes (usually in
189 ~/.pam_mount.conf.xml) to mount if allowed by the master config‐
190 uration file by the presence of the <luserconf> element. With
191 it, users may mount and unmount any volumes they specify that
192 they have ownership of (in case of local mounts) - the mount
193 process is called as superuser. On some filesystem configura‐
194 tions this may be a security risk so user-defined volumes are
195 not allowed by the default pam_mount.conf.xml distributed with
196 pam_mount. Luserconfigs are parsed after any volumes from the
197 global configuration file are mounted, so mounting home directo‐
198 ries 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 per-user configuration files (see <luserconf>). It does
204 not apply to the master file. Specifying <mntoptions> is for‐
205 bidden and ignored in per-user configs. It defaults to
206 allow="nosuid,nodev", and the default is cleared when the first
207 <mntoptions allow="..."> tag is seen. All further <mntoptions>
208 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. (Does not apply to the master file.)
213 <mntoptions require="options,..." />
215 All options listed in require must appear in the option list of
216 per-user mounts. (Does not apply to the master file.) It
217 defaults to nosuid,nodev, and the default is cleared when the
218 first <mntoptions require="..."> tag is seen. All further
219 <mntoptions> are additive, though.
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
231 enable attribute. Normally, directories created this way are
232 retained after logout, but remove may be set to true to remove
233 the mountpoint again, but only if it was automatically created
234 by 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 -p0 -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
365 Remember that ~ can be used in the mountpoint attribute to denote the
366 home directory as retrievable through getpwent(3).
367 sshfs and ccgfs
369 Not specifying any path after the colon (:) uses the path whereever ssh
370 will put you in, usually the home directory.
371 <volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~"
373 />
374 <volume fstype="fuse" path="ccgfs-ssh-pull#%(USER)@host:directory"
376 mountpoint="~" />
377 encfs 1.4.x and up
379 <volume fstype="fuse" path="encfs#/crypto/%(USER)" mountpoint="~"
380 options="nonempty" />
381 encfs 1.3.x
383 encfs 1.3.x did not support option passthrough, which is why a separate
384 helper (/sbin/mount.encfs13, installed by pam_mount) is needed. This
385 variant also supports 1.4.x, but it is encouraged to use fstype=fuse in
386 that case.
387 <volume fstype="encfs13" path="/crypto/%(USER)" mountpoint="~"
389 options="nonempty" />
390 NFS mounts
392 <volume fstype="nfs" server="fileserver" path="/home/%(USER)" mount‐
393 point="~" />
394 CIFS/SMB mounts
396 <volume user="user" fstype="smbfs" server="krueger" path="public"
397 mountpoint="/home/user/krueger" />
398 NCP mounts
400 <volume user="user" fstype="ncpfs" server="krueger" path="public"
401 mountpoint="/home/user/krueger" options="user=user.context" />
402 Bind mounts
404 This may come useful in conjunction with pam_chroot:
405 <volume path="/bin" mountpoint="~/bin" options="bind" />
407 tmpfs mounts
409 Volatile tmpfs mount with restricted size (thanks to Mike Hommey for
410 this example):
411 <volume user="test" fstype="tmpfs" mountpoint="/home/test"
413 options="size=10M,uid=%(USER),mode=0700" />
414 dm-crypt volumes
416 Crypt mounts require a kernel with CONFIG_BLK_DEV_DM and CON‐
417 FIG_DM_CRYPT enabled, as well as all the ciphers that are going to be
418 used, e.g. CONFIG_CRYPTO_AES, CONFIG_CRYPTO_BLOWFISH, CON‐
419 FIG_CRYPTO_TWOFISH.
420 <volume path="/home/%(USER).img" mountpoint="~"
422 cipher="aes-cbc-essiv:sha256" fskeycipher="aes-256-cbc" fskey‐
423 hash="sha1" fskeypath="/home/%(USER).key" />
424 LUKS volumes
426 <volume path="/home/%(USER).img" mountpoint="~"
427 cipher="aes-cbc-essiv:sha256" />
428 cryptoloop volumes
430 cryptoloop is not explicitly supported by pam_mount. Citing the Linux
431 kernel config help text: "WARNING: This device [cryptoloop] is not safe
432 for journal[l]ed filesystems[...]. Please use the Device Mapper [dm-
433 crypt] module instead."
434 OpenBSD encrypted home
436 OpenBSD encrypted home directory example:
437 <volume path="/home/user.img" mountpoint="/home/user" options="svnd0"
439 />
440pam_mount 2.5 2010-08-10 pam_mount.conf(5)