chiark / gitweb /
udevadm-settle: add missing brace
[elogind.git] / 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
26         <refentryinfo>
27                 <title>loginctl</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>loginctl</refentrytitle>
42                 <manvolnum>1</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>loginctl</refname>
47                 <refpurpose>Control the systemd login manager</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <cmdsynopsis>
52                         <command>loginctl</command>
53                         <arg choice="opt" rep="repeat">OPTIONS</arg>
54                         <arg choice="req">COMMAND</arg>
55                         <arg choice="opt" rep="repeat">NAME</arg>
56                 </cmdsynopsis>
57         </refsynopsisdiv>
58
59         <refsect1>
60                 <title>Description</title>
61
62                 <para><command>loginctl</command> may be used to
63                 introspect and control the state of the
64                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
65                 login manager <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
66         </refsect1>
67
68         <refsect1>
69                 <title>Options</title>
70
71                 <para>The following options are understood:</para>
72
73                 <variablelist>
74                         <varlistentry>
75                                 <term><option>-h</option></term>
76                                 <term><option>--help</option></term>
77
78                                 <listitem><para>Prints a short help
79                                 text and exits.</para></listitem>
80                         </varlistentry>
81
82                         <varlistentry>
83                                 <term><option>--version</option></term>
84
85                                 <listitem><para>Prints a short version
86                                 string and exits.</para></listitem>
87                         </varlistentry>
88
89                         <varlistentry>
90                                 <term><option>-p</option></term>
91                                 <term><option>--property=</option></term>
92
93                                 <listitem><para>When showing
94                                 session/user/seat properties, limit
95                                 display to certain properties as
96                                 specified as argument. If not
97                                 specified, all set properties are
98                                 shown. The argument should be a
99                                 property name, such as
100                                 <literal>Sessions</literal>. If
101                                 specified more than once, all
102                                 properties with the specified names
103                                 are shown.</para></listitem>
104                         </varlistentry>
105
106                         <varlistentry>
107                                 <term><option>-a</option></term>
108                                 <term><option>--all</option></term>
109
110                                 <listitem><para>When showing
111                                 session/user/seat properties, show all
112                                 properties regardless whether they are
113                                 set or not.</para></listitem>
114                         </varlistentry>
115
116                         <varlistentry>
117                                 <term><option>-l</option></term>
118                                 <term><option>--full</option></term>
119
120                                 <listitem><para>Do not ellipsize
121                                 process tree entries.</para>
122                                 </listitem>
123                         </varlistentry>
124
125                         <varlistentry>
126                                 <term><option>--no-pager</option></term>
127
128                                 <listitem><para>Do not pipe output into a
129                                 pager.</para></listitem>
130                         </varlistentry>
131
132                         <varlistentry>
133                                 <term><option>--no-ask-password</option></term>
134
135                                 <listitem><para>Do not query the user
136                                 for authentication for privileged
137                                 operations.</para></listitem>
138                         </varlistentry>
139
140                         <varlistentry>
141                                 <term><option>--kill-who=</option></term>
142
143                                 <listitem><para>When used with
144                                 <command>kill-session</command>,
145                                 choose which processes to kill. Must
146                                 be one of <option>leader</option>, or
147                                 <option>all</option> to select whether
148                                 to kill only the leader process of the
149                                 session or all processes of the
150                                 session. If omitted, defaults to
151                                 <option>all</option>.</para></listitem>
152                         </varlistentry>
153
154                         <varlistentry>
155                                 <term><option>-s</option></term>
156                                 <term><option>--signal=</option></term>
157
158                                 <listitem><para>When used with
159                                 <command>kill-session</command> or
160                                 <command>kill-user</command>, choose
161                                 which signal to send to selected
162                                 processes. Must be one of the well
163                                 known signal specifiers, such as
164                                 <constant>SIGTERM</constant>,
165                                 <constant>SIGINT</constant> or
166                                 <constant>SIGSTOP</constant>. If
167                                 omitted, defaults to
168                                 <constant>SIGTERM</constant>.</para></listitem>
169                         </varlistentry>
170
171                         <varlistentry>
172                                 <term><option>-H</option></term>
173                                 <term><option>--host</option></term>
174
175                                 <listitem><para>Execute the operation
176                                 remotely. Specify a hostname, or
177                                 username and hostname separated by <literal>@</literal>,
178                                 to connect to. This will use SSH to
179                                 talk to the remote login manager
180                                 instance.</para></listitem>
181                         </varlistentry>
182
183                         <varlistentry>
184                                 <term><option>-P</option></term>
185                                 <term><option>--privileged</option></term>
186
187                                 <listitem><para>Acquire privileges via
188                                 PolicyKit before executing the
189                                 operation.</para></listitem>
190                         </varlistentry>
191                 </variablelist>
192
193                 <para>The following commands are understood:</para>
194
195                 <variablelist>
196                         <varlistentry>
197                                 <term><command>list-sessions</command></term>
198
199                                 <listitem><para>List current sessions.</para></listitem>
200                         </varlistentry>
201
202                         <varlistentry>
203                                 <term><command>session-status [ID...]</command></term>
204
205                                 <listitem><para>Show terse runtime
206                                 status information about one or more
207                                 sessions. This function is intended to
208                                 generate human-readable output. If you
209                                 are looking for computer-parsable
210                                 output, use
211                                 <command>show-session</command>
212                                 instead.</para></listitem>
213                         </varlistentry>
214
215                         <varlistentry>
216                                 <term><command>show-session [ID...]</command></term>
217
218                                 <listitem><para>Show properties of one
219                                 or more sessions or the manager
220                                 itself. If no argument is specified,
221                                 properties of the manager will be
222                                 shown. If a session ID is specified,
223                                 properties of the session are shown. By
224                                 default, empty properties are
225                                 suppressed. Use <option>--all</option>
226                                 to show those too. To select specific
227                                 properties to show, use
228                                 <option>--property=</option>. This
229                                 command is intended to be used
230                                 whenever computer-parsable output is
231                                 required. Use
232                                 <command>session-status</command> if
233                                 you are looking for formatted
234                                 human-readable
235                                 output.</para></listitem>
236                         </varlistentry>
237
238                         <varlistentry>
239                                 <term><command>activate [ID...]</command></term>
240
241                                 <listitem><para>Activate one or more
242                                 sessions. This brings one or more
243                                 sessions into the foreground, if
244                                 another session is currently in the
245                                 foreground on the respective
246                                 seat.</para></listitem>
247                         </varlistentry>
248
249                         <varlistentry>
250                                 <term><command>lock-session [ID...]</command></term>
251                                 <term><command>unlock-session [ID...]</command></term>
252
253                                 <listitem><para>Activates/deactivates
254                                 the screen lock on one or more
255                                 sessions, if the session supports it.</para></listitem>
256                         </varlistentry>
257
258                         <varlistentry>
259                                 <term><command>lock-sessions</command></term>
260                                 <term><command>unlock-sessions</command></term>
261
262                                 <listitem><para>Activates/deactivates
263                                 the screen lock on all current
264                                 sessions supporting
265                                 it.</para></listitem>
266                         </varlistentry>
267
268                         <varlistentry>
269                                 <term><command>terminate-session [ID...]</command></term>
270
271                                 <listitem><para>Terminates a
272                                 session. This kills all processes of
273                                 the session and deallocates all
274                                 resources attached to the
275                                 session.</para></listitem>
276                         </varlistentry>
277
278                         <varlistentry>
279                                 <term><command>kill-session [ID...]</command></term>
280
281                                 <listitem><para>Send a signal to one
282                                 or more processes of the session. Use
283                                 <option>--kill-who=</option> to select
284                                 which process to kill. Use
285                                 <option>--signal=</option> to select
286                                 the signal to send.</para></listitem>
287                         </varlistentry>
288
289                         <varlistentry>
290                                 <term><command>list-users</command></term>
291
292                                 <listitem><para>List currently logged
293                                 in users.</para></listitem>
294                         </varlistentry>
295
296                         <varlistentry>
297                                 <term><command>user-status [USER...]</command></term>
298
299                                 <listitem><para>Show terse runtime
300                                 status information about one or more
301                                 logged in users. This function is
302                                 intended to generate human-readable
303                                 output. If you are looking for
304                                 computer-parsable output, use
305                                 <command>show-user</command>
306                                 instead. Users may be specified by
307                                 their usernames or numeric user
308                                 IDs.</para></listitem>
309                         </varlistentry>
310
311                         <varlistentry>
312                                 <term><command>show-user [USER...]</command></term>
313
314                                 <listitem><para>Show properties of one
315                                 or more users or the manager
316                                 itself. If no argument is specified,
317                                 properties of the manager will be
318                                 shown. If a user is specified,
319                                 properties of the user are shown. By
320                                 default, empty properties are
321                                 suppressed. Use <option>--all</option>
322                                 to show those too. To select specific
323                                 properties to show, use
324                                 <option>--property=</option>. This
325                                 command is intended to be used
326                                 whenever computer-parsable output is
327                                 required. Use
328                                 <command>user-status</command> if
329                                 you are looking for formatted
330                                 human-readable
331                                 output.</para></listitem>
332                         </varlistentry>
333
334                         <varlistentry>
335                                 <term><command>enable-linger [USER...]</command></term>
336                                 <term><command>disable-linger [USER...]</command></term>
337
338                                 <listitem><para>Enable/disable user
339                                 lingering for one or more users. If
340                                 enabled for a specific user, a user
341                                 manager is spawned for him/her at
342                                 boot and kept around after
343                                 logouts. This allows users who are not
344                                 logged in to run long-running
345                                 services.</para></listitem>
346                         </varlistentry>
347
348                         <varlistentry>
349                                 <term><command>terminate-user [USER...]</command></term>
350
351                                 <listitem><para>Terminates all
352                                 sessions of a user. This kills all
353                                 processes of all sessions of the user
354                                 and deallocates all runtime resources
355                                 attached to the
356                                 user.</para></listitem>
357                         </varlistentry>
358
359                         <varlistentry>
360                                 <term><command>kill-user [USER...]</command></term>
361
362                                 <listitem><para>Send a signal to all
363                                 processes of a user. Use
364                                 <option>--signal=</option> to select
365                                 the signal to send.</para></listitem>
366                         </varlistentry>
367
368                         <varlistentry>
369                                 <term><command>list-seats</command></term>
370
371                                 <listitem><para>List currently
372                                 available seats on the local
373                                 system.</para></listitem>
374                         </varlistentry>
375
376                         <varlistentry>
377                                 <term><command>seat-status [NAME...]</command></term>
378
379                                 <listitem><para>Show terse runtime
380                                 status information about one or more
381                                 seats. This function is
382                                 intended to generate human-readable
383                                 output. If you are looking for
384                                 computer-parsable output, use
385                                 <command>show-seat</command>
386                                 instead.</para></listitem>
387                         </varlistentry>
388
389                         <varlistentry>
390                                 <term><command>show-seat [NAME...]</command></term>
391
392                                 <listitem><para>Show properties of one
393                                 or more seats or the manager
394                                 itself. If no argument is specified,
395                                 properties of the manager will be
396                                 shown. If a seat is specified,
397                                 properties of the seat are shown. By
398                                 default, empty properties are
399                                 suppressed. Use <option>--all</option>
400                                 to show those too. To select specific
401                                 properties to show, use
402                                 <option>--property=</option>. This
403                                 command is intended to be used
404                                 whenever computer-parsable output is
405                                 required. Use
406                                 <command>seat-status</command> if you
407                                 are looking for formatted
408                                 human-readable
409                                 output.</para></listitem>
410                         </varlistentry>
411
412                         <varlistentry>
413                                 <term><command>attach [NAME] [DEVICE...]</command></term>
414
415                                 <listitem><para>Persistently attach
416                                 one or more devices to a seat. The
417                                 devices should be specified via device
418                                 paths in the <filename>/sys</filename>
419                                 file system. To create a new seat,
420                                 attach at least one graphics card to a
421                                 previously unused seat name. Seat
422                                 names may consist only of a-z, A-Z,
423                                 0-9, <literal>-</literal> and
424                                 <literal>_</literal> and must be
425                                 prefixed with <literal>seat</literal>.
426                                 To drop assignment of a device to a
427                                 specific seat, just reassign it to a
428                                 different seat, or use
429                                 <command>flush-devices</command>.
430                                 </para></listitem>
431                         </varlistentry>
432
433                         <varlistentry>
434                                 <term><command>flush-devices</command></term>
435
436                                 <listitem><para>Removes all device
437                                 assignments previously created with
438                                 <command>attach</command>. After this
439                                 call, only automatically generated
440                                 seats will remain, and all seat
441                                 hardware is assigned to
442                                 them.</para></listitem>
443                         </varlistentry>
444
445                         <varlistentry>
446                                 <term><command>terminate-seat [NAME...]</command></term>
447
448                                 <listitem><para>Terminates all
449                                 sessions on a seat. This kills all
450                                 processes of all sessions on a seat and
451                                 deallocates all runtime resources
452                                 attached to them.</para></listitem>
453                         </varlistentry>
454                 </variablelist>
455
456         </refsect1>
457
458         <refsect1>
459                 <title>Exit status</title>
460
461                 <para>On success, 0 is returned, a non-zero failure
462                 code otherwise.</para>
463         </refsect1>
464
465         <refsect1>
466                 <title>Environment</title>
467
468                 <variablelist class='environment-variables'>
469                         <varlistentry>
470                                 <term><varname>$SYSTEMD_PAGER</varname></term>
471                                 <listitem><para>Pager to use when
472                                 <option>--no-pager</option> is not given;
473                                 overrides <varname>$PAGER</varname>.  Setting
474                                 this to an empty string or the value
475                                 <literal>cat</literal> is equivalent to passing
476                                 <option>--no-pager</option>.</para></listitem>
477                         </varlistentry>
478                 </variablelist>
479         </refsect1>
480
481         <refsect1>
482                 <title>See Also</title>
483                 <para>
484                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
485                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
486                         <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
487                         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
488                 </para>
489         </refsect1>
490
491 </refentry>