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