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