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