man/loginctl.xml

   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">
   4
   5 <!--
   6   This file is part of elogind.
   7   SPDX-License-Identifier: LGPL-2.1+
   8
   9
  10   Copyright 2010 Lennart Poettering
  11
  12   elogind is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   elogind is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with elogind; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <!-- 0 /// elogind does not need to activate loginctl in configure
  27 <refentry id="loginctl" conditional='ENABLE_LOGIND'
  28     xmlns:xi="http://www.w3.org/2001/XInclude">
  29 else -->
  30 <refentry id="loginctl" xmlns:xi="http://www.w3.org/2001/XInclude">
  31 <!-- // 0 -->
  32
  33   <refentryinfo>
  34     <title>loginctl</title>
  35     <productname>elogind</productname>
  36
  37     <authorgroup>
  38       <author>
  39         <contrib>Developer</contrib>
  40         <firstname>Lennart</firstname>
  41         <surname>Poettering</surname>
  42         <email>lennart@poettering.net</email>
  43       </author>
  44     </authorgroup>
  45   </refentryinfo>
  46
  47   <refmeta>
  48     <refentrytitle>loginctl</refentrytitle>
  49     <manvolnum>1</manvolnum>
  50   </refmeta>
  51
  52   <refnamediv>
  53     <refname>loginctl</refname>
  54     <refpurpose>Control the elogind login manager</refpurpose>
  55   </refnamediv>
  56
  57   <refsynopsisdiv>
  58     <cmdsynopsis>
  59       <command>loginctl</command>
  60       <arg choice="opt" rep="repeat">OPTIONS</arg>
  61       <arg choice="req">COMMAND</arg>
  62       <arg choice="opt" rep="repeat">NAME</arg>
  63     </cmdsynopsis>
  64   </refsynopsisdiv>
  65
  66   <refsect1>
  67     <title>Description</title>
  68
  69     <para><command>loginctl</command> may be used to introspect and
  70     control the state of the
  71     <!-- 0 /// elogind has no services and is in section 8
  72     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  73     login manager
  74     <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  75     --><!-- else -->
  76     <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  77     login manager</para>
  78     <!-- // 0 -->
  79   </refsect1>
  80
  81   <refsect1>
  82     <title>Options</title>
  83
  84     <para>The following options are understood:</para>
  85
  86     <variablelist>
  87       <varlistentry>
  88         <term><option>--no-ask-password</option></term>
  89
  90         <listitem><para>Do not query the user for authentication for
  91         privileged operations.</para></listitem>
  92       </varlistentry>
  93
  94       <varlistentry>
  95         <term><option>-p</option></term>
  96         <term><option>--property=</option></term>
  97
  98         <listitem><para>When showing session/user/seat properties,
  99         limit display to certain properties as specified as argument.
 100         If not specified, all set properties are shown. The argument
 101         should be a property name, such as
 102         <literal>Sessions</literal>. If specified more than once, all
 103         properties with the specified names are
 104         shown.</para></listitem>
 105       </varlistentry>
 106
 107       <varlistentry>
 108         <term><option>--value</option></term>
 109
 110         <listitem>
 111           <para>When printing properties with <command>show</command>,
 112           only print the value, and skip the property name and
 113           <literal>=</literal>.</para>
 114         </listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term><option>-a</option></term>
 119         <term><option>--all</option></term>
 120
 121         <listitem><para>When showing session/user/seat properties,
 122         show all properties regardless of whether they are set or
 123         not.</para></listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term><option>-l</option></term>
 128         <term><option>--full</option></term>
 129
 130         <listitem><para>Do not ellipsize process tree entries.</para>
 131         </listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135         <term><option>--kill-who=</option></term>
 136
 137         <listitem><para>When used with
 138         <command>kill-session</command>, choose which processes to
 139         kill. Must be one of <option>leader</option>, or
 140         <option>all</option> to select whether to kill only the leader
 141         process of the session or all processes of the session. If
 142         omitted, defaults to <option>all</option>.</para></listitem>
 143       </varlistentry>
 144
 145       <varlistentry>
 146         <term><option>-s</option></term>
 147         <term><option>--signal=</option></term>
 148
 149         <listitem><para>When used with <command>kill-session</command>
 150         or <command>kill-user</command>, choose which signal to send
 151         to selected processes. Must be one of the well known signal
 152         specifiers, such as <constant>SIGTERM</constant>,
 153         <constant>SIGINT</constant> or <constant>SIGSTOP</constant>.
 154         If omitted, defaults to
 155         <constant>SIGTERM</constant>.</para></listitem>
 156       </varlistentry>
 157
 158       <!-- 0 /// elogind does not support systemd-journal
 159       <varlistentry>
 160         <term><option>-n</option></term>
 161         <term><option>&#x2D;&#x2D;lines=</option></term>
 162
 163         <listitem><para>When used with <command>user-status</command>
 164         and <command>session-status</command>, controls the number of
 165         journal lines to show, counting from the most recent ones.
 166         Takes a positive integer argument. Defaults to 10.</para>
 167         </listitem>
 168       </varlistentry>
 169
 170       <varlistentry>
 171         <term><option>-o</option></term>
 172         <term><option>&#x2D;&#x2D;output=</option></term>
 173
 174         <listitem><para>When used with <command>user-status</command>
 175         and <command>session-status</command>, controls the formatting
 176         of the journal entries that are shown. For the available
 177         choices, see
 178         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 179         Defaults to <literal>short</literal>.</para></listitem>
 180       </varlistentry>
 181       // 0 -->
 182
 183       <xi:include href="user-system-options.xml" xpointer="host" />
 184       <xi:include href="user-system-options.xml" xpointer="machine" />
 185
 186       <xi:include href="standard-options.xml" xpointer="no-pager" />
 187       <xi:include href="standard-options.xml" xpointer="no-legend" />
 188       <xi:include href="standard-options.xml" xpointer="help" />
 189       <xi:include href="standard-options.xml" xpointer="version" />
 190     </variablelist>
 191   </refsect1>
 192
 193   <refsect1>
 194     <title>Commands</title>
 195
 196     <para>The following commands are understood:</para>
 197
 198     <refsect2><title>Session Commands</title><variablelist>
 199
 200       <varlistentry>
 201         <term><command>list-sessions</command></term>
 202
 203         <listitem><para>List current sessions.</para></listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term><command>session-status</command> <optional><replaceable>ID</replaceable>…</optional></term>
 208
 209         <listitem><para>Show terse runtime status information about
 210         one or more sessions, followed by the most recent log data
 211         from the journal. Takes one or more session identifiers as
 212         parameters. If no session identifiers are passed, the status of
 213         the caller's session is shown. This function is intended to
 214         generate human-readable output. If you are looking for
 215         computer-parsable output, use <command>show-session</command>
 216         instead.</para></listitem>
 217       </varlistentry>
 218
 219       <varlistentry>
 220         <term><command>show-session</command> <optional><replaceable>ID</replaceable>…</optional></term>
 221
 222         <listitem><para>Show properties of one or more sessions or the
 223         manager itself. If no argument is specified, properties of the
 224         manager will be shown. If a session ID is specified,
 225         properties of the session are shown. By default, empty
 226         properties are suppressed. Use <option>--all</option> to show
 227         those too. To select specific properties to show, use
 228         <option>--property=</option>. This command is intended to be
 229         used whenever computer-parsable output is required. Use
 230         <command>session-status</command> if you are looking for
 231         formatted human-readable output.</para></listitem>
 232       </varlistentry>
 233
 234       <varlistentry>
 235         <term><command>activate</command> <optional><replaceable>ID</replaceable></optional></term>
 236
 237         <listitem><para>Activate a session. This brings a session into
 238         the foreground if another session is currently in the
 239         foreground on the respective seat. Takes a session identifier
 240         as argument. If no argument is specified, the session of the
 241         caller is put into foreground.</para></listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term><command>lock-session</command> <optional><replaceable>ID</replaceable>…</optional></term>
 246         <term><command>unlock-session</command> <optional><replaceable>ID</replaceable>…</optional></term>
 247
 248         <listitem><para>Activates/deactivates the screen lock on one
 249         or more sessions, if the session supports it. Takes one or
 250         more session identifiers as arguments. If no argument is
 251         specified, the session of the caller is locked/unlocked.
 252         </para></listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term><command>lock-sessions</command></term>
 257         <term><command>unlock-sessions</command></term>
 258
 259         <listitem><para>Activates/deactivates the screen lock on all
 260         current sessions supporting it. </para></listitem>
 261       </varlistentry>
 262
 263       <varlistentry>
 264         <term><command>terminate-session</command> <replaceable>ID</replaceable>…</term>
 265
 266         <listitem><para>Terminates a session. This kills all processes
 267         of the session and deallocates all resources attached to the
 268         session. </para></listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><command>kill-session</command> <replaceable>ID</replaceable>…</term>
 273
 274         <listitem><para>Send a signal to one or more processes of the
 275         session. Use <option>--kill-who=</option> to select which
 276         process to kill. Use <option>--signal=</option> to select the
 277         signal to send.</para></listitem>
 278       </varlistentry>
 279     </variablelist></refsect2>
 280
 281     <refsect2><title>User Commands</title><variablelist>
 282       <varlistentry>
 283         <term><command>list-users</command></term>
 284
 285         <listitem><para>List currently logged in users.
 286         </para></listitem>
 287       </varlistentry>
 288
 289       <varlistentry>
 290         <term><command>user-status</command> <optional><replaceable>USER</replaceable>…</optional></term>
 291
 292         <listitem><para>Show terse runtime status information about
 293         one or more logged in users, followed by the most recent log
 294         data from the journal. Takes one or more user names or numeric
 295         user IDs as parameters. If no parameters are passed, the status
 296         is shown for the user of the session of the caller. This
 297         function is intended to generate human-readable output. If you
 298         are looking for computer-parsable output, use
 299         <command>show-user</command> instead.</para></listitem>
 300       </varlistentry>
 301
 302       <varlistentry>
 303         <term><command>show-user</command> <optional><replaceable>USER</replaceable>…</optional></term>
 304
 305         <listitem><para>Show properties of one or more users or the
 306         manager itself. If no argument is specified, properties of the
 307         manager will be shown. If a user is specified, properties of
 308         the user are shown. By default, empty properties are
 309         suppressed. Use <option>--all</option> to show those too. To
 310         select specific properties to show, use
 311         <option>--property=</option>. This command is intended to be
 312         used whenever computer-parsable output is required. Use
 313         <command>user-status</command> if you are looking for
 314         formatted human-readable output.</para></listitem>
 315       </varlistentry>
 316
 317       <!-- 0 /// elogind does not spawn a user manager. Mask until lingeringin elogind is clarified.
 318       <varlistentry>
 319         <term><command>enable-linger</command> <optional><replaceable>USER</replaceable>…</optional></term>
 320         <term><command>disable-linger</command> <optional><replaceable>USER</replaceable>…</optional></term>
 321
 322         <listitem><para>Enable/disable user lingering for one or more
 323         users. If enabled for a specific user, a user manager is
 324         spawned for the user at boot and kept around after logouts.
 325         This allows users who are not logged in to run long-running
 326         services. Takes one or more user names or numeric UIDs as
 327         argument. If no argument is specified, enables/disables
 328         lingering for the user of the session of the caller.</para>
 329
 330         <para>See also <varname>KillUserProcesses=</varname> setting in
 331         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 332         </para></listitem>
 333       </varlistentry>
 334       // 0 -->
 335
 336       <varlistentry>
 337         <term><command>terminate-user</command> <replaceable>USER</replaceable>…</term>
 338
 339         <listitem><para>Terminates all sessions of a user. This kills
 340         all processes of all sessions of the user and deallocates all
 341         runtime resources attached to the user.</para></listitem>
 342       </varlistentry>
 343
 344       <varlistentry>
 345         <term><command>kill-user</command> <replaceable>USER</replaceable>…</term>
 346
 347         <listitem><para>Send a signal to all processes of a user. Use
 348         <option>--signal=</option> to select the signal to send.
 349         </para></listitem>
 350       </varlistentry>
 351     </variablelist></refsect2>
 352
 353     <refsect2><title>Seat Commands</title><variablelist>
 354       <varlistentry>
 355         <term><command>list-seats</command></term>
 356
 357         <listitem><para>List currently available seats on the local
 358         system.</para></listitem>
 359       </varlistentry>
 360
 361       <varlistentry>
 362         <term><command>seat-status</command> <optional><replaceable>NAME</replaceable>…</optional></term>
 363
 364         <listitem><para>Show terse runtime status information about
 365         one or more seats. Takes one or more seat names as parameters.
 366         If no seat names are passed the status of the caller's
 367         session's seat is shown. This function is intended to generate
 368         human-readable output. If you are looking for
 369         computer-parsable output, use <command>show-seat</command>
 370         instead.</para></listitem>
 371       </varlistentry>
 372
 373       <varlistentry>
 374         <term><command>show-seat</command> <optional><replaceable>NAME</replaceable>…</optional></term>
 375
 376         <listitem><para>Show properties of one or more seats or the
 377         manager itself. If no argument is specified, properties of the
 378         manager will be shown. If a seat is specified, properties of
 379         the seat are shown. By default, empty properties are
 380         suppressed. Use <option>--all</option> to show those too. To
 381         select specific properties to show, use
 382         <option>--property=</option>. This command is intended to be
 383         used whenever computer-parsable output is required. Use
 384         <command>seat-status</command> if you are looking for
 385         formatted human-readable output.</para></listitem>
 386       </varlistentry>
 387
 388       <varlistentry>
 389         <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>…</term>
 390
 391         <listitem><para>Persistently attach one or more devices to a
 392         seat. The devices should be specified via device paths in the
 393         <filename>/sys</filename> file system. To create a new seat,
 394         attach at least one graphics card to a previously unused seat
 395         name. Seat names may consist only of a–z, A–Z, 0–9,
 396         <literal>-</literal> and <literal>_</literal> and must be
 397         prefixed with <literal>seat</literal>. To drop assignment of a
 398         device to a specific seat, just reassign it to a different
 399         seat, or use <command>flush-devices</command>.
 400         </para></listitem>
 401       </varlistentry>
 402
 403       <varlistentry>
 404         <term><command>flush-devices</command></term>
 405
 406         <listitem><para>Removes all device assignments previously
 407         created with <command>attach</command>. After this call, only
 408         automatically generated seats will remain, and all seat
 409         hardware is assigned to them.</para></listitem>
 410       </varlistentry>
 411
 412       <varlistentry>
 413         <term><command>terminate-seat</command> <replaceable>NAME</replaceable>…</term>
 414
 415         <listitem><para>Terminates all sessions on a seat. This kills
 416         all processes of all sessions on the seat and deallocates all
 417         runtime resources attached to them.</para></listitem>
 418       </varlistentry>
 419     </variablelist></refsect2>
 420
 421     <!-- 1 /// elogind additionally supports a few systemctl commands. -->
 422     <refsect2><title>System Commands</title><variablelist>
 423       <varlistentry>
 424         <term><command>poweroff</command></term>
 425
 426         <listitem>
 427           <para>Print a wall message to all users, shut down and
 428             power-off the system.</para>
 429         </listitem>
 430       </varlistentry>
 431       <varlistentry>
 432         <term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term>
 433
 434         <listitem>
 435           <para>Print a wall message to all users, shut down and
 436             reboot the system.</para>
 437
 438           <para>If the optional argument
 439           <replaceable>arg</replaceable> is given, it will be passed
 440           as the optional argument to the
 441           <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 442           system call. The value is architecture and firmware
 443           specific. As an example, <literal>recovery</literal> might
 444           be used to trigger system recovery, and
 445           <literal>fota</literal> might be used to trigger a
 446           <quote>firmware over the air</quote> update.</para>
 447         </listitem>
 448       </varlistentry>
 449
 450       <varlistentry>
 451         <term><command>suspend</command></term>
 452
 453         <listitem>
 454           <para>Suspend the system.
 455           </para>
 456         </listitem>
 457       </varlistentry>
 458
 459       <varlistentry>
 460         <term><command>hibernate</command></term>
 461
 462         <listitem>
 463           <para>Hibernate the system.
 464           </para>
 465         </listitem>
 466       </varlistentry>
 467
 468       <varlistentry>
 469         <term><command>hybrid-sleep</command></term>
 470
 471         <listitem>
 472           <para>Hibernate and suspend the system.</para>
 473         </listitem>
 474       </varlistentry>
 475     </variablelist></refsect2>
 476     <!-- // 1 -->
 477   </refsect1>
 478
 479   <refsect1>
 480     <title>Exit status</title>
 481
 482     <para>On success, 0 is returned, a non-zero failure code
 483     otherwise.</para>
 484   </refsect1>
 485
 486   <refsect1>
 487     <title>Examples</title>
 488
 489     <example>
 490       <title>Querying user status</title>
 491
 492       <!-- 0 /// With elogind no Unit and jurnald output is generated
 493       <programlisting>$ loginctl user-status
 494 fatima (1005)
 495            Since: Sat 2016-04-09 14:23:31 EDT; 54min ago
 496            State: active
 497         Sessions: 5 *3
 498             Unit: user-1005.slice
 499                   ├─user@1005.service
 500                     …
 501                   ├─session-3.scope
 502                     …
 503                   └─session-5.scope
 504                     ├─3473 login &#x2D;&#x2D; fatima
 505                     └─3515 -zsh
 506
 507 Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session):
 508                        session opened for user fatima by LOGIN(uid=0)
 509 Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima
 510 </programlisting>
 511       --><!-- else -->
 512       <programlisting>$ loginctl user-status
 513 fatima (1005)
 514            Since: Sat 2016-04-09 14:23:31 EDT; 54min ago
 515            State: active
 516         Sessions: 5 *3
 517             Unit: user-1005.slice
 518 </programlisting>
 519       <!-- // 0 -->
 520
 521       <para>There are two sessions, 3 and 5. Session 3 is a graphical session,
 522       marked with a star. The tree of processing including the two corresponding
 523       scope units and the user manager unit are shown.</para>
 524     </example>
 525   </refsect1>
 526
 527   <xi:include href="less-variables.xml" />
 528
 529   <refsect1>
 530     <title>See Also</title>
 531     <para>
 532       <!-- 0 /// elogind is in section 8
 533       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 534       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 535       <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 536       --><!-- else -->
 537       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 538       <!-- // 0 -->
 539       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 540     </para>
 541   </refsect1>
 542
 543 </refentry>