systemd-ask-password.xml revision e287086b8aa2558356af225a12d9bfea8e7d61ca
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering This file is part of systemd.
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering Copyright 2011 Lennart Poettering
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering systemd is free software; you can redistribute it and/or modify it
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering under the terms of the GNU Lesser General Public License as published by
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering (at your option) any later version.
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering systemd is distributed in the hope that it will be useful, but
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering Lesser General Public License for more details.
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering You should have received a copy of the GNU Lesser General Public License
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
dfdebb1b925332352966804303b2516a6506a429Zbigniew Jędrzejewski-Szmek<refentry id="systemd-ask-password"
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek xmlns:xi="http://www.w3.org/2001/XInclude">
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>systemd-ask-password</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>systemd-ask-password</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>systemd-ask-password</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Query the user for a system password</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><command>systemd-ask-password</command> may be used to query
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek a system password or passphrase from the user, using a question
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek message specified on the command line. When run from a TTY it will
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek query a password on the TTY and print it to standard output. When
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek run with no TTY or with <option>--no-tty</option> it will query
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the password system-wide and allow active users to respond via
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek several agents. The latter is only available to privileged
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek processes.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The purpose of this tool is to query system-wide passwords
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek -- that is passwords not attached to a specific user account.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Examples include: unlocking encrypted hard disks when they are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek plugged in or at boot, entering an SSL certificate passphrase for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek web and VPN servers.</para>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <para>Existing agents are:
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <itemizedlist>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <listitem><para>A boot-time password agent asking the user for
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering passwords using Plymouth</para></listitem>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <listitem><para>A boot-time password agent querying the user
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering directly on the console</para></listitem>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <listitem><para>An agent requesting password input via a
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <listitem><para>A command line agent which can be started
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering temporarily to process queued password
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <listitem><para>A TTY agent that is temporarily spawned during
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Additional password agents may be implemented according to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Password Agent Specification</ulink>.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If a password is queried on a TTY, the user may press TAB to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek hide the asterisks normally shown for each character typed.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Pressing Backspace as first key achieves the same effect.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The following options are understood:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--icon=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Specify an icon name alongside the password
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek query, which may be used in all agents supporting graphical
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek display. The icon name should follow the <ulink
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Icon Naming Specification</ulink>.</para></listitem>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <varlistentry>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <listitem><para>Specify an identifier for this password
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering query. This identifier is freely choosable and allows
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering recognition of queries by involved agents. It should include
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering the subsystem doing the query and the specific object the
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering query is done for. Example:
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <literal>--id=cryptsetup:/dev/sda5</literal>.</para></listitem>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering </varlistentry>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <varlistentry>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <listitem><para>Configure a kernel keyring key name to use as
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering cache for the password. If set, then the tool will try to push
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering any collected passwords into the kernel keyring of the root
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering user, as a key of the specified name. If combined with
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <option>--accept-cached</option> it will also try to retrieve
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering the such cached passwords from the key in the kernel keyring
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering instead of querying the user right-away. By using this option
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering the kernel keyring may be used as effective cache to avoid
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering repeatedly asking users for passwords, if there are multiple
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering objects that may be unlocked with the same password. The
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering cached key will have a timeout of 2.5min set, after which it
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering will be purged from the kernel keyring. Note that it is
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering possible to cache multiple passwords under the same keyname,
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering in which case they will be stored as NUL-separated list of
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering passwords. Use
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <citerefentry><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering to access the cached key via the kernel keyring
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering directly. Example: <literal>--keyname=cryptsetup</literal></para></listitem>
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--timeout=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Specify the query timeout in seconds. Defaults
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to 90s. A timeout of 0 waits indefinitely. </para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--echo</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Echo the user input instead of masking it.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This is useful when using
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>systemd-ask-password</filename> to query for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--no-tty</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Never ask for password on current TTY even if
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek one is available. Always use agent system.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--accept-cached</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>If passed, accept cached passwords, i.e.
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering passwords previously typed in. </para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--multiple</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>When used in conjunction with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--accept-cached</option> accept multiple passwords.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This will output one password per line.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="help" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>On success, 0 is returned, a non-zero failure code
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek otherwise.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
e287086b8aa2558356af225a12d9bfea8e7d61caLennart Poettering <citerefentry><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>