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