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 [ID...]</command></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 [ID...]</command></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 [ID...]</command></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 [ID...]</command></term>
252 <term><command>unlock-session [ID...]</command></term>
254 <listitem><para>Activates/deactivates
255 the screen lock on one or more
256 sessions, if the session supports it.</para></listitem>
260 <term><command>lock-sessions</command></term>
261 <term><command>unlock-sessions</command></term>
263 <listitem><para>Activates/deactivates
264 the screen lock on all current
266 it.</para></listitem>
270 <term><command>terminate-session [ID...]</command></term>
272 <listitem><para>Terminates a
273 session. This kills all processes of
274 the session and deallocates all
275 resources attached to the
276 session.</para></listitem>
280 <term><command>kill-session [ID...]</command></term>
282 <listitem><para>Send a signal to one
283 or more processes of the session. Use
284 <option>--kill-who=</option> to select
285 which process to kill. Use
286 <option>--signal=</option> to select
287 the signal to send.</para></listitem>
291 <term><command>list-users</command></term>
293 <listitem><para>List currently logged
294 in users.</para></listitem>
298 <term><command>user-status [USER...]</command></term>
300 <listitem><para>Show terse runtime
301 status information about one or more
302 logged in users. This function is
303 intended to generate human-readable
304 output. If you are looking for
305 computer-parsable output, use
306 <command>show-user</command>
307 instead. Users may be specified by
308 their usernames or numeric user
309 IDs.</para></listitem>
313 <term><command>show-user [USER...]</command></term>
315 <listitem><para>Show properties of one
316 or more users or the manager
317 itself. If no argument is specified,
318 properties of the manager will be
319 shown. If a user is specified,
320 properties of the user are shown. By
321 default, empty properties are
322 suppressed. Use <option>--all</option>
323 to show those too. To select specific
324 properties to show, use
325 <option>--property=</option>. This
326 command is intended to be used
327 whenever computer-parsable output is
329 <command>user-status</command> if
330 you are looking for formatted
332 output.</para></listitem>
336 <term><command>enable-linger [USER...]</command></term>
337 <term><command>disable-linger [USER...]</command></term>
339 <listitem><para>Enable/disable user
340 lingering for one or more users. If
341 enabled for a specific user, a user
342 manager is spawned for him/her at
343 boot and kept around after
344 logouts. This allows users who are not
345 logged in to run long-running
346 services.</para></listitem>
350 <term><command>terminate-user [USER...]</command></term>
352 <listitem><para>Terminates all
353 sessions of a user. This kills all
354 processes of all sessions of the user
355 and deallocates all runtime resources
357 user.</para></listitem>
361 <term><command>kill-user [USER...]</command></term>
363 <listitem><para>Send a signal to all
364 processes of a user. Use
365 <option>--signal=</option> to select
366 the signal to send.</para></listitem>
370 <term><command>list-seats</command></term>
372 <listitem><para>List currently
373 available seats on the local
374 system.</para></listitem>
378 <term><command>seat-status [NAME...]</command></term>
380 <listitem><para>Show terse runtime
381 status information about one or more
382 seats. This function is
383 intended to generate human-readable
384 output. If you are looking for
385 computer-parsable output, use
386 <command>show-seat</command>
387 instead.</para></listitem>
391 <term><command>show-seat [NAME...]</command></term>
393 <listitem><para>Show properties of one
394 or more seats or the manager
395 itself. If no argument is specified,
396 properties of the manager will be
397 shown. If a seat is specified,
398 properties of the seat are shown. By
399 default, empty properties are
400 suppressed. Use <option>--all</option>
401 to show those too. To select specific
402 properties to show, use
403 <option>--property=</option>. This
404 command is intended to be used
405 whenever computer-parsable output is
407 <command>seat-status</command> if you
408 are looking for formatted
410 output.</para></listitem>
414 <term><command>attach [NAME] [DEVICE...]</command></term>
416 <listitem><para>Persistently attach
417 one or more devices to a seat. The
418 devices should be specified via device
419 paths in the <filename>/sys</filename>
420 file system. To create a new seat,
421 attach at least one graphics card to a
422 previously unused seat name. Seat
423 names may consist only of a-z, A-Z,
424 0-9, <literal>-</literal> and
425 <literal>_</literal> and must be
426 prefixed with <literal>seat</literal>.
427 To drop assignment of a device to a
428 specific seat, just reassign it to a
429 different seat, or use
430 <command>flush-devices</command>.
435 <term><command>flush-devices</command></term>
437 <listitem><para>Removes all device
438 assignments previously created with
439 <command>attach</command>. After this
440 call, only automatically generated
441 seats will remain, and all seat
442 hardware is assigned to
443 them.</para></listitem>
447 <term><command>terminate-seat [NAME...]</command></term>
449 <listitem><para>Terminates all
450 sessions on a seat. This kills all
451 processes of all sessions on a seat and
452 deallocates all runtime resources
453 attached to them.</para></listitem>
460 <title>Exit status</title>
462 <para>On success, 0 is returned, a non-zero failure
463 code otherwise.</para>
467 <title>Environment</title>
469 <variablelist class='environment-variables'>
471 <term><varname>$SYSTEMD_PAGER</varname></term>
472 <listitem><para>Pager to use when
473 <option>--no-pager</option> is not given;
474 overrides <varname>$PAGER</varname>. Setting
475 this to an empty string or the value
476 <literal>cat</literal> is equivalent to passing
477 <option>--no-pager</option>.</para></listitem>
483 <title>See Also</title>
485 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
486 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
487 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
488 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>