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