systemd-ask-password.xml revision a45ad38bec7edb577b1130010ebef9c750474beb
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering This file is part of systemd.
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering Copyright 2011 Lennart Poettering
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering systemd is free software; you can redistribute it and/or modify it
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering under the terms of the GNU Lesser General Public License as published by
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering (at your option) any later version.
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering systemd is distributed in the hope that it will be useful, but
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering Lesser General Public License for more details.
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering You should have received a copy of the GNU Lesser General Public License
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <refentryinfo>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering </authorgroup>
9473414219330b9febc1d0712bbf49ad74cf962fLennart Poettering </refentryinfo>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <refentrytitle>systemd-ask-password</refentrytitle>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <refpurpose>Query the user for a system password</refpurpose>
0d0f0c50d3a1d90f03972a6abb82e6413daaa583Shawn Landden <refsynopsisdiv>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering </cmdsynopsis>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering </refsynopsisdiv>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <para><command>systemd-ask-password</command> may be
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering used to query a system password or passphrase from the
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering user, using a question message specified on the
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering command line. When run from a TTY it will query a
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering password on the TTY and print it to STDOUT. When run
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering with no TTY or with <option>--no-tty</option> it will
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering query the password system-wide and allow active users
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering to respond via several agents. The latter is
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering only available to privileged processes.</para>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <para>The purpose of this tool is to query system-wide
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering passwords -- that is passwords not attached to a
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering specific user account. Examples include: unlocking
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering encrypted hard disks when they are plugged in or at
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering boot, entering an SSL certificate passphrase for web
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering and VPN servers.</para>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <para>Existing agents are: a boot-time password agent
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering asking the user for passwords using Plymouth; a
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering boot-time password agent querying the user directly on
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering the console; an agent requesting password input via a
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering message; an agent suitable for running in a GNOME
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering session; a command line agent which can be started
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering temporarily to process queued password requests; a TTY
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering agent that is temporarily spawned during
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering invocations.</para>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <para>Additional password agents may be implemented
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering according to the <ulink
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering Password Agent Specification</ulink>.</para>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <para>If a password is queried on a tty the user may
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering press TAB to hide the asterisks normally shown for
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering each character typed. Pressing Backspace as first key
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering achieves the same effect.</para>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <para>The following options are understood:</para>
b7def684941808600c344f0be7a2b9fcdda97e0fLennart Poettering <variablelist>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <varlistentry>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering </varlistentry>
67ab5f761f9b854d8ce85f9ee47b298e497f8bd9Tom Gundersen <varlistentry>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering alongside the password query, which may
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering be used in all agents supporting
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering graphical display. The icon name
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering should follow the <ulink
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering </varlistentry>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <varlistentry>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering timeout in seconds. Defaults to
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering </varlistentry>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <varlistentry>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering on current TTY even if one is
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering available. Always use agent
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering </varlistentry>
40b8acd039cf1ea00167017e63d9c0a773002f0eMichal Schmidt <varlistentry>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <term><option>--accept-cached</option></term>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering cached passwords, i.e. passwords
b7def684941808600c344f0be7a2b9fcdda97e0fLennart Poettering </varlistentry>
0d0f0c50d3a1d90f03972a6abb82e6413daaa583Shawn Landden <varlistentry>
d2e54fae5ca7a0f71b5ac8b356a589ff0a09ea0aKay Sievers conjunction with
40b8acd039cf1ea00167017e63d9c0a773002f0eMichal Schmidt accept multiple passwords. This will
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering output one password per
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering </varlistentry>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering </variablelist>
b7def684941808600c344f0be7a2b9fcdda97e0fLennart Poettering <para>On success 0 is returned, a non-zero failure
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering code otherwise.</para>
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
40b8acd039cf1ea00167017e63d9c0a773002f0eMichal Schmidt <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <citerefentry><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
6b1dc2bd3cdb3bd932b0692be636ddd2879edb92Lennart Poettering <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>