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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2010 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="loginctl" 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>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>-a</option></term>
 100         <term><option>--all</option></term>
 101
 102         <listitem><para>When showing session/user/seat properties,
 103         show all properties regardless of whether they are set or
 104         not.</para></listitem>
 105       </varlistentry>
 106
 107       <varlistentry>
 108         <term><option>-l</option></term>
 109         <term><option>--full</option></term>
 110
 111         <listitem><para>Do not ellipsize process tree entries.</para>
 112         </listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term><option>--kill-who=</option></term>
 117
 118         <listitem><para>When used with
 119         <command>kill-session</command>, choose which processes to
 120         kill. Must be one of <option>leader</option>, or
 121         <option>all</option> to select whether to kill only the leader
 122         process of the session or all processes of the session. If
 123         omitted, defaults to <option>all</option>.</para></listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term><option>-s</option></term>
 128         <term><option>--signal=</option></term>
 129
 130         <listitem><para>When used with <command>kill-session</command>
 131         or <command>kill-user</command>, choose which signal to send
 132         to selected processes. Must be one of the well known signal
 133         specifiers, such as <constant>SIGTERM</constant>,
 134         <constant>SIGINT</constant> or <constant>SIGSTOP</constant>.
 135         If omitted, defaults to
 136         <constant>SIGTERM</constant>.</para></listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term><option>-n</option></term>
 141         <term><option>--lines=</option></term>
 142
 143         <listitem><para>When used with <command>user-status</command>
 144         and <command>session-status</command>, controls the number of
 145         journal lines to show, counting from the most recent ones.
 146         Takes a positive integer argument. Defaults to 10.</para>
 147         </listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term><option>-o</option></term>
 152         <term><option>--output=</option></term>
 153
 154         <listitem><para>When used with <command>user-status</command>
 155         and <command>session-status</command>, controls the formatting
 156         of the journal entries that are shown. For the available
 157         choices, see
 158         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 159         Defaults to <literal>short</literal>.</para></listitem>
 160       </varlistentry>
 161
 162       <xi:include href="user-system-options.xml" xpointer="host" />
 163       <xi:include href="user-system-options.xml" xpointer="machine" />
 164
 165       <xi:include href="standard-options.xml" xpointer="no-pager" />
 166       <xi:include href="standard-options.xml" xpointer="no-legend" />
 167       <xi:include href="standard-options.xml" xpointer="help" />
 168       <xi:include href="standard-options.xml" xpointer="version" />
 169     </variablelist>
 170   </refsect1>
 171
 172   <refsect1>
 173     <title>Commands</title>
 174
 175     <para>The following commands are understood:</para>
 176
 177     <refsect2><title>Session Commands</title><variablelist>
 178
 179       <varlistentry>
 180         <term><command>list-sessions</command></term>
 181
 182         <listitem><para>List current sessions.</para></listitem>
 183       </varlistentry>
 184
 185       <varlistentry>
 186         <term><command>session-status</command> <optional><replaceable>ID</replaceable>...</optional></term>
 187
 188         <listitem><para>Show terse runtime status information about
 189         one or more sessions, followed by the most recent log data
 190         from the journal. Takes one or more session identifiers as
 191         parameters. If no session identifiers are passed the status of
 192         the caller's session is shown. This function is intended to
 193         generate human-readable output. If you are looking for
 194         computer-parsable output, use <command>show-session</command>
 195         instead.</para></listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
 200
 201         <listitem><para>Show properties of one or more sessions or the
 202         manager itself. If no argument is specified, properties of the
 203         manager will be shown. If a session ID is specified,
 204         properties of the session are shown. By default, empty
 205         properties are suppressed. Use <option>--all</option> to show
 206         those too. To select specific properties to show, use
 207         <option>--property=</option>. This command is intended to be
 208         used whenever computer-parsable output is required. Use
 209         <command>session-status</command> if you are looking for
 210         formatted human-readable output.</para></listitem>
 211       </varlistentry>
 212
 213       <varlistentry>
 214         <term><command>activate</command> <optional><replaceable>ID</replaceable></optional></term>
 215
 216         <listitem><para>Activate a session. This brings a session into
 217         the foreground, if another session is currently in the
 218         foreground on the respective seat. Takes a session identifier
 219         as argument. If no argument is specified the session of the
 220         caller is put into foreground.</para></listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term><command>lock-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
 225         <term><command>unlock-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
 226
 227         <listitem><para>Activates/deactivates the screen lock on one
 228         or more sessions, if the session supports it. Takes one or
 229         more session identifiers as arguments. If no argument is
 230         specified the session of the caller is locked/unlocked.
 231         </para></listitem>
 232       </varlistentry>
 233
 234       <varlistentry>
 235         <term><command>lock-sessions</command></term>
 236         <term><command>unlock-sessions</command></term>
 237
 238         <listitem><para>Activates/deactivates the screen lock on all
 239         current sessions supporting it. </para></listitem>
 240       </varlistentry>
 241
 242       <varlistentry>
 243         <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term>
 244
 245         <listitem><para>Terminates a session. This kills all processes
 246         of the session and deallocates all resources attached to the
 247         session. </para></listitem>
 248       </varlistentry>
 249
 250       <varlistentry>
 251         <term><command>kill-session</command> <replaceable>ID</replaceable>...</term>
 252
 253         <listitem><para>Send a signal to one or more processes of the
 254         session. Use <option>--kill-who=</option> to select which
 255         process to kill. Use <option>--signal=</option> to select the
 256         signal to send.</para></listitem>
 257       </varlistentry>
 258     </variablelist></refsect2>
 259
 260     <refsect2><title>User Commands</title><variablelist>
 261       <varlistentry>
 262         <term><command>list-users</command></term>
 263
 264         <listitem><para>List currently logged in users.
 265         </para></listitem>
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term><command>user-status</command> <optional><replaceable>USER</replaceable>...</optional></term>
 270
 271         <listitem><para>Show terse runtime status information about
 272         one or more logged in users, followed by the most recent log
 273         data from the journal. Takes one or more user names or numeric
 274         user IDs as parameters. If no parameters are passed the status
 275         of the caller's user is shown. This function is intended to
 276         generate human-readable output. If you are looking for
 277         computer-parsable output, use <command>show-user</command>
 278         instead. Users may be specified by their usernames or numeric
 279         user IDs. </para></listitem>
 280       </varlistentry>
 281
 282       <varlistentry>
 283         <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term>
 284
 285         <listitem><para>Show properties of one or more users or the
 286         manager itself. If no argument is specified, properties of the
 287         manager will be shown. If a user is specified, properties of
 288         the user are shown. By default, empty properties are
 289         suppressed. Use <option>--all</option> to show those too. To
 290         select specific properties to show, use
 291         <option>--property=</option>. This command is intended to be
 292         used whenever computer-parsable output is required. Use
 293         <command>user-status</command> if you are looking for
 294         formatted human-readable output.</para></listitem>
 295       </varlistentry>
 296
 297       <varlistentry>
 298         <term><command>enable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term>
 299         <term><command>disable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term>
 300
 301         <listitem><para>Enable/disable user lingering for one or more
 302         users. If enabled for a specific user, a user manager is
 303         spawned for the user at boot and kept around after logouts.
 304         This allows users who are not logged in to run long-running
 305         services. Takes one or more user names or numeric UIDs as
 306         argument. If no argument is specified enables/disables
 307         lingering for the user of the session of the caller.
 308         </para></listitem>
 309       </varlistentry>
 310
 311       <varlistentry>
 312         <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term>
 313
 314         <listitem><para>Terminates all sessions of a user. This kills
 315         all processes of all sessions of the user and deallocates all
 316         runtime resources attached to the user.</para></listitem>
 317       </varlistentry>
 318
 319       <varlistentry>
 320         <term><command>kill-user</command> <replaceable>USER</replaceable>...</term>
 321
 322         <listitem><para>Send a signal to all processes of a user. Use
 323         <option>--signal=</option> to select the signal to send.
 324         </para></listitem>
 325       </varlistentry>
 326     </variablelist></refsect2>
 327
 328     <refsect2><title>Seat Commands</title><variablelist>
 329       <varlistentry>
 330         <term><command>list-seats</command></term>
 331
 332         <listitem><para>List currently available seats on the local
 333         system.</para></listitem>
 334       </varlistentry>
 335
 336       <varlistentry>
 337         <term><command>seat-status</command> <optional><replaceable>NAME</replaceable>...</optional></term>
 338
 339         <listitem><para>Show terse runtime status information about
 340         one or more seats. Takes one or more seat names as parameters.
 341         If no seat names are passed the status of the caller's
 342         session's seat is shown. This function is intended to generate
 343         human-readable output. If you are looking for
 344         computer-parsable output, use <command>show-seat</command>
 345         instead.</para></listitem>
 346       </varlistentry>
 347
 348       <varlistentry>
 349         <term><command>show-seat</command> <optional><replaceable>NAME</replaceable>...</optional></term>
 350
 351         <listitem><para>Show properties of one or more seats or the
 352         manager itself. If no argument is specified, properties of the
 353         manager will be shown. If a seat is specified, properties of
 354         the seat are shown. By default, empty properties are
 355         suppressed. Use <option>--all</option> to show those too. To
 356         select specific properties to show, use
 357         <option>--property=</option>. This command is intended to be
 358         used whenever computer-parsable output is required. Use
 359         <command>seat-status</command> if you are looking for
 360         formatted human-readable output.</para></listitem>
 361       </varlistentry>
 362
 363       <varlistentry>
 364         <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term>
 365
 366         <listitem><para>Persistently attach one or more devices to a
 367         seat. The devices should be specified via device paths in the
 368         <filename>/sys</filename> file system. To create a new seat,
 369         attach at least one graphics card to a previously unused seat
 370         name. Seat names may consist only of a-z, A-Z, 0-9,
 371         <literal>-</literal> and <literal>_</literal> and must be
 372         prefixed with <literal>seat</literal>. To drop assignment of a
 373         device to a specific seat, just reassign it to a different
 374         seat, or use <command>flush-devices</command>.
 375         </para></listitem>
 376       </varlistentry>
 377
 378       <varlistentry>
 379         <term><command>flush-devices</command></term>
 380
 381         <listitem><para>Removes all device assignments previously
 382         created with <command>attach</command>. After this call, only
 383         automatically generated seats will remain, and all seat
 384         hardware is assigned to them.</para></listitem>
 385       </varlistentry>
 386
 387       <varlistentry>
 388         <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term>
 389
 390         <listitem><para>Terminates all sessions on a seat. This kills
 391         all processes of all sessions on the seat and deallocates all
 392         runtime resources attached to them.</para></listitem>
 393       </varlistentry>
 394     </variablelist></refsect2>
 395
 396   </refsect1>
 397
 398   <refsect1>
 399     <title>Exit status</title>
 400
 401     <para>On success, 0 is returned, a non-zero failure code
 402     otherwise.</para>
 403   </refsect1>
 404
 405   <xi:include href="less-variables.xml" />
 406
 407   <refsect1>
 408     <title>See Also</title>
 409     <para>
 410       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 411       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 412       <citerefentry><refentrytitle>logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 413       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 414     </para>
 415   </refsect1>
 416
 417 </refentry>