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