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
  26         <refentryinfo>
  27                 <title>loginctl</title>
  28                 <productname>systemd</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 systemd 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
  63                 introspect and control the state of the
  64                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  65                 login manager <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  66         </refsect1>
  67
  68         <refsect1>
  69                 <title>Options</title>
  70
  71                 <para>The following options are understood:</para>
  72
  73                 <variablelist>
  74                         <varlistentry>
  75                                 <term><option>-h</option></term>
  76                                 <term><option>--help</option></term>
  77
  78                                 <listitem><para>Prints a short help
  79                                 text and exits.</para></listitem>
  80                         </varlistentry>
  81
  82                         <varlistentry>
  83                                 <term><option>--version</option></term>
  84
  85                                 <listitem><para>Prints a short version
  86                                 string and exits.</para></listitem>
  87                         </varlistentry>
  88
  89                         <varlistentry>
  90                                 <term><option>--no-pager</option></term>
  91
  92                                 <listitem><para>Do not pipe output into a
  93                                 pager.</para></listitem>
  94                         </varlistentry>
  95
  96                         <varlistentry>
  97                                 <term><option>--no-ask-password</option></term>
  98
  99                                 <listitem><para>Do not query the user
 100                                 for authentication for privileged
 101                                 operations.</para></listitem>
 102                         </varlistentry>
 103
 104                         <varlistentry>
 105                                 <term><option>-H</option></term>
 106                                 <term><option>--host</option></term>
 107
 108                                 <listitem><para>Execute the operation
 109                                 remotely. Specify a hostname, or
 110                                 username and hostname separated by <literal>@</literal>,
 111                                 to connect to. This will use SSH to
 112                                 talk to the remote login manager
 113                                 instance.</para></listitem>
 114                         </varlistentry>
 115
 116                         <varlistentry>
 117                                 <term><option>-M</option></term>
 118                                 <term><option>--machine=</option></term>
 119
 120                                 <listitem><para>Execute the operation on a
 121                                 local container. Specify a container
 122                                 name to connect to.</para></listitem>
 123                         </varlistentry>
 124
 125                         <varlistentry>
 126                                 <term><option>-p</option></term>
 127                                 <term><option>--property=</option></term>
 128
 129                                 <listitem><para>When showing
 130                                 session/user/seat properties, limit
 131                                 display to certain properties as
 132                                 specified as argument. If not
 133                                 specified, all set properties are
 134                                 shown. The argument should be a
 135                                 property name, such as
 136                                 <literal>Sessions</literal>. If
 137                                 specified more than once, all
 138                                 properties with the specified names
 139                                 are shown.</para></listitem>
 140                         </varlistentry>
 141
 142                         <varlistentry>
 143                                 <term><option>-a</option></term>
 144                                 <term><option>--all</option></term>
 145
 146                                 <listitem><para>When showing
 147                                 session/user/seat properties, show all
 148                                 properties regardless whether they are
 149                                 set or not.</para></listitem>
 150                         </varlistentry>
 151
 152                         <varlistentry>
 153                                 <term><option>-l</option></term>
 154                                 <term><option>--full</option></term>
 155
 156                                 <listitem><para>Do not ellipsize
 157                                 process tree entries.</para>
 158                                 </listitem>
 159                         </varlistentry>
 160
 161                         <varlistentry>
 162                                 <term><option>--kill-who=</option></term>
 163
 164                                 <listitem><para>When used with
 165                                 <command>kill-session</command>,
 166                                 choose which processes to kill. Must
 167                                 be one of <option>leader</option>, or
 168                                 <option>all</option> to select whether
 169                                 to kill only the leader process of the
 170                                 session or all processes of the
 171                                 session. If omitted, defaults to
 172                                 <option>all</option>.</para></listitem>
 173                         </varlistentry>
 174
 175                         <varlistentry>
 176                                 <term><option>-s</option></term>
 177                                 <term><option>--signal=</option></term>
 178
 179                                 <listitem><para>When used with
 180                                 <command>kill-session</command> or
 181                                 <command>kill-user</command>, choose
 182                                 which signal to send to selected
 183                                 processes. Must be one of the well
 184                                 known signal specifiers, such as
 185                                 <constant>SIGTERM</constant>,
 186                                 <constant>SIGINT</constant> or
 187                                 <constant>SIGSTOP</constant>. If
 188                                 omitted, defaults to
 189                                 <constant>SIGTERM</constant>.</para></listitem>
 190                         </varlistentry>
 191
 192                 </variablelist>
 193
 194                 <para>The following commands are understood:</para>
 195
 196                 <variablelist>
 197                         <varlistentry>
 198                                 <term><command>list-sessions</command></term>
 199
 200                                 <listitem><para>List current sessions.</para></listitem>
 201                         </varlistentry>
 202
 203                         <varlistentry>
 204                                 <term><command>session-status</command> <replaceable>ID</replaceable>...</term>
 205
 206                                 <listitem><para>Show terse runtime
 207                                 status information about one or more
 208                                 sessions. This function is intended to
 209                                 generate human-readable output. If you
 210                                 are looking for computer-parsable
 211                                 output, use
 212                                 <command>show-session</command>
 213                                 instead.</para></listitem>
 214                         </varlistentry>
 215
 216                         <varlistentry>
 217                                 <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
 218
 219                                 <listitem><para>Show properties of one
 220                                 or more sessions or the manager
 221                                 itself. If no argument is specified,
 222                                 properties of the manager will be
 223                                 shown. If a session ID is specified,
 224                                 properties of the session are shown. By
 225                                 default, empty properties are
 226                                 suppressed. Use <option>--all</option>
 227                                 to show those too. To select specific
 228                                 properties to show, use
 229                                 <option>--property=</option>. This
 230                                 command is intended to be used
 231                                 whenever computer-parsable output is
 232                                 required. Use
 233                                 <command>session-status</command> if
 234                                 you are looking for formatted
 235                                 human-readable
 236                                 output.</para></listitem>
 237                         </varlistentry>
 238
 239                         <varlistentry>
 240                                 <term><command>activate</command> <replaceable>ID</replaceable>...</term>
 241
 242                                 <listitem><para>Activate one or more
 243                                 sessions. This brings one or more
 244                                 sessions into the foreground, if
 245                                 another session is currently in the
 246                                 foreground on the respective
 247                                 seat.</para></listitem>
 248                         </varlistentry>
 249
 250                         <varlistentry>
 251                                 <term><command>lock-session</command> <replaceable>ID</replaceable>...</term>
 252                                 <term><command>unlock-session</command> <replaceable>ID</replaceable>...</term>
 253
 254                                 <listitem><para>Activates/deactivates
 255                                 the screen lock on one or more
 256                                 sessions, if the session supports it.
 257                                 </para></listitem>
 258                         </varlistentry>
 259
 260                         <varlistentry>
 261                                 <term><command>lock-sessions</command></term>
 262                                 <term><command>unlock-sessions</command></term>
 263
 264                                 <listitem><para>Activates/deactivates
 265                                 the screen lock on all current
 266                                 sessions supporting it.
 267                                 </para></listitem>
 268                         </varlistentry>
 269
 270                         <varlistentry>
 271                                 <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term>
 272
 273                                 <listitem><para>Terminates a session.
 274                                 This kills all processes of the
 275                                 session and deallocates all resources
 276                                 attached to the session.
 277                                 </para></listitem>
 278                         </varlistentry>
 279
 280                         <varlistentry>
 281                                 <term><command>kill-session</command> <replaceable>ID</replaceable>...</term>
 282
 283                                 <listitem><para>Send a signal to one
 284                                 or more processes of the session. Use
 285                                 <option>--kill-who=</option> to select
 286                                 which process to kill. Use
 287                                 <option>--signal=</option> to select
 288                                 the signal to send.</para></listitem>
 289                         </varlistentry>
 290
 291                         <varlistentry>
 292                                 <term><command>list-users</command></term>
 293
 294                                 <listitem><para>List currently logged
 295                                 in users.</para></listitem>
 296                         </varlistentry>
 297
 298                         <varlistentry>
 299                                 <term><command>user-status</command> <replaceable>USER</replaceable>...</term>
 300
 301                                 <listitem><para>Show terse runtime
 302                                 status information about one or more
 303                                 logged in users. This function is
 304                                 intended to generate human-readable
 305                                 output. If you are looking for
 306                                 computer-parsable output, use
 307                                 <command>show-user</command> instead.
 308                                 Users may be specified by their
 309                                 usernames or numeric user IDs.
 310                                 </para></listitem>
 311                         </varlistentry>
 312
 313                         <varlistentry>
 314                                 <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term>
 315
 316                                 <listitem><para>Show properties of one
 317                                 or more users or the manager
 318                                 itself. If no argument is specified,
 319                                 properties of the manager will be
 320                                 shown. If a user is specified,
 321                                 properties of the user are shown. By
 322                                 default, empty properties are
 323                                 suppressed. Use <option>--all</option>
 324                                 to show those too. To select specific
 325                                 properties to show, use
 326                                 <option>--property=</option>. This
 327                                 command is intended to be used
 328                                 whenever computer-parsable output is
 329                                 required. Use
 330                                 <command>user-status</command> if
 331                                 you are looking for formatted
 332                                 human-readable
 333                                 output.</para></listitem>
 334                         </varlistentry>
 335
 336                         <varlistentry>
 337                                 <term><command>enable-linger</command> <replaceable>USER</replaceable>...</term>
 338                                 <term><command>disable-linger</command> <replaceable>USER</replaceable>...</term>
 339
 340                                 <listitem><para>Enable/disable user
 341                                 lingering for one or more users. If
 342                                 enabled for a specific user, a user
 343                                 manager is spawned for the user at
 344                                 boot and kept around after
 345                                 logouts. This allows users who are not
 346                                 logged in to run long-running
 347                                 services.</para></listitem>
 348                         </varlistentry>
 349
 350                         <varlistentry>
 351                                 <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term>
 352
 353                                 <listitem><para>Terminates all
 354                                 sessions of a user. This kills all
 355                                 processes of all sessions of the user
 356                                 and deallocates all runtime resources
 357                                 attached to the user.
 358                                 </para></listitem>
 359                         </varlistentry>
 360
 361                         <varlistentry>
 362                                 <term><command>kill-user</command> <replaceable>USER</replaceable>...</term>
 363
 364                                 <listitem><para>Send a signal to all
 365                                 processes of a user. Use
 366                                 <option>--signal=</option> to select
 367                                 the signal to send.</para></listitem>
 368                         </varlistentry>
 369
 370                         <varlistentry>
 371                                 <term><command>list-seats</command></term>
 372
 373                                 <listitem><para>List currently
 374                                 available seats on the local
 375                                 system.</para></listitem>
 376                         </varlistentry>
 377
 378                         <varlistentry>
 379                                 <term><command>seat-status</command> <replaceable>NAME</replaceable>...</term>
 380
 381                                 <listitem><para>Show terse runtime
 382                                 status information about one or more
 383                                 seats. This function is
 384                                 intended to generate human-readable
 385                                 output. If you are looking for
 386                                 computer-parsable output, use
 387                                 <command>show-seat</command>
 388                                 instead.</para></listitem>
 389                         </varlistentry>
 390
 391                         <varlistentry>
 392                                 <term><command>show-seat</command> <replaceable>NAME</replaceable>...</term>
 393
 394                                 <listitem><para>Show properties of one
 395                                 or more seats or the manager
 396                                 itself. If no argument is specified,
 397                                 properties of the manager will be
 398                                 shown. If a seat is specified,
 399                                 properties of the seat are shown. By
 400                                 default, empty properties are
 401                                 suppressed. Use <option>--all</option>
 402                                 to show those too. To select specific
 403                                 properties to show, use
 404                                 <option>--property=</option>. This
 405                                 command is intended to be used
 406                                 whenever computer-parsable output is
 407                                 required. Use
 408                                 <command>seat-status</command> if you
 409                                 are looking for formatted
 410                                 human-readable
 411                                 output.</para></listitem>
 412                         </varlistentry>
 413
 414                         <varlistentry>
 415                                 <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term>
 416
 417                                 <listitem><para>Persistently attach
 418                                 one or more devices to a seat. The
 419                                 devices should be specified via device
 420                                 paths in the <filename>/sys</filename>
 421                                 file system. To create a new seat,
 422                                 attach at least one graphics card to a
 423                                 previously unused seat name. Seat
 424                                 names may consist only of a-z, A-Z,
 425                                 0-9, <literal>-</literal> and
 426                                 <literal>_</literal> and must be
 427                                 prefixed with <literal>seat</literal>.
 428                                 To drop assignment of a device to a
 429                                 specific seat, just reassign it to a
 430                                 different seat, or use
 431                                 <command>flush-devices</command>.
 432                                 </para></listitem>
 433                         </varlistentry>
 434
 435                         <varlistentry>
 436                                 <term><command>flush-devices</command></term>
 437
 438                                 <listitem><para>Removes all device
 439                                 assignments previously created with
 440                                 <command>attach</command>. After this
 441                                 call, only automatically generated
 442                                 seats will remain, and all seat
 443                                 hardware is assigned to
 444                                 them.</para></listitem>
 445                         </varlistentry>
 446
 447                         <varlistentry>
 448                                 <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term>
 449
 450                                 <listitem><para>Terminates all
 451                                 sessions on a seat. This kills all
 452                                 processes of all sessions on the seat
 453                                 and deallocates all runtime resources
 454                                 attached to them.</para></listitem>
 455                         </varlistentry>
 456                 </variablelist>
 457
 458         </refsect1>
 459
 460         <refsect1>
 461                 <title>Exit status</title>
 462
 463                 <para>On success, 0 is returned, a non-zero failure
 464                 code otherwise.</para>
 465         </refsect1>
 466
 467         <refsect1>
 468                 <title>Environment</title>
 469
 470                 <variablelist class='environment-variables'>
 471                         <varlistentry>
 472                                 <term><varname>$SYSTEMD_PAGER</varname></term>
 473                                 <listitem><para>Pager to use when
 474                                 <option>--no-pager</option> is not given;
 475                                 overrides <varname>$PAGER</varname>.  Setting
 476                                 this to an empty string or the value
 477                                 <literal>cat</literal> is equivalent to passing
 478                                 <option>--no-pager</option>.</para></listitem>
 479                         </varlistentry>
 480                 </variablelist>
 481         </refsect1>
 482
 483         <refsect1>
 484                 <title>See Also</title>
 485                 <para>
 486                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 487                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 488                         <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 489                         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 490                 </para>
 491         </refsect1>
 492
 493 </refentry>