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