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