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