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='ENABLE_LOGIND'
  25           xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27         <refentryinfo>
  28                 <title>loginctl</title>
  29                 <productname>systemd</productname>
  30
  31                 <authorgroup>
  32                         <author>
  33                                 <contrib>Developer</contrib>
  34                                 <firstname>Lennart</firstname>
  35                                 <surname>Poettering</surname>
  36                                 <email>lennart@poettering.net</email>
  37                         </author>
  38                 </authorgroup>
  39         </refentryinfo>
  40
  41         <refmeta>
  42                 <refentrytitle>loginctl</refentrytitle>
  43                 <manvolnum>1</manvolnum>
  44         </refmeta>
  45
  46         <refnamediv>
  47                 <refname>loginctl</refname>
  48                 <refpurpose>Control the systemd login manager</refpurpose>
  49         </refnamediv>
  50
  51         <refsynopsisdiv>
  52                 <cmdsynopsis>
  53                         <command>loginctl</command>
  54                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  55                         <arg choice="req">COMMAND</arg>
  56                         <arg choice="opt" rep="repeat">NAME</arg>
  57                 </cmdsynopsis>
  58         </refsynopsisdiv>
  59
  60         <refsect1>
  61                 <title>Description</title>
  62
  63                 <para><command>loginctl</command> may be used to
  64                 introspect and control the state of the
  65                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  66                 login manager <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  67         </refsect1>
  68
  69         <refsect1>
  70                 <title>Options</title>
  71
  72                 <para>The following options are understood:</para>
  73
  74                 <variablelist>
  75                         <varlistentry>
  76                                 <term><option>--no-ask-password</option></term>
  77
  78                                 <listitem><para>Do not query the user
  79                                 for authentication for privileged
  80                                 operations.</para></listitem>
  81                         </varlistentry>
  82
  83                         <varlistentry>
  84                                 <term><option>-p</option></term>
  85                                 <term><option>--property=</option></term>
  86
  87                                 <listitem><para>When showing
  88                                 session/user/seat properties, limit
  89                                 display to certain properties as
  90                                 specified as argument. If not
  91                                 specified, all set properties are
  92                                 shown. The argument should be a
  93                                 property name, such as
  94                                 <literal>Sessions</literal>. If
  95                                 specified more than once, all
  96                                 properties with the specified names
  97                                 are shown.</para></listitem>
  98                         </varlistentry>
  99
 100                         <varlistentry>
 101                                 <term><option>-a</option></term>
 102                                 <term><option>--all</option></term>
 103
 104                                 <listitem><para>When showing
 105                                 session/user/seat properties, show all
 106                                 properties regardless of whether they are
 107                                 set or not.</para></listitem>
 108                         </varlistentry>
 109
 110                         <varlistentry>
 111                                 <term><option>-l</option></term>
 112                                 <term><option>--full</option></term>
 113
 114                                 <listitem><para>Do not ellipsize
 115                                 process tree entries.</para>
 116                                 </listitem>
 117                         </varlistentry>
 118
 119                         <varlistentry>
 120                                 <term><option>--kill-who=</option></term>
 121
 122                                 <listitem><para>When used with
 123                                 <command>kill-session</command>,
 124                                 choose which processes to kill. Must
 125                                 be one of <option>leader</option>, or
 126                                 <option>all</option> to select whether
 127                                 to kill only the leader process of the
 128                                 session or all processes of the
 129                                 session. If omitted, defaults to
 130                                 <option>all</option>.</para></listitem>
 131                         </varlistentry>
 132
 133                         <varlistentry>
 134                                 <term><option>-s</option></term>
 135                                 <term><option>--signal=</option></term>
 136
 137                                 <listitem><para>When used with
 138                                 <command>kill-session</command> or
 139                                 <command>kill-user</command>, choose
 140                                 which signal to send to selected
 141                                 processes. Must be one of the well
 142                                 known signal specifiers, such as
 143                                 <constant>SIGTERM</constant>,
 144                                 <constant>SIGINT</constant> or
 145                                 <constant>SIGSTOP</constant>. If
 146                                 omitted, defaults to
 147                                 <constant>SIGTERM</constant>.</para></listitem>
 148                         </varlistentry>
 149
 150                         <varlistentry>
 151                                 <term><option>-n</option></term>
 152                                 <term><option>--lines=</option></term>
 153
 154                                 <listitem><para>When used with
 155                                 <command>user-status</command> and
 156                                 <command>session-status</command>,
 157                                 controls the number of journal lines
 158                                 to show, counting from the most recent
 159                                 ones. Takes a positive integer
 160                                 argument. Defaults to 10.</para>
 161                                 </listitem>
 162                         </varlistentry>
 163
 164                         <varlistentry>
 165                                 <term><option>-o</option></term>
 166                                 <term><option>--output=</option></term>
 167
 168                                 <listitem><para>When used with
 169                                 <command>user-status</command> and
 170                                 <command>session-status</command>,
 171                                 controls the formatting of the journal
 172                                 entries that are shown. For the
 173                                 available choices, see
 174                                 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 175                                 Defaults to
 176                                 <literal>short</literal>.</para></listitem>
 177                         </varlistentry>
 178
 179                         <xi:include href="user-system-options.xml" xpointer="host" />
 180                         <xi:include href="user-system-options.xml" xpointer="machine" />
 181
 182                         <xi:include href="standard-options.xml" xpointer="no-pager" />
 183                         <xi:include href="standard-options.xml" xpointer="no-legend" />
 184                         <xi:include href="standard-options.xml" xpointer="help" />
 185                         <xi:include href="standard-options.xml" xpointer="version" />
 186                 </variablelist>
 187         </refsect1>
 188
 189         <refsect1>
 190                 <title>Commands</title>
 191
 192                 <para>The following commands are understood:</para>
 193
 194                 <refsect2><title>Session Commands</title><variablelist>
 195
 196                         <varlistentry>
 197                                 <term><command>list-sessions</command></term>
 198
 199                                 <listitem><para>List current sessions.</para></listitem>
 200                         </varlistentry>
 201
 202                         <varlistentry>
 203                                 <term><command>session-status</command> <optional><replaceable>ID</replaceable>...</optional></term>
 204
 205                                 <listitem><para>Show terse runtime
 206                                 status information about one or more
 207                                 sessions, followed by the most recent
 208                                 log data from the journal. Takes one
 209                                 or more session identifiers as
 210                                 parameters. If no session identifiers
 211                                 are passed the status of the caller's
 212                                 session is shown. This function is
 213                                 intended to generate human-readable
 214                                 output. If you are looking for
 215                                 computer-parsable output, use
 216                                 <command>show-session</command>
 217                                 instead.</para></listitem>
 218                         </varlistentry>
 219
 220                         <varlistentry>
 221                                 <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
 222
 223                                 <listitem><para>Show properties of one
 224                                 or more sessions or the manager
 225                                 itself. If no argument is specified,
 226                                 properties of the manager will be
 227                                 shown. If a session ID is specified,
 228                                 properties of the session are shown. By
 229                                 default, empty properties are
 230                                 suppressed. Use <option>--all</option>
 231                                 to show those too. To select specific
 232                                 properties to show, use
 233                                 <option>--property=</option>. This
 234                                 command is intended to be used
 235                                 whenever computer-parsable output is
 236                                 required. Use
 237                                 <command>session-status</command> if
 238                                 you are looking for formatted
 239                                 human-readable
 240                                 output.</para></listitem>
 241                         </varlistentry>
 242
 243                         <varlistentry>
 244                                 <term><command>activate</command> <optional><replaceable>ID</replaceable></optional></term>
 245
 246                                 <listitem><para>Activate a
 247                                 session. This brings a session into
 248                                 the foreground, if another session is
 249                                 currently in the foreground on the
 250                                 respective seat. Takes a session
 251                                 identifier as argument. If no argument
 252                                 is specified the session of the caller
 253                                 is put into
 254                                 foreground.</para></listitem>
 255                         </varlistentry>
 256
 257                         <varlistentry>
 258                                 <term><command>lock-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
 259                                 <term><command>unlock-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
 260
 261                                 <listitem><para>Activates/deactivates
 262                                 the screen lock on one or more
 263                                 sessions, if the session supports
 264                                 it. Takes one or more session
 265                                 identifiers as arguments. If no
 266                                 argument is specified the session of
 267                                 the caller is locked/unlocked.
 268                                 </para></listitem>
 269                         </varlistentry>
 270
 271                         <varlistentry>
 272                                 <term><command>lock-sessions</command></term>
 273                                 <term><command>unlock-sessions</command></term>
 274
 275                                 <listitem><para>Activates/deactivates
 276                                 the screen lock on all current
 277                                 sessions supporting it.
 278                                 </para></listitem>
 279                         </varlistentry>
 280
 281                         <varlistentry>
 282                                 <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term>
 283
 284                                 <listitem><para>Terminates a session.
 285                                 This kills all processes of the
 286                                 session and deallocates all resources
 287                                 attached to the session.
 288                                 </para></listitem>
 289                         </varlistentry>
 290
 291                         <varlistentry>
 292                                 <term><command>kill-session</command> <replaceable>ID</replaceable>...</term>
 293
 294                                 <listitem><para>Send a signal to one
 295                                 or more processes of the session. Use
 296                                 <option>--kill-who=</option> to select
 297                                 which process to kill. Use
 298                                 <option>--signal=</option> to select
 299                                 the signal to send.</para></listitem>
 300                         </varlistentry>
 301                 </variablelist></refsect2>
 302
 303                 <refsect2><title>User Commands</title><variablelist>
 304                         <varlistentry>
 305                                 <term><command>list-users</command></term>
 306
 307                                 <listitem><para>List currently logged
 308                                 in users.</para></listitem>
 309                         </varlistentry>
 310
 311                         <varlistentry>
 312                                 <term><command>user-status</command> <optional><replaceable>USER</replaceable>...</optional></term>
 313
 314                                 <listitem><para>Show terse runtime
 315                                 status information about one or more
 316                                 logged in users, followed by the most
 317                                 recent log data from the
 318                                 journal. Takes one or more user names
 319                                 or numeric user IDs as parameters. If
 320                                 no parameters are passed the status of
 321                                 the caller's user is shown. This
 322                                 function is intended to generate
 323                                 human-readable output. If you are
 324                                 looking for computer-parsable output,
 325                                 use <command>show-user</command>
 326                                 instead.  Users may be specified by
 327                                 their usernames or numeric user IDs.
 328                                 </para></listitem>
 329                         </varlistentry>
 330
 331                         <varlistentry>
 332                                 <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term>
 333
 334                                 <listitem><para>Show properties of one
 335                                 or more users or the manager
 336                                 itself. If no argument is specified,
 337                                 properties of the manager will be
 338                                 shown. If a user is specified,
 339                                 properties of the user are shown. By
 340                                 default, empty properties are
 341                                 suppressed. Use <option>--all</option>
 342                                 to show those too. To select specific
 343                                 properties to show, use
 344                                 <option>--property=</option>. This
 345                                 command is intended to be used
 346                                 whenever computer-parsable output is
 347                                 required. Use
 348                                 <command>user-status</command> if
 349                                 you are looking for formatted
 350                                 human-readable
 351                                 output.</para></listitem>
 352                         </varlistentry>
 353
 354                         <varlistentry>
 355                                 <term><command>enable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term>
 356                                 <term><command>disable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term>
 357
 358                                 <listitem><para>Enable/disable user
 359                                 lingering for one or more users. If
 360                                 enabled for a specific user, a user
 361                                 manager is spawned for the user at
 362                                 boot and kept around after
 363                                 logouts. This allows users who are not
 364                                 logged in to run long-running
 365                                 services. Takes one or more user names
 366                                 or numeric UIDs as argument. If no
 367                                 argument is specified enables/disables
 368                                 lingering for the user of the session
 369                                 of the caller.</para></listitem>
 370                         </varlistentry>
 371
 372                         <varlistentry>
 373                                 <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term>
 374
 375                                 <listitem><para>Terminates all
 376                                 sessions of a user. This kills all
 377                                 processes of all sessions of the user
 378                                 and deallocates all runtime resources
 379                                 attached to the user.
 380                                 </para></listitem>
 381                         </varlistentry>
 382
 383                         <varlistentry>
 384                                 <term><command>kill-user</command> <replaceable>USER</replaceable>...</term>
 385
 386                                 <listitem><para>Send a signal to all
 387                                 processes of a user. Use
 388                                 <option>--signal=</option> to select
 389                                 the signal to send.</para></listitem>
 390                         </varlistentry>
 391                 </variablelist></refsect2>
 392
 393                 <refsect2><title>Seat Commands</title><variablelist>
 394                         <varlistentry>
 395                                 <term><command>list-seats</command></term>
 396
 397                                 <listitem><para>List currently
 398                                 available seats on the local
 399                                 system.</para></listitem>
 400                         </varlistentry>
 401
 402                         <varlistentry>
 403                                 <term><command>seat-status</command> <optional><replaceable>NAME</replaceable>...</optional></term>
 404
 405                                 <listitem><para>Show terse runtime
 406                                 status information about one or more
 407                                 seats. Takes one or more seat names as
 408                                 parameters. If no seat names are
 409                                 passed the status of the caller's
 410                                 session's seat is shown. This function
 411                                 is intended to generate human-readable
 412                                 output. If you are looking for
 413                                 computer-parsable output, use
 414                                 <command>show-seat</command>
 415                                 instead.</para></listitem>
 416                         </varlistentry>
 417
 418                         <varlistentry>
 419                                 <term><command>show-seat</command> <optional><replaceable>NAME</replaceable>...</optional></term>
 420
 421                                 <listitem><para>Show properties of one
 422                                 or more seats or the manager
 423                                 itself. If no argument is specified,
 424                                 properties of the manager will be
 425                                 shown. If a seat is specified,
 426                                 properties of the seat are shown. By
 427                                 default, empty properties are
 428                                 suppressed. Use <option>--all</option>
 429                                 to show those too. To select specific
 430                                 properties to show, use
 431                                 <option>--property=</option>. This
 432                                 command is intended to be used
 433                                 whenever computer-parsable output is
 434                                 required. Use
 435                                 <command>seat-status</command> if you
 436                                 are looking for formatted
 437                                 human-readable
 438                                 output.</para></listitem>
 439                         </varlistentry>
 440
 441                         <varlistentry>
 442                                 <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term>
 443
 444                                 <listitem><para>Persistently attach
 445                                 one or more devices to a seat. The
 446                                 devices should be specified via device
 447                                 paths in the <filename>/sys</filename>
 448                                 file system. To create a new seat,
 449                                 attach at least one graphics card to a
 450                                 previously unused seat name. Seat
 451                                 names may consist only of a-z, A-Z,
 452                                 0-9, <literal>-</literal> and
 453                                 <literal>_</literal> and must be
 454                                 prefixed with <literal>seat</literal>.
 455                                 To drop assignment of a device to a
 456                                 specific seat, just reassign it to a
 457                                 different seat, or use
 458                                 <command>flush-devices</command>.
 459                                 </para></listitem>
 460                         </varlistentry>
 461
 462                         <varlistentry>
 463                                 <term><command>flush-devices</command></term>
 464
 465                                 <listitem><para>Removes all device
 466                                 assignments previously created with
 467                                 <command>attach</command>. After this
 468                                 call, only automatically generated
 469                                 seats will remain, and all seat
 470                                 hardware is assigned to
 471                                 them.</para></listitem>
 472                         </varlistentry>
 473
 474                         <varlistentry>
 475                                 <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term>
 476
 477                                 <listitem><para>Terminates all
 478                                 sessions on a seat. This kills all
 479                                 processes of all sessions on the seat
 480                                 and deallocates all runtime resources
 481                                 attached to them.</para></listitem>
 482                         </varlistentry>
 483                 </variablelist></refsect2>
 484
 485         </refsect1>
 486
 487         <refsect1>
 488                 <title>Exit status</title>
 489
 490                 <para>On success, 0 is returned, a non-zero failure
 491                 code otherwise.</para>
 492         </refsect1>
 493
 494         <xi:include href="less-variables.xml" />
 495
 496         <refsect1>
 497                 <title>See Also</title>
 498                 <para>
 499                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 500                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 501                         <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 502                         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 503                 </para>
 504         </refsect1>
 505
 506 </refentry>