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.5/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>
 119
 120         <xi:include href="version-info.xml" xpointer="v188"/></listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><command>terminate-session</command> <replaceable>ID</replaceable>…</term>
 125
 126         <listitem><para>Terminates a session. This kills all processes of the session and deallocates all
 127         resources attached to the session. If the argument is specified as empty string the session invoking
 128         the command is terminated.</para>
 129
 130         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term><command>kill-session</command> <replaceable>ID</replaceable>…</term>
 135
 136         <listitem><para>Send a signal to one or more processes of the session. Use
 137         <option>--kill-whom=</option> to select which process to kill. Use <option>--signal=</option> to
 138         select the signal to send. If the argument is specified as empty string the signal is sent to the
 139         session invoking the command.</para>
 140
 141         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 142       </varlistentry>
 143     </variablelist></refsect2>
 144
 145     <refsect2><title>User Commands</title><variablelist>
 146       <varlistentry>
 147         <term><command>list-users</command></term>
 148
 149         <listitem><para>List currently logged in users.
 150         </para></listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term><command>user-status</command> <optional><replaceable>USER</replaceable>…</optional></term>
 155
 156         <listitem><para>Show terse runtime status information about
 157         one or more logged in users, followed by the most recent log
 158         data from the journal. Takes one or more user names or numeric
 159         user IDs as parameters. If no parameters are passed, the status
 160         is shown for the user of the session of the caller. This
 161         function is intended to generate human-readable output. If you
 162         are looking for computer-parsable output, use
 163         <command>show-user</command> instead.</para>
 164
 165         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term><command>show-user</command> <optional><replaceable>USER</replaceable>…</optional></term>
 170
 171         <listitem><para>Show properties of one or more users or the
 172         manager itself. If no argument is specified, properties of the
 173         manager will be shown. If a user is specified, properties of
 174         the user are shown. By default, empty properties are
 175         suppressed. Use <option>--all</option> to show those too. To
 176         select specific properties to show, use
 177         <option>--property=</option>. This command is intended to be
 178         used whenever computer-parsable output is required. Use
 179         <command>user-status</command> if you are looking for
 180         formatted human-readable output.</para>
 181
 182         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 183       </varlistentry>
 184
 185       <varlistentry>
 186         <term><command>enable-linger</command> <optional><replaceable>USER</replaceable>…</optional></term>
 187         <term><command>disable-linger</command> <optional><replaceable>USER</replaceable>…</optional></term>
 188
 189         <listitem><para>Enable/disable user lingering for one or more
 190         users. If enabled for a specific user, a user manager is
 191         spawned for the user at boot and kept around after logouts.
 192         This allows users who are not logged in to run long-running
 193         services. Takes one or more user names or numeric UIDs as
 194         argument. If no argument is specified, enables/disables
 195         lingering for the user of the session of the caller.</para>
 196
 197         <para>See also <varname>KillUserProcesses=</varname> setting in
 198         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 199         </para>
 200
 201         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term><command>terminate-user</command> <replaceable>USER</replaceable>…</term>
 206
 207         <listitem><para>Terminates all sessions of a user. This kills all processes of all sessions of the
 208         user and deallocates all runtime resources attached to the user. If the argument is specified as
 209         empty string the sessions of the user invoking the command are terminated.</para>
 210
 211         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><command>kill-user</command> <replaceable>USER</replaceable>…</term>
 216
 217         <listitem><para>Send a signal to all processes of a user. Use <option>--signal=</option> to select
 218         the signal to send. If the argument is specified as empty string the signal is sent to the sessions
 219         of the user invoking the command.</para>
 220
 221         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 222       </varlistentry>
 223     </variablelist></refsect2>
 224
 225     <refsect2><title>Seat Commands</title><variablelist>
 226       <varlistentry>
 227         <term><command>list-seats</command></term>
 228
 229         <listitem><para>List currently available seats on the local
 230         system.</para></listitem>
 231       </varlistentry>
 232
 233       <varlistentry>
 234         <term><command>seat-status</command> <optional><replaceable>NAME</replaceable>…</optional></term>
 235
 236         <listitem><para>Show terse runtime status information about
 237         one or more seats. Takes one or more seat names as parameters.
 238         If no seat names are passed the status of the caller's
 239         session's seat is shown. This function is intended to generate
 240         human-readable output. If you are looking for
 241         computer-parsable output, use <command>show-seat</command>
 242         instead.</para>
 243
 244         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term><command>show-seat</command> <optional><replaceable>NAME</replaceable>…</optional></term>
 249
 250         <listitem><para>Show properties of one or more seats or the
 251         manager itself. If no argument is specified, properties of the
 252         manager will be shown. If a seat is specified, properties of
 253         the seat are shown. By default, empty properties are
 254         suppressed. Use <option>--all</option> to show those too. To
 255         select specific properties to show, use
 256         <option>--property=</option>. This command is intended to be
 257         used whenever computer-parsable output is required. Use
 258         <command>seat-status</command> if you are looking for
 259         formatted human-readable output.</para>
 260
 261         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 262       </varlistentry>
 263
 264       <varlistentry>
 265         <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>…</term>
 266
 267         <listitem><para>Persistently attach one or more devices to a
 268         seat. The devices should be specified via device paths in the
 269         <filename>/sys/</filename> file system. To create a new seat,
 270         attach at least one graphics card to a previously unused seat
 271         name. Seat names may consist only of a–z, A–Z, 0–9,
 272         <literal>-</literal> and <literal>_</literal> and must be
 273         prefixed with <literal>seat</literal>. To drop assignment of a
 274         device to a specific seat, just reassign it to a different
 275         seat, or use <command>flush-devices</command>.
 276         </para>
 277
 278         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 279       </varlistentry>
 280
 281       <varlistentry>
 282         <term><command>flush-devices</command></term>
 283
 284         <listitem><para>Removes all device assignments previously
 285         created with <command>attach</command>. After this call, only
 286         automatically generated seats will remain, and all seat
 287         hardware is assigned to them.</para></listitem>
 288       </varlistentry>
 289
 290       <varlistentry>
 291         <term><command>terminate-seat</command> <replaceable>NAME</replaceable>…</term>
 292
 293         <listitem><para>Terminates all sessions on a seat. This kills
 294         all processes of all sessions on the seat and deallocates all
 295         runtime resources attached to them.</para>
 296
 297         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 298       </varlistentry>
 299     </variablelist></refsect2>
 300
 301   </refsect1>
 302
 303   <refsect1>
 304     <title>Options</title>
 305
 306     <para>The following options are understood:</para>
 307
 308     <variablelist>
 309       <varlistentry>
 310         <term><option>--no-ask-password</option></term>
 311
 312         <listitem><para>Do not query the user for authentication for
 313         privileged operations.</para></listitem>
 314       </varlistentry>
 315
 316       <varlistentry>
 317         <term><option>-p</option></term>
 318         <term><option>--property=</option></term>
 319
 320         <listitem><para>When showing session/user/seat properties,
 321         limit display to certain properties as specified as argument.
 322         If not specified, all set properties are shown. The argument
 323         should be a property name, such as
 324         <literal>Sessions</literal>. If specified more than once, all
 325         properties with the specified names are
 326         shown.</para></listitem>
 327       </varlistentry>
 328
 329       <varlistentry>
 330         <term><option>--value</option></term>
 331
 332         <listitem><para>When showing session/user/seat properties,
 333         only print the value, and skip the property name and
 334         <literal>=</literal>.</para>
 335
 336         <xi:include href="version-info.xml" xpointer="v230"/></listitem>
 337       </varlistentry>
 338
 339       <varlistentry>
 340         <term><option>-a</option></term>
 341         <term><option>--all</option></term>
 342
 343         <listitem><para>When showing session/user/seat properties,
 344         show all properties regardless of whether they are set or
 345         not.</para></listitem>
 346       </varlistentry>
 347
 348       <varlistentry>
 349         <term><option>-l</option></term>
 350         <term><option>--full</option></term>
 351
 352         <listitem><para>Do not ellipsize process tree entries.</para>
 353
 354         <xi:include href="version-info.xml" xpointer="v198"/>
 355         </listitem>
 356       </varlistentry>
 357
 358       <varlistentry>
 359         <term><option>--kill-whom=</option></term>
 360
 361         <listitem><para>When used with <command>kill-session</command>, choose which processes to kill.
 362         Takes one of <literal>leader</literal> or <literal>all</literal>, to select whether to kill only
 363         the leader process of the session or all processes of the session. If omitted, defaults to
 364         <option>all</option>.</para>
 365
 366         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 367       </varlistentry>
 368
 369       <varlistentry>
 370         <term><option>-s</option></term>
 371         <term><option>--signal=</option></term>
 372
 373         <listitem><para>When used with <command>kill-session</command> or <command>kill-user</command>,
 374         choose which signal to send to selected processes. Must be one of the well known signal specifiers,
 375         such as <constant>SIGTERM</constant>, <constant>SIGINT</constant> or <constant>SIGSTOP</constant>.
 376         If omitted, defaults to <constant>SIGTERM</constant>.</para>
 377
 378         <para>The special value <literal>help</literal> will list the known values and the program will exit
 379         immediately, and the special value <literal>list</literal> will list known values along with the
 380         numerical signal numbers and the program will exit immediately.</para></listitem>
 381       </varlistentry>
 382
 383       <varlistentry>
 384         <term><option>-n</option></term>
 385         <term><option>--lines=</option></term>
 386
 387         <listitem><para>When used with <command>user-status</command>
 388         and <command>session-status</command>, controls the number of
 389         journal lines to show, counting from the most recent ones.
 390         Takes a positive integer argument. Defaults to 10.</para>
 391
 392         <xi:include href="version-info.xml" xpointer="v219"/>
 393         </listitem>
 394       </varlistentry>
 395
 396       <varlistentry>
 397         <term><option>-o</option></term>
 398         <term><option>--output=</option></term>
 399
 400         <listitem><para>When used with <command>user-status</command>
 401         and <command>session-status</command>, controls the formatting
 402         of the journal entries that are shown. For the available
 403         choices, see
 404         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 405         Defaults to <literal>short</literal>.</para>
 406
 407         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 408       </varlistentry>
 409
 410       <xi:include href="user-system-options.xml" xpointer="host" />
 411       <xi:include href="user-system-options.xml" xpointer="machine" />
 412
 413       <xi:include href="standard-options.xml" xpointer="no-pager" />
 414       <xi:include href="standard-options.xml" xpointer="no-legend" />
 415       <xi:include href="standard-options.xml" xpointer="help" />
 416       <xi:include href="standard-options.xml" xpointer="version" />
 417     </variablelist>
 418   </refsect1>
 419
 420   <refsect1>
 421     <title>Exit status</title>
 422
 423     <para>On success, 0 is returned, a non-zero failure code
 424     otherwise.</para>
 425   </refsect1>
 426
 427   <refsect1>
 428     <title>Examples</title>
 429
 430     <example>
 431       <title>Querying user status</title>
 432
 433       <programlisting>$ loginctl user-status
 434 fatima (1005)
 435            Since: Sat 2016-04-09 14:23:31 EDT; 54min ago
 436            State: active
 437         Sessions: 5 *3
 438             Unit: user-1005.slice
 439                   ├─user@1005.service
 440                     …
 441                   ├─session-3.scope
 442                     …
 443                   └─session-5.scope
 444                     ├─3473 login -- fatima
 445                     └─3515 -zsh
 446
 447 Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session):
 448                        session opened for user fatima by LOGIN(uid=0)
 449 Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima
 450 </programlisting>
 451
 452       <para>There are two sessions, 3 and 5. Session 3 is a graphical session,
 453       marked with a star. The tree of processing including the two corresponding
 454       scope units and the user manager unit are shown.</para>
 455     </example>
 456   </refsect1>
 457
 458   <xi:include href="common-variables.xml" />
 459
 460   <refsect1>
 461     <title>See Also</title>
 462     <para><simplelist type="inline">
 463       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 464       <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 465       <member><citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 466       <member><citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 467     </simplelist></para>
 468   </refsect1>
 469
 470 </refentry>