[thirdparty/systemd.git] / man / systemd-ask-password.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="systemd-ask-password"
    xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>systemd-ask-password</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd-ask-password</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd-ask-password</refname>
    <refpurpose>Query the user for a system password</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>systemd-ask-password</command> may be used to query
    a system password or passphrase from the user, using a question
    message specified on the command line. When run from a TTY it will
    query a password on the TTY and print it to standard output. When
    run with no TTY or with <option>--no-tty</option> it will use the
    system-wide query mechanism, which allows active users to respond via
    several agents, listed below.</para>

    <para>The purpose of this tool is to query system-wide passwords
    — that is passwords not attached to a specific user account.
    Examples include: unlocking encrypted hard disks when they are
    plugged in or at boot, entering an SSL certificate passphrase for
    web and VPN servers.</para>

    <para>Existing agents are:
    <itemizedlist>

      <listitem><para>A boot-time password agent asking the user for
      passwords using
      <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      </para></listitem>

      <listitem><para>A boot-time password agent querying the user
      directly on the console —
      <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      </para></listitem>

      <listitem><para>An agent requesting password input via a
      <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
      message —
      <citerefentry><refentrytitle>systemd-ask-password-wall.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      </para></listitem>

      <listitem><para>A TTY agent that is temporarily spawned during
      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
      invocations,</para></listitem>

      <listitem><para>A command line agent which can be started
      temporarily to process queued password
      requests — <command>systemd-tty-ask-password-agent --query</command>.
      </para></listitem>
    </itemizedlist></para>

    <para>Answering system-wide password queries is a privileged operation, hence
    all the agents listed above (except for the last one), run as privileged
    system services. The last one also needs elevated privileges, so
    should be run through
    <citerefentry project='die-net'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    or similar.</para>

    <para>Additional password agents may be implemented according to
    the <ulink url="https://systemd.io/PASSWORD_AGENTS/">systemd Password Agent
    Specification</ulink>.</para>

    <para>If a password is queried on a TTY, the user may press TAB to
    hide the asterisks normally shown for each character typed.
    Pressing Backspace as first key achieves the same effect.</para>

  </refsect1>

  <refsect1>
    <title>Options</title>

    <para>The following options are understood:</para>

    <variablelist>
      <varlistentry>
        <term><option>--icon=</option></term>

        <listitem><para>Specify an icon name alongside the password
        query, which may be used in all agents supporting graphical
        display. The icon name should follow the <ulink
        url="https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
        Icon Naming Specification</ulink>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--id=</option></term>
        <listitem><para>Specify an identifier for this password
        query. This identifier is freely choosable and allows
        recognition of queries by involved agents. It should include
        the subsystem doing the query and the specific object the
        query is done for. Example:
        <literal>--id=cryptsetup:/dev/sda5</literal>.</para>

        <xi:include href="version-info.xml" xpointer="v227"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--keyname=</option></term>
        <listitem><para>Configure a kernel keyring key name to use as
        cache for the password. If set, then the tool will try to push
        any collected passwords into the kernel keyring of the root
        user, as a key of the specified name. If combined with
        <option>--accept-cached</option>, it will also try to retrieve
        such cached passwords from the key in the kernel keyring
        instead of querying the user right away. By using this option,
        the kernel keyring may be used as effective cache to avoid
        repeatedly asking users for passwords, if there are multiple
        objects that may be unlocked with the same password. The
        cached key will have a timeout of 2.5min set, after which it
        will be purged from the kernel keyring. Note that it is
        possible to cache multiple passwords under the same keyname,
        in which case they will be stored as <constant>NUL</constant>-separated list of
        passwords. Use
        <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
        to access the cached key via the kernel keyring
        directly. Example: <literal>--keyname=cryptsetup</literal></para>

        <xi:include href="version-info.xml" xpointer="v227"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--credential=</option></term>
        <listitem><para>Configure a credential to read the password from – if it exists. This may be used in
        conjunction with the <varname>ImportCredential=</varname>, <varname>LoadCredential=</varname> and
        <varname>SetCredential=</varname> settings in unit files. See
        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
        details. If not specified, defaults to <literal>password</literal>. This option has no effect if no
        credentials directory is passed to the program (i.e. <varname>$CREDENTIALS_DIRECTORY</varname> is not
        set) or if the no credential of the specified name exists.</para>

        <xi:include href="version-info.xml" xpointer="v249"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--timeout=</option></term>

        <listitem><para>Specify the query timeout in seconds. Defaults
        to 90s. A timeout of 0 waits indefinitely. </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--echo=yes|no|masked</option></term>

        <listitem><para>Controls whether to echo user input. Takes a boolean or the special string
        <literal>masked</literal>, the default being the latter. If enabled the typed characters are echoed
        literally, which is useful for prompting for usernames and other non-protected data. If disabled the
        typed characters are not echoed in any form, the user will not get feedback on their input. If set to
        <literal>masked</literal>, an asterisk (<literal>*</literal>) is echoed for each character
        typed. In this mode, if the user hits the tabulator key (<literal>↹</literal>), echo is turned
        off. (Alternatively, if the user hits the backspace key (<literal>⌫</literal>) while no data has
        been entered otherwise, echo is turned off, too).</para>

        <xi:include href="version-info.xml" xpointer="v249"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--echo</option></term>
        <term><option>-e</option></term>

        <listitem><para>Equivalent to <option>--echo=yes</option>, see above.</para>

        <xi:include href="version-info.xml" xpointer="v217"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--emoji=yes|no|auto</option></term>

        <listitem><para>Controls whether or not to prefix the query with a
        lock and key emoji (🔐), if the TTY settings permit this. The default
        is <literal>auto</literal>, which defaults to <literal>yes</literal>,
        unless <option>--echo=yes</option> is given.</para>

        <xi:include href="version-info.xml" xpointer="v249"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--no-tty</option></term>

        <listitem><para>Never ask for password on current TTY even if
        one is available. Always use agent system.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--accept-cached</option></term>

        <listitem><para>If passed, accept cached passwords, i.e.
        passwords previously entered.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--multiple</option></term>

        <listitem><para>When used in conjunction with
        <option>--accept-cached</option> accept multiple passwords.
        This will output one password per line.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--no-output</option></term>

        <listitem><para>Do not print passwords to standard output.  This is useful if you want to store a
        password in kernel keyring with <option>--keyname=</option> but do not want it to show up on screen
        or in logs.</para>

        <xi:include href="version-info.xml" xpointer="v230"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-n</option></term>

        <listitem><para>By default, when the acquired password is written to standard output it is suffixed
        by a newline character. This may be turned off with the <option>-n</option> switch, similarly to the
        switch of the same name of the <citerefentry
        project='man-pages'><refentrytitle>echo</refentrytitle><manvolnum>1</manvolnum></citerefentry>
        command.</para>

        <xi:include href="version-info.xml" xpointer="v249"/></listitem>
      </varlistentry>

      <xi:include href="standard-options.xml" xpointer="help" />
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Exit status</title>

    <para>On success, 0 is returned, a non-zero failure code
    otherwise.</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>
