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