chiark / gitweb /
bash: Add host, privileged, and no-pager bash option completions.
[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 General Public License as published by
12   the Free Software Foundation; either version 2 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   General Public License for more details.
19
20   You should have received a copy of the GNU General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="systemd-ask-password">
25
26         <refentryinfo>
27                 <title>systemd-ask-password</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>systemd-ask-password</refentrytitle>
42                 <manvolnum>1</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>systemd-ask-password</refname>
47                 <refpurpose>Query the user for a system password</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <cmdsynopsis>
52                         <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command>
53                 </cmdsynopsis>
54         </refsynopsisdiv>
55
56         <refsect1>
57                 <title>Description</title>
58
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>
68
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>
75
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>
86                 invocations.</para>
87
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>
92
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>
97
98         </refsect1>
99
100         <refsect1>
101                 <title>Options</title>
102
103                 <para>The following options are understood:</para>
104
105                 <variablelist>
106                         <varlistentry>
107                                 <term><option>--h</option></term>
108                                 <term><option>--help</option></term>
109
110                                 <listitem><para>Prints a short help
111                                 text and exits.</para></listitem>
112                         </varlistentry>
113
114                         <varlistentry>
115                                 <term><option>--icon=</option></term>
116
117                                 <listitem><para>Specify an icon name
118                                 alongside the pasword 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
123                                 Icon Naming
124                                 Specification</ulink>.</para></listitem>
125                         </varlistentry>
126
127                         <varlistentry>
128                                 <term><option>--timeout=</option></term>
129
130                                 <listitem><para>Specify the query
131                                 timeout in seconds. Defaults to
132                                 90s.</para></listitem>
133                         </varlistentry>
134
135                         <varlistentry>
136                                 <term><option>--no-tty</option></term>
137
138                                 <listitem><para>Never ask for password
139                                 on current TTY even if one is
140                                 available. Always use agent
141                                 system.</para></listitem>
142                         </varlistentry>
143
144                         <varlistentry>
145                                 <term><option>--accept-cached</option></term>
146
147                                 <listitem><para>If passed accept
148                                 cached passwords, i.e. passwords
149                                 previously typed in.</para></listitem>
150                         </varlistentry>
151
152                         <varlistentry>
153                                 <term><option>--multiple</option></term>
154
155                                 <listitem><para>When used in
156                                 conjunction with
157                                 <option>--accept-cached</option>
158                                 accept multiple passwords. This will
159                                 output one password per
160                                 line.</para></listitem>
161                         </varlistentry>
162                 </variablelist>
163
164         </refsect1>
165
166         <refsect1>
167                 <title>Exit status</title>
168
169                 <para>On success 0 is returned, a non-zero failure
170                 code otherwise.</para>
171         </refsect1>
172
173         <refsect1>
174                 <title>See Also</title>
175                 <para>
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>
180                 </para>
181         </refsect1>
182
183 </refentry>