chiark / gitweb /
headers: fix git URLs for source files
[elogind.git] / man / systemd-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 General Public License as published by
12   the Free Software Foundation; either version 2 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   General Public License for more details.
19
20   You should have received a copy of the GNU General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="systemd-loginctl">
25
26         <refentryinfo>
27                 <title>systemd-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>systemd-loginctl</refentrytitle>
42                 <manvolnum>1</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>systemd-loginctl</refname>
47                 <refpurpose>Control the systemd login manager</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <cmdsynopsis>
52                         <command>systemd-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>systemd-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.</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>--kill-who=</option></term>
123
124                                 <listitem><para>When used with
125                                 <command>kill-session</command>,
126                                 choose which processes to kill. Must
127                                 be one of <option>leader</option>, or
128                                 <option>all</option> to select whether
129                                 to kill only the leader process of the
130                                 session or all processes of the
131                                 session. If omitted defaults to
132                                 <option>all</option>.</para></listitem>
133                         </varlistentry>
134
135                         <varlistentry>
136                                 <term><option>--signal=</option></term>
137                                 <term><option>-s</option></term>
138
139                                 <listitem><para>When used with
140                                 <command>kill-session</command> or
141                                 <command>kill-user</command>, choose
142                                 which signal to send to selected
143                                 processes. Must be one of the well
144                                 known signal specifiers such as
145                                 SIGTERM, SIGINT or SIGSTOP. If omitted
146                                 defaults to
147                                 <option>SIGTERM</option>.</para></listitem>
148                         </varlistentry>
149
150                         <varlistentry>
151                                 <term><option>-H</option></term>
152                                 <term><option>--host</option></term>
153
154                                 <listitem><para>Execute operation
155                                 remotely. Specify a hostname, or
156                                 username and hostname separated by @,
157                                 to connect to. This will use SSH to
158                                 talk to the remote login manager
159                                 instance.</para></listitem>
160                         </varlistentry>
161
162                         <varlistentry>
163                                 <term><option>-P</option></term>
164                                 <term><option>--privileged</option></term>
165
166                                 <listitem><para>Acquire privileges via
167                                 PolicyKit before executing the
168                                 operation.</para></listitem>
169                         </varlistentry>
170                 </variablelist>
171
172                 <para>The following commands are understood:</para>
173
174                 <variablelist>
175                         <varlistentry>
176                                 <term><command>list-sessions</command></term>
177
178                                 <listitem><para>List current sessions.</para></listitem>
179                         </varlistentry>
180
181                         <varlistentry>
182                                 <term><command>session-status [ID...]</command></term>
183
184                                 <listitem><para>Show terse runtime
185                                 status information about one or more
186                                 sessions. This function is intended to
187                                 generate human-readable output. If you
188                                 are looking for computer-parsable
189                                 output, use
190                                 <command>show-session</command>
191                                 instead.</para></listitem>
192                         </varlistentry>
193
194                         <varlistentry>
195                                 <term><command>show-session [ID...]</command></term>
196
197                                 <listitem><para>Show properties of one
198                                 or more sessions or the manager
199                                 itself. If no argument is specified
200                                 properties of the manager will be
201                                 shown. If a session ID is specified
202                                 properties of the session is shown. By
203                                 default, empty properties are
204                                 suppressed. Use <option>--all</option>
205                                 to show those too. To select specific
206                                 properties to show use
207                                 <option>--property=</option>. This
208                                 command is intended to be used
209                                 whenever computer-parsable output is
210                                 required. Use
211                                 <command>session-status</command> if
212                                 you are looking for formatted
213                                 human-readable
214                                 output.</para></listitem>
215                         </varlistentry>
216
217                         <varlistentry>
218                                 <term><command>activate [ID...]</command></term>
219
220                                 <listitem><para>Activate one or more
221                                 sessions. This brings one or more
222                                 sessions into the foreground, if
223                                 another session is currently in the
224                                 foreground on the respective
225                                 seat.</para></listitem>
226                         </varlistentry>
227
228                         <varlistentry>
229                                 <term><command>lock-session [ID...]</command></term>
230                                 <term><command>unlock-session [ID...]</command></term>
231
232                                 <listitem><para>Activates/deactivates
233                                 the screen lock on one or more
234                                 sessions, if the session supports it.</para></listitem>
235                         </varlistentry>
236
237                         <varlistentry>
238                                 <term><command>terminate-session [ID...]</command></term>
239
240                                 <listitem><para>Terminates a
241                                 session. This kills all processes of
242                                 the session and deallocates all
243                                 resources attached to the
244                                 session.</para></listitem>
245                         </varlistentry>
246
247                         <varlistentry>
248                                 <term><command>kill-session [ID...]</command></term>
249
250                                 <listitem><para>Send a signal to one
251                                 or more processes of the session. Use
252                                 <option>--kill-who=</option> to select
253                                 which process to kill. Use
254                                 <option>--signal=</option> to select
255                                 the signal to send.</para></listitem>
256                         </varlistentry>
257
258                         <varlistentry>
259                                 <term><command>list-users</command></term>
260
261                                 <listitem><para>List currently logged
262                                 in users.</para></listitem>
263                         </varlistentry>
264
265                         <varlistentry>
266                                 <term><command>user-status [USER...]</command></term>
267
268                                 <listitem><para>Show terse runtime
269                                 status information about one or more
270                                 logged in users. This function is
271                                 intended to generate human-readable
272                                 output. If you are looking for
273                                 computer-parsable output, use
274                                 <command>show-user</command>
275                                 instead. Users may be specified by
276                                 their usernames or numeric user
277                                 IDs.</para></listitem>
278                         </varlistentry>
279
280                         <varlistentry>
281                                 <term><command>show-user [USER...]</command></term>
282
283                                 <listitem><para>Show properties of one
284                                 or more users or the manager
285                                 itself. If no argument is specified
286                                 properties of the manager will be
287                                 shown. If a user is specified
288                                 properties of the user is shown. By
289                                 default, empty properties are
290                                 suppressed. Use <option>--all</option>
291                                 to show those too. To select specific
292                                 properties to show use
293                                 <option>--property=</option>. This
294                                 command is intended to be used
295                                 whenever computer-parsable output is
296                                 required. Use
297                                 <command>user-status</command> if
298                                 you are looking for formatted
299                                 human-readable
300                                 output.</para></listitem>
301                         </varlistentry>
302
303                         <varlistentry>
304                                 <term><command>enable-linger [USER...]</command></term>
305                                 <term><command>disable-linger [USER...]</command></term>
306
307                                 <listitem><para>Enable/disable user
308                                 lingering for one or more users. If
309                                 enabled for a specific user a user
310                                 manager is spawned for him/her at
311                                 boot, and kept around after
312                                 logouts. This allows users who aren't
313                                 logged in to run long-running
314                                 services.</para></listitem>
315                         </varlistentry>
316
317                         <varlistentry>
318                                 <term><command>terminate-user [USER...]</command></term>
319
320                                 <listitem><para>Terminates all
321                                 sessions of a user. This kills all
322                                 processes of all sessions of the user
323                                 and deallocates all runtime resources
324                                 attached to the
325                                 user.</para></listitem>
326                         </varlistentry>
327
328                         <varlistentry>
329                                 <term><command>kill-user [USER...]</command></term>
330
331                                 <listitem><para>Send a signal to all
332                                 processes of a user. Use
333                                 <option>--signal=</option> to select
334                                 the signal to send.</para></listitem>
335                         </varlistentry>
336
337                         <varlistentry>
338                                 <term><command>list-seats</command></term>
339
340                                 <listitem><para>List currently
341                                 available seats on the local
342                                 system.</para></listitem>
343                         </varlistentry>
344
345                         <varlistentry>
346                                 <term><command>seat-status [NAME...]</command></term>
347
348                                 <listitem><para>Show terse runtime
349                                 status information about one or more
350                                 seats. This function is
351                                 intended to generate human-readable
352                                 output. If you are looking for
353                                 computer-parsable output, use
354                                 <command>show-seat</command>
355                                 instead.</para></listitem>
356                         </varlistentry>
357
358                         <varlistentry>
359                                 <term><command>show-seat [NAME...]</command></term>
360
361                                 <listitem><para>Show properties of one
362                                 or more seats or the manager
363                                 itself. If no argument is specified
364                                 properties of the manager will be
365                                 shown. If a seat is specified
366                                 properties of the seat are shown. By
367                                 default, empty properties are
368                                 suppressed. Use <option>--all</option>
369                                 to show those too. To select specific
370                                 properties to show use
371                                 <option>--property=</option>. This
372                                 command is intended to be used
373                                 whenever computer-parsable output is
374                                 required. Use
375                                 <command>seat-status</command> if you
376                                 are looking for formatted
377                                 human-readable
378                                 output.</para></listitem>
379                         </varlistentry>
380
381                         <varlistentry>
382                                 <term><command>attach [NAME] [DEVICE...]</command></term>
383
384                                 <listitem><para>Attach one or more
385                                 devices to a seat. The devices should
386                                 be specified via device paths in the
387                                 <filename>/sys</filename> file
388                                 system. To create a new seat attach at
389                                 least one graphics card to a
390                                 previously unused seat names. seat
391                                 names may consist only of a-z, A-Z,
392                                 0-9, "-" and "_" and must be prefixed
393                                 with "seat". To drop assignment of a
394                                 device to a specific seat just
395                                 reassign it to a different seat, or
396                                 use
397                                 <command>flush-devices</command>.</para></listitem>
398                         </varlistentry>
399
400                         <varlistentry>
401                                 <term><command>flush-devices</command></term>
402
403                                 <listitem><para>Removes all device
404                                 assignments previously created with
405                                 <command>attach</command>. After this
406                                 call only automatically generated
407                                 seats will remain and all seat
408                                 hardware is assigned to
409                                 them.</para></listitem>
410                         </varlistentry>
411
412                         <varlistentry>
413                                 <term><command>terminate-seat [NAME...]</command></term>
414
415                                 <listitem><para>Terminates all
416                                 sessions on a seat. This kills all
417                                 processes of all sessions on a seat and
418                                 deallocates all runtime resources
419                                 attached to them.</para></listitem>
420                         </varlistentry>
421                 </variablelist>
422
423         </refsect1>
424
425         <refsect1>
426                 <title>Exit status</title>
427
428                 <para>On success 0 is returned, a non-zero failure
429                 code otherwise.</para>
430         </refsect1>
431
432         <refsect1>
433                 <title>Environment</title>
434
435                 <variablelist>
436                         <varlistentry>
437                                 <term><varname>$SYSTEMD_PAGER</varname></term>
438                                 <listitem><para>Pager to use when
439                                 <option>--no-pager</option> is not given;
440                                 overrides <varname>$PAGER</varname>.  Setting
441                                 this to an empty string or the value
442                                 <literal>cat</literal> is equivalent to passing
443                                 <option>--no-pager</option>.</para></listitem>
444                         </varlistentry>
445                 </variablelist>
446         </refsect1>
447
448         <refsect1>
449                 <title>See Also</title>
450                 <para>
451                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
452                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
453                         <citerefentry><refentrytitle>systemd-logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
454                 </para>
455         </refsect1>
456
457 </refentry>