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