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