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