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 Record[1]
18       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 for the
106           current session.
107
108       $XDG_RUNTIME_DIR
109           Path to a user-private user-writable directory that is bound to the
110           user login time on the machine. It is automatically created the
111           first time a user logs in and removed on the user's final logout.
112           If a user logs in twice at the same time, both sessions will see
113           the same $XDG_RUNTIME_DIR and the same contents. If a user logs in
114           once, then logs out again, and logs in again, the directory
115           contents will have been lost in between, but applications should
116           not rely on this behavior and must be able to deal with stale
117           files. To store session-private data in this directory, the user
118           should include the value of $XDG_SESSION_ID in the filename. This
119           directory shall be used for runtime file system objects such as
120           AF_UNIX sockets, FIFOs, PID files and similar. It is guaranteed
121           that this directory is local and offers the greatest possible file
122           system feature set the operating system provides. For further
123           details, see the XDG Base Directory Specification[3].
124           $XDG_RUNTIME_DIR is not set if the current user is not the original
125           user of the session.
126
127       $TZ, $EMAIL, $LANG
128           If a JSON user record is known for the user logging in these
129           variables are initialized from the respective data in the record.
130
131       The following environment variables are read by the module and may be
132       used by the PAM service to pass metadata to the module. If these
133       variables are not set when the PAM module is invoked but can be
134       determined otherwise they are set by the module, so that these
135       variables are initialized for the session and applications if known at
136       all.
137
138       $XDG_SESSION_TYPE
139           The session type. This may be used instead of type= on the module
140           parameter line, and is usually preferred.
141
142       $XDG_SESSION_CLASS
143           The session class. This may be used instead of class= on the module
144           parameter line, and is usually preferred.
145
146       $XDG_SESSION_DESKTOP
147           The desktop identifier. This may be used instead of desktop= on the
148           module parameter line, and is usually preferred.
149
150       $XDG_SEAT
151           The seat name the session shall be registered for, if any.
152
153       $XDG_VTNR
154           The VT number the session shall be registered for, if any. (Only
155           applies to seats with a VT available, such as "seat0")
156
157       If not set, pam_systemd will initialize $XDG_SEAT and $XDG_VTNR based
158       on the $DISPLAY variable (if the latter is set).
159

SESSION LIMITS

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

EXAMPLE

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

SEE ALSO

221       systemd(1), systemd-logind.service(8), logind.conf(5), loginctl(1),
222       pam_systemd_home(8), pam.conf(5), pam.d(5), pam(8), pam_loginuid(8),
223       systemd.scope(5), systemd.slice(5), systemd.service(5)
224

NOTES

226        1. JSON User Record
227           https://systemd.io/USER_RECORD
228
229        2. Desktop Entry Specification
230           http://standards.freedesktop.org/desktop-entry-spec/latest/
231
232        3. XDG Base Directory Specification
233           http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
234
235
236
237systemd 245                                                     PAM_SYSTEMD(8)
Impressum