chiark / gitweb /
journald: move /dev/log socket to /run
[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><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>--no-tty</option></term>
131
132                                 <listitem><para>Never ask for password
133                                 on current TTY even if one is
134                                 available. Always use agent
135                                 system.</para></listitem>
136                         </varlistentry>
137
138                         <varlistentry>
139                                 <term><option>--accept-cached</option></term>
140
141                                 <listitem><para>If passed, accept
142                                 cached passwords, i.e. passwords
143                                 previously typed in.</para></listitem>
144                         </varlistentry>
145
146                         <varlistentry>
147                                 <term><option>--multiple</option></term>
148
149                                 <listitem><para>When used in
150                                 conjunction with
151                                 <option>--accept-cached</option>
152                                 accept multiple passwords. This will
153                                 output one password per
154                                 line.</para></listitem>
155                         </varlistentry>
156
157                         <xi:include href="standard-options.xml" xpointer="help" />
158                 </variablelist>
159
160         </refsect1>
161
162         <refsect1>
163                 <title>Exit status</title>
164
165                 <para>On success, 0 is returned, a non-zero failure
166                 code otherwise.</para>
167         </refsect1>
168
169         <refsect1>
170                 <title>See Also</title>
171                 <para>
172                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
173                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
174                         <citerefentry><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
175                         <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
176                 </para>
177         </refsect1>
178
179 </refentry>