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