mirror of
https://github.com/systemd/systemd.git
synced 2024-11-12 15:21:19 +03:00
e287086b8a
This adds support for caching harddisk passwords in the kernel keyring if it is available, thus supporting caching without Plymouth being around. This is also useful for hooking up "gdm-auto-login" with the collected boot-time harddisk password, in order to support gnome keyring passphrase unlocking via the HDD password, if it is the same. Any passwords added to the kernel keyring this way have a timeout of 2.5min at which time they are purged from the kernel.
219 lines
8.2 KiB
XML
219 lines
8.2 KiB
XML
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
|
|
<!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 2011 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="systemd-ask-password"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>systemd-ask-password</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>systemd-ask-password</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>systemd-ask-password</refname>
|
|
<refpurpose>Query the user for a system password</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><command>systemd-ask-password</command> may be used to query
|
|
a system password or passphrase from the user, using a question
|
|
message specified on the command line. When run from a TTY it will
|
|
query a password on the TTY and print it to standard output. When
|
|
run with no TTY or with <option>--no-tty</option> it will query
|
|
the password system-wide and allow active users to respond via
|
|
several agents. The latter is only available to privileged
|
|
processes.</para>
|
|
|
|
<para>The purpose of this tool is to query system-wide passwords
|
|
-- that is passwords not attached to a specific user account.
|
|
Examples include: unlocking encrypted hard disks when they are
|
|
plugged in or at boot, entering an SSL certificate passphrase for
|
|
web and VPN servers.</para>
|
|
|
|
<para>Existing agents are:
|
|
<itemizedlist>
|
|
|
|
<listitem><para>A boot-time password agent asking the user for
|
|
passwords using Plymouth</para></listitem>
|
|
|
|
<listitem><para>A boot-time password agent querying the user
|
|
directly on the console</para></listitem>
|
|
|
|
<listitem><para>An agent requesting password input via a
|
|
<citerefentry
|
|
project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
message</para></listitem>
|
|
|
|
<listitem><para>A command line agent which can be started
|
|
temporarily to process queued password
|
|
requests</para></listitem>
|
|
|
|
<listitem><para>A TTY agent that is temporarily spawned during
|
|
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
invocations</para></listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>Additional password agents may be implemented according to
|
|
the <ulink
|
|
url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd
|
|
Password Agent Specification</ulink>.</para>
|
|
|
|
<para>If a password is queried on a TTY, the user may press TAB to
|
|
hide the asterisks normally shown for each character typed.
|
|
Pressing Backspace as first key achieves the same effect.</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<para>The following options are understood:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--icon=</option></term>
|
|
|
|
<listitem><para>Specify an icon name alongside the password
|
|
query, which may be used in all agents supporting graphical
|
|
display. The icon name should follow the <ulink
|
|
url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
|
|
Icon Naming Specification</ulink>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--id=</option></term>
|
|
<listitem><para>Specify an identifier for this password
|
|
query. This identifier is freely choosable and allows
|
|
recognition of queries by involved agents. It should include
|
|
the subsystem doing the query and the specific object the
|
|
query is done for. Example:
|
|
<literal>--id=cryptsetup:/dev/sda5</literal>.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--keyname=</option></term>
|
|
<listitem><para>Configure a kernel keyring key name to use as
|
|
cache for the password. If set, then the tool will try to push
|
|
any collected passwords into the kernel keyring of the root
|
|
user, as a key of the specified name. If combined with
|
|
<option>--accept-cached</option> it will also try to retrieve
|
|
the such cached passwords from the key in the kernel keyring
|
|
instead of querying the user right-away. By using this option
|
|
the kernel keyring may be used as effective cache to avoid
|
|
repeatedly asking users for passwords, if there are multiple
|
|
objects that may be unlocked with the same password. The
|
|
cached key will have a timeout of 2.5min set, after which it
|
|
will be purged from the kernel keyring. Note that it is
|
|
possible to cache multiple passwords under the same keyname,
|
|
in which case they will be stored as NUL-separated list of
|
|
passwords. Use
|
|
<citerefentry><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
to access the cached key via the kernel keyring
|
|
directly. Example: <literal>--keyname=cryptsetup</literal></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--timeout=</option></term>
|
|
|
|
<listitem><para>Specify the query timeout in seconds. Defaults
|
|
to 90s. A timeout of 0 waits indefinitely. </para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--echo</option></term>
|
|
|
|
<listitem><para>Echo the user input instead of masking it.
|
|
This is useful when using
|
|
<filename>systemd-ask-password</filename> to query for
|
|
usernames. </para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--no-tty</option></term>
|
|
|
|
<listitem><para>Never ask for password on current TTY even if
|
|
one is available. Always use agent system.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--accept-cached</option></term>
|
|
|
|
<listitem><para>If passed, accept cached passwords, i.e.
|
|
passwords previously typed in. </para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--multiple</option></term>
|
|
|
|
<listitem><para>When used in conjunction with
|
|
<option>--accept-cached</option> accept multiple passwords.
|
|
This will output one password per line.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<xi:include href="standard-options.xml" xpointer="help" />
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Exit status</title>
|
|
|
|
<para>On success, 0 is returned, a non-zero failure code
|
|
otherwise.</para>
|
|
</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>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
|
<citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|