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