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">

 <!--
   This file is part of systemd.

   Copyright 2011 Lennart Poettering

   systemd is free software; you can redistribute it and/or modify it
   under the terms of the GNU Lesser General Public License as published by
   the Free Software Foundation; either version 2.1 of the License, or
   (at your option) any later version.

   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public License
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->

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

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

     <authorgroup>
       <author>
         <contrib>Developer</contrib>
         <firstname>Lennart</firstname>
         <surname>Poettering</surname>
         <email>lennart@poettering.net</email>
       </author>
     </authorgroup>
   </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 query
     the password system-wide and allow active users to respond via
     several agents. The latter is only available to privileged
     processes.</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 Plymouth</para></listitem>

       <listitem><para>A boot-time password agent querying the user
       directly on the console</para></listitem>

       <listitem><para>An agent requesting password input via a
       <citerefentry
       project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
       message</para></listitem>

       <listitem><para>A command line agent which can be started
       temporarily to process queued password
       requests</para></listitem>

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

     <para>Additional password agents may be implemented according to
     the <ulink
     url="http://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>

       <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>systemctl</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">

	<!--
	This file is part of systemd.

	Copyright 2011 Lennart Poettering

	systemd is free software; you can redistribute it and/or modify it
	under the terms of the GNU Lesser General Public License as published by
	the Free Software Foundation; either version 2.1 of the License, or
	(at your option) any later version.

	systemd is distributed in the hope that it will be useful, but
	WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	Lesser General Public License for more details.

	You should have received a copy of the GNU Lesser General Public License
	along with systemd; If not, see <http://www.gnu.org/licenses/>.
	-->

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

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

	<authorgroup>
	<author>
	<contrib>Developer</contrib>
	<firstname>Lennart</firstname>
	<surname>Poettering</surname>
	<email>lennart@poettering.net</email>
	</author>
	</authorgroup>
	</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 query
	the password system-wide and allow active users to respond via
	several agents. The latter is only available to privileged
	processes.</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 Plymouth</para></listitem>

	<listitem><para>A boot-time password agent querying the user
	directly on the console</para></listitem>

	<listitem><para>An agent requesting password input via a
	<citerefentry
	project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	message</para></listitem>

	<listitem><para>A command line agent which can be started
	temporarily to process queued password
	requests</para></listitem>

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

	<para>Additional password agents may be implemented according to
	the <ulink
	url="http://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>

	<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>systemctl</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>