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 Record[1]
18 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 for the
106 current session.
107 $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 $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 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 $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 $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 $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 $XDG_SEAT
151 The seat name the session shall be registered for, if any.
152 $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 If not set, pam_systemd will initialize $XDG_SEAT and $XDG_VTNR based
158 on the $DISPLAY variable (if the latter is set).
159
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 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 systemd.memory_max
177 Sets unit MemoryMax=.
178 systemd.tasks_max
180 Sets unit TasksMax=.
181 systemd.cpu_weight
183 Sets unit CPUWeight=.
184 systemd.io_weight
186 Sets unit IOWeight=.
187 systemd.runtime_max_sec
189 Sets unit RuntimeMaxSec=.
190 Example data as can be provided from an another PAM module:
192 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
202 Here's an example PAM configuration fragment that allows users sessions
203 to be managed by systemd-logind.service:
204 #%PAM-1.0
206 auth sufficient pam_unix.so
207 auth required pam_deny.so
208 account required pam_nologin.so
210 account sufficient pam_unix.so
211 account required pam_permit.so
212 password sufficient pam_unix.so sha512 shadow try_first_pass try_authtok
214 password required pam_deny.so
215 -session optional pam_loginuid.so
217 -session optional pam_systemd.so
218 session required pam_unix.so
219
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
226 1. JSON User Record
227 https://systemd.io/USER_RECORD
228 2. Desktop Entry Specification
230 http://standards.freedesktop.org/desktop-entry-spec/latest/
231 3. XDG Base Directory Specification
233 http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
234systemd 245 PAM_SYSTEMD(8)