1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 Copyright 2010 Lennart Poettering
11 <refentry id=
"loginctl" conditional='ENABLE_LOGIND'
12 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
15 <title>loginctl
</title>
16 <productname>systemd
</productname>
20 <contrib>Developer
</contrib>
21 <firstname>Lennart
</firstname>
22 <surname>Poettering
</surname>
23 <email>lennart@poettering.net
</email>
29 <refentrytitle>loginctl
</refentrytitle>
30 <manvolnum>1</manvolnum>
34 <refname>loginctl
</refname>
35 <refpurpose>Control the systemd login manager
</refpurpose>
40 <command>loginctl
</command>
41 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
42 <arg choice=
"req">COMMAND
</arg>
43 <arg choice=
"opt" rep=
"repeat">NAME
</arg>
48 <title>Description
</title>
50 <para><command>loginctl
</command> may be used to introspect and
51 control the state of the
52 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
54 <citerefentry><refentrytitle>systemd-logind.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
58 <title>Options
</title>
60 <para>The following options are understood:
</para>
64 <term><option>--no-ask-password
</option></term>
66 <listitem><para>Do not query the user for authentication for
67 privileged operations.
</para></listitem>
71 <term><option>-p
</option></term>
72 <term><option>--property=
</option></term>
74 <listitem><para>When showing session/user/seat properties,
75 limit display to certain properties as specified as argument.
76 If not specified, all set properties are shown. The argument
77 should be a property name, such as
78 <literal>Sessions
</literal>. If specified more than once, all
79 properties with the specified names are
80 shown.
</para></listitem>
84 <term><option>--value
</option></term>
86 <listitem><para>When showing session/user/seat properties,
87 only print the value, and skip the property name and
88 <literal>=
</literal>.
</para></listitem>
92 <term><option>-a
</option></term>
93 <term><option>--all
</option></term>
95 <listitem><para>When showing session/user/seat properties,
96 show all properties regardless of whether they are set or
97 not.
</para></listitem>
101 <term><option>-l
</option></term>
102 <term><option>--full
</option></term>
104 <listitem><para>Do not ellipsize process tree entries.
</para>
109 <term><option>--kill-who=
</option></term>
111 <listitem><para>When used with
112 <command>kill-session
</command>, choose which processes to
113 kill. Must be one of
<option>leader
</option>, or
114 <option>all
</option> to select whether to kill only the leader
115 process of the session or all processes of the session. If
116 omitted, defaults to
<option>all
</option>.
</para></listitem>
120 <term><option>-s
</option></term>
121 <term><option>--signal=
</option></term>
123 <listitem><para>When used with
<command>kill-session
</command>
124 or
<command>kill-user
</command>, choose which signal to send
125 to selected processes. Must be one of the well known signal
126 specifiers, such as
<constant>SIGTERM
</constant>,
127 <constant>SIGINT
</constant> or
<constant>SIGSTOP
</constant>.
128 If omitted, defaults to
129 <constant>SIGTERM
</constant>.
</para></listitem>
133 <term><option>-n
</option></term>
134 <term><option>--lines=
</option></term>
136 <listitem><para>When used with
<command>user-status
</command>
137 and
<command>session-status
</command>, controls the number of
138 journal lines to show, counting from the most recent ones.
139 Takes a positive integer argument. Defaults to
10.
</para>
144 <term><option>-o
</option></term>
145 <term><option>--output=
</option></term>
147 <listitem><para>When used with
<command>user-status
</command>
148 and
<command>session-status
</command>, controls the formatting
149 of the journal entries that are shown. For the available
151 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
152 Defaults to
<literal>short
</literal>.
</para></listitem>
155 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
156 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
158 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
159 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
160 <xi:include href=
"standard-options.xml" xpointer=
"help" />
161 <xi:include href=
"standard-options.xml" xpointer=
"version" />
166 <title>Commands
</title>
168 <para>The following commands are understood:
</para>
170 <refsect2><title>Session Commands
</title><variablelist>
173 <term><command>list-sessions
</command></term>
175 <listitem><para>List current sessions.
</para></listitem>
179 <term><command>session-status
</command> <optional><replaceable>ID
</replaceable>…
</optional></term>
181 <listitem><para>Show terse runtime status information about
182 one or more sessions, followed by the most recent log data
183 from the journal. Takes one or more session identifiers as
184 parameters. If no session identifiers are passed, the status of
185 the caller's session is shown. This function is intended to
186 generate human-readable output. If you are looking for
187 computer-parsable output, use
<command>show-session
</command>
188 instead.
</para></listitem>
192 <term><command>show-session
</command> <optional><replaceable>ID
</replaceable>…
</optional></term>
194 <listitem><para>Show properties of one or more sessions or the
195 manager itself. If no argument is specified, properties of the
196 manager will be shown. If a session ID is specified,
197 properties of the session are shown. By default, empty
198 properties are suppressed. Use
<option>--all
</option> to show
199 those too. To select specific properties to show, use
200 <option>--property=
</option>. This command is intended to be
201 used whenever computer-parsable output is required. Use
202 <command>session-status
</command> if you are looking for
203 formatted human-readable output.
</para></listitem>
207 <term><command>activate
</command> <optional><replaceable>ID
</replaceable></optional></term>
209 <listitem><para>Activate a session. This brings a session into
210 the foreground if another session is currently in the
211 foreground on the respective seat. Takes a session identifier
212 as argument. If no argument is specified, the session of the
213 caller is put into foreground.
</para></listitem>
217 <term><command>lock-session
</command> <optional><replaceable>ID
</replaceable>…
</optional></term>
218 <term><command>unlock-session
</command> <optional><replaceable>ID
</replaceable>…
</optional></term>
220 <listitem><para>Activates/deactivates the screen lock on one
221 or more sessions, if the session supports it. Takes one or
222 more session identifiers as arguments. If no argument is
223 specified, the session of the caller is locked/unlocked.
228 <term><command>lock-sessions
</command></term>
229 <term><command>unlock-sessions
</command></term>
231 <listitem><para>Activates/deactivates the screen lock on all
232 current sessions supporting it.
</para></listitem>
236 <term><command>terminate-session
</command> <replaceable>ID
</replaceable>…
</term>
238 <listitem><para>Terminates a session. This kills all processes
239 of the session and deallocates all resources attached to the
240 session.
</para></listitem>
244 <term><command>kill-session
</command> <replaceable>ID
</replaceable>…
</term>
246 <listitem><para>Send a signal to one or more processes of the
247 session. Use
<option>--kill-who=
</option> to select which
248 process to kill. Use
<option>--signal=
</option> to select the
249 signal to send.
</para></listitem>
251 </variablelist></refsect2>
253 <refsect2><title>User Commands
</title><variablelist>
255 <term><command>list-users
</command></term>
257 <listitem><para>List currently logged in users.
262 <term><command>user-status
</command> <optional><replaceable>USER
</replaceable>…
</optional></term>
264 <listitem><para>Show terse runtime status information about
265 one or more logged in users, followed by the most recent log
266 data from the journal. Takes one or more user names or numeric
267 user IDs as parameters. If no parameters are passed, the status
268 is shown for the user of the session of the caller. This
269 function is intended to generate human-readable output. If you
270 are looking for computer-parsable output, use
271 <command>show-user
</command> instead.
</para></listitem>
275 <term><command>show-user
</command> <optional><replaceable>USER
</replaceable>…
</optional></term>
277 <listitem><para>Show properties of one or more users or the
278 manager itself. If no argument is specified, properties of the
279 manager will be shown. If a user is specified, properties of
280 the user are shown. By default, empty properties are
281 suppressed. Use
<option>--all
</option> to show those too. To
282 select specific properties to show, use
283 <option>--property=
</option>. This command is intended to be
284 used whenever computer-parsable output is required. Use
285 <command>user-status
</command> if you are looking for
286 formatted human-readable output.
</para></listitem>
290 <term><command>enable-linger
</command> <optional><replaceable>USER
</replaceable>…
</optional></term>
291 <term><command>disable-linger
</command> <optional><replaceable>USER
</replaceable>…
</optional></term>
293 <listitem><para>Enable/disable user lingering for one or more
294 users. If enabled for a specific user, a user manager is
295 spawned for the user at boot and kept around after logouts.
296 This allows users who are not logged in to run long-running
297 services. Takes one or more user names or numeric UIDs as
298 argument. If no argument is specified, enables/disables
299 lingering for the user of the session of the caller.
</para>
301 <para>See also
<varname>KillUserProcesses=
</varname> setting in
302 <citerefentry><refentrytitle>logind.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
307 <term><command>terminate-user
</command> <replaceable>USER
</replaceable>…
</term>
309 <listitem><para>Terminates all sessions of a user. This kills
310 all processes of all sessions of the user and deallocates all
311 runtime resources attached to the user.
</para></listitem>
315 <term><command>kill-user
</command> <replaceable>USER
</replaceable>…
</term>
317 <listitem><para>Send a signal to all processes of a user. Use
318 <option>--signal=
</option> to select the signal to send.
321 </variablelist></refsect2>
323 <refsect2><title>Seat Commands
</title><variablelist>
325 <term><command>list-seats
</command></term>
327 <listitem><para>List currently available seats on the local
328 system.
</para></listitem>
332 <term><command>seat-status
</command> <optional><replaceable>NAME
</replaceable>…
</optional></term>
334 <listitem><para>Show terse runtime status information about
335 one or more seats. Takes one or more seat names as parameters.
336 If no seat names are passed the status of the caller's
337 session's seat is shown. This function is intended to generate
338 human-readable output. If you are looking for
339 computer-parsable output, use
<command>show-seat
</command>
340 instead.
</para></listitem>
344 <term><command>show-seat
</command> <optional><replaceable>NAME
</replaceable>…
</optional></term>
346 <listitem><para>Show properties of one or more seats or the
347 manager itself. If no argument is specified, properties of the
348 manager will be shown. If a seat is specified, properties of
349 the seat are shown. By default, empty properties are
350 suppressed. Use
<option>--all
</option> to show those too. To
351 select specific properties to show, use
352 <option>--property=
</option>. This command is intended to be
353 used whenever computer-parsable output is required. Use
354 <command>seat-status
</command> if you are looking for
355 formatted human-readable output.
</para></listitem>
359 <term><command>attach
</command> <replaceable>NAME
</replaceable> <replaceable>DEVICE
</replaceable>…
</term>
361 <listitem><para>Persistently attach one or more devices to a
362 seat. The devices should be specified via device paths in the
363 <filename>/sys
</filename> file system. To create a new seat,
364 attach at least one graphics card to a previously unused seat
365 name. Seat names may consist only of a–z, A–Z,
0–
9,
366 <literal>-
</literal> and
<literal>_
</literal> and must be
367 prefixed with
<literal>seat
</literal>. To drop assignment of a
368 device to a specific seat, just reassign it to a different
369 seat, or use
<command>flush-devices
</command>.
374 <term><command>flush-devices
</command></term>
376 <listitem><para>Removes all device assignments previously
377 created with
<command>attach
</command>. After this call, only
378 automatically generated seats will remain, and all seat
379 hardware is assigned to them.
</para></listitem>
383 <term><command>terminate-seat
</command> <replaceable>NAME
</replaceable>…
</term>
385 <listitem><para>Terminates all sessions on a seat. This kills
386 all processes of all sessions on the seat and deallocates all
387 runtime resources attached to them.
</para></listitem>
389 </variablelist></refsect2>
394 <title>Exit status
</title>
396 <para>On success,
0 is returned, a non-zero failure code
401 <title>Examples
</title>
404 <title>Querying user status
</title>
406 <programlisting>$ loginctl user-status
408 Since: Sat
2016-
04-
09 14:
23:
31 EDT;
54min ago
411 Unit: user-
1005.slice
417 ├─
3473 login -- fatima
420 Apr
09 14:
40:
30 laptop login[
2325]: pam_unix(login:session):
421 session opened for user fatima by LOGIN(uid=
0)
422 Apr
09 14:
40:
30 laptop login[
2325]: LOGIN ON tty3 BY fatima
425 <para>There are two sessions,
3 and
5. Session
3 is a graphical session,
426 marked with a star. The tree of processing including the two corresponding
427 scope units and the user manager unit are shown.
</para>
431 <xi:include href=
"less-variables.xml" />
434 <title>See Also
</title>
436 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
437 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
438 <citerefentry><refentrytitle>systemd-logind.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
439 <citerefentry><refentrytitle>logind.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>