loginctl.xml 22.2 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

24 25
<refentry id="loginctl" conditional='ENABLE_LOGIND'
          xmlns:xi="http://www.w3.org/2001/XInclude">
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52

        <refentryinfo>
                <title>loginctl</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>loginctl</refentrytitle>
                <manvolnum>1</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>loginctl</refname>
                <refpurpose>Control the systemd login manager</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <cmdsynopsis>
53 54 55 56
                        <command>loginctl</command>
                        <arg choice="opt" rep="repeat">OPTIONS</arg>
                        <arg choice="req">COMMAND</arg>
                        <arg choice="opt" rep="repeat">NAME</arg>
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
                </cmdsynopsis>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para><command>loginctl</command> may be used to
                introspect and control the state of the
                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                login manager <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
        </refsect1>

        <refsect1>
                <title>Options</title>

                <para>The following options are understood:</para>

                <variablelist>
                        <varlistentry>
76
                                <term><option>--no-legend</option></term>
77

78 79 80 81 82
                                <listitem>
                                        <para>Do not print the legend,
                                        i.e. the column headers and
                                        the footer.</para>
                                </listitem>
83 84 85
                        </varlistentry>

                        <varlistentry>
86
                                <term><option>--no-ask-password</option></term>
87

88 89 90
                                <listitem><para>Do not query the user
                                for authentication for privileged
                                operations.</para></listitem>
91 92 93 94 95 96 97
                        </varlistentry>

                        <varlistentry>
                                <term><option>-p</option></term>
                                <term><option>--property=</option></term>

                                <listitem><para>When showing
98
                                session/user/seat properties, limit
99 100
                                display to certain properties as
                                specified as argument. If not
101
                                specified, all set properties are
102 103 104
                                shown. The argument should be a
                                property name, such as
                                <literal>Sessions</literal>. If
105
                                specified more than once, all
106 107 108 109 110 111 112 113 114
                                properties with the specified names
                                are shown.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-a</option></term>
                                <term><option>--all</option></term>

                                <listitem><para>When showing
115
                                session/user/seat properties, show all
116
                                properties regardless of whether they are
117 118 119 120
                                set or not.</para></listitem>
                        </varlistentry>

                        <varlistentry>
121
                                <term><option>-l</option></term>
122 123
                                <term><option>--full</option></term>

124 125
                                <listitem><para>Do not ellipsize
                                process tree entries.</para>
126 127 128 129 130 131 132 133 134 135 136 137 138
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--kill-who=</option></term>

                                <listitem><para>When used with
                                <command>kill-session</command>,
                                choose which processes to kill. Must
                                be one of <option>leader</option>, or
                                <option>all</option> to select whether
                                to kill only the leader process of the
                                session or all processes of the
139
                                session. If omitted, defaults to
140 141 142 143 144 145 146 147 148 149 150 151
                                <option>all</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-s</option></term>
                                <term><option>--signal=</option></term>

                                <listitem><para>When used with
                                <command>kill-session</command> or
                                <command>kill-user</command>, choose
                                which signal to send to selected
                                processes. Must be one of the well
152 153 154 155 156 157
                                known signal specifiers, such as
                                <constant>SIGTERM</constant>,
                                <constant>SIGINT</constant> or
                                <constant>SIGSTOP</constant>. If
                                omitted, defaults to
                                <constant>SIGTERM</constant>.</para></listitem>
158 159
                        </varlistentry>

160 161
                        <xi:include href="user-system-options.xml" xpointer="host" />
                        <xi:include href="user-system-options.xml" xpointer="machine" />
162

163 164 165
                        <xi:include href="standard-options.xml" xpointer="help" />
                        <xi:include href="standard-options.xml" xpointer="version" />
                        <xi:include href="standard-options.xml" xpointer="no-pager" />
166 167 168 169 170 171 172 173 174 175 176 177
                </variablelist>

                <para>The following commands are understood:</para>

                <variablelist>
                        <varlistentry>
                                <term><command>list-sessions</command></term>

                                <listitem><para>List current sessions.</para></listitem>
                        </varlistentry>

                        <varlistentry>
178
                                <term><command>session-status</command> <replaceable>ID</replaceable>...</term>
