summaryrefslogtreecommitdiff
path: root/man/loginctl.xml
blob: 790a3e4bf8360975ff4cae8ad048b5d74d900d80 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
<?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/>.
-->

<refentry id="loginctl" conditional='HAVE_PAM'>

        <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>
                        <command>loginctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
                </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>
                                <term><option>-h</option></term>
                                <term><option>--help</option></term>

                                <listitem><para>Prints a short help
                                text and exits.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--version</option></term>

                                <listitem><para>Prints a short version
                                string and exits.</para></listitem>
                        </varlistentry>

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

                                <listitem><para>When showing
                                session/user properties, limit
                                display to certain properties as
                                specified as argument. If not
                                specified all set properties are
                                shown. The argument should be a
                                property name, such as
                                <literal>Sessions</literal>. If
                                specified more than once all
                                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
                                unit/job/manager properties, show all
                                properties regardless whether they are
                                set or not.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-l</option></term>
                                <term><option>--full</option></term>

                                <listitem><para>Do not ellipsize cgroup
                                members.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--no-pager</option></term>

                                <listitem><para>Do not pipe output into a
                                pager.</para></listitem>
                        </varlistentry>

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

                                <listitem><para>Don't query the user
                                for authentication for privileged
                                operations.</para></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
                                session. If omitted, defaults to
                                <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
                                known signal specifiers, such as
                                <constant>SIGTERM</constant>,
                                <constant>SIGINT</constant> or
                                <constant>SIGSTOP</constant>. If
                                omitted defaults to
                                <constant>SIGTERM</constant>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-H</option></term>
                                <term><option>--host</option></term>

                                <listitem><para>Execute operation
                                remotely. Specify a hostname, or
                                username and hostname separated by <literal>@</literal>,
                                to connect to. This will use SSH to
                                talk to the remote login manager
                                instance.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-P</option></term>
                                <term><option>--privileged</option></term>

                                <listitem><para>Acquire privileges via
                                PolicyKit before executing the
                                operation.</para></listitem>
                        </varlistentry>
                </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>
                                <term><command>session-status [ID...]</command></term>

                                <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>
                                <term><command>show-session [ID...]</command></term>

                                <listitem><para>Show properties of one
                                or more sessions or the manager
                                itself. If no argument is specified
                                properties of the manager will be
                                shown. If a session ID is specified
                                properties of the session is shown. By
                                default, empty properties are
                                suppressed. Use <option>--all</option>
                                to show those too. To select specific
                                properties to show use
                                <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>
                                <term><command>activate [ID...]</command></term>

                                <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>
                                <term><command>lock-session [ID...]</command></term>
                                <term><command>unlock-session [ID...]</command></term>

                                <listitem><para>Activates/deactivates
                                the screen lock on one or more
                                sessions, if the session supports it.</para></listitem>
                        </varlistentry>

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

                                <listitem><para>Activates/deactivates
                                the screen lock on all current
                                sessions supporting
                                it.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>terminate-session [ID...]</command></term>

                                <listitem><para>Terminates a
                                session. This kills all processes of
                                the session and deallocates all
                                resources attached to the
                                session.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>kill-session [ID...]</command></term>

                                <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>
                                <term><command>user-status [USER...]</command></term>

                                <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
                                <command>show-user</command>
                                instead. Users may be specified by
                                their usernames or numeric user
                                IDs.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>show-user [USER...]</command></term>

                                <listitem><para>Show properties of one
                                or more users or the manager
                                itself. If no argument is specified,
                                properties of the manager will be
                                shown. If a user is specified,
                                properties of the user are shown. By
                                default, empty properties are
                                suppressed. Use <option>--all</option>
                                to show those too. To select specific
                                properties to show use
                                <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>
                                <term><command>enable-linger [USER...]</command></term>
                                <term><command>disable-linger [USER...]</command></term>

                                <listitem><para>Enable/disable user
                                lingering for one or more users. If
                                enabled for a specific user, a user
                                manager is spawned for him/her at
                                boot and kept around after
                                logouts. This allows users who aren't
                                logged in to run long-running
                                services.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>terminate-user [USER...]</command></term>

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

                        <varlistentry>
                                <term><command>kill-user [USER...]</command></term>

                                <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>
                                <term><command>seat-status [NAME...]</command></term>

                                <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>
                                <term><command>show-seat [NAME...]</command></term>

                                <listitem><para>Show properties of one
                                or more seats or the manager
                                itself. If no argument is specified,
                                properties of the manager will be
                                shown. If a seat is specified,
                                properties of the seat are shown. By
                                default, empty properties are
                                suppressed. Use <option>--all</option>
                                to show those too. To select specific
                                properties to show, use
                                <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>
                                <term><command>attach [NAME] [DEVICE...]</command></term>

                                <listitem><para>Persistently attach
                                one or more devices to a seat. The
                                devices should be specified via device
                                paths in the <filename>/sys</filename>
                                file system. To create a new seat,
                                attach at least one graphics card to a
                                previously unused seat name. Seat
                                names may consist only of a-z, A-Z,
                                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>
                        </varlistentry>

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

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

                        <varlistentry>
                                <term><command>terminate-seat [NAME...]</command></term>

                                <listitem><para>Terminates all
                                sessions on a seat. This kills all
                                processes of all sessions on a seat and
                                deallocates all runtime resources
                                attached to them.</para></listitem>
                        </varlistentry>
                </variablelist>

        </refsect1>

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

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

        <refsect1>
                <title>Environment</title>

                <variablelist class='environment-variables'>
                        <varlistentry>
                                <term><varname>$SYSTEMD_PAGER</varname></term>
                                <listitem><para>Pager to use when
                                <option>--no-pager</option> is not given;
                                overrides <varname>$PAGER</varname>.  Setting
                                this to an empty string or the value
                                <literal>cat</literal> is equivalent to passing
                                <option>--no-pager</option>.</para></listitem>
                        </varlistentry>
                </variablelist>
        </refsect1>

        <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>