man/loginctl.xml

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