179 180 181 182 183 184 185 186 187 188 189 190

                                <listitem><para>Show terse runtime
                                status information about one or more
                                sessions. This function is intended to
                                generate human-readable output. If you
                                are looking for computer-parsable
                                output, use
                                <command>show-session</command>
                                instead.</para></listitem>
                        </varlistentry>

                        <varlistentry>
191
                                <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
192 193 194

                                <listitem><para>Show properties of one
                                or more sessions or the manager
195
                                itself. If no argument is specified,
196
                                properties of the manager will be
197 198
                                shown. If a session ID is specified,
                                properties of the session are shown. By
199 200 201
                                default, empty properties are
                                suppressed. Use <option>--all</option>
                                to show those too. To select specific
202
                                properties to show, use
203 204 205 206 207 208 209 210 211 212 213
                                <option>--property=</option>. This
                                command is intended to be used
                                whenever computer-parsable output is
                                required. Use
                                <command>session-status</command> if
                                you are looking for formatted
                                human-readable
                                output.</para></listitem>
                        </varlistentry>

                        <varlistentry>
214
                                <term><command>activate</command> <replaceable>ID</replaceable>...</term>
215 216 217 218 219 220 221 222 223 224

                                <listitem><para>Activate one or more
                                sessions. This brings one or more
                                sessions into the foreground, if
                                another session is currently in the
                                foreground on the respective
                                seat.</para></listitem>
                        </varlistentry>

                        <varlistentry>
225 226
                                <term><command>lock-session</command> <replaceable>ID</replaceable>...</term>
                                <term><command>unlock-session</command> <replaceable>ID</replaceable>...</term>
227 228 229

                                <listitem><para>Activates/deactivates
                                the screen lock on one or more
230 231
                                sessions, if the session supports it.
                                </para></listitem>
232 233 234 235 236 237 238 239
                        </varlistentry>

                        <varlistentry>
                                <term><command>lock-sessions</command></term>
                                <term><command>unlock-sessions</command></term>

                                <listitem><para>Activates/deactivates
                                the screen lock on all current
240 241
                                sessions supporting it.
                                </para></listitem>
242 243 244
                        </varlistentry>

                        <varlistentry>
245
                                <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term>
246

247 248 249 250 251
                                <listitem><para>Terminates a session.
                                This kills all processes of the
                                session and deallocates all resources
                                attached to the session.
                                </para></listitem>
252 253 254
                        </varlistentry>

                        <varlistentry>
255
                                <term><command>kill-session</command> <replaceable>ID</replaceable>...</term>
256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272

                                <listitem><para>Send a signal to one
                                or more processes of the session. Use
                                <option>--kill-who=</option> to select
                                which process to kill. Use
                                <option>--signal=</option> to select
                                the signal to send.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>list-users</command></term>

                                <listitem><para>List currently logged
                                in users.</para></listitem>
                        </varlistentry>

                        <varlistentry>
273
                                <term><command>user-status</command> <replaceable>USER</replaceable>...</term>
274 275 276 277 278 279 280

                                <listitem><para>Show terse runtime
                                status information about one or more
                                logged in users. This function is
                                intended to generate human-readable
                                output. If you are looking for
                                computer-parsable output, use
281 282 283 284
                                <command>show-user</command> instead.
                                Users may be specified by their
                                usernames or numeric user IDs.
                                </para></listitem>
285 286 287
                        </varlistentry>

                        <varlistentry>
288
                                <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term>
289 290 291

                                <listitem><para>Show properties of one
                                or more users or the manager
292
                                itself. If no argument is specified,
293
                                properties of the manager will be
294 295
                                shown. If a user is specified,
                                properties of the user are shown. By
296 297 298
                                default, empty properties are
                                suppressed. Use <option>--all</option>
                                to show those too. To select specific
299
                                properties to show, use
300 301 302 303 304 305 306 307 308 309 310
                                <option>--property=</option>. This
                                command is intended to be used
                                whenever computer-parsable output is
                                required. Use
                                <command>user-status</command> if
                                you are looking for formatted
                                human-readable
                                output.</para></listitem>
                        </varlistentry>

                        <varlistentry>
