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>-h</option></term>
  77                                 <term><option>--help</option></term>
  78
  79                                 <listitem><para>Prints a short help
  80                                 text and exits.</para></listitem>
  81                         </varlistentry>
  82
  83                         <varlistentry>
  84                                 <term><option>--version</option></term>
  85
  86                                 <listitem><para>Prints a short version
  87                                 string and exits.</para></listitem>
  88                         </varlistentry>
  89
  90                         <varlistentry>
  91                                 <term><option>--no-pager</option></term>
  92
  93                                 <listitem><para>Do not pipe output into a
  94                                 pager.</para></listitem>
  95                         </varlistentry>
  96
  97                         <varlistentry>
  98                                 <term><option>--no-legend</option></term>
  99
 100                                 <listitem>
 101                                         <para>Do not print the legend,
 102                                         i.e. the column headers and
 103                                         the footer.</para>
 104                                 </listitem>
 105                         </varlistentry>
 106
 107                         <varlistentry>
 108                                 <term><option>--no-ask-password</option></term>
 109
 110                                 <listitem><para>Do not query the user
 111                                 for authentication for privileged
 112                                 operations.</para></listitem>
 113                         </varlistentry>
 114
 115                         <varlistentry>
 116                                 <term><option>-H</option></term>
 117                                 <term><option>--host</option></term>
 118
 119                                 <listitem><para>Execute the operation
 120                                 remotely. Specify a hostname, or
 121                                 username and hostname separated by <literal>@</literal>,
 122                                 to connect to. This will use SSH to
 123                                 talk to the remote login manager
 124                                 instance.</para></listitem>
 125                         </varlistentry>
 126
 127                         <varlistentry>
 128                                 <term><option>-M</option></term>
 129                                 <term><option>--machine=</option></term>
 130
 131                                 <listitem><para>Execute the operation on a
 132                                 local container. Specify a container
 133                                 name to connect to.</para></listitem>
 134                         </varlistentry>
 135
 136                         <varlistentry>
 137                                 <term><option>-p</option></term>
 138                                 <term><option>--property=</option></term>
 139
 140                                 <listitem><para>When showing
 141                                 session/user/seat properties, limit
 142                                 display to certain properties as
 143                                 specified as argument. If not
 144                                 specified, all set properties are
 145                                 shown. The argument should be a
 146                                 property name, such as
 147                                 <literal>Sessions</literal>. If
 148                                 specified more than once, all
 149                                 properties with the specified names
 150                                 are shown.</para></listitem>
 151                         </varlistentry>
 152
 153                         <varlistentry>
 154                                 <term><option>-a</option></term>
 155                                 <term><option>--all</option></term>
 156
 157                                 <listitem><para>When showing
 158                                 session/user/seat properties, show all
 159                                 properties regardless of whether they are
 160                                 set or not.</para></listitem>
 161                         </varlistentry>
 162
 163                         <varlistentry>
 164                                 <term><option>-l</option></term>
 165                                 <term><option>--full</option></term>
 166
 167                                 <listitem><para>Do not ellipsize
 168                                 process tree entries.</para>
 169                                 </listitem>
 170                         </varlistentry>
 171
 172                         <varlistentry>
 173                                 <term><option>--kill-who=</option></term>
 174
 175                                 <listitem><para>When used with
 176                                 <command>kill-session</command>,
 177                                 choose which processes to kill. Must
 178                                 be one of <option>leader</option>, or
 179                                 <option>all</option> to select whether
 180                                 to kill only the leader process of the
 181                                 session or all processes of the
 182                                 session. If omitted, defaults to
 183                                 <option>all</option>.</para></listitem>
 184                         </varlistentry>
 185
 186                         <varlistentry>
 187                                 <term><option>-s</option></term>
 188                                 <term><option>--signal=</option></term>
 189
 190                                 <listitem><para>When used with
 191                                 <command>kill-session</command> or
 192                                 <command>kill-user</command>, choose
 193                                 which signal to send to selected
 194                                 processes. Must be one of the well
 195                                 known signal specifiers, such as
 196                                 <constant>SIGTERM</constant>,
 197                                 <constant>SIGINT</constant> or
 198                                 <constant>SIGSTOP</constant>. If
 199                                 omitted, defaults to
 200                                 <constant>SIGTERM</constant>.</para></listitem>
 201                         </varlistentry>
 202
 203                 </variablelist>
 204
 205                 <para>The following commands are understood:</para>
 206
 207                 <variablelist>
 208                         <varlistentry>
 209                                 <term><command>list-sessions</command></term>
 210
 211                                 <listitem><para>List current sessions.</para></listitem>
 212                         </varlistentry>
 213
 214                         <varlistentry>
 215                                 <term><command>session-status</command> <replaceable>ID</replaceable>...</term>
 216
 217                                 <listitem><para>Show terse runtime
 218                                 status information about one or more
 219                                 sessions. This function is intended to
 220                                 generate human-readable output. If you
 221                                 are looking for computer-parsable
 222                                 output, use
 223                                 <command>show-session</command>
 224                                 instead.</para></listitem>
 225                         </varlistentry>
 226
 227                         <varlistentry>
 228                                 <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
 229
 230                                 <listitem><para>Show properties of one
 231                                 or more sessions or the manager
 232                                 itself. If no argument is specified,
 233                                 properties of the manager will be
 234                                 shown. If a session ID is specified,
 235                                 properties of the session are shown. By
 236                                 default, empty properties are
 237                                 suppressed. Use <option>--all</option>
 238                                 to show those too. To select specific
 239                                 properties to show, use
 240                                 <option>--property=</option>. This
 241                                 command is intended to be used
 242                                 whenever computer-parsable output is
 243                                 required. Use
 244                                 <command>session-status</command> if
 245                                 you are looking for formatted
 246                                 human-readable
 247                                 output.</para></listitem>
 248                         </varlistentry>
 249
 250                         <varlistentry>
 251                                 <term><command>activate</command> <replaceable>ID</replaceable>...</term>
 252
 253                                 <listitem><para>Activate one or more
 254                                 sessions. This brings one or more
 255                                 sessions into the foreground, if
 256                                 another session is currently in the
 257                                 foreground on the respective
 258                                 seat.</para></listitem>
 259                         </varlistentry>
 260
 261                         <varlistentry>
 262                                 <term><command>lock-session</command> <replaceable>ID</replaceable>...</term>
 263                                 <term><command>unlock-session</command> <replaceable>ID</replaceable>...</term>
 264
 265                                 <listitem><para>Activates/deactivates
 266                                 the screen lock on one or more
 267                                 sessions, if the session supports it.
 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
 302                         <varlistentry>
 303                                 <term><command>list-users</command></term>
 304
 305                                 <listitem><para>List currently logged
 306                                 in users.</para></listitem>
 307                         </varlistentry>
 308
 309                         <varlistentry>
 310                                 <term><command>user-status</command> <replaceable>USER</replaceable>...</term>
 311
 312                                 <listitem><para>Show terse runtime
 313                                 status information about one or more
 314                                 logged in users. This function is
 315                                 intended to generate human-readable
 316                                 output. If you are looking for
 317                                 computer-parsable output, use
 318                                 <command>show-user</command> instead.
 319                                 Users may be specified by their
 320                                 usernames or numeric user IDs.
 321                                 </para></listitem>
 322                         </varlistentry>
 323
 324                         <varlistentry>
 325                                 <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term>
 326
 327                                 <listitem><para>Show properties of one
 328                                 or more users or the manager
 329                                 itself. If no argument is specified,
 330                                 properties of the manager will be
 331                                 shown. If a user is specified,
 332                                 properties of the user are shown. By
 333                                 default, empty properties are
 334                                 suppressed. Use <option>--all</option>
 335                                 to show those too. To select specific
 336                                 properties to show, use
 337                                 <option>--property=</option>. This
 338                                 command is intended to be used
 339                                 whenever computer-parsable output is
 340                                 required. Use
 341                                 <command>user-status</command> if
 342                                 you are looking for formatted
 343                                 human-readable
 344                                 output.</para></listitem>
 345                         </varlistentry>
 346
 347                         <varlistentry>
 348                                 <term><command>enable-linger</command> <replaceable>USER</replaceable>...</term>
 349                                 <term><command>disable-linger</command> <replaceable>USER</replaceable>...</term>
 350
 351                                 <listitem><para>Enable/disable user
 352                                 lingering for one or more users. If
 353                                 enabled for a specific user, a user
 354                                 manager is spawned for the user at
 355                                 boot and kept around after
 356                                 logouts. This allows users who are not
 357                                 logged in to run long-running
 358                                 services.</para></listitem>
 359                         </varlistentry>
 360
 361                         <varlistentry>
 362                                 <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term>
 363
 364                                 <listitem><para>Terminates all
 365                                 sessions of a user. This kills all
 366                                 processes of all sessions of the user
 367                                 and deallocates all runtime resources
 368                                 attached to the user.
 369                                 </para></listitem>
 370                         </varlistentry>
 371
 372                         <varlistentry>
 373                                 <term><command>kill-user</command> <replaceable>USER</replaceable>...</term>
 374
 375                                 <listitem><para>Send a signal to all
 376                                 processes of a user. Use
 377                                 <option>--signal=</option> to select
 378                                 the signal to send.</para></listitem>
 379                         </varlistentry>
 380
 381                         <varlistentry>
 382                                 <term><command>list-seats</command></term>
 383
 384                                 <listitem><para>List currently
 385                                 available seats on the local
 386                                 system.</para></listitem>
 387                         </varlistentry>
 388
 389                         <varlistentry>
 390                                 <term><command>seat-status</command> <replaceable>NAME</replaceable>...</term>
 391
 392                                 <listitem><para>Show terse runtime
 393                                 status information about one or more
 394                                 seats. This function is
 395                                 intended to generate human-readable
 396                                 output. If you are looking for
 397                                 computer-parsable output, use
 398                                 <command>show-seat</command>
 399                                 instead.</para></listitem>
 400                         </varlistentry>
 401
 402                         <varlistentry>
 403                                 <term><command>show-seat</command> <replaceable>NAME</replaceable>...</term>
 404
 405                                 <listitem><para>Show properties of one
 406                                 or more seats or the manager
 407                                 itself. If no argument is specified,
 408                                 properties of the manager will be
 409                                 shown. If a seat is specified,
 410                                 properties of the seat are shown. By
 411                                 default, empty properties are
 412                                 suppressed. Use <option>--all</option>
 413                                 to show those too. To select specific
 414                                 properties to show, use
 415                                 <option>--property=</option>. This
 416                                 command is intended to be used
 417                                 whenever computer-parsable output is
 418                                 required. Use
 419                                 <command>seat-status</command> if you
 420                                 are looking for formatted
 421                                 human-readable
 422                                 output.</para></listitem>
 423                         </varlistentry>
 424
 425                         <varlistentry>
 426                                 <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term>
 427
 428                                 <listitem><para>Persistently attach
 429                                 one or more devices to a seat. The
 430                                 devices should be specified via device
 431                                 paths in the <filename>/sys</filename>
 432                                 file system. To create a new seat,
 433                                 attach at least one graphics card to a
 434                                 previously unused seat name. Seat
 435                                 names may consist only of a-z, A-Z,
 436                                 0-9, <literal>-</literal> and
 437                                 <literal>_</literal> and must be
 438                                 prefixed with <literal>seat</literal>.
 439                                 To drop assignment of a device to a
 440                                 specific seat, just reassign it to a
 441                                 different seat, or use
 442                                 <command>flush-devices</command>.
 443                                 </para></listitem>
 444                         </varlistentry>
 445
 446                         <varlistentry>
 447                                 <term><command>flush-devices</command></term>
 448
 449                                 <listitem><para>Removes all device
 450                                 assignments previously created with
 451                                 <command>attach</command>. After this
 452                                 call, only automatically generated
 453                                 seats will remain, and all seat
 454                                 hardware is assigned to
 455                                 them.</para></listitem>
 456                         </varlistentry>
 457
 458                         <varlistentry>
 459                                 <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term>
 460
 461                                 <listitem><para>Terminates all
 462                                 sessions on a seat. This kills all
 463                                 processes of all sessions on the seat
 464                                 and deallocates all runtime resources
 465                                 attached to them.</para></listitem>
 466                         </varlistentry>
 467                 </variablelist>
 468
 469         </refsect1>
 470
 471         <refsect1>
 472                 <title>Exit status</title>
 473
 474                 <para>On success, 0 is returned, a non-zero failure
 475                 code otherwise.</para>
 476         </refsect1>
 477
 478         <xi:include href="less-variables.xml" />
 479
 480         <refsect1>
 481                 <title>See Also</title>
 482                 <para>
 483                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 484                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 485                         <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 486                         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 487                 </para>
 488         </refsect1>
 489
 490 </refentry>