man/loginctl.xml

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