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-legend</option></term>
100 <para>Do not print the legend,
101 i.e. the column headers and
107 <term><option>--no-ask-password</option></term>
109 <listitem><para>Do not query the user
110 for authentication for privileged
111 operations.</para></listitem>
115 <term><option>-H</option></term>
116 <term><option>--host</option></term>
118 <listitem><para>Execute the operation
119 remotely. Specify a hostname, or
120 username and hostname separated by <literal>@</literal>,
121 to connect to. This will use SSH to
122 talk to the remote login manager
123 instance.</para></listitem>
127 <term><option>-M</option></term>
128 <term><option>--machine=</option></term>
130 <listitem><para>Execute the operation on a
131 local container. Specify a container
132 name to connect to.</para></listitem>
136 <term><option>-p</option></term>
137 <term><option>--property=</option></term>
139 <listitem><para>When showing
140 session/user/seat properties, limit
141 display to certain properties as
142 specified as argument. If not
143 specified, all set properties are
144 shown. The argument should be a
145 property name, such as
146 <literal>Sessions</literal>. If
147 specified more than once, all
148 properties with the specified names
149 are shown.</para></listitem>
153 <term><option>-a</option></term>
154 <term><option>--all</option></term>
156 <listitem><para>When showing
157 session/user/seat properties, show all
158 properties regardless whether they are
159 set or not.</para></listitem>
163 <term><option>-l</option></term>
164 <term><option>--full</option></term>
166 <listitem><para>Do not ellipsize
167 process tree entries.</para>
172 <term><option>--kill-who=</option></term>
174 <listitem><para>When used with
175 <command>kill-session</command>,
176 choose which processes to kill. Must
177 be one of <option>leader</option>, or
178 <option>all</option> to select whether
179 to kill only the leader process of the
180 session or all processes of the
181 session. If omitted, defaults to
182 <option>all</option>.</para></listitem>
186 <term><option>-s</option></term>
187 <term><option>--signal=</option></term>
189 <listitem><para>When used with
190 <command>kill-session</command> or
191 <command>kill-user</command>, choose
192 which signal to send to selected
193 processes. Must be one of the well
194 known signal specifiers, such as
195 <constant>SIGTERM</constant>,
196 <constant>SIGINT</constant> or
197 <constant>SIGSTOP</constant>. If
199 <constant>SIGTERM</constant>.</para></listitem>
204 <para>The following commands are understood:</para>
208 <term><command>list-sessions</command></term>
210 <listitem><para>List current sessions.</para></listitem>
214 <term><command>session-status</command> <replaceable>ID</replaceable>...</term>
216 <listitem><para>Show terse runtime
217 status information about one or more
218 sessions. This function is intended to
219 generate human-readable output. If you
220 are looking for computer-parsable
222 <command>show-session</command>
223 instead.</para></listitem>
227 <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
229 <listitem><para>Show properties of one
230 or more sessions or the manager
231 itself. If no argument is specified,
232 properties of the manager will be
233 shown. If a session ID is specified,
234 properties of the session are shown. By
235 default, empty properties are
236 suppressed. Use <option>--all</option>
237 to show those too. To select specific
238 properties to show, use
239 <option>--property=</option>. This
240 command is intended to be used
241 whenever computer-parsable output is
243 <command>session-status</command> if
244 you are looking for formatted
246 output.</para></listitem>
250 <term><command>activate</command> <replaceable>ID</replaceable>...</term>
252 <listitem><para>Activate one or more
253 sessions. This brings one or more
254 sessions into the foreground, if
255 another session is currently in the
256 foreground on the respective
257 seat.</para></listitem>
261 <term><command>lock-session</command> <replaceable>ID</replaceable>...</term>
262 <term><command>unlock-session</command> <replaceable>ID</replaceable>...</term>
264 <listitem><para>Activates/deactivates
265 the screen lock on one or more
266 sessions, if the session supports it.
271 <term><command>lock-sessions</command></term>
272 <term><command>unlock-sessions</command></term>
274 <listitem><para>Activates/deactivates
275 the screen lock on all current
276 sessions supporting it.
281 <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term>
283 <listitem><para>Terminates a session.
284 This kills all processes of the
285 session and deallocates all resources
286 attached to the session.
291 <term><command>kill-session</command> <replaceable>ID</replaceable>...</term>
293 <listitem><para>Send a signal to one
294 or more processes of the session. Use
295 <option>--kill-who=</option> to select
296 which process to kill. Use
297 <option>--signal=</option> to select
298 the signal to send.</para></listitem>
302 <term><command>list-users</command></term>
304 <listitem><para>List currently logged
305 in users.</para></listitem>
309 <term><command>user-status</command> <replaceable>USER</replaceable>...</term>
311 <listitem><para>Show terse runtime
312 status information about one or more
313 logged in users. This function is
314 intended to generate human-readable
315 output. If you are looking for
316 computer-parsable output, use
317 <command>show-user</command> instead.
318 Users may be specified by their
319 usernames or numeric user IDs.
324 <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term>
326 <listitem><para>Show properties of one
327 or more users or the manager
328 itself. If no argument is specified,
329 properties of the manager will be
330 shown. If a user is specified,
331 properties of the user are shown. By
332 default, empty properties are
333 suppressed. Use <option>--all</option>
334 to show those too. To select specific
335 properties to show, use
336 <option>--property=</option>. This
337 command is intended to be used
338 whenever computer-parsable output is
340 <command>user-status</command> if
341 you are looking for formatted
343 output.</para></listitem>
347 <term><command>enable-linger</command> <replaceable>USER</replaceable>...</term>
348 <term><command>disable-linger</command> <replaceable>USER</replaceable>...</term>
350 <listitem><para>Enable/disable user
351 lingering for one or more users. If
352 enabled for a specific user, a user
353 manager is spawned for the user at
354 boot and kept around after
355 logouts. This allows users who are not
356 logged in to run long-running
357 services.</para></listitem>
361 <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term>
363 <listitem><para>Terminates all
364 sessions of a user. This kills all
365 processes of all sessions of the user
366 and deallocates all runtime resources
367 attached to the user.
372 <term><command>kill-user</command> <replaceable>USER</replaceable>...</term>
374 <listitem><para>Send a signal to all
375 processes of a user. Use
376 <option>--signal=</option> to select
377 the signal to send.</para></listitem>
381 <term><command>list-seats</command></term>
383 <listitem><para>List currently
384 available seats on the local
385 system.</para></listitem>
389 <term><command>seat-status</command> <replaceable>NAME</replaceable>...</term>
391 <listitem><para>Show terse runtime
392 status information about one or more
393 seats. This function is
394 intended to generate human-readable
395 output. If you are looking for
396 computer-parsable output, use
397 <command>show-seat</command>
398 instead.</para></listitem>
402 <term><command>show-seat</command> <replaceable>NAME</replaceable>...</term>
404 <listitem><para>Show properties of one
405 or more seats or the manager
406 itself. If no argument is specified,
407 properties of the manager will be
408 shown. If a seat is specified,
409 properties of the seat are shown. By
410 default, empty properties are
411 suppressed. Use <option>--all</option>
412 to show those too. To select specific
413 properties to show, use
414 <option>--property=</option>. This
415 command is intended to be used
416 whenever computer-parsable output is
418 <command>seat-status</command> if you
419 are looking for formatted
421 output.</para></listitem>
425 <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term>
427 <listitem><para>Persistently attach
428 one or more devices to a seat. The
429 devices should be specified via device
430 paths in the <filename>/sys</filename>
431 file system. To create a new seat,
432 attach at least one graphics card to a
433 previously unused seat name. Seat
434 names may consist only of a-z, A-Z,
435 0-9, <literal>-</literal> and
436 <literal>_</literal> and must be
437 prefixed with <literal>seat</literal>.
438 To drop assignment of a device to a
439 specific seat, just reassign it to a
440 different seat, or use
441 <command>flush-devices</command>.
446 <term><command>flush-devices</command></term>
448 <listitem><para>Removes all device
449 assignments previously created with
450 <command>attach</command>. After this
451 call, only automatically generated
452 seats will remain, and all seat
453 hardware is assigned to
454 them.</para></listitem>
458 <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term>
460 <listitem><para>Terminates all
461 sessions on a seat. This kills all
462 processes of all sessions on the seat
463 and deallocates all runtime resources
464 attached to them.</para></listitem>
471 <title>Exit status</title>
473 <para>On success, 0 is returned, a non-zero failure
474 code otherwise.</para>
478 <title>Environment</title>
480 <variablelist class='environment-variables'>
482 <term><varname>$SYSTEMD_PAGER</varname></term>
483 <listitem><para>Pager to use when
484 <option>--no-pager</option> is not given;
485 overrides <varname>$PAGER</varname>. Setting
486 this to an empty string or the value
487 <literal>cat</literal> is equivalent to passing
488 <option>--no-pager</option>.</para></listitem>
494 <title>See Also</title>
496 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
497 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
498 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
499 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>