summaryrefslogtreecommitdiff
path: root/man/systemd-ask-password.xml
diff options
context:
space:
mode:
authorDaniel Mack <github@zonque.org>2015-10-07 15:32:42 +0200
committerDaniel Mack <github@zonque.org>2015-10-07 15:32:42 +0200
commit79bec997c911be7c903db9f7e5d07ab2cd303ed7 (patch)
tree1e6e62138a8920a3210b8063157612b484efbea6 /man/systemd-ask-password.xml
parentf74431288aec78ffdd05be9a519eab3dbe1c4f81 (diff)
parente287086b8aa2558356af225a12d9bfea8e7d61ca (diff)
Merge pull request #1484 from poettering/ask-pass-kernel-keyring
cache harddisk passwords in the kernel keyring
Diffstat (limited to 'man/systemd-ask-password.xml')
-rw-r--r--man/systemd-ask-password.xml70
1 files changed, 57 insertions, 13 deletions
diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml
index 877c71af53..10bb529b81 100644
--- a/man/systemd-ask-password.xml
+++ b/man/systemd-ask-password.xml
@@ -1,4 +1,4 @@
-<?xml version='1.0'?> <!--*-nxml-*-->
+<?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">
@@ -72,17 +72,28 @@
plugged in or at boot, entering an SSL certificate passphrase for
web and VPN servers.</para>
- <para>Existing agents are: a boot-time password agent asking the
- user for passwords using Plymouth; a boot-time password agent
- querying the user directly on the console; an agent requesting
- password input via a
- <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- message; an agent suitable for running in a GNOME session; a
- command line agent which can be started temporarily to process
- queued password requests; a TTY agent that is temporarily spawned
- during
- <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- invocations.</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
@@ -112,6 +123,38 @@
</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
+ the 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><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
@@ -138,7 +181,7 @@
<term><option>--accept-cached</option></term>
<listitem><para>If passed, accept cached passwords, i.e.
- passwords previously typed in.</para></listitem>
+ passwords previously typed in. </para></listitem>
</varlistentry>
<varlistentry>
@@ -166,6 +209,7 @@
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><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>