1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2011 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="systemd-ask-password">
27 <title>systemd-ask-password</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemd-ask-password</refentrytitle>
42 <manvolnum>1</manvolnum>
46 <refname>systemd-ask-password</refname>
47 <refpurpose>Query the user for a system password</refpurpose>
52 <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command>
57 <title>Description</title>
59 <para><command>systemd-ask-password</command> may be
60 used to query a system password or passphrase from the
61 user, using a question message specified on the
62 command line. When run from a TTY it will query a
63 password on the TTY and print it to STDOUT. When run
64 with no TTY or with <option>--no-tty</option> it will
65 query the password system-wide and allow active users
66 to respond via several agents. The latter is
67 only available to privileged processes.</para>
69 <para>The purpose of this tool is to query system-wide
70 passwords -- that is passwords not attached to a
71 specific user account. Examples include: unlocking
72 encrypted hard disks when they are plugged in or at
73 boot, entering an SSL certificate passphrase for web
74 and VPN servers.</para>
76 <para>Existing agents are: a boot-time password agent
77 asking the user for passwords using Plymouth; a
78 boot-time password agent querying the user directly on
79 the console; an agent requesting password input via a
80 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
81 message; an agent suitable for running in a GNOME
82 session; a command line agent which can be started
83 temporarily to process queued password requests; a TTY
84 agent that is temporarily spawned during
85 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
88 <para>Additional password agents may be implemented
89 according to the <ulink
90 url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd
91 Password Agent Specification</ulink>.</para>
93 <para>If a password is queried on a TTY the user may
94 press TAB to hide the asterisks normally shown for
95 each character typed. Pressing Backspace as first key
96 achieves the same effect.</para>
101 <title>Options</title>
103 <para>The following options are understood:</para>
107 <term><option>-h</option></term>
108 <term><option>--help</option></term>
110 <listitem><para>Prints a short help
111 text and exits.</para></listitem>
115 <term><option>--icon=</option></term>
117 <listitem><para>Specify an icon name
118 alongside the password query, which may
119 be used in all agents supporting
120 graphical display. The icon name
121 should follow the <ulink
122 url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
124 Specification</ulink>.</para></listitem>
128 <term><option>--timeout=</option></term>
130 <listitem><para>Specify the query
131 timeout in seconds. Defaults to
132 90s.</para></listitem>
136 <term><option>--no-tty</option></term>
138 <listitem><para>Never ask for password
139 on current TTY even if one is
140 available. Always use agent
141 system.</para></listitem>
145 <term><option>--accept-cached</option></term>
147 <listitem><para>If passed accept
148 cached passwords, i.e. passwords
149 previously typed in.</para></listitem>
153 <term><option>--multiple</option></term>
155 <listitem><para>When used in
157 <option>--accept-cached</option>
158 accept multiple passwords. This will
159 output one password per
160 line.</para></listitem>
167 <title>Exit status</title>
169 <para>On success 0 is returned, a non-zero failure
170 code otherwise.</para>
174 <title>See Also</title>
176 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
177 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
178 <citerefentry><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
179 <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>