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 debug[=]
88 Takes an optional boolean argument. If yes or without the argument,
89 the module will log debugging information as it operates.
90
92 Only session is provided.
93
95 The following environment variables are initialized by the module and
96 available to the processes of the user's session:
97 $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 $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 $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 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 $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 $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 $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 $XDG_SEAT
150 The seat name the session shall be registered for, if any.
151 $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 If not set, pam_systemd will initialize $XDG_SEAT and $XDG_VTNR based
157 on the $DISPLAY variable (if the latter is set).
158
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 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 systemd.memory_max=
176 Sets unit MemoryMax=.
177 systemd.tasks_max=
179 Sets unit TasksMax=.
180 systemd.cpu_weight=
182 Sets unit CPUWeight=.
183 systemd.io_weight=
185 Sets unit IOWeight=.
186 systemd.runtime_max_sec=
188 Sets unit RuntimeMaxSec=.
189 Example data as can be provided from an another PAM module:
191 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
201 Here's an example PAM configuration fragment that allows users sessions
202 to be managed by systemd-logind.service:
203 #%PAM-1.0
205 auth sufficient pam_unix.so
206 -auth sufficient pam_systemd_home.so
207 auth required pam_deny.so
208 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 -password sufficient pam_systemd_home.so
215 password sufficient pam_unix.so sha512 shadow try_first_pass use_authtok
216 password required pam_deny.so
218 -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
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
231 1. JSON User Records
232 https://systemd.io/USER_RECORD
233 2. Desktop Entry Specification
235 https://standards.freedesktop.org/desktop-entry-spec/latest/
236 3. XDG Base Directory Specification
238 https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
239systemd 253 PAM_SYSTEMD(8)