man/systemd-ask-password.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-ask-password"
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-ask-password</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-ask-password</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-ask-password</refname>
  21     <refpurpose>Query the user for a system password</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command>
  27     </cmdsynopsis>
  28   </refsynopsisdiv>
  29
  30   <refsect1>
  31     <title>Description</title>
  32
  33     <para><command>systemd-ask-password</command> may be used to query
  34     a system password or passphrase from the user, using a question
  35     message specified on the command line. When run from a TTY it will
  36     query a password on the TTY and print it to standard output. When
  37     run with no TTY or with <option>--no-tty</option> it will use the
  38     system-wide query mechanism, which allows active users to respond via
  39     several agents, listed below.</para>
  40
  41     <para>The purpose of this tool is to query system-wide passwords
  42     — that is passwords not attached to a specific user account.
  43     Examples include: unlocking encrypted hard disks when they are
  44     plugged in or at boot, entering an SSL certificate passphrase for
  45     web and VPN servers.</para>
  46
  47     <para>Existing agents are:
  48     <itemizedlist>
  49
  50       <listitem><para>A boot-time password agent asking the user for
  51       passwords using
  52       <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  53       </para></listitem>
  54
  55       <listitem><para>A boot-time password agent querying the user
  56       directly on the console —
  57       <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  58       </para></listitem>
  59
  60       <listitem><para>An agent requesting password input via a
  61       <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  62       message —
  63       <citerefentry><refentrytitle>systemd-ask-password-wall.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  64       </para></listitem>
  65
  66       <listitem><para>A TTY agent that is temporarily spawned during
  67       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  68       invocations,</para></listitem>
  69
  70       <listitem><para>A command line agent which can be started
  71       temporarily to process queued password
  72       requests — <command>systemd-tty-ask-password-agent --query</command>.
  73       </para></listitem>
  74     </itemizedlist></para>
  75
  76     <para>Answering system-wide password queries is a privileged operation, hence
  77     all the agents listed above (except for the last one), run as privileged
  78     system services. The last one also needs elevated privileges, so
  79     should be run through
  80     <citerefentry project='die-net'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  81     or similar.</para>
  82
  83     <para>Additional password agents may be implemented according to
  84     the <ulink url="https://systemd.io/PASSWORD_AGENTS/">systemd Password Agent
  85     Specification</ulink>.</para>
  86
  87     <para>If a password is queried on a TTY, the user may press TAB to
  88     hide the asterisks normally shown for each character typed.
  89     Pressing Backspace as first key achieves the same effect.</para>
  90
  91   </refsect1>
  92
  93   <refsect1>
  94     <title>Options</title>
  95
  96     <para>The following options are understood:</para>
  97
  98     <variablelist>
  99       <varlistentry>
 100         <term><option>--icon=</option></term>
 101
 102         <listitem><para>Specify an icon name alongside the password
 103         query, which may be used in all agents supporting graphical
 104         display. The icon name should follow the <ulink
 105         url="https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
 106         Icon Naming Specification</ulink>.</para></listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><option>--id=</option></term>
 111         <listitem><para>Specify an identifier for this password
 112         query. This identifier is freely choosable and allows
 113         recognition of queries by involved agents. It should include
 114         the subsystem doing the query and the specific object the
 115         query is done for. Example:
 116         <literal>--id=cryptsetup:/dev/sda5</literal>.</para></listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term><option>--keyname=</option></term>
 121         <listitem><para>Configure a kernel keyring key name to use as
 122         cache for the password. If set, then the tool will try to push
 123         any collected passwords into the kernel keyring of the root
 124         user, as a key of the specified name. If combined with
 125         <option>--accept-cached</option>, it will also try to retrieve
 126         such cached passwords from the key in the kernel keyring
 127         instead of querying the user right away. By using this option,
 128         the kernel keyring may be used as effective cache to avoid
 129         repeatedly asking users for passwords, if there are multiple
 130         objects that may be unlocked with the same password. The
 131         cached key will have a timeout of 2.5min set, after which it
 132         will be purged from the kernel keyring. Note that it is
 133         possible to cache multiple passwords under the same keyname,
 134         in which case they will be stored as <constant>NUL</constant>-separated list of
 135         passwords. Use
 136         <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 137         to access the cached key via the kernel keyring
 138         directly. Example: <literal>--keyname=cryptsetup</literal></para></listitem>
 139       </varlistentry>
 140
 141       <varlistentry>
 142         <term><option>--credential=</option></term>
 143         <listitem><para>Configure a credential to read the password from – if it exists. This may be used in
 144         conjunction with the <varname>LoadCredential=</varname> and <varname>SetCredential=</varname>
 145         settings in unit files. See
 146         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 147         details. If not specified, defaults to <literal>password</literal>. This option has no effect if no
 148         credentials directory is passed to the program (i.e. <varname>$CREDENTIALS_DIRECTORY</varname> is not
 149         set) or if the no credential of the specified name exists.</para></listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term><option>--timeout=</option></term>
 154
 155         <listitem><para>Specify the query timeout in seconds. Defaults
 156         to 90s. A timeout of 0 waits indefinitely. </para></listitem>
 157       </varlistentry>
 158
 159       <varlistentry>
 160         <term><option>--echo=yes|no|masked</option></term>
 161
 162         <listitem><para>Controls whether to echo user input. Takes a boolean or the special string
 163         <literal>masked</literal>, the default being the latter. If enabled the typed characters are echoed
 164         literally, which is useful for prompting for usernames and other non-protected data. If disabled the
 165         typed characters are not echoed in any form, the user will not get feedback on their input. If set to
 166         <literal>masked</literal>, an asterisk (<literal>*</literal>) is echoed for each character
 167         typed. In this mode, if the user hits the tabulator key (<literal>↹</literal>), echo is turned
 168         off. (Alternatively, if the user hits the backspace key (<literal>⌫</literal>) while no data has
 169         been entered otherwise, echo is turned off, too).</para></listitem>
 170       </varlistentry>
 171
 172       <varlistentry>
 173         <term><option>--echo</option></term>
 174         <term><option>-e</option></term>
 175
 176         <listitem><para>Equivalent to <option>--echo=yes</option>, see above.</para></listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term><option>--emoji=yes|no|auto</option></term>
 181
 182         <listitem><para>Controls whether or not to prefix the query with a
 183         lock and key emoji (🔐), if the TTY settings permit this. The default
 184         is <literal>auto</literal>, which defaults to <literal>yes</literal>,
 185         unless <option>--echo=yes</option> is given.</para></listitem>
 186       </varlistentry>
 187
 188       <varlistentry>
 189         <term><option>--no-tty</option></term>
 190
 191         <listitem><para>Never ask for password on current TTY even if
 192         one is available. Always use agent system.</para></listitem>
 193       </varlistentry>
 194
 195       <varlistentry>
 196         <term><option>--accept-cached</option></term>
 197
 198         <listitem><para>If passed, accept cached passwords, i.e.
 199         passwords previously entered.</para></listitem>
 200       </varlistentry>
 201
 202       <varlistentry>
 203         <term><option>--multiple</option></term>
 204
 205         <listitem><para>When used in conjunction with
 206         <option>--accept-cached</option> accept multiple passwords.
 207         This will output one password per line.</para></listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term><option>--no-output</option></term>
 212
 213         <listitem><para>Do not print passwords to standard output.  This is useful if you want to store a
 214         password in kernel keyring with <option>--keyname=</option> but do not want it to show up on screen
 215         or in logs.</para></listitem>
 216       </varlistentry>
 217
 218       <varlistentry>
 219         <term><option>-n</option></term>
 220
 221         <listitem><para>By default, when writing the acquired password to standard output it is suffixed by a
 222         newline character. This may be turned off with the <option>-n</option> switch, similar to the switch
 223         of the same name of the <citerefentry
 224         project='man-pages'><refentrytitle>echo</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 225         command.</para></listitem>
 226       </varlistentry>
 227
 228       <xi:include href="standard-options.xml" xpointer="help" />
 229     </variablelist>
 230
 231   </refsect1>
 232
 233   <refsect1>
 234     <title>Exit status</title>
 235
 236     <para>On success, 0 is returned, a non-zero failure code
 237     otherwise.</para>
 238   </refsect1>
 239
 240   <refsect1>
 241     <title>See Also</title>
 242     <para>
 243       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 244       <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 245       <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 246       <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 247       <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 248       <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 249     </para>
 250   </refsect1>
 251
 252 </refentry>