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