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 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="loginctl" conditional='ENABLE_LOGIND'>
27 <title>loginctl</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>loginctl</refentrytitle>
42 <manvolnum>1</manvolnum>
46 <refname>loginctl</refname>
47 <refpurpose>Control the systemd login manager</refpurpose>
52 <command>loginctl</command>
53 <arg choice="opt" rep="repeat">OPTIONS</arg>
54 <arg choice="req">COMMAND</arg>
55 <arg choice="opt" rep="repeat">NAME</arg>
60 <title>Description</title>
62 <para><command>loginctl</command> may be used to
63 introspect and control the state of the
64 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
65 login manager <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
69 <title>Options</title>
71 <para>The following options are understood:</para>
75 <term><option>-h</option></term>
76 <term><option>--help</option></term>
78 <listitem><para>Prints a short help
79 text and exits.</para></listitem>
83 <term><option>--version</option></term>
85 <listitem><para>Prints a short version
86 string and exits.</para></listitem>
90 <term><option>--no-pager</option></term>
92 <listitem><para>Do not pipe output into a
93 pager.</para></listitem>
97 <term><option>--no-ask-password</option></term>
99 <listitem><para>Do not query the user
100 for authentication for privileged
101 operations.</para></listitem>
105 <term><option>-H</option></term>
106 <term><option>--host</option></term>
108 <listitem><para>Execute the operation
109 remotely. Specify a hostname, or
110 username and hostname separated by <literal>@</literal>,
111 to connect to. This will use SSH to
112 talk to the remote login manager
113 instance.</para></listitem>
117 <term><option>-M</option></term>
118 <term><option>--machine=</option></term>
120 <listitem><para>Execute the operation on a
121 local container. Specify a container
122 name to connect to.</para></listitem>
126 <term><option>-p</option></term>
127 <term><option>--property=</option></term>
129 <listitem><para>When showing
130 session/user/seat properties, limit
131 display to certain properties as
132 specified as argument. If not
133 specified, all set properties are
134 shown. The argument should be a
135 property name, such as
136 <literal>Sessions</literal>. If
137 specified more than once, all
138 properties with the specified names
139 are shown.</para></listitem>
143 <term><option>-a</option></term>
144 <term><option>--all</option></term>
146 <listitem><para>When showing
147 session/user/seat properties, show all
148 properties regardless whether they are
149 set or not.</para></listitem>
153 <term><option>-l</option></term>
154 <term><option>--full</option></term>
156 <listitem><para>Do not ellipsize
157 process tree entries.</para>
162 <term><option>--kill-who=</option></term>
164 <listitem><para>When used with
165 <command>kill-session</command>,
166 choose which processes to kill. Must
167 be one of <option>leader</option>, or
168 <option>all</option> to select whether
169 to kill only the leader process of the
170 session or all processes of the
171 session. If omitted, defaults to
172 <option>all</option>.</para></listitem>
176 <term><option>-s</option></term>
177 <term><option>--signal=</option></term>
179 <listitem><para>When used with
180 <command>kill-session</command> or
181 <command>kill-user</command>, choose
182 which signal to send to selected
183 processes. Must be one of the well
184 known signal specifiers, such as
185 <constant>SIGTERM</constant>,
186 <constant>SIGINT</constant> or
187 <constant>SIGSTOP</constant>. If
189 <constant>SIGTERM</constant>.</para></listitem>
194 <para>The following commands are understood:</para>
198 <term><command>list-sessions</command></term>
200 <listitem><para>List current sessions.</para></listitem>
204 <term><command>session-status</command> <replaceable>ID</replaceable>...</term>
206 <listitem><para>Show terse runtime
207 status information about one or more
208 sessions. This function is intended to
209 generate human-readable output. If you
210 are looking for computer-parsable
212 <command>show-session</command>
213 instead.</para></listitem>
217 <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
219 <listitem><para>Show properties of one
220 or more sessions or the manager
221 itself. If no argument is specified,
222 properties of the manager will be
223 shown. If a session ID is specified,
224 properties of the session are shown. By
225 default, empty properties are
226 suppressed. Use <option>--all</option>
227 to show those too. To select specific
228 properties to show, use
229 <option>--property=</option>. This
230 command is intended to be used
231 whenever computer-parsable output is
233 <command>session-status</command> if
234 you are looking for formatted
236 output.</para></listitem>
240 <term><command>activate</command> <replaceable>ID</replaceable>...</term>
242 <listitem><para>Activate one or more
243 sessions. This brings one or more
244 sessions into the foreground, if
245 another session is currently in the
246 foreground on the respective
247 seat.</para></listitem>
251 <term><command>lock-session</command> <replaceable>ID</replaceable>...</term>
252 <term><command>unlock-session</command> <replaceable>ID</replaceable>...</term>
254 <listitem><para>Activates/deactivates
255 the screen lock on one or more
256 sessions, if the session supports it.
261 <term><command>lock-sessions</command></term>
262 <term><command>unlock-sessions</command></term>
264 <listitem><para>Activates/deactivates
265 the screen lock on all current
266 sessions supporting it.
271 <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term>
273 <listitem><para>Terminates a session.
274 This kills all processes of the
275 session and deallocates all resources
276 attached to the session.
281 <term><command>kill-session</command> <replaceable>ID</replaceable>...</term>
283 <listitem><para>Send a signal to one
284 or more processes of the session. Use
285 <option>--kill-who=</option> to select
286 which process to kill. Use
287 <option>--signal=</option> to select
288 the signal to send.</para></listitem>
292 <term><command>list-users</command></term>
294 <listitem><para>List currently logged
295 in users.</para></listitem>
299 <term><command>user-status</command> <replaceable>USER</replaceable>...</term>
301 <listitem><para>Show terse runtime
302 status information about one or more
303 logged in users. This function is
304 intended to generate human-readable
305 output. If you are looking for
306 computer-parsable output, use
307 <command>show-user</command> instead.
308 Users may be specified by their
309 usernames or numeric user IDs.
314 <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term>
316 <listitem><para>Show properties of one
317 or more users or the manager
318 itself. If no argument is specified,
319 properties of the manager will be
320 shown. If a user is specified,
321 properties of the user are shown. By
322 default, empty properties are
323 suppressed. Use <option>--all</option>
324 to show those too. To select specific
325 properties to show, use
326 <option>--property=</option>. This
327 command is intended to be used
328 whenever computer-parsable output is
330 <command>user-status</command> if
331 you are looking for formatted
333 output.</para></listitem>
337 <term><command>enable-linger</command> <replaceable>USER</replaceable>...</term>
338 <term><command>disable-linger</command> <replaceable>USER</replaceable>...</term>
340 <listitem><para>Enable/disable user
341 lingering for one or more users. If
342 enabled for a specific user, a user
343 manager is spawned for the user at
344 boot and kept around after
345 logouts. This allows users who are not
346 logged in to run long-running
347 services.</para></listitem>
351 <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term>
353 <listitem><para>Terminates all
354 sessions of a user. This kills all
355 processes of all sessions of the user
356 and deallocates all runtime resources
357 attached to the user.
362 <term><command>kill-user</command> <replaceable>USER</replaceable>...</term>
364 <listitem><para>Send a signal to all
365 processes of a user. Use
366 <option>--signal=</option> to select
367 the signal to send.</para></listitem>
371 <term><command>list-seats</command></term>
373 <listitem><para>List currently
374 available seats on the local
375 system.</para></listitem>
379 <term><command>seat-status</command> <replaceable>NAME</replaceable>...</term>
381 <listitem><para>Show terse runtime
382 status information about one or more
383 seats. This function is
384 intended to generate human-readable
385 output. If you are looking for
386 computer-parsable output, use
387 <command>show-seat</command>
388 instead.</para></listitem>
392 <term><command>show-seat</command> <replaceable>NAME</replaceable>...</term>
394 <listitem><para>Show properties of one
395 or more seats or the manager
396 itself. If no argument is specified,
397 properties of the manager will be
398 shown. If a seat is specified,
399 properties of the seat are shown. By
400 default, empty properties are
401 suppressed. Use <option>--all</option>
402 to show those too. To select specific
403 properties to show, use
404 <option>--property=</option>. This
405 command is intended to be used
406 whenever computer-parsable output is
408 <command>seat-status</command> if you
409 are looking for formatted
411 output.</para></listitem>
415 <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term>
417 <listitem><para>Persistently attach
418 one or more devices to a seat. The
419 devices should be specified via device
420 paths in the <filename>/sys</filename>
421 file system. To create a new seat,
422 attach at least one graphics card to a
423 previously unused seat name. Seat
424 names may consist only of a-z, A-Z,
425 0-9, <literal>-</literal> and
426 <literal>_</literal> and must be
427 prefixed with <literal>seat</literal>.
428 To drop assignment of a device to a
429 specific seat, just reassign it to a
430 different seat, or use
431 <command>flush-devices</command>.
436 <term><command>flush-devices</command></term>
438 <listitem><para>Removes all device
439 assignments previously created with
440 <command>attach</command>. After this
441 call, only automatically generated
442 seats will remain, and all seat
443 hardware is assigned to
444 them.</para></listitem>
448 <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term>
450 <listitem><para>Terminates all
451 sessions on a seat. This kills all
452 processes of all sessions on the seat
453 and deallocates all runtime resources
454 attached to them.</para></listitem>
461 <title>Exit status</title>
463 <para>On success, 0 is returned, a non-zero failure
464 code otherwise.</para>
468 <title>Environment</title>
470 <variablelist class='environment-variables'>
472 <term><varname>$SYSTEMD_PAGER</varname></term>
473 <listitem><para>Pager to use when
474 <option>--no-pager</option> is not given;
475 overrides <varname>$PAGER</varname>. Setting
476 this to an empty string or the value
477 <literal>cat</literal> is equivalent to passing
478 <option>--no-pager</option>.</para></listitem>
484 <title>See Also</title>
486 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
487 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
488 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
489 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>