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+ -->
   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
  85     url="https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd
  86     Password Agent Specification</ulink>.</para>
  87
  88     <para>If a password is queried on a TTY, the user may press TAB to
  89     hide the asterisks normally shown for each character typed.
  90     Pressing Backspace as first key achieves the same effect.</para>
  91
  92   </refsect1>
  93
  94   <refsect1>
  95     <title>Options</title>
  96
  97     <para>The following options are understood:</para>
  98
  99     <variablelist>
 100       <varlistentry>
 101         <term><option>--icon=</option></term>
 102
 103         <listitem><para>Specify an icon name alongside the password
 104         query, which may be used in all agents supporting graphical
 105         display. The icon name should follow the <ulink
 106         url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
 107         Icon Naming Specification</ulink>.</para></listitem>
 108       </varlistentry>
 109
 110       <varlistentry>
 111         <term><option>--id=</option></term>
 112         <listitem><para>Specify an identifier for this password
 113         query. This identifier is freely choosable and allows
 114         recognition of queries by involved agents. It should include
 115         the subsystem doing the query and the specific object the
 116         query is done for. Example:
 117         <literal>--id=cryptsetup:/dev/sda5</literal>.</para></listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term><option>--keyname=</option></term>
 122         <listitem><para>Configure a kernel keyring key name to use as
 123         cache for the password. If set, then the tool will try to push
 124         any collected passwords into the kernel keyring of the root
 125         user, as a key of the specified name. If combined with
 126         <option>--accept-cached</option>, it will also try to retrieve
 127         such cached passwords from the key in the kernel keyring
 128         instead of querying the user right away. By using this option,
 129         the kernel keyring may be used as effective cache to avoid
 130         repeatedly asking users for passwords, if there are multiple
 131         objects that may be unlocked with the same password. The
 132         cached key will have a timeout of 2.5min set, after which it
 133         will be purged from the kernel keyring. Note that it is
 134         possible to cache multiple passwords under the same keyname,
 135         in which case they will be stored as NUL-separated list of
 136         passwords. Use
 137         <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 138         to access the cached key via the kernel keyring
 139         directly. Example: <literal>--keyname=cryptsetup</literal></para></listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><option>--timeout=</option></term>
 144
 145         <listitem><para>Specify the query timeout in seconds. Defaults
 146         to 90s. A timeout of 0 waits indefinitely. </para></listitem>
 147       </varlistentry>
 148
 149       <varlistentry>
 150         <term><option>--echo</option></term>
 151
 152         <listitem><para>Echo the user input instead of masking it.
 153         This is useful when using
 154         <filename>systemd-ask-password</filename> to query for
 155         usernames. </para></listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><option>--no-tty</option></term>
 160
 161         <listitem><para>Never ask for password on current TTY even if
 162         one is available. Always use agent system.</para></listitem>
 163       </varlistentry>
 164
 165       <varlistentry>
 166         <term><option>--accept-cached</option></term>
 167
 168         <listitem><para>If passed, accept cached passwords, i.e.
 169         passwords previously entered.</para></listitem>
 170       </varlistentry>
 171
 172       <varlistentry>
 173         <term><option>--multiple</option></term>
 174
 175         <listitem><para>When used in conjunction with
 176         <option>--accept-cached</option> accept multiple passwords.
 177         This will output one password per line.</para></listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><option>--no-output</option></term>
 182
 183         <listitem><para>Do not print passwords to standard output.
 184         This is useful if you want to store a password in kernel
 185         keyring with <option>--keyname</option> but do not want it
 186         to show up on screen or in logs.</para></listitem>
 187       </varlistentry>
 188
 189       <xi:include href="standard-options.xml" xpointer="help" />
 190     </variablelist>
 191
 192   </refsect1>
 193
 194   <refsect1>
 195     <title>Exit status</title>
 196
 197     <para>On success, 0 is returned, a non-zero failure code
 198     otherwise.</para>
 199   </refsect1>
 200
 201   <refsect1>
 202     <title>See Also</title>
 203     <para>
 204       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 205       <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 206       <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 207       <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 208       <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 209       <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 210     </para>
 211   </refsect1>
 212
 213 </refentry>