chiark / gitweb /
import-raw: when downloading raw images, generate sparse files if we can
[elogind.git] / man / systemd-ask-password.xml
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">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2011 Lennart Poettering
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="systemd-ask-password"
25           xmlns:xi="http://www.w3.org/2001/XInclude">
26
27         <refentryinfo>
28                 <title>systemd-ask-password</title>
29                 <productname>systemd</productname>
30
31                 <authorgroup>
32                         <author>
33                                 <contrib>Developer</contrib>
34                                 <firstname>Lennart</firstname>
35                                 <surname>Poettering</surname>
36                                 <email>lennart@poettering.net</email>
37                         </author>
38                 </authorgroup>
39         </refentryinfo>
40
41         <refmeta>
42                 <refentrytitle>systemd-ask-password</refentrytitle>
43                 <manvolnum>1</manvolnum>
44         </refmeta>
45
46         <refnamediv>
47                 <refname>systemd-ask-password</refname>
48                 <refpurpose>Query the user for a system password</refpurpose>
49         </refnamediv>
50
51         <refsynopsisdiv>
52                 <cmdsynopsis>
53                         <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command>
54                 </cmdsynopsis>
55         </refsynopsisdiv>
56
57         <refsect1>
58                 <title>Description</title>
59
60                 <para><command>systemd-ask-password</command> may be
61                 used to query a system password or passphrase from the
62                 user, using a question message specified on the
63                 command line. When run from a TTY it will query a
64                 password on the TTY and print it to standard output. When run
65                 with no TTY or with <option>--no-tty</option> it will
66                 query the password system-wide and allow active users
67                 to respond via several agents. The latter is
68                 only available to privileged processes.</para>
69
70                 <para>The purpose of this tool is to query system-wide
71                 passwords -- that is passwords not attached to a
72                 specific user account. Examples include: unlocking
73                 encrypted hard disks when they are plugged in or at
74                 boot, entering an SSL certificate passphrase for web
75                 and VPN servers.</para>
76
77                 <para>Existing agents are: a boot-time password agent
78                 asking the user for passwords using Plymouth; a
79                 boot-time password agent querying the user directly on
80                 the console; an agent requesting password input via a
81                 <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
82                 message; an agent suitable for running in a GNOME
83                 session; a command line agent which can be started
84                 temporarily to process queued password requests; a TTY
85                 agent that is temporarily spawned during
86                 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
87                 invocations.</para>
88
89                 <para>Additional password agents may be implemented
90                 according to the <ulink
91                 url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd
92                 Password Agent Specification</ulink>.</para>
93
94                 <para>If a password is queried on a TTY, the user may
95                 press TAB to hide the asterisks normally shown for
96                 each character typed. Pressing Backspace as first key
97                 achieves the same effect.</para>
98
99         </refsect1>
100
101         <refsect1>
102                 <title>Options</title>
103
104                 <para>The following options are understood:</para>
105
106                 <variablelist>
107                         <varlistentry>
108                                 <term><option>--icon=</option></term>
109
110                                 <listitem><para>Specify an icon name
111                                 alongside the password query, which may
112                                 be used in all agents supporting
113                                 graphical display. The icon name
114                                 should follow the <ulink
115                                 url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
116                                 Icon Naming
117                                 Specification</ulink>.</para></listitem>
118                         </varlistentry>
119
120                         <varlistentry>
121                                 <term><option>--timeout=</option></term>
122
123                                 <listitem><para>Specify the query
124                                 timeout in seconds. Defaults to
125                                 90s. A timeout of 0 waits indefinitely.
126                                 </para></listitem>
127                         </varlistentry>
128
129                         <varlistentry>
130                                 <term><option>--echo</option></term>
131
132                                 <listitem><para>Echo the user input
133                                 instead of masking it. This is useful
134                                 when using
135                                 <filename>systemd-ask-password</filename>
136                                 to query for usernames.
137                                 </para></listitem>
138                         </varlistentry>
139
140                         <varlistentry>
141                                 <term><option>--no-tty</option></term>
142
143                                 <listitem><para>Never ask for password
144                                 on current TTY even if one is
145                                 available. Always use agent
146                                 system.</para></listitem>
147                         </varlistentry>
148
149                         <varlistentry>
150                                 <term><option>--accept-cached</option></term>
151
152                                 <listitem><para>If passed, accept
153                                 cached passwords, i.e. passwords
154                                 previously typed in.</para></listitem>
155                         </varlistentry>
156
157                         <varlistentry>
158                                 <term><option>--multiple</option></term>
159
160                                 <listitem><para>When used in
161                                 conjunction with
162                                 <option>--accept-cached</option>
163                                 accept multiple passwords. This will
164                                 output one password per
165                                 line.</para></listitem>
166                         </varlistentry>
167
168                         <xi:include href="standard-options.xml" xpointer="help" />
169                 </variablelist>
170
171         </refsect1>
172
173         <refsect1>
174                 <title>Exit status</title>
175
176                 <para>On success, 0 is returned, a non-zero failure
177                 code otherwise.</para>
178         </refsect1>
179
180         <refsect1>
181                 <title>See Also</title>
182                 <para>
183                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
184                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
185                         <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
186                         <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
187                 </para>
188         </refsect1>
189
190 </refentry>