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.5/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</command> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg>
  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>
 117
 118         <xi:include href="version-info.xml" xpointer="v227"/></listitem>
 119       </varlistentry>
 120
 121       <varlistentry>
 122         <term><option>--keyname=</option></term>
 123         <listitem><para>Configure a kernel keyring key name to use as
 124         cache for the password. If set, then the tool will try to push
 125         any collected passwords into the kernel keyring of the root
 126         user, as a key of the specified name. If combined with
 127         <option>--accept-cached</option>, it will also try to retrieve
 128         such cached passwords from the key in the kernel keyring
 129         instead of querying the user right away. By using this option,
 130         the kernel keyring may be used as effective cache to avoid
 131         repeatedly asking users for passwords, if there are multiple
 132         objects that may be unlocked with the same password. The
 133         cached key will have a timeout of 2.5min set, after which it
 134         will be purged from the kernel keyring. Note that it is
 135         possible to cache multiple passwords under the same keyname,
 136         in which case they will be stored as <constant>NUL</constant>-separated list of
 137         passwords. Use
 138         <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 139         to access the cached key via the kernel keyring
 140         directly. Example: <literal>--keyname=cryptsetup</literal></para>
 141
 142         <xi:include href="version-info.xml" xpointer="v227"/></listitem>
 143       </varlistentry>
 144
 145       <varlistentry>
 146         <term><option>--credential=</option></term>
 147         <listitem><para>Configure a credential to read the password from – if it exists. This may be used in
 148         conjunction with the <varname>ImportCredential=</varname>, <varname>LoadCredential=</varname> and
 149         <varname>SetCredential=</varname> settings in unit files. See
 150         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 151         details. If not specified, defaults to <literal>password</literal>. This option has no effect if no
 152         credentials directory is passed to the program (i.e. <varname>$CREDENTIALS_DIRECTORY</varname> is not
 153         set) or if the no credential of the specified name exists.</para>
 154
 155         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><option>--timeout=</option></term>
 160
 161         <listitem><para>Specify the query timeout in seconds. Defaults
 162         to 90s. A timeout of 0 waits indefinitely. </para></listitem>
 163       </varlistentry>
 164
 165       <varlistentry>
 166         <term><option>--echo=yes|no|masked</option></term>
 167
 168         <listitem><para>Controls whether to echo user input. Takes a boolean or the special string
 169         <literal>masked</literal>, the default being the latter. If enabled the typed characters are echoed
 170         literally, which is useful for prompting for usernames and other non-protected data. If disabled the
 171         typed characters are not echoed in any form, the user will not get feedback on their input. If set to
 172         <literal>masked</literal>, an asterisk (<literal>*</literal>) is echoed for each character
 173         typed. In this mode, if the user hits the tabulator key (<literal>↹</literal>), echo is turned
 174         off. (Alternatively, if the user hits the backspace key (<literal>⌫</literal>) while no data has
 175         been entered otherwise, echo is turned off, too).</para>
 176
 177         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><option>--echo</option></term>
 182         <term><option>-e</option></term>
 183
 184         <listitem><para>Equivalent to <option>--echo=yes</option>, see above.</para>
 185
 186         <xi:include href="version-info.xml" xpointer="v217"/></listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term><option>--emoji=yes|no|auto</option></term>
 191
 192         <listitem><para>Controls whether or not to prefix the query with a
 193         lock and key emoji (🔐), if the TTY settings permit this. The default
 194         is <literal>auto</literal>, which defaults to <literal>yes</literal>,
 195         unless <option>--echo=yes</option> is given.</para>
 196
 197         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term><option>--no-tty</option></term>
 202
 203         <listitem><para>Never ask for password on current TTY even if
 204         one is available. Always use agent system.</para></listitem>
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term><option>--accept-cached</option></term>
 209
 210         <listitem><para>If passed, accept cached passwords, i.e.
 211         passwords previously entered.</para></listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><option>--multiple</option></term>
 216
 217         <listitem><para>When used in conjunction with
 218         <option>--accept-cached</option> accept multiple passwords.
 219         This will output one password per line.</para></listitem>
 220       </varlistentry>
 221
 222       <varlistentry>
 223         <term><option>--no-output</option></term>
 224
 225         <listitem><para>Do not print passwords to standard output.  This is useful if you want to store a
 226         password in kernel keyring with <option>--keyname=</option> but do not want it to show up on screen
 227         or in logs.</para>
 228
 229         <xi:include href="version-info.xml" xpointer="v230"/></listitem>
 230       </varlistentry>
 231
 232       <varlistentry>
 233         <term><option>-n</option></term>
 234
 235         <listitem><para>By default, when the acquired password is written to standard output it is suffixed
 236         by a newline character. This may be turned off with the <option>-n</option> switch, similarly to the
 237         switch of the same name of the <citerefentry
 238         project='man-pages'><refentrytitle>echo</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 239         command.</para>
 240
 241         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 242       </varlistentry>
 243
 244       <xi:include href="standard-options.xml" xpointer="help" />
 245     </variablelist>
 246
 247   </refsect1>
 248
 249   <refsect1>
 250     <title>Exit status</title>
 251
 252     <para>On success, 0 is returned, a non-zero failure code
 253     otherwise.</para>
 254   </refsect1>
 255
 256   <refsect1>
 257     <title>See Also</title>
 258     <para><simplelist type="inline">
 259       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 260       <member><citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 261       <member><citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 262       <member><citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 263       <member><citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 264       <member><citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 265     </simplelist></para>
 266   </refsect1>
 267
 268 </refentry>