1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2011 Lennart Poettering
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
26 <refentry id=
"systemd-ask-password"
27 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
30 <title>systemd-ask-password
</title>
31 <productname>systemd
</productname>
35 <contrib>Developer
</contrib>
36 <firstname>Lennart
</firstname>
37 <surname>Poettering
</surname>
38 <email>lennart@poettering.net
</email>
44 <refentrytitle>systemd-ask-password
</refentrytitle>
45 <manvolnum>1</manvolnum>
49 <refname>systemd-ask-password
</refname>
50 <refpurpose>Query the user for a system password
</refpurpose>
55 <command>systemd-ask-password
<arg choice=
"opt" rep=
"repeat">OPTIONS
</arg> <arg choice=
"opt">MESSAGE
</arg></command>
60 <title>Description
</title>
62 <para><command>systemd-ask-password
</command> may be used to query
63 a system password or passphrase from the user, using a question
64 message specified on the command line. When run from a TTY it will
65 query a password on the TTY and print it to standard output. When
66 run with no TTY or with
<option>--no-tty
</option> it will use the
67 system-wide query mechanism, which allows active users to respond via
68 several agents, listed below.
</para>
70 <para>The purpose of this tool is to query system-wide passwords
71 — that is passwords not attached to a specific user account.
72 Examples include: unlocking encrypted hard disks when they are
73 plugged in or at boot, entering an SSL certificate passphrase for
74 web and VPN servers.
</para>
76 <para>Existing agents are:
79 <listitem><para>A boot-time password agent asking the user for
81 <citerefentry project='die-net'
><refentrytitle>plymouth
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
84 <listitem><para>A boot-time password agent querying the user
85 directly on the console —
86 <citerefentry><refentrytitle>systemd-ask-password-console.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
89 <listitem><para>An agent requesting password input via a
90 <citerefentry project='man-pages'
><refentrytitle>wall
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
92 <citerefentry><refentrytitle>systemd-ask-password-wall.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
95 <listitem><para>A TTY agent that is temporarily spawned during
96 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
97 invocations,
</para></listitem>
99 <listitem><para>A command line agent which can be started
100 temporarily to process queued password
101 requests —
<command>systemd-tty-ask-password-agent --query
</command>.
103 </itemizedlist></para>
105 <para>Answering system-wide password queries is a privileged operation, hence
106 all the agents listed above (except for the last one), run as privileged
107 system services. The last one also needs elevated privileges, so
108 should be run through
109 <citerefentry project='die-net'
><refentrytitle>sudo
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
112 <para>Additional password agents may be implemented according to
114 url=
"https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd
115 Password Agent Specification
</ulink>.
</para>
117 <para>If a password is queried on a TTY, the user may press TAB to
118 hide the asterisks normally shown for each character typed.
119 Pressing Backspace as first key achieves the same effect.
</para>
124 <title>Options
</title>
126 <para>The following options are understood:
</para>
130 <term><option>--icon=
</option></term>
132 <listitem><para>Specify an icon name alongside the password
133 query, which may be used in all agents supporting graphical
134 display. The icon name should follow the
<ulink
135 url=
"http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
136 Icon Naming Specification
</ulink>.
</para></listitem>
140 <term><option>--id=
</option></term>
141 <listitem><para>Specify an identifier for this password
142 query. This identifier is freely choosable and allows
143 recognition of queries by involved agents. It should include
144 the subsystem doing the query and the specific object the
145 query is done for. Example:
146 <literal>--id=cryptsetup:/dev/sda5
</literal>.
</para></listitem>
150 <term><option>--keyname=
</option></term>
151 <listitem><para>Configure a kernel keyring key name to use as
152 cache for the password. If set, then the tool will try to push
153 any collected passwords into the kernel keyring of the root
154 user, as a key of the specified name. If combined with
155 <option>--accept-cached
</option>, it will also try to retrieve
156 such cached passwords from the key in the kernel keyring
157 instead of querying the user right away. By using this option,
158 the kernel keyring may be used as effective cache to avoid
159 repeatedly asking users for passwords, if there are multiple
160 objects that may be unlocked with the same password. The
161 cached key will have a timeout of
2.5min set, after which it
162 will be purged from the kernel keyring. Note that it is
163 possible to cache multiple passwords under the same keyname,
164 in which case they will be stored as NUL-separated list of
166 <citerefentry project='die-net'
><refentrytitle>keyctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
167 to access the cached key via the kernel keyring
168 directly. Example:
<literal>--keyname=cryptsetup
</literal></para></listitem>
172 <term><option>--timeout=
</option></term>
174 <listitem><para>Specify the query timeout in seconds. Defaults
175 to
90s. A timeout of
0 waits indefinitely.
</para></listitem>
179 <term><option>--echo
</option></term>
181 <listitem><para>Echo the user input instead of masking it.
182 This is useful when using
183 <filename>systemd-ask-password
</filename> to query for
184 usernames.
</para></listitem>
188 <term><option>--no-tty
</option></term>
190 <listitem><para>Never ask for password on current TTY even if
191 one is available. Always use agent system.
</para></listitem>
195 <term><option>--accept-cached
</option></term>
197 <listitem><para>If passed, accept cached passwords, i.e.
198 passwords previously entered.
</para></listitem>
202 <term><option>--multiple
</option></term>
204 <listitem><para>When used in conjunction with
205 <option>--accept-cached
</option> accept multiple passwords.
206 This will output one password per line.
</para></listitem>
210 <term><option>--no-output
</option></term>
212 <listitem><para>Do not print passwords to standard output.
213 This is useful if you want to store a password in kernel
214 keyring with
<option>--keyname
</option> but do not want it
215 to show up on screen or in logs.
</para></listitem>
218 <xi:include href=
"standard-options.xml" xpointer=
"help" />
224 <title>Exit status
</title>
226 <para>On success,
0 is returned, a non-zero failure code
231 <title>See Also
</title>
233 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
234 <citerefentry><refentrytitle>systemd-ask-password-console.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
235 <citerefentry><refentrytitle>systemd-tty-ask-password-agent
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
236 <citerefentry project='die-net'
><refentrytitle>keyctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
237 <citerefentry project='die-net'
><refentrytitle>plymouth
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
238 <citerefentry project='man-pages'
><refentrytitle>wall
</refentrytitle><manvolnum>1</manvolnum></citerefentry>