man/systemd-ask-password.xml

   1 <?xml version='1.0'?>
   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   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd-ask-password"
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>systemd-ask-password</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>systemd-ask-password</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>systemd-ask-password</refname>
  24     <refpurpose>Query the user for a system password</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command>
  30     </cmdsynopsis>
  31   </refsynopsisdiv>
  32
  33   <refsect1>
  34     <title>Description</title>
  35
  36     <para><command>systemd-ask-password</command> may be used to query
  37     a system password or passphrase from the user, using a question
  38     message specified on the command line. When run from a TTY it will
  39     query a password on the TTY and print it to standard output. When
  40     run with no TTY or with <option>--no-tty</option> it will use the
  41     system-wide query mechanism, which allows active users to respond via
  42     several agents, listed below.</para>
  43
  44     <para>The purpose of this tool is to query system-wide passwords
  45     — that is passwords not attached to a specific user account.
  46     Examples include: unlocking encrypted hard disks when they are
  47     plugged in or at boot, entering an SSL certificate passphrase for
  48     web and VPN servers.</para>
  49
  50     <para>Existing agents are:
  51     <itemizedlist>
  52
  53       <listitem><para>A boot-time password agent asking the user for
  54       passwords using
  55       <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  56       </para></listitem>
  57
  58       <listitem><para>A boot-time password agent querying the user
  59       directly on the console —
  60       <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  61       </para></listitem>
  62
  63       <listitem><para>An agent requesting password input via a
  64       <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  65       message —
  66       <citerefentry><refentrytitle>systemd-ask-password-wall.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
  67       </para></listitem>
  68
  69       <listitem><para>A TTY agent that is temporarily spawned during
  70       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  71       invocations,</para></listitem>
  72
  73       <listitem><para>A command line agent which can be started
  74       temporarily to process queued password
  75       requests — <command>systemd-tty-ask-password-agent --query</command>.
  76       </para></listitem>
  77     </itemizedlist></para>
  78
  79     <para>Answering system-wide password queries is a privileged operation, hence
  80     all the agents listed above (except for the last one), run as privileged
  81     system services. The last one also needs elevated privileges, so
  82     should be run through
  83     <citerefentry project='die-net'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  84     or similar.</para>
  85
  86     <para>Additional password agents may be implemented according to
  87     the <ulink
  88     url="https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd
  89     Password Agent Specification</ulink>.</para>
  90
  91     <para>If a password is queried on a TTY, the user may press TAB to
  92     hide the asterisks normally shown for each character typed.
  93     Pressing Backspace as first key achieves the same effect.</para>
  94
  95   </refsect1>
  96
  97   <refsect1>
  98     <title>Options</title>
  99
 100     <para>The following options are understood:</para>
 101
 102     <variablelist>
 103       <varlistentry>
 104         <term><option>--icon=</option></term>
 105
 106         <listitem><para>Specify an icon name alongside the password
 107         query, which may be used in all agents supporting graphical
 108         display. The icon name should follow the <ulink
 109         url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
 110         Icon Naming Specification</ulink>.</para></listitem>
 111       </varlistentry>
 112
 113       <varlistentry>
 114         <term><option>--id=</option></term>
 115         <listitem><para>Specify an identifier for this password
 116         query. This identifier is freely choosable and allows
 117         recognition of queries by involved agents. It should include
 118         the subsystem doing the query and the specific object the
 119         query is done for. Example:
 120         <literal>--id=cryptsetup:/dev/sda5</literal>.</para></listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><option>--keyname=</option></term>
 125         <listitem><para>Configure a kernel keyring key name to use as
 126         cache for the password. If set, then the tool will try to push
 127         any collected passwords into the kernel keyring of the root
 128         user, as a key of the specified name. If combined with
 129         <option>--accept-cached</option>, it will also try to retrieve
 130         such cached passwords from the key in the kernel keyring
 131         instead of querying the user right away. By using this option,
 132         the kernel keyring may be used as effective cache to avoid
 133         repeatedly asking users for passwords, if there are multiple
 134         objects that may be unlocked with the same password. The
 135         cached key will have a timeout of 2.5min set, after which it
 136         will be purged from the kernel keyring. Note that it is
 137         possible to cache multiple passwords under the same keyname,
 138         in which case they will be stored as NUL-separated list of
 139         passwords. Use
 140         <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 141         to access the cached key via the kernel keyring
 142         directly. Example: <literal>--keyname=cryptsetup</literal></para></listitem>
 143       </varlistentry>
 144
 145       <varlistentry>
 146         <term><option>--timeout=</option></term>
 147
 148         <listitem><para>Specify the query timeout in seconds. Defaults
 149         to 90s. A timeout of 0 waits indefinitely. </para></listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term><option>--echo</option></term>
 154
 155         <listitem><para>Echo the user input instead of masking it.
 156         This is useful when using
 157         <filename>systemd-ask-password</filename> to query for
 158         usernames. </para></listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term><option>--no-tty</option></term>
 163
 164         <listitem><para>Never ask for password on current TTY even if
 165         one is available. Always use agent system.</para></listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term><option>--accept-cached</option></term>
 170
 171         <listitem><para>If passed, accept cached passwords, i.e.
 172         passwords previously entered.</para></listitem>
 173       </varlistentry>
 174
 175       <varlistentry>
 176         <term><option>--multiple</option></term>
 177
 178         <listitem><para>When used in conjunction with
 179         <option>--accept-cached</option> accept multiple passwords.
 180         This will output one password per line.</para></listitem>
 181       </varlistentry>
 182
 183       <varlistentry>
 184         <term><option>--no-output</option></term>
 185
 186         <listitem><para>Do not print passwords to standard output.
 187         This is useful if you want to store a password in kernel
 188         keyring with <option>--keyname</option> but do not want it
 189         to show up on screen or in logs.</para></listitem>
 190       </varlistentry>
 191
 192       <xi:include href="standard-options.xml" xpointer="help" />
 193     </variablelist>
 194
 195   </refsect1>
 196
 197   <refsect1>
 198     <title>Exit status</title>
 199
 200     <para>On success, 0 is returned, a non-zero failure code
 201     otherwise.</para>
 202   </refsect1>
 203
 204   <refsect1>
 205     <title>See Also</title>
 206     <para>
 207       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 208       <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 209       <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 210       <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 211       <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 212       <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 213     </para>
 214   </refsect1>
 215
 216 </refentry>