Commit	Line	Data
514094f9	1	<?xml version='1.0'?>
3a54a157	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
12b42c76	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
db9ecf05	4	<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
f3bc7fdc	5
dfdebb1b	6	<refentry id="systemd-ask-password"
798d3a52 ZJS	7	xmlns:xi="http://www.w3.org/2001/XInclude">
	8
	9	<refentryinfo>
	10	<title>systemd-ask-password</title>
	11	<productname>systemd</productname>
798d3a52 ZJS	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
c65aafbb ZJS	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>
798d3a52 ZJS	40
798d3a52 ZJS	41	<para>The purpose of this tool is to query system-wide passwords
ccddd104	42	— that is passwords not attached to a specific user account.
798d3a52 ZJS	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
e287086b LP	47	<para>Existing agents are:
	48	<itemizedlist>
	49
	50	<listitem><para>A boot-time password agent asking the user for
c65aafbb ZJS	51	passwords using
	52	<citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
	53	</para></listitem>
e287086b LP	54
e287086b LP	55	<listitem><para>A boot-time password agent querying the user
c65aafbb ZJS	56	directly on the console —
	57	<citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
	58	</para></listitem>
e287086b LP	59
e287086b LP	60	<listitem><para>An agent requesting password input via a
c65aafbb ZJS	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>
e287086b LP	65
	66	<listitem><para>A TTY agent that is temporarily spawned during
	67	<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
