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='HAVE_PAM'>
27 <title>loginctl</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>loginctl</refentrytitle>
42 <manvolnum>1</manvolnum>
46 <refname>loginctl</refname>
47 <refpurpose>Control the systemd login manager</refpurpose>
52 <command>loginctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
57 <title>Description</title>
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>
66 <title>Options</title>
68 <para>The following options are understood:</para>
72 <term><option>-h</option></term>
73 <term><option>--help</option></term>
75 <listitem><para>Prints a short help
76 text and exits.</para></listitem>
80 <term><option>--version</option></term>
82 <listitem><para>Prints a short version
83 string and exits.</para></listitem>
87 <term><option>-p</option></term>
88 <term><option>--property=</option></term>
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>
104 <term><option>-a</option></term>
105 <term><option>--all</option></term>
107 <listitem><para>When showing
108 unit/job/manager properties, show all
109 properties regardless whether they are
110 set or not.</para></listitem>
114 <term><option>-l</option></term>
115 <term><option>--full</option></term>
117 <listitem><para>Do not ellipsize cgroup
123 <term><option>--no-pager</option></term>
125 <listitem><para>Do not pipe output into a
126 pager.</para></listitem>
130 <term><option>--no-ask-password</option></term>
132 <listitem><para>Don't query the user
133 for authentication for privileged
134 operations.</para></listitem>
138 <term><option>--kill-who=</option></term>
140 <listitem><para>When used with
141 <command>kill-session</command>,
142 choose which processes to kill. Must
143 be one of <option>leader</option>, or
144 <option>all</option> to select whether
145 to kill only the leader process of the
146 session or all processes of the
147 session. If omitted defaults to
148 <option>all</option>.</para></listitem>
152 <term><option>-s</option></term>
153 <term><option>--signal=</option></term>
155 <listitem><para>When used with
156 <command>kill-session</command> or
157 <command>kill-user</command>, choose
158 which signal to send to selected
159 processes. Must be one of the well
160 known signal specifiers such as
161 SIGTERM, SIGINT or SIGSTOP. If omitted
163 <option>SIGTERM</option>.</para></listitem>
167 <term><option>-H</option></term>
168 <term><option>--host</option></term>
170 <listitem><para>Execute operation
171 remotely. Specify a hostname, or
172 username and hostname separated by @,
173 to connect to. This will use SSH to
174 talk to the remote login manager
175 instance.</para></listitem>
179 <term><option>-P</option></term>
180 <term><option>--privileged</option></term>
182 <listitem><para>Acquire privileges via
183 PolicyKit before executing the
184 operation.</para></listitem>
188 <para>The following commands are understood:</para>
192 <term><command>list-sessions</command></term>
194 <listitem><para>List current sessions.</para></listitem>
198 <term><command>session-status [ID...]</command></term>
200 <listitem><para>Show terse runtime
201 status information about one or more
202 sessions. This function is intended to
203 generate human-readable output. If you
204 are looking for computer-parsable
206 <command>show-session</command>
207 instead.</para></listitem>
211 <term><command>show-session [ID...]</command></term>
213 <listitem><para>Show properties of one
214 or more sessions or the manager
215 itself. If no argument is specified
216 properties of the manager will be
217 shown. If a session ID is specified
218 properties of the session is shown. By
219 default, empty properties are
220 suppressed. Use <option>--all</option>
221 to show those too. To select specific
222 properties to show use
223 <option>--property=</option>. This
224 command is intended to be used
225 whenever computer-parsable output is
227 <command>session-status</command> if
228 you are looking for formatted
230 output.</para></listitem>
234 <term><command>activate [ID...]</command></term>
236 <listitem><para>Activate one or more
237 sessions. This brings one or more
238 sessions into the foreground, if
239 another session is currently in the
240 foreground on the respective
241 seat.</para></listitem>
245 <term><command>lock-session [ID...]</command></term>
246 <term><command>unlock-session [ID...]</command></term>
248 <listitem><para>Activates/deactivates
249 the screen lock on one or more
250 sessions, if the session supports it.</para></listitem>
254 <term><command>lock-sessions</command></term>
255 <term><command>unlock-sessions</command></term>
257 <listitem><para>Activates/deactivates
258 the screen lock on all current
260 it.</para></listitem>
264 <term><command>terminate-session [ID...]</command></term>
266 <listitem><para>Terminates a
267 session. This kills all processes of
268 the session and deallocates all
269 resources attached to the
270 session.</para></listitem>
274 <term><command>kill-session [ID...]</command></term>
276 <listitem><para>Send a signal to one
277 or more processes of the session. Use
278 <option>--kill-who=</option> to select
279 which process to kill. Use
280 <option>--signal=</option> to select
281 the signal to send.</para></listitem>
285 <term><command>list-users</command></term>
287 <listitem><para>List currently logged
288 in users.</para></listitem>
292 <term><command>user-status [USER...]</command></term>
294 <listitem><para>Show terse runtime
295 status information about one or more
296 logged in users. This function is
297 intended to generate human-readable
298 output. If you are looking for
299 computer-parsable output, use
300 <command>show-user</command>
301 instead. Users may be specified by
302 their usernames or numeric user
303 IDs.</para></listitem>
307 <term><command>show-user [USER...]</command></term>
309 <listitem><para>Show properties of one
310 or more users or the manager
311 itself. If no argument is specified
312 properties of the manager will be
313 shown. If a user is specified
314 properties of the user is shown. By
315 default, empty properties are
316 suppressed. Use <option>--all</option>
317 to show those too. To select specific
318 properties to show use
319 <option>--property=</option>. This
320 command is intended to be used
321 whenever computer-parsable output is
323 <command>user-status</command> if
324 you are looking for formatted
326 output.</para></listitem>
330 <term><command>enable-linger [USER...]</command></term>
331 <term><command>disable-linger [USER...]</command></term>
333 <listitem><para>Enable/disable user
334 lingering for one or more users. If
335 enabled for a specific user a user
336 manager is spawned for him/her at
337 boot, and kept around after
338 logouts. This allows users who aren't
339 logged in to run long-running
340 services.</para></listitem>
344 <term><command>terminate-user [USER...]</command></term>
346 <listitem><para>Terminates all
347 sessions of a user. This kills all
348 processes of all sessions of the user
349 and deallocates all runtime resources
351 user.</para></listitem>
355 <term><command>kill-user [USER...]</command></term>
357 <listitem><para>Send a signal to all
358 processes of a user. Use
359 <option>--signal=</option> to select
360 the signal to send.</para></listitem>
364 <term><command>list-seats</command></term>
366 <listitem><para>List currently
367 available seats on the local
368 system.</para></listitem>
372 <term><command>seat-status [NAME...]</command></term>
374 <listitem><para>Show terse runtime
375 status information about one or more
376 seats. This function is
377 intended to generate human-readable
378 output. If you are looking for
379 computer-parsable output, use
380 <command>show-seat</command>
381 instead.</para></listitem>
385 <term><command>show-seat [NAME...]</command></term>
387 <listitem><para>Show properties of one
388 or more seats or the manager
389 itself. If no argument is specified
390 properties of the manager will be
391 shown. If a seat is specified
392 properties of the seat are shown. By
393 default, empty properties are
394 suppressed. Use <option>--all</option>
395 to show those too. To select specific
396 properties to show use
397 <option>--property=</option>. This
398 command is intended to be used
399 whenever computer-parsable output is
401 <command>seat-status</command> if you
402 are looking for formatted
404 output.</para></listitem>
408 <term><command>attach [NAME] [DEVICE...]</command></term>
410 <listitem><para>Persistently attach
411 one or more devices to a seat. The
412 devices should be specified via device
413 paths in the <filename>/sys</filename>
414 file system. To create a new seat
415 attach at least one graphics card to a
416 previously unused seat name. Seat
417 names may consist only of a-z, A-Z,
418 0-9, "-" and "_" and must be prefixed
419 with "seat". To drop assignment of a
420 device to a specific seat just
421 reassign it to a different seat, or
423 <command>flush-devices</command>.</para></listitem>
427 <term><command>flush-devices</command></term>
429 <listitem><para>Removes all device
430 assignments previously created with
431 <command>attach</command>. After this
432 call only automatically generated
433 seats will remain and all seat
434 hardware is assigned to
435 them.</para></listitem>
439 <term><command>terminate-seat [NAME...]</command></term>
441 <listitem><para>Terminates all
442 sessions on a seat. This kills all
443 processes of all sessions on a seat and
444 deallocates all runtime resources
445 attached to them.</para></listitem>
452 <title>Exit status</title>
454 <para>On success 0 is returned, a non-zero failure
455 code otherwise.</para>
459 <title>Environment</title>
461 <variablelist class='environment-variables'>
463 <term><varname>$SYSTEMD_PAGER</varname></term>
464 <listitem><para>Pager to use when
465 <option>--no-pager</option> is not given;
466 overrides <varname>$PAGER</varname>. Setting
467 this to an empty string or the value
468 <literal>cat</literal> is equivalent to passing
469 <option>--no-pager</option>.</para></listitem>
475 <title>See Also</title>
477 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
478 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
479 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
480 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>