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">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
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.
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.
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/>.
24 <refentry id="loginctl" conditional='ENABLE_LOGIND'
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>loginctl</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>loginctl</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>loginctl</refname>
48 <refpurpose>Control the systemd login manager</refpurpose>
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>
61 <title>Description</title>
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>
70 <title>Options</title>
72 <para>The following options are understood:</para>
76 <term><option>--no-ask-password</option></term>
78 <listitem><para>Do not query the user
79 for authentication for privileged
80 operations.</para></listitem>
84 <term><option>-p</option></term>
85 <term><option>--property=</option></term>
87 <listitem><para>When showing
88 session/user/seat properties, limit
89 display to certain properties as
90 specified as argument. If not
91 specified, all set properties are
92 shown. The argument should be a
93 property name, such as
94 <literal>Sessions</literal>. If
95 specified more than once, all
96 properties with the specified names
97 are shown.</para></listitem>
101 <term><option>-a</option></term>
102 <term><option>--all</option></term>
104 <listitem><para>When showing
105 session/user/seat properties, show all
106 properties regardless of whether they are
107 set or not.</para></listitem>
111 <term><option>-l</option></term>
112 <term><option>--full</option></term>
114 <listitem><para>Do not ellipsize
115 process tree entries.</para>
120 <term><option>--kill-who=</option></term>
122 <listitem><para>When used with
123 <command>kill-session</command>,
124 choose which processes to kill. Must
125 be one of <option>leader</option>, or
126 <option>all</option> to select whether
127 to kill only the leader process of the
128 session or all processes of the
129 session. If omitted, defaults to
130 <option>all</option>.</para></listitem>
134 <term><option>-s</option></term>
135 <term><option>--signal=</option></term>
137 <listitem><para>When used with
138 <command>kill-session</command> or
139 <command>kill-user</command>, choose
140 which signal to send to selected
141 processes. Must be one of the well
142 known signal specifiers, such as
143 <constant>SIGTERM</constant>,
144 <constant>SIGINT</constant> or
145 <constant>SIGSTOP</constant>. If
147 <constant>SIGTERM</constant>.</para></listitem>
151 <term><option>-n</option></term>
152 <term><option>--lines=</option></term>
154 <listitem><para>When used with
155 <command>user-status</command> and
156 <command>session-status</command>,
157 controls the number of journal lines
158 to show, counting from the most recent
159 ones. Takes a positive integer
160 argument. Defaults to 10.</para>
165 <term><option>-o</option></term>
166 <term><option>--output=</option></term>
168 <listitem><para>When used with
169 <command>user-status</command> and
170 <command>session-status</command>,
171 controls the formatting of the journal
172 entries that are shown. For the
173 available choices, see
174 <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
176 <literal>short</literal>.</para></listitem>
179 <xi:include href="user-system-options.xml" xpointer="host" />
180 <xi:include href="user-system-options.xml" xpointer="machine" />
182 <xi:include href="standard-options.xml" xpointer="no-pager" />
183 <xi:include href="standard-options.xml" xpointer="no-legend" />
184 <xi:include href="standard-options.xml" xpointer="help" />
185 <xi:include href="standard-options.xml" xpointer="version" />
190 <title>Commands</title>
192 <para>The following commands are understood:</para>
194 <refsect2><title>Session Commands</title><variablelist>
197 <term><command>list-sessions</command></term>
199 <listitem><para>List current sessions.</para></listitem>
203 <term><command>session-status</command> <optional><replaceable>ID</replaceable>...</optional></term>
205 <listitem><para>Show terse runtime
206 status information about one or more
207 sessions, followed by the most recent
208 log data from the journal. Takes one
209 or more session identifiers as
210 parameters. If no session identifiers
211 are passed the status of the caller's
212 session is shown. This function is
213 intended to generate human-readable
214 output. If you are looking for
215 computer-parsable output, use
216 <command>show-session</command>
217 instead.</para></listitem>
221 <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
223 <listitem><para>Show properties of one
224 or more sessions or the manager
225 itself. If no argument is specified,
226 properties of the manager will be
227 shown. If a session ID is specified,
228 properties of the session are shown. By
229 default, empty properties are
230 suppressed. Use <option>--all</option>
231 to show those too. To select specific
232 properties to show, use
233 <option>--property=</option>. This
234 command is intended to be used
235 whenever computer-parsable output is
237 <command>session-status</command> if
238 you are looking for formatted
240 output.</para></listitem>
244 <term><command>activate</command> <optional><replaceable>ID</replaceable></optional></term>
246 <listitem><para>Activate a
247 session. This brings a session into
248 the foreground, if another session is
249 currently in the foreground on the
250 respective seat. Takes a session
251 identifier as argument. If no argument
252 is specified the session of the caller
254 foreground.</para></listitem>
258 <term><command>lock-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
259 <term><command>unlock-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
261 <listitem><para>Activates/deactivates
262 the screen lock on one or more
263 sessions, if the session supports
264 it. Takes one or more session
265 identifiers as arguments. If no
266 argument is specified the session of
267 the caller is locked/unlocked.
272 <term><command>lock-sessions</command></term>
273 <term><command>unlock-sessions</command></term>
275 <listitem><para>Activates/deactivates
276 the screen lock on all current
277 sessions supporting it.
282 <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term>
284 <listitem><para>Terminates a session.
285 This kills all processes of the
286 session and deallocates all resources
287 attached to the session.
292 <term><command>kill-session</command> <replaceable>ID</replaceable>...</term>
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>
301 </variablelist></refsect2>
303 <refsect2><title>User Commands</title><variablelist>
305 <term><command>list-users</command></term>
307 <listitem><para>List currently logged
308 in users.</para></listitem>
312 <term><command>user-status</command> <optional><replaceable>USER</replaceable>...</optional></term>
314 <listitem><para>Show terse runtime
315 status information about one or more
316 logged in users, followed by the most
317 recent log data from the
318 journal. Takes one or more user names
319 or numeric user IDs as parameters. If
320 no parameters are passed the status of
321 the caller's user is shown. This
322 function is intended to generate
323 human-readable output. If you are
324 looking for computer-parsable output,
325 use <command>show-user</command>
326 instead. Users may be specified by
327 their usernames or numeric user IDs.
332 <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term>
334 <listitem><para>Show properties of one
335 or more users or the manager
336 itself. If no argument is specified,
337 properties of the manager will be
338 shown. If a user is specified,
339 properties of the user are shown. By
340 default, empty properties are
341 suppressed. Use <option>--all</option>
342 to show those too. To select specific
343 properties to show, use
344 <option>--property=</option>. This
345 command is intended to be used
346 whenever computer-parsable output is
348 <command>user-status</command> if
349 you are looking for formatted
351 output.</para></listitem>
355 <term><command>enable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term>
356 <term><command>disable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term>
358 <listitem><para>Enable/disable user
359 lingering for one or more users. If
360 enabled for a specific user, a user
361 manager is spawned for the user at
362 boot and kept around after
363 logouts. This allows users who are not
364 logged in to run long-running
365 services. Takes one or more user names
366 or numeric UIDs as argument. If no
367 argument is specified enables/disables
368 lingering for the user of the session
369 of the caller.</para></listitem>
373 <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term>
375 <listitem><para>Terminates all
376 sessions of a user. This kills all
377 processes of all sessions of the user
378 and deallocates all runtime resources
379 attached to the user.
384 <term><command>kill-user</command> <replaceable>USER</replaceable>...</term>
386 <listitem><para>Send a signal to all
387 processes of a user. Use
388 <option>--signal=</option> to select
389 the signal to send.</para></listitem>
391 </variablelist></refsect2>
393 <refsect2><title>Seat Commands</title><variablelist>
395 <term><command>list-seats</command></term>
397 <listitem><para>List currently
398 available seats on the local
399 system.</para></listitem>
403 <term><command>seat-status</command> <optional><replaceable>NAME</replaceable>...</optional></term>
405 <listitem><para>Show terse runtime
406 status information about one or more
407 seats. Takes one or more seat names as
408 parameters. If no seat names are
409 passed the status of the caller's
410 session's seat is shown. This function
411 is intended to generate human-readable
412 output. If you are looking for
413 computer-parsable output, use
414 <command>show-seat</command>
415 instead.</para></listitem>
419 <term><command>show-seat</command> <optional><replaceable>NAME</replaceable>...</optional></term>
421 <listitem><para>Show properties of one
422 or more seats or the manager
423 itself. If no argument is specified,
424 properties of the manager will be
425 shown. If a seat is specified,
426 properties of the seat are shown. By
427 default, empty properties are
428 suppressed. Use <option>--all</option>
429 to show those too. To select specific
430 properties to show, use
431 <option>--property=</option>. This
432 command is intended to be used
433 whenever computer-parsable output is
435 <command>seat-status</command> if you
436 are looking for formatted
438 output.</para></listitem>
442 <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term>
444 <listitem><para>Persistently attach
445 one or more devices to a seat. The
446 devices should be specified via device
447 paths in the <filename>/sys</filename>
448 file system. To create a new seat,
449 attach at least one graphics card to a
450 previously unused seat name. Seat
451 names may consist only of a-z, A-Z,
452 0-9, <literal>-</literal> and
453 <literal>_</literal> and must be
454 prefixed with <literal>seat</literal>.
455 To drop assignment of a device to a
456 specific seat, just reassign it to a
457 different seat, or use
458 <command>flush-devices</command>.
463 <term><command>flush-devices</command></term>
465 <listitem><para>Removes all device
466 assignments previously created with
467 <command>attach</command>. After this
468 call, only automatically generated
469 seats will remain, and all seat
470 hardware is assigned to
471 them.</para></listitem>
475 <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term>
477 <listitem><para>Terminates all
478 sessions on a seat. This kills all
479 processes of all sessions on the seat
480 and deallocates all runtime resources
481 attached to them.</para></listitem>
483 </variablelist></refsect2>
488 <title>Exit status</title>
490 <para>On success, 0 is returned, a non-zero failure
491 code otherwise.</para>
494 <xi:include href="less-variables.xml" />
497 <title>See Also</title>
499 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
500 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
501 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
502 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>