mirror of
https://github.com/systemd/systemd
synced 2024-07-05 17:39:42 +00:00
ea54517476
--output= is documented to only affect journal output in *-status. Let's use --json= and -j standard options for list-* instead.
473 lines
20 KiB
XML
473 lines
20 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
||
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
||
|
||
<refentry id="loginctl" conditional='ENABLE_LOGIND'
|
||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
||
<refentryinfo>
|
||
<title>loginctl</title>
|
||
<productname>systemd</productname>
|
||
</refentryinfo>
|
||
|
||
<refmeta>
|
||
<refentrytitle>loginctl</refentrytitle>
|
||
<manvolnum>1</manvolnum>
|
||
</refmeta>
|
||
|
||
<refnamediv>
|
||
<refname>loginctl</refname>
|
||
<refpurpose>Control the systemd login manager</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsynopsisdiv>
|
||
<cmdsynopsis>
|
||
<command>loginctl</command>
|
||
<arg choice="opt" rep="repeat">OPTIONS</arg>
|
||
<arg choice="req">COMMAND</arg>
|
||
<arg choice="opt" rep="repeat">NAME</arg>
|
||
</cmdsynopsis>
|
||
</refsynopsisdiv>
|
||
|
||
<refsect1>
|
||
<title>Description</title>
|
||
|
||
<para><command>loginctl</command> may be used to introspect and
|
||
control the state of the
|
||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||
login manager
|
||
<citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Commands</title>
|
||
|
||
<para>The following commands are understood:</para>
|
||
|
||
<refsect2><title>Session Commands</title><variablelist>
|
||
|
||
<varlistentry>
|
||
<term><command>list-sessions</command></term>
|
||
|
||
<listitem><para>List current sessions. The JSON format output can be toggled using <option>--json=</option>
|
||
or <option>-j</option> option.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>session-status</command> <optional><replaceable>ID</replaceable>…</optional></term>
|
||
|
||
<listitem><para>Show terse runtime status information about
|
||
one or more sessions, followed by the most recent log data
|
||
from the journal. Takes one or more session identifiers as
|
||
parameters. If no session identifiers are passed, the status of
|
||
the caller's session is shown. This function is intended to
|
||
generate human-readable output. If you are looking for
|
||
computer-parsable output, use <command>show-session</command>
|
||
instead.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>show-session</command> <optional><replaceable>ID</replaceable>…</optional></term>
|
||
|
||
<listitem><para>Show properties of one or more sessions or the manager itself. If no argument is
|
||
specified, properties of the manager will be shown. If a session ID is specified, properties of
|
||
the session are shown. Specially, if the given ID is <literal>self</literal>, the session to which
|
||
the <command>loginctl</command> process belongs is used. If <literal>auto</literal>, the current
|
||
session is used as with <literal>self</literal> if exists, and falls back to the current user's
|
||
graphical session. By default, empty properties are suppressed. Use <option>--all</option> to show
|
||
those too. To select specific properties to show, use <option>--property=</option>. This command
|
||
is intended to be used whenever computer-parsable output is required. Use <command>session-status</command>
|
||
if you are looking for formatted human-readable output.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>activate</command> <optional><replaceable>ID</replaceable></optional></term>
|
||
|
||
<listitem><para>Activate a session. This brings a session into
|
||
the foreground if another session is currently in the
|
||
foreground on the respective seat. Takes a session identifier
|
||
as argument. If no argument is specified, the session of the
|
||
caller is put into foreground.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v219"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>lock-session</command> <optional><replaceable>ID</replaceable>…</optional></term>
|
||
<term><command>unlock-session</command> <optional><replaceable>ID</replaceable>…</optional></term>
|
||
|
||
<listitem><para>Activates/deactivates the screen lock on one
|
||
or more sessions, if the session supports it. Takes one or
|
||
more session identifiers as arguments. If no argument is
|
||
specified, the session of the caller is locked/unlocked.
|
||
</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>lock-sessions</command></term>
|
||
<term><command>unlock-sessions</command></term>
|
||
|
||
<listitem><para>Activates/deactivates the screen lock on all
|
||
current sessions supporting it. </para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v188"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>terminate-session</command> <replaceable>ID</replaceable>…</term>
|
||
|
||
<listitem><para>Terminates a session. This kills all processes of the session and deallocates all
|
||
resources attached to the session. If the argument is specified as empty string the session invoking
|
||
the command is terminated.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>kill-session</command> <replaceable>ID</replaceable>…</term>
|
||
|
||
<listitem><para>Send a signal to one or more processes of the session. Use
|
||
<option>--kill-whom=</option> to select which process to kill. Use <option>--signal=</option> to
|
||
select the signal to send. If the argument is specified as empty string the signal is sent to the
|
||
session invoking the command.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
</variablelist></refsect2>
|
||
|
||
<refsect2><title>User Commands</title><variablelist>
|
||
<varlistentry>
|
||
<term><command>list-users</command></term>
|
||
|
||
<listitem><para>List currently logged in users. The JSON format output can be toggled using
|
||
<option>--json=</option> or <option>-j</option> option.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>user-status</command> <optional><replaceable>USER</replaceable>…</optional></term>
|
||
|
||
<listitem><para>Show terse runtime status information about
|
||
one or more logged in users, followed by the most recent log
|
||
data from the journal. Takes one or more user names or numeric
|
||
user IDs as parameters. If no parameters are passed, the status
|
||
is shown for the user of the session of the caller. This
|
||
function is intended to generate human-readable output. If you
|
||
are looking for computer-parsable output, use
|
||
<command>show-user</command> instead.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>show-user</command> <optional><replaceable>USER</replaceable>…</optional></term>
|
||
|
||
<listitem><para>Show properties of one or more users or the
|
||
manager itself. If no argument is specified, properties of the
|
||
manager will be shown. If a user is specified, properties of
|
||
the user are shown. By default, empty properties are
|
||
suppressed. Use <option>--all</option> to show those too. To
|
||
select specific properties to show, use
|
||
<option>--property=</option>. This command is intended to be
|
||
used whenever computer-parsable output is required. Use
|
||
<command>user-status</command> if you are looking for
|
||
formatted human-readable output.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>enable-linger</command> <optional><replaceable>USER</replaceable>…</optional></term>
|
||
<term><command>disable-linger</command> <optional><replaceable>USER</replaceable>…</optional></term>
|
||
|
||
<listitem><para>Enable/disable user lingering for one or more
|
||
users. If enabled for a specific user, a user manager is
|
||
spawned for the user at boot and kept around after logouts.
|
||
This allows users who are not logged in to run long-running
|
||
services. Takes one or more user names or numeric UIDs as
|
||
argument. If no argument is specified, enables/disables
|
||
lingering for the user of the session of the caller.</para>
|
||
|
||
<para>See also <varname>KillUserProcesses=</varname> setting in
|
||
<citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
|
||
</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>terminate-user</command> <replaceable>USER</replaceable>…</term>
|
||
|
||
<listitem><para>Terminates all sessions of a user. This kills all processes of all sessions of the
|
||
user and deallocates all runtime resources attached to the user. If the argument is specified as
|
||
empty string the sessions of the user invoking the command are terminated.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>kill-user</command> <replaceable>USER</replaceable>…</term>
|
||
|
||
<listitem><para>Send a signal to all processes of a user. Use <option>--signal=</option> to select
|
||
the signal to send. If the argument is specified as empty string the signal is sent to the sessions
|
||
of the user invoking the command.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
</variablelist></refsect2>
|
||
|
||
<refsect2><title>Seat Commands</title><variablelist>
|
||
<varlistentry>
|
||
<term><command>list-seats</command></term>
|
||
|
||
<listitem><para>List currently available seats on the local system. The JSON format output can be
|
||
toggled using <option>--json=</option> or <option>-j</option> option.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>seat-status</command> <optional><replaceable>NAME</replaceable>…</optional></term>
|
||
|
||
<listitem><para>Show terse runtime status information about
|
||
one or more seats. Takes one or more seat names as parameters.
|
||
If no seat names are passed the status of the caller's
|
||
session's seat is shown. This function is intended to generate
|
||
human-readable output. If you are looking for
|
||
computer-parsable output, use <command>show-seat</command>
|
||
instead.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>show-seat</command> <optional><replaceable>NAME</replaceable>…</optional></term>
|
||
|
||
<listitem><para>Show properties of one or more seats or the
|
||
manager itself. If no argument is specified, properties of the
|
||
manager will be shown. If a seat is specified, properties of
|
||
the seat are shown. By default, empty properties are
|
||
suppressed. Use <option>--all</option> to show those too. To
|
||
select specific properties to show, use
|
||
<option>--property=</option>. This command is intended to be
|
||
used whenever computer-parsable output is required. Use
|
||
<command>seat-status</command> if you are looking for
|
||
formatted human-readable output.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>…</term>
|
||
|
||
<listitem><para>Persistently attach one or more devices to a
|
||
seat. The devices should be specified via device paths in the
|
||
<filename>/sys/</filename> file system. To create a new seat,
|
||
attach at least one graphics card to a previously unused seat
|
||
name. Seat names may consist only of a–z, A–Z, 0–9,
|
||
<literal>-</literal> and <literal>_</literal> and must be
|
||
prefixed with <literal>seat</literal>. To drop assignment of a
|
||
device to a specific seat, just reassign it to a different
|
||
seat, or use <command>flush-devices</command>.
|
||
</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>flush-devices</command></term>
|
||
|
||
<listitem><para>Removes all device assignments previously
|
||
created with <command>attach</command>. After this call, only
|
||
automatically generated seats will remain, and all seat
|
||
hardware is assigned to them.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><command>terminate-seat</command> <replaceable>NAME</replaceable>…</term>
|
||
|
||
<listitem><para>Terminates all sessions on a seat. This kills
|
||
all processes of all sessions on the seat and deallocates all
|
||
runtime resources attached to them.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||
</varlistentry>
|
||
</variablelist></refsect2>
|
||
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Options</title>
|
||
|
||
<para>The following options are understood:</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><option>--no-ask-password</option></term>
|
||
|
||
<listitem><para>Do not query the user for authentication for
|
||
privileged operations.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>-p</option></term>
|
||
<term><option>--property=</option></term>
|
||
|
||
<listitem><para>When showing session/user/seat properties,
|
||
limit display to certain properties as specified as argument.
|
||
If not specified, all set properties are shown. The argument
|
||
should be a property name, such as
|
||
<literal>Sessions</literal>. If specified more than once, all
|
||
properties with the specified names are
|
||
shown.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--value</option></term>
|
||
|
||
<listitem><para>When showing session/user/seat properties,
|
||
only print the value, and skip the property name and
|
||
<literal>=</literal>.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v230"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>-a</option></term>
|
||
<term><option>--all</option></term>
|
||
|
||
<listitem><para>When showing session/user/seat properties,
|
||
show all properties regardless of whether they are set or
|
||
not.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>-l</option></term>
|
||
<term><option>--full</option></term>
|
||
|
||
<listitem><para>Do not ellipsize process tree entries.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v198"/>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--kill-whom=</option></term>
|
||
|
||
<listitem><para>When used with <command>kill-session</command>, choose which processes to kill.
|
||
Takes one of <literal>leader</literal> or <literal>all</literal>, to select whether to kill only
|
||
the leader process of the session or all processes of the session. If omitted, defaults to
|
||
<option>all</option>.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v252"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>-s</option></term>
|
||
<term><option>--signal=</option></term>
|
||
|
||
<listitem><para>When used with <command>kill-session</command> or <command>kill-user</command>,
|
||
choose which signal to send to selected processes. Must be one of the well known signal specifiers,
|
||
such as <constant>SIGTERM</constant>, <constant>SIGINT</constant> or <constant>SIGSTOP</constant>.
|
||
If omitted, defaults to <constant>SIGTERM</constant>.</para>
|
||
|
||
<para>The special value <literal>help</literal> will list the known values and the program will exit
|
||
immediately, and the special value <literal>list</literal> will list known values along with the
|
||
numerical signal numbers and the program will exit immediately.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>-n</option></term>
|
||
<term><option>--lines=</option></term>
|
||
|
||
<listitem><para>When used with <command>user-status</command>
|
||
and <command>session-status</command>, controls the number of
|
||
journal lines to show, counting from the most recent ones.
|
||
Takes a positive integer argument. Defaults to 10.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v219"/>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>-o</option></term>
|
||
<term><option>--output=</option></term>
|
||
|
||
<listitem><para>When used with <command>user-status</command>
|
||
and <command>session-status</command>, controls the formatting
|
||
of the journal entries that are shown. For the available
|
||
choices, see
|
||
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
|
||
Defaults to <literal>short</literal>.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v219"/></listitem>
|
||
</varlistentry>
|
||
|
||
<xi:include href="user-system-options.xml" xpointer="host" />
|
||
<xi:include href="user-system-options.xml" xpointer="machine" />
|
||
|
||
<xi:include href="standard-options.xml" xpointer="no-pager" />
|
||
<xi:include href="standard-options.xml" xpointer="no-legend" />
|
||
<xi:include href="standard-options.xml" xpointer="json" />
|
||
<xi:include href="standard-options.xml" xpointer="j" />
|
||
<xi:include href="standard-options.xml" xpointer="help" />
|
||
<xi:include href="standard-options.xml" xpointer="version" />
|
||
</variablelist>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Exit status</title>
|
||
|
||
<para>On success, 0 is returned, a non-zero failure code
|
||
otherwise.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Examples</title>
|
||
|
||
<example>
|
||
<title>Querying user status</title>
|
||
|
||
<programlisting>$ loginctl user-status
|
||
fatima (1005)
|
||
Since: Sat 2016-04-09 14:23:31 EDT; 54min ago
|
||
State: active
|
||
Sessions: 5 *3
|
||
Unit: user-1005.slice
|
||
├─user@1005.service
|
||
…
|
||
├─session-3.scope
|
||
…
|
||
└─session-5.scope
|
||
├─3473 login -- fatima
|
||
└─3515 -zsh
|
||
|
||
Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session):
|
||
session opened for user fatima by LOGIN(uid=0)
|
||
Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima
|
||
</programlisting>
|
||
|
||
<para>There are two sessions, 3 and 5. Session 3 is a graphical session,
|
||
marked with a star. The tree of processing including the two corresponding
|
||
scope units and the user manager unit are shown.</para>
|
||
</example>
|
||
</refsect1>
|
||
|
||
<xi:include href="common-variables.xml" />
|
||
|
||
<refsect1>
|
||
<title>See Also</title>
|
||
<para><simplelist type="inline">
|
||
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
||
<member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
||
<member><citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
|
||
<member><citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
|
||
</simplelist></para>
|
||
</refsect1>
|
||
|
||
</refentry>
|