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