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