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