c65aafbb ZJS	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>
e287086b	74	</itemizedlist></para>
798d3a52	75
c65aafbb ZJS	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
798d3a52	83	<para>Additional password agents may be implemented according to
f856778b	84	the <ulink url="https://systemd.io/PASSWORD_AGENTS/">systemd Password Agent
f856778b	85	Specification</ulink>.</para>
798d3a52 ZJS	86
	87	<para>If a password is queried on a TTY, the user may press TAB to
	88	hide the asterisks normally shown for each character typed.
	89	Pressing Backspace as first key achieves the same effect.</para>
	90
	91	</refsect1>
	92
	93	<refsect1>
	94	<title>Options</title>
	95
	96	<para>The following options are understood:</para>
	97
	98	<variablelist>
	99	<varlistentry>
	100	<term><option>--icon=</option></term>
	101
	102	<listitem><para>Specify an icon name alongside the password
	103	query, which may be used in all agents supporting graphical
	104	display. The icon name should follow the <ulink
41d6f3bf	105	url="https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG
798d3a52 ZJS	106	Icon Naming Specification</ulink>.</para></listitem>
	107	</varlistentry>
	108
e287086b LP	109	<varlistentry>
	110	<term><option>--id=</option></term>
	111	<listitem><para>Specify an identifier for this password
	112	query. This identifier is freely choosable and allows
	113	recognition of queries by involved agents. It should include
	114	the subsystem doing the query and the specific object the
	115	query is done for. Example:
ec07c3c8 AK	116	<literal>--id=cryptsetup:/dev/sda5</literal>.</para>
	117
	118	<xi:include href="version-info.xml" xpointer="v227"/></listitem>
e287086b LP	119	</varlistentry>
	120
	121	<varlistentry>
	122	<term><option>--keyname=</option></term>
	123	<listitem><para>Configure a kernel keyring key name to use as
	124	cache for the password. If set, then the tool will try to push
	125	any collected passwords into the kernel keyring of the root
	126	user, as a key of the specified name. If combined with
b938cb90	127	<option>--accept-cached</option>, it will also try to retrieve
a8eaaee7	128	such cached passwords from the key in the kernel keyring
b938cb90	129	instead of querying the user right away. By using this option,
e287086b LP	130	the kernel keyring may be used as effective cache to avoid
	131	repeatedly asking users for passwords, if there are multiple
	132	objects that may be unlocked with the same password. The
	133	cached key will have a timeout of 2.5min set, after which it
	134	will be purged from the kernel keyring. Note that it is
	135	possible to cache multiple passwords under the same keyname,
6b44ad0b	136	in which case they will be stored as <constant>NUL</constant>-separated list of
e287086b	137	passwords. Use
524f3e5c	138	<citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
e287086b	139	to access the cached key via the kernel keyring
ec07c3c8 AK	140	directly. Example: <literal>--keyname=cryptsetup</literal></para>
	141
	142	<xi:include href="version-info.xml" xpointer="v227"/></listitem>
e287086b LP	143	</varlistentry>
e287086b LP	144
8806bb4b LP	145	<varlistentry>
	146	<term><option>--credential=</option></term>
	147	<listitem><para>Configure a credential to read the password from – if it exists. This may be used in
bbfb25f4 DDM	148	conjunction with the <varname>ImportCredential=</varname>, <varname>LoadCredential=</varname> and
bbfb25f4 DDM	149	<varname>SetCredential=</varname> settings in unit files. See
8806bb4b LP	150	<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
	151	details. If not specified, defaults to <literal>password</literal>. This option has no effect if no
	152	credentials directory is passed to the program (i.e. <varname>$CREDENTIALS_DIRECTORY</varname> is not
ec07c3c8 AK	153	set) or if the no credential of the specified name exists.</para>
	154
	155	<xi:include href="version-info.xml" xpointer="v249"/></listitem>
8806bb4b LP	156	</varlistentry>
8806bb4b LP	157
798d3a52 ZJS	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
49365d1c LP	165	<varlistentry>
	166	<term><option>--echo=yes\|no\|masked</option></term>
	167
	168	<listitem><para>Controls whether to echo user input. Takes a boolean or the special string
	169	<literal>masked</literal>, the default being the latter. If enabled the typed characters are echoed
	170	literally, which is useful for prompting for usernames and other non-protected data. If disabled the
	171	typed characters are not echoed in any form, the user will not get feedback on their input. If set to
	172	<literal>masked</literal>, an asterisk (<literal>*</literal>) is echoed for each character
	173	typed. In this mode, if the user hits the tabulator key (<literal>↹</literal>), echo is turned
	174	off. (Alternatively, if the user hits the backspace key (<literal>⌫</literal>) while no data has
ec07c3c8 AK	175	been entered otherwise, echo is turned off, too).</para>
	176
	177	<xi:include href="version-info.xml" xpointer="v249"/></listitem>
