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