311 312
                                <term><command>enable-linger</command> <replaceable>USER</replaceable>...</term>
                                <term><command>disable-linger</command> <replaceable>USER</replaceable>...</term>
313 314 315

                                <listitem><para>Enable/disable user
                                lingering for one or more users. If
316
                                enabled for a specific user, a user
317
                                manager is spawned for the user at
318 319
                                boot and kept around after
                                logouts. This allows users who are not
320 321 322 323 324
                                logged in to run long-running
                                services.</para></listitem>
                        </varlistentry>

                        <varlistentry>
325
                                <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term>
326 327 328 329 330

                                <listitem><para>Terminates all
                                sessions of a user. This kills all
                                processes of all sessions of the user
                                and deallocates all runtime resources
331 332
                                attached to the user.
                                </para></listitem>
333 334 335
                        </varlistentry>

                        <varlistentry>
336
                                <term><command>kill-user</command> <replaceable>USER</replaceable>...</term>
337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352

                                <listitem><para>Send a signal to all
                                processes of a user. Use
                                <option>--signal=</option> to select
                                the signal to send.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>list-seats</command></term>

                                <listitem><para>List currently
                                available seats on the local
                                system.</para></listitem>
                        </varlistentry>

                        <varlistentry>
353
                                <term><command>seat-status</command> <replaceable>NAME</replaceable>...</term>
354 355 356 357 358 359 360 361 362 363 364 365

                                <listitem><para>Show terse runtime
                                status information about one or more
                                seats. This function is
                                intended to generate human-readable
                                output. If you are looking for
                                computer-parsable output, use
                                <command>show-seat</command>
                                instead.</para></listitem>
                        </varlistentry>

                        <varlistentry>
366
                                <term><command>show-seat</command> <replaceable>NAME</replaceable>...</term>
367 368 369

                                <listitem><para>Show properties of one
                                or more seats or the manager
370
                                itself. If no argument is specified,
371
                                properties of the manager will be
372
                                shown. If a seat is specified,
373 374 375 376
                                properties of the seat are shown. By
                                default, empty properties are
                                suppressed. Use <option>--all</option>
                                to show those too. To select specific
377
                                properties to show, use
378 379 380 381 382 383 384 385 386 387 388
                                <option>--property=</option>. This
                                command is intended to be used
                                whenever computer-parsable output is
                                required. Use
                                <command>seat-status</command> if you
                                are looking for formatted
                                human-readable
                                output.</para></listitem>
                        </varlistentry>

                        <varlistentry>
389
                                <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term>
390 391 392 393 394

                                <listitem><para>Persistently attach
                                one or more devices to a seat. The
                                devices should be specified via device
                                paths in the <filename>/sys</filename>
395
                                file system. To create a new seat,
396 397 398
                                attach at least one graphics card to a
                                previously unused seat name. Seat
                                names may consist only of a-z, A-Z,
399 400 401 402 403 404 405 406
                                0-9, <literal>-</literal> and
                                <literal>_</literal> and must be
                                prefixed with <literal>seat</literal>.
                                To drop assignment of a device to a
                                specific seat, just reassign it to a
                                different seat, or use
                                <command>flush-devices</command>.
                                </para></listitem>
407 408 409 410 411 412 413 414
                        </varlistentry>

                        <varlistentry>
                                <term><command>flush-devices</command></term>

                                <listitem><para>Removes all device
                                assignments previously created with
                                <command>attach</command>. After this
415 416
                                call, only automatically generated
                                seats will remain, and all seat
417 418 419 420 421
                                hardware is assigned to
                                them.</para></listitem>
                        </varlistentry>

                        <varlistentry>
422
                                <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term>
423 424 425

                                <listitem><para>Terminates all
                                sessions on a seat. This kills all
426 427
                                processes of all sessions on the seat
                                and deallocates all runtime resources
428 429 430 431 432 433 434 435 436
                                attached to them.</para></listitem>
                        </varlistentry>
                </variablelist>

        </refsect1>

        <refsect1>
                <title>Exit status</title>

437
                <para>On success, 0 is returned, a non-zero failure
438 439 440
                code otherwise.</para>
        </refsect1>

441
        <xi:include href="less-variables.xml" />
442 443 444 445 446 447 448 449 450 451 452 453

        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>