systemd-ask-password.xml revision f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering "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
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering under the terms of the GNU General Public License as published by
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering the Free Software Foundation; either version 2 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
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering General Public License for more details.
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering You should have received a copy of the GNU General Public License
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <refentryinfo>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </authorgroup>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </refentryinfo>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <refentrytitle>systemd-ask-password</refentrytitle>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <refpurpose>Query the user for a system password</refpurpose>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <refsynopsisdiv>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </cmdsynopsis>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </refsynopsisdiv>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <para><command>systemd-ask-password</command> may be
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering used to query a system password or passphrase from the
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering user, using a question message specified on the
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering command line. When run from a TTY it will query a
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering password on the TTY and print it to STDOUT. When run
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering with no TTY or with <option>--no-tty</option> it will
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering query the password system-wide and allow active users
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering to respond via several agents. The latter is
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering only available to privileged processes.</para>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <para>The purpose of this tool is to query system-wide
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering passwords -- that is passwords not attached to a
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering specific user account. Examples include: unlocking
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering encrypted hard disks when they are plugged in or at
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering boot, entering an SSL certificate passphrase for web
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering and VPN servers.</para>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <para>Existing agents are: a boot-time password agent
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering asking the user for passwords using Plymouth; a
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering boot-time password agent querying the user directly on
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering the console; an agent requesting password input via a
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering message; an agent suitable for running in a GNOME
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering session; a command line agent which can be started
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering temporarily to process queued password requests; a TTY
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering agent that is temporarily spawned during
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering invocations.</para>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <para>Additional password agents may be implemented
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering according to the <ulink
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering Password Agent Specification</ulink>.</para>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <para>If a password is queried on a tty the user may
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering press TAB to hide the asterisks normally shown for
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering each character typed. Pressing Backspace as first key
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering achieves the same effect.</para>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <para>The following options are understood:</para>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <variablelist>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering alongside the pasword query, which may
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering be used in all agents supporting
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering graphical display. The icon name
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering should follow the <ulink
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering on current TTY even if one is
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering available. Always use agent
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <term><option>--accept-cached</option></term>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering cached passwords, i.e. passwords
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering conjunction with
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering accept multiple passwords. This will
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering output one password per
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </varlistentry>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering </variablelist>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <para>On success 0 is returned, a non-zero failure
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering code otherwise.</para>
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <citerefentry><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
f3bc7fdc7bf47193a9f8618a7d22a6ceec2df6f7Lennart Poettering <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>