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