1PAM_SYSTEMD(8)                    pam_systemd                   PAM_SYSTEMD(8)
2
3
4

NAME

6       pam_systemd - Register user sessions in the systemd login manager
7

SYNOPSIS

9       pam_systemd.so
10

DESCRIPTION

12       pam_systemd registers user sessions with the systemd login manager
13       systemd-logind.service(8), and hence the systemd control group
14       hierarchy.
15
16       The module also applies various resource management and runtime
17       parameters to the new session, as configured in the JSON User
18       Records[1] of the user, when one is defined.
19
20       On login, this module — in conjunction with systemd-logind.service —
21       ensures the following:
22
23        1. If it does not exist yet, the user runtime directory /run/user/$UID
24           is either created or mounted as new "tmpfs" file system with quota
25           applied, and its ownership changed to the user that is logging in.
26
27        2. The $XDG_SESSION_ID environment variable is initialized. If
28           auditing is available and pam_loginuid.so was run before this
29           module (which is highly recommended), the variable is initialized
30           from the auditing session id (/proc/self/sessionid). Otherwise, an
31           independent session counter is used.
32
33        3. A new systemd scope unit is created for the session. If this is the
34           first concurrent session of the user, an implicit per-user slice
35           unit below user.slice is automatically created and the scope placed
36           into it. An instance of the system service user@.service, which
37           runs the systemd user manager instance, is started.
38
39        4. The "$TZ", "$EMAIL" and "$LANG" environment variables are
40           configured for the user, based on the respective data from the
41           user's JSON record (if it is defined). Moreover, any environment
42           variables explicitly configured in the user record are imported,
43           and the umask, nice level, and resource limits initialized.
44
45       On logout, this module ensures the following:
46
47        1. If enabled in logind.conf(5) (KillUserProcesses=), all processes of
48           the session are terminated. If the last concurrent session of a
49           user ends, the user's systemd instance will be terminated too, and
50           so will the user's slice unit.
51
52        2. If the last concurrent session of a user ends, the user runtime
53           directory /run/user/$UID and all its contents are removed, too.
54
55       If the system was not booted up with systemd as init system, this
56       module does nothing and immediately returns PAM_SUCCESS.
57

OPTIONS

59       The following options are understood:
60
61       class=
62           Takes a string argument which sets the session class. The
63           XDG_SESSION_CLASS environment variable (see below) takes
64           precedence. One of "user", "greeter", "lock-screen" or
65           "background". See sd_session_get_class(3) for details about the
66           session class.
67
68       type=
69           Takes a string argument which sets the session type. The
70           XDG_SESSION_TYPE environment variable (see below) takes precedence.
71           One of "unspecified", "tty", "x11", "wayland" or "mir". See
72           sd_session_get_type(3) for details about the session type.
73
74       desktop=
75           Takes a single, short identifier string for the desktop
76           environment. The XDG_SESSION_DESKTOP environment variable (see
77           below) takes precedence. This may be used to indicate the session
78           desktop used, where this applies and if this information is
79           available. For example: "GNOME", or "KDE". It is recommended to use
80           the same identifiers and capitalization as for
81           $XDG_CURRENT_DESKTOP, as defined by the Desktop Entry
82           Specification[2]. (However, note that the option only takes a
83           single item, and not a colon-separated list like
84           $XDG_CURRENT_DESKTOP.) See sd_session_get_desktop(3) for further
85           details.
86
87       debug[=]
88           Takes an optional boolean argument. If yes or without the argument,
89           the module will log debugging information as it operates.
90

MODULE TYPES PROVIDED

92       Only session is provided.
93

ENVIRONMENT

