man/systemd-ask-password.xml

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