49365d1c LP	178	</varlistentry>
49365d1c LP	179
798d3a52 ZJS	180	<varlistentry>
798d3a52 ZJS	181	<term><option>--echo</option></term>
49365d1c	182	<term><option>-e</option></term>
798d3a52	183
aefdc112 AK	184	<listitem><para>Equivalent to <option>--echo=yes</option>, see above.</para>
	185
	186	<xi:include href="version-info.xml" xpointer="v217"/></listitem>
798d3a52 ZJS	187	</varlistentry>
798d3a52 ZJS	188
e390c34d CH	189	<varlistentry>
	190	<term><option>--emoji=yes\|no\|auto</option></term>
	191
	192	<listitem><para>Controls whether or not to prefix the query with a
	193	lock and key emoji (🔐), if the TTY settings permit this. The default
	194	is <literal>auto</literal>, which defaults to <literal>yes</literal>,
ec07c3c8 AK	195	unless <option>--echo=yes</option> is given.</para>
	196
	197	<xi:include href="version-info.xml" xpointer="v249"/></listitem>
e390c34d CH	198	</varlistentry>
e390c34d CH	199
798d3a52 ZJS	200	<varlistentry>
	201	<term><option>--no-tty</option></term>
	202
	203	<listitem><para>Never ask for password on current TTY even if
	204	one is available. Always use agent system.</para></listitem>
	205	</varlistentry>
	206
	207	<varlistentry>
	208	<term><option>--accept-cached</option></term>
	209
	210	<listitem><para>If passed, accept cached passwords, i.e.
a8eaaee7	211	passwords previously entered.</para></listitem>
798d3a52 ZJS	212	</varlistentry>
	213
	214	<varlistentry>
	215	<term><option>--multiple</option></term>
	216
	217	<listitem><para>When used in conjunction with
	218	<option>--accept-cached</option> accept multiple passwords.
	219	This will output one password per line.</para></listitem>
	220	</varlistentry>
	221
a5a4e365 CH	222	<varlistentry>
	223	<term><option>--no-output</option></term>
	224
b80ef40c LP	225	<listitem><para>Do not print passwords to standard output. This is useful if you want to store a
b80ef40c LP	226	password in kernel keyring with <option>--keyname=</option> but do not want it to show up on screen
ec07c3c8 AK	227	or in logs.</para>
	228
	229	<xi:include href="version-info.xml" xpointer="v230"/></listitem>
b80ef40c LP	230	</varlistentry>
	231
	232	<varlistentry>
	233	<term><option>-n</option></term>
	234
15102ced ZJS	235	<listitem><para>By default, when the acquired password is written to standard output it is suffixed
	236	by a newline character. This may be turned off with the <option>-n</option> switch, similarly to the
	237	switch of the same name of the <citerefentry
b80ef40c	238	project='man-pages'><refentrytitle>echo</refentrytitle><manvolnum>1</manvolnum></citerefentry>
ec07c3c8 AK	239	command.</para>
	240
	241	<xi:include href="version-info.xml" xpointer="v249"/></listitem>
a5a4e365 CH	242	</varlistentry>
a5a4e365 CH	243
798d3a52 ZJS	244	<xi:include href="standard-options.xml" xpointer="help" />
	245	</variablelist>
	246
	247	</refsect1>
	248
	249	<refsect1>
	250	<title>Exit status</title>
	251
	252	<para>On success, 0 is returned, a non-zero failure code
	253	otherwise.</para>
	254	</refsect1>
	255
	256	<refsect1>
	257	<title>See Also</title>
	258	<para>
	259	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
c65aafbb	260	<citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
3f1dc090	261	<citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
524f3e5c	262	<citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a52 ZJS	263	<citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
	264	<citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	265	</para>
	266	</refsect1>
f3bc7fdc LP	267
f3bc7fdc LP	268	</refentry>