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