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