path: root/man/loginctl.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="loginctl" conditional='HAVE_PAM'>

        <refentryinfo>
                <title>loginctl</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </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 <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
                </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>Options</title>

                <para>The following options are understood:</para>

                <variablelist>
                        <varlistentry>
                                <term><option>-h</option></term>
                                <term><option>--help</option></term>

                                <listitem><para>Prints a short help
                                text and exits.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--version</option></term>

                                <listitem><para>Prints a short version
                                string and exits.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-p</option></term>
                                <term><option>--property=</option></term>

                                <listitem><para>When showing
                                session/user 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>-a</option></term>
                                <term><option>--all</option></term>

                                <listitem><para>When showing
                                unit/job/manager properties, show all
                                properties regardless 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 cgroup
                                members.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--no-pager</option></term>

                                <listitem><para>Do not pipe output into a
                                pager.</para></listitem>
                        </varlistentry>

                        <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>--kill-who=</option></term>

                                <listitem><para>When used with
                                <command>kill-session</command>,
                                choose which processes to kill. Must
                                be one of <option>leader</option>, or
                                <option>all</option> 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></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></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-H</option></term>
                                <term><option>--host</option></term>

                                <listitem><para>Execute operation
                                remotely. Specify a hostname, or
                                username and hostname separated by <literal>@</literal>,
                                to connect to. This will use SSH to
                                talk to the remote login manager
                                instance.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-P</option></term>
                                <term><option>--privileged</option></term>

                                <listitem><para>Acquire privileges via
                                PolicyKit before executing the
                                operation.</para></listitem>
                        </varlistentry>
                </variablelist>

                <para>The following commands are understood:</para>

                <variablelist>
                        <varlistentry>
                                <term><command>list-sessions</command></term>

                                <listitem><para>List current sessions.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>session-status [ID...]</command></term>

                                <listitem><para>Show terse runtime
                                status information about one or more
                                sessions. This function is intended to
                                generate human-readable output. If you
                                are looking for computer-parsable
                                output, use
                                <command>show-session</command>
                                instead.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>show-session [ID...]</command></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 is 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>session-status</command> if
                                you are looking for formatted
                                human-readable
                                output.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>activate [ID...]</command></term>

                                <listitem><para>Activate one or more
                                sessions. This brings one or more
                                sessions into the foreground, if
                                another session is currently in the
                                foreground on the respective
                                seat.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>lock-session [ID...]</command></term>
                                <term><command>unlock-session [ID...]</command></term>

                                <listitem><para>Activates/deactivates
                                the screen lock on one or more
                                sessions, if the session supports it.</para></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></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>terminate-session [ID...]</command></term>

                                <listitem><para>Terminates a
                                session. This kills all processes of
                                the session and deallocates all
                                resources attached to the
                                session.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>kill-session [ID...]</command></term>

                                <listitem><para>Send a signal to one
                                or more processes of the session. Use
                                <option>--kill-who=</option> to select
                                which process to kill. Use
                                <option>--signal=</option> to select
                                the signal to send.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>list-users</command></term>

                                <listitem><para>List currently logged
                                in users.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>user-status [USER...]</command></term>

                                <listitem><para>Show terse runtime
                                status information about one or more
                                logged in users. This function is
                                intended to generate human-readable
                                output. If you are looking for
                                computer-parsable output, use
                                <command>show-user</command>
                                instead. Users may be specified by
                                their usernames or numeric user
                                IDs.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>show-user [USER...]</command></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></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>enable-linger [USER...]</command></term>
                                <term><command>disable-linger [USER...]</command></term>

                                <listitem><para>Enable/disable user
                                lingering for one or more users. If
                                enabled for a specific user, a user
                                manager is spawned for him/her at
                                boot and kept around after
                                logouts. This allows users who are not
                                logged in to run long-running
                                services.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>terminate-user [USER...]</command></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.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>kill-user [USER...]</command></term>

                                <listitem><para>Send a signal to all
                                processes of a user. Use
                                <option>--signal=</option> to select
                                the signal to send.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>list-seats</command></term>

                                <listitem><para>List currently
                                available seats on the local
                                system.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>seat-status [NAME...]</command></term>

                                <listitem><para>Show terse runtime
                                status information about one or more
                                seats. This function is
                                intended to generate human-readable
                                output. If you are looking for
                                computer-parsable output, use
                                <command>show-seat</command>
                                instead.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>show-seat [NAME...]</command></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></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><command>attach [NAME] [DEVICE...]</command></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></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 [NAME...]</command></term>

                                <listitem><para>Terminates all
                                sessions on a seat. This kills all
                                processes of all sessions on a seat and
                                deallocates all runtime resources
                                attached to them.</para></listitem>
                        </varlistentry>
                </variablelist>

        </refsect1>

        <refsect1>
                <title>Exit status</title>

                <para>On success, 0 is returned, a non-zero failure
                code otherwise.</para>
        </refsect1>

        <refsect1>
                <title>Environment</title>

                <variablelist class='environment-variables'>
                        <varlistentry>
                                <term><varname>$SYSTEMD_PAGER</varname></term>
                                <listitem><para>Pager to use when
                                <option>--no-pager</option> is not given;
                                overrides <varname>$PAGER</varname>.  Setting
                                this to an empty string or the value
                                <literal>cat</literal> is equivalent to passing
                                <option>--no-pager</option>.</para></listitem>
                        </varlistentry>
                </variablelist>
        </refsect1>

        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>