1 .\"@ pam_xdg - manage XDG Base Directories (runtime dir life time, environ).
2 .\"
3 .\" Copyright (c) 2021 Steffen Nurpmeso <steffen@sdaoden.eu>.
4 .\" SPDX-License-Identifier: ISC
5 .\"
6 .\" Permission to use, copy, modify, and/or distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .
18 .Dd July 29, 2021
19 .Dt PAM_XDG 8
20 .Os
21 .
22 .
23 .Sh NAME
24 .Nm pam_xdg.so
25 .Nd PAM module that manages XDG Base Directories
26 .
27 .
28 .Sh SYNOPSIS
29 .
30 .Nm
31 .Op Ar runtime
32 .Op Ar notroot
33 .\".Op Ar track_user_sessions Op Ar per_user_lock
34 .
35 .
36 .Sh DESCRIPTION
37 .
38 .Nm
39 is a PAM module that manages creation of the
40 .Ev XDG_RUNTIME_DIR
41 directory, as well as injection of environment variables denoting all
42 directories specified by the
43 .Lk https://specifications.\:freedesktop.\:org/basedir-\:\
44 spec/\:basedir-\:spec-\:latest.html "XDG Base Directory Specification"
45 into user sessions.
46 .
47 .Pp
48 When linked into the PAM session system the runtime directory will be
49 created once a user creates his or her first login session.
50 Unless
51 .Ar runtime
52 was given all XDG related environment variables will be created in all
53 user sessions with their default or computed values, otherwise only
54 .Ev XDG_RUNTIME_DIR .
55 If
56 .Ar notroot
57 was given the module will bypass itself for root account logins and
58 perform no actions for root.
59 .\"Lastly
60 .\".Ar track_user_sessions
61 .\"will enable session tracking: once the last session ends, the user's
62 .\".Ev XDG_RUNTIME_DIR
63 .\"will be recursively removed; on high-load servers setting
64 .\".Ar per_user_lock
65 .\"then will reduce lock file lock contention.
66 .
67 .Pp
68 In order to make use of this module, place the following in the
69 .Ql session
70 part of the control file of desire under
71 .Pa /etc/pam.d ,
72 on Linux it may be
73 .Pa /etc/pam.d/common-session
74 if that exists, on BSD's the files
75 .Pa /etc/pam.d/system
76 as well as
77 .Pa /etc/pam.d/login ,
78 .Pa /etc/pam.d/sshd
79 and
80 .Pa /etc/pam.d/su
81 may be desirable, adjusting paths as necessary:
82 .
83 .Bd -literal -offset indent
84 session optional pam_xdg.so notroot \"track_user_sessions
85 .Ed
86 .
87 .
88 .Sh "SEE ALSO"
89 .
90 .Xr pam 3 ,
91 .Xr pam.conf 5
92 .
93 .
94 .Sh AUTHORS
95 .
96 .An "Steffen Nurpmeso" Aq steffen@sdaoden.eu .
97 .
98 .
99 .Sh CAVEATS
100 .
101 On Unix systems any
102 .Dq daemonized
103 program or script is reparented to the program running with PID 1,
104 therefore leaving the PAM user session without PAM recognizing this.
105 Yet careless such code may hold or expect availability of resources of
106 the session it just left, truly performing cleanup when sessions end
107 seems thus unwise.
108 .\"However, many PAM modules do support cleanup upon closing the last
109 .\"session of a user, and therefore
110 .\".Nm
111 .\"supports this optionally, too.
112 .
113 .\" s-ts-mode
|