95       The following environment variables are initialized by the module and
96       available to the processes of the user's session:
97
98       $XDG_SESSION_ID
99           A short session identifier, suitable to be used in filenames. The
100           string itself should be considered opaque, although often it is
101           just the audit session ID as reported by /proc/self/sessionid. Each
102           ID will be assigned only once during machine uptime. It may hence
103           be used to uniquely label files or other resources of this session.
104           Combine this ID with the boot identifier, as returned by
105           sd_id128_get_boot(3), for a globally unique identifier.
106
107       $XDG_RUNTIME_DIR
108           Path to a user-private user-writable directory that is bound to the
109           user login time on the machine. It is automatically created the
110           first time a user logs in and removed on the user's final logout.
111           If a user logs in twice at the same time, both sessions will see
112           the same $XDG_RUNTIME_DIR and the same contents. If a user logs in
113           once, then logs out again, and logs in again, the directory
114           contents will have been lost in between, but applications should
115           not rely on this behavior and must be able to deal with stale
116           files. To store session-private data in this directory, the user
117           should include the value of $XDG_SESSION_ID in the filename. This
118           directory shall be used for runtime file system objects such as
119           AF_UNIX sockets, FIFOs, PID files and similar. It is guaranteed
120           that this directory is local and offers the greatest possible file
121           system feature set the operating system provides. For further
122           details, see the XDG Base Directory Specification[3].
123           $XDG_RUNTIME_DIR is not set if the current user is not the original
124           user of the session.
125
126       $TZ, $EMAIL, $LANG
127           If a JSON user record is known for the user logging in these
128           variables are initialized from the respective data in the record.
129
130       The following environment variables are read by the module and may be
131       used by the PAM service to pass metadata to the module. If these
132       variables are not set when the PAM module is invoked but can be
133       determined otherwise they are set by the module, so that these
134       variables are initialized for the session and applications if known at
135       all.
136
137       $XDG_SESSION_TYPE
138           The session type. This may be used instead of type= on the module
139           parameter line, and is usually preferred.
140
141       $XDG_SESSION_CLASS
142           The session class. This may be used instead of class= on the module
143           parameter line, and is usually preferred.
144
145       $XDG_SESSION_DESKTOP
146           The desktop identifier. This may be used instead of desktop= on the
147           module parameter line, and is usually preferred.
148
149       $XDG_SEAT
150           The seat name the session shall be registered for, if any.
151
152       $XDG_VTNR
153           The VT number the session shall be registered for, if any. (Only
154           applies to seats with a VT available, such as "seat0")
155
156       If not set, pam_systemd will initialize $XDG_SEAT and $XDG_VTNR based
157       on the $DISPLAY variable (if the latter is set).
158

SESSION LIMITS

160       PAM modules earlier in the stack, that is those that come before
161       pam_systemd.so, can set session scope limits using the PAM context
162       objects. The data for these objects is provided as NUL-terminated C
163       strings and maps directly to the respective unit resource control
164       directives. Note that these limits apply to individual sessions of the
165       user, they do not apply to all user processes as a combined whole. In
166       particular, the per-user user@.service unit instance, which runs the
167       systemd --user manager process and its children, and is tracked outside
168       of any session, being shared by all the user's sessions, is not covered
169       by these limits.
170
171       See systemd.resource-control(5) for more information about the
172       resources. Also, see pam_set_data(3) for additional information about
173       how to set the context objects.
174
175       systemd.memory_max=
176           Sets unit MemoryMax=.
177
178       systemd.tasks_max=
179           Sets unit TasksMax=.
180
181       systemd.cpu_weight=
182           Sets unit CPUWeight=.
183
184       systemd.io_weight=
185           Sets unit IOWeight=.
186
187       systemd.runtime_max_sec=
188           Sets unit RuntimeMaxSec=.
189
190       Example data as can be provided from an another PAM module:
191
192           pam_set_data(handle, "systemd.memory_max", (void *)"200M", cleanup);
193           pam_set_data(handle, "systemd.tasks_max",  (void *)"50",   cleanup);
194           pam_set_data(handle, "systemd.cpu_weight", (void *)"100",  cleanup);
195           pam_set_data(handle, "systemd.io_weight",  (void *)"340",  cleanup);
196           pam_set_data(handle, "systemd.runtime_max_sec", (void *)"3600", cleanup);
197
198
199

EXAMPLE

201       Here's an example PAM configuration fragment that allows users sessions
202       to be managed by systemd-logind.service:
203
204           #%PAM-1.0
205           auth      sufficient pam_unix.so
206           -auth     sufficient pam_systemd_home.so
207           auth      required   pam_deny.so
208
209           account   required   pam_nologin.so
210           -account  sufficient pam_systemd_home.so
211           account   sufficient pam_unix.so
212           account   required   pam_permit.so
213
214           -password sufficient pam_systemd_home.so
215           password  sufficient pam_unix.so sha512 shadow try_first_pass use_authtok
216
217           password  required   pam_deny.so
218
219           -session  optional   pam_keyinit.so revoke
220           -session  optional   pam_loginuid.so
221           -session  optional   pam_systemd_home.so
222           -session  optional   pam_systemd.so
223           session   required   pam_unix.so
224

SEE ALSO

226       systemd(1), systemd-logind.service(8), logind.conf(5), loginctl(1),
227       pam_systemd_home(8), pam.conf(5), pam.d(5), pam(8), pam_loginuid(8),
228       systemd.scope(5), systemd.slice(5), systemd.service(5)
229

NOTES

231        1. JSON User Records
232           https://systemd.io/USER_RECORD
233
234        2. Desktop Entry Specification
235           https://standards.freedesktop.org/desktop-entry-spec/latest/
236
237        3. XDG Base Directory Specification
238           https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
239
240
241
242systemd 253                                                     PAM_SYSTEMD(8)
Impressum