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