man/systemd-ask-password.xml - systemd-stable - Rivoreo Source Code Repositories

 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

 <!--
   SPDX-License-Identifier: LGPL-2.1+
 -->

 <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://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">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="http://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></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 NUL-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></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</option></term>

         <listitem><para>Echo the user input instead of masking it.
         This is useful when using
         <filename>systemd-ask-password</filename> to query for
         usernames. </para></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></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>
	<?xml version='1.0'?> <!--- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil --->
	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

	<!--
	SPDX-License-Identifier: LGPL-2.1+
	-->

	<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://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">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="http://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></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 NUL-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></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</option></term>

	<listitem><para>Echo the user input instead of masking it.
	This is useful when using
	<filename>systemd-ask-password</filename> to query for
	usernames. </para></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></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>