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