1PAM_SYSTEMD(8) pam_systemd PAM_SYSTEMD(8)
2
6 pam_systemd - Register user sessions in the systemd login manager
7
9 pam_systemd.so
10
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 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 On login, this module — in conjunction with systemd-logind.service —
21 ensures the following:
22 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 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 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 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 On logout, this module ensures the following:
46 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 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 If the system was not booted up with systemd as init system, this
56 module does nothing and immediately returns PAM_SUCCESS.
57
59 The following options are understood:
60 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 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 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 default-capability-bounding-set=, default-capability-ambient-set=
88 Takes a comma-separated list of process capabilities (e.g.
89 CAP_WAKE_ALARM, CAP_BLOCK_SUSPEND, ...) to set for the invoked
90 session's processes, if the user record does not encode appropriate
91 sets of capabilities directly. See capabilities(7) for details on
92 the capabilities concept. If not specified, the default bounding
93 set is left as is (i.e. usually contains the full set of
94 capabilities). The default ambient set is set to CAP_WAKE_ALARM for
95 regular users if the PAM session is associated with a local seat or
96 if it is invoked for the "systemd-user" service. Otherwise defaults
97 to the empty set.
98 debug[=]
100 Takes an optional boolean argument. If yes or without the argument,
101 the module will log debugging information as it operates.
102
104 Only session is provided.
105
107 The following environment variables are initialized by the module and
108 available to the processes of the user's session:
109 $XDG_SESSION_ID
111 A short session identifier, suitable to be used in filenames. The
112 string itself should be considered opaque, although often it is
113 just the audit session ID as reported by /proc/self/sessionid. Each
114 ID will be assigned only once during machine uptime. It may hence
115 be used to uniquely label files or other resources of this session.
116 Combine this ID with the boot identifier, as returned by
117 sd_id128_get_boot(3), for a globally unique identifier.
118 $XDG_RUNTIME_DIR
120 Path to a user-private user-writable directory that is bound to the
121 user login time on the machine. It is automatically created the
122 first time a user logs in and removed on the user's final logout.
123 If a user logs in twice at the same time, both sessions will see
124 the same $XDG_RUNTIME_DIR and the same contents. If a user logs in
125 once, then logs out again, and logs in again, the directory
126 contents will have been lost in between, but applications should
127 not rely on this behavior and must be able to deal with stale
128 files. To store session-private data in this directory, the user
129 should include the value of $XDG_SESSION_ID in the filename. This
130 directory shall be used for runtime file system objects such as
131 AF_UNIX sockets, FIFOs, PID files and similar. It is guaranteed
132 that this directory is local and offers the greatest possible file
133 system feature set the operating system provides. For further
134 details, see the XDG Base Directory Specification[3].
135 $XDG_RUNTIME_DIR is not set if the current user is not the original
136 user of the session.
137 $TZ, $EMAIL, $LANG
139 If a JSON user record is known for the user logging in these
140 variables are initialized from the respective data in the record.
141 The following environment variables are read by the module and may be
143 used by the PAM service to pass metadata to the module. If these
144 variables are not set when the PAM module is invoked but can be
145 determined otherwise they are set by the module, so that these
146 variables are initialized for the session and applications if known at
147 all.
148 $XDG_SESSION_TYPE
150 The session type. This may be used instead of type= on the module
151 parameter line, and is usually preferred.
152 $XDG_SESSION_CLASS
154 The session class. This may be used instead of class= on the module
155 parameter line, and is usually preferred.
156 $XDG_SESSION_DESKTOP
158 The desktop identifier. This may be used instead of desktop= on the
159 module parameter line, and is usually preferred.
160 $XDG_SEAT
162 The seat name the session shall be registered for, if any.
163 $XDG_VTNR
165 The VT number the session shall be registered for, if any. (Only
166 applies to seats with a VT available, such as "seat0")
167 If not set, pam_systemd will initialize $XDG_SEAT and $XDG_VTNR based
169 on the $DISPLAY variable (if the latter is set).
170
172 PAM modules earlier in the stack, that is those that come before
173 pam_systemd.so, can set session scope limits using the PAM context
174 objects. The data for these objects is provided as NUL-terminated C
175 strings and maps directly to the respective unit resource control
176 directives. Note that these limits apply to individual sessions of the
177 user, they do not apply to all user processes as a combined whole. In
178 particular, the per-user user@.service unit instance, which runs the
179 systemd --user manager process and its children, and is tracked outside
180 of any session, being shared by all the user's sessions, is not covered
181 by these limits.
182 See systemd.resource-control(5) for more information about the
184 resources. Also, see pam_set_data(3) for additional information about
185 how to set the context objects.
186 systemd.memory_max=
188 Sets unit MemoryMax=.
189 systemd.tasks_max=
191 Sets unit TasksMax=.
192 systemd.cpu_weight=
194 Sets unit CPUWeight=.
195 systemd.io_weight=
197 Sets unit IOWeight=.
198 systemd.runtime_max_sec=
200 Sets unit RuntimeMaxSec=.
201 Example data as can be provided from an another PAM module:
203 pam_set_data(handle, "systemd.memory_max", (void *)"200M", cleanup);
205 pam_set_data(handle, "systemd.tasks_max", (void *)"50", cleanup);
206 pam_set_data(handle, "systemd.cpu_weight", (void *)"100", cleanup);
207 pam_set_data(handle, "systemd.io_weight", (void *)"340", cleanup);
208 pam_set_data(handle, "systemd.runtime_max_sec", (void *)"3600", cleanup);
209
213 Here's an example PAM configuration fragment that allows users sessions
214 to be managed by systemd-logind.service:
215 #%PAM-1.0
217 auth sufficient pam_unix.so
218 -auth sufficient pam_systemd_home.so
219 auth required pam_deny.so
220 account required pam_nologin.so
222 -account sufficient pam_systemd_home.so
223 account sufficient pam_unix.so
224 account required pam_permit.so
225 -password sufficient pam_systemd_home.so
227 password sufficient pam_unix.so sha512 shadow try_first_pass use_authtok
228 password required pam_deny.so
230 -session optional pam_keyinit.so revoke
232 -session optional pam_loginuid.so
233 -session optional pam_systemd_home.so
234 -session optional pam_systemd.so
235 session required pam_unix.so
236
238 systemd(1), systemd-logind.service(8), logind.conf(5), loginctl(1),
239 pam_systemd_home(8), pam.conf(5), pam.d(5), pam(8), pam_loginuid(8),
240 systemd.scope(5), systemd.slice(5), systemd.service(5)
241
243 1. JSON User Records
244 https://systemd.io/USER_RECORD
245 2. Desktop Entry Specification
247 https://standards.freedesktop.org/desktop-entry-spec/latest/
248 3. XDG Base Directory Specification
250 https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
251systemd 254 PAM_SYSTEMD(8)