summaryrefslogtreecommitdiffstats
path: root/man/pam_systemd_loadkey.xml
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-10 20:49:52 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-10 20:49:52 +0000
commit55944e5e40b1be2afc4855d8d2baf4b73d1876b5 (patch)
tree33f869f55a1b149e9b7c2b7e201867ca5dd52992 /man/pam_systemd_loadkey.xml
parentInitial commit. (diff)
downloadsystemd-55944e5e40b1be2afc4855d8d2baf4b73d1876b5.tar.xz
systemd-55944e5e40b1be2afc4855d8d2baf4b73d1876b5.zip
Adding upstream version 255.4.upstream/255.4
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man/pam_systemd_loadkey.xml')
-rw-r--r--man/pam_systemd_loadkey.xml99
1 files changed, 99 insertions, 0 deletions
diff --git a/man/pam_systemd_loadkey.xml b/man/pam_systemd_loadkey.xml
new file mode 100644
index 0000000..afb41f3
--- /dev/null
+++ b/man/pam_systemd_loadkey.xml
@@ -0,0 +1,99 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!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="pam_systemd_loadkey" conditional='HAVE_PAM' xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>pam_systemd_loadkey</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>pam_systemd_loadkey</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>pam_systemd_loadkey</refname>
+ <refpurpose>Read password from kernel keyring and set it as PAM authtok</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <para><filename>pam_systemd_loadkey.so</filename></para>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><command>pam_systemd_loadkey</command> reads a NUL-separated password list from the kernel keyring,
+ and sets the last password in the list as the PAM authtok.</para>
+
+ <para>The password list is supposed to be stored in the "user" keyring of the root user,
+ by an earlier call to
+ <citerefentry><refentrytitle>systemd-ask-password</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ with <option>--keyname=</option>.
+ You can pass the keyname to <command>pam_systemd_loadkey</command> via the <option>keyname=</option> option.</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Options</title>
+
+ <para>The following options are understood:</para>
+
+ <variablelist class='pam-directives'>
+
+ <varlistentry>
+ <term><varname>keyname=</varname></term>
+
+ <listitem><para>Takes a string argument which sets the keyname to read.
+ The default is <literal>cryptsetup</literal>, which is used by
+ <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ to store LUKS passphrase during boot.</para>
+
+ <xi:include href="version-info.xml" xpointer="v255"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>debug</varname></term>
+
+ <listitem><para>The module will log debugging information as it operates.</para>
+
+ <xi:include href="version-info.xml" xpointer="v255"/></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Example</title>
+
+ <para>This module is intended to be used when you use LUKS with a passphrase, enable autologin in the display
+ manager, and want to unlock Gnome Keyring / KDE KWallet automatically. So in total, you only enter one password
+ during boot.</para>
+
+ <para>You need to set the password of your Gnome Keyring/KWallet to the same as your LUKS passphrase.
+ Then add the following lines to your display manager's PAM config under <filename>/etc/pam.d/</filename> (e.g. <filename>sddm-autologin</filename>):</para>
+
+ <programlisting>
+-auth optional pam_systemd_loadkey.so
+-session optional pam_gnome_keyring.so auto_start
+-session optional pam_kwallet5.so auto_start
+ </programlisting>
+
+ <para>And add the following lines to your display manager's systemd service file, so it can access root's keyring:</para>
+
+ <programlisting>
+[Service]
+KeyringMode=inherit
+ </programlisting>
+
+ <para>In this setup, early during the boot process,
+ <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ will ask for the passphrase and store it in the kernel keyring with the keyname <literal>cryptsetup</literal>.
+ Then when the display manager does the autologin, pam_systemd_loadkey will read the passphrase from the kernel keyring,
+ set it as the PAM authtok, and then pam_gnome_keyring and pam_kwallet5 will unlock with the same passphrase.</para>
+ </refsect1>
+
+</refentry>