File gnome-keyring-bsc1039461-pam-man-page.patch of Package gnome-keyring
diff --git a/pam/Makefile.am b/pam/Makefile.am index 5c83c00..9b5bcc8 100644 --- a/pam/Makefile.am +++ b/pam/Makefile.am @@ -72,3 +72,18 @@ test_pam_CFLAGS = $(pam_CFLAGS) check_PROGRAMS += $(pam_TESTS) TESTS += $(pam_TESTS) + +# ----------------------------------------------------------------------------- +# Man page + +man_MANS = pam_gnome_keyring.8 + +if ENABLE_DOC + +%.8: pam/%.8.xml + @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + +endif + +BUILT_EXTRA_DIST = $(man_MANS) +EXTRA_DIST += pam_gnome_keyring.8.xml diff --git a/pam/pam_gnome_keyring.8.xml b/pam/pam_gnome_keyring.8.xml new file mode 100644 index 0000000..d4679a4 --- /dev/null +++ b/pam/pam_gnome_keyring.8.xml @@ -0,0 +1,268 @@ +<?xml version="1.0" encoding='UTF-8'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> + +<refentry id="pam_gnome_keyring"> + + <refmeta> + <refentrytitle>pam_gnome_keyring</refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo class="sectdesc">Gnome Keyring PAM Module Manual</refmiscinfo> + </refmeta> + + <refnamediv id="pam_gnome_keyring-name"> + <refname>pam_gnome_keyring</refname> + <refpurpose>automatic unlocking of Gnome Keyring</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis id="pam_gnome_keyring-cmdsynopsis"> + <command>pam_gnome_keyring.so</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id="pam_gnome_keyring-description"> + + <title>DESCRIPTION</title> + + <para> + The Gnome Keyring service module for PAM provides functionality for three + PAM categories: authentication, session management and password + management. In terms of module-type parameter, they are auth, session and + password. + </para> + + <refsect2 id="pam_gnome_keyring-description-auth"> + + <title>Authentication Module</title> + + <para> + Gnome Keyring authentication module retrieves password obtained by + previous module in PAM stack and stores it for later use. When no + password was obtained this module does nothing and returns success. It + will never prompt for password by itself. Unless otherwise noted, this + module returns success. + </para> + + <para> + The following options may be passed to authentication module: + </para> + + <variablelist> + <varlistentry> + <term> + <option>auto_start</option> + </term> + <listitem> + <para> + Gnome Keyring daemon is started if not already running and login + keyring unlocked using provided password. If any of this fail, + this module returns error. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>only_if=service</option> + </term> + <listitem> + <para> + Comma separated list of services (eg. gdm,xdm) this module will + handle. If a service is not in this list, module returns success + without doing anything. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="pam_gnome_keyring-description-session"> + + <title>Session Management Module</title> + + <para> + The Gnome Keyring session management module provides functions to + initiate and terminate sessions. If Gnome Keyring daemon is not running + or no password was stored by authentication module, this module returns + success. Otherwise it will attempt to unlock login keyring. If + unlocking fails, this module will return error. When session is + terminated and daemon was started in either module, then that daemon + will be terminated. + </para> + + <para> + The following options may be passed to session management module: + </para> + + <variablelist> + <varlistentry> + <term> + <option>auto_start</option> + </term> + <listitem> + <para> + Same as in authentication. Please note that either authentication + or session management module must have option auto_start for + Gnome Keyring daemon to be started. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>only_if=service</option> + </term> + <listitem> + <para> + List of services to handle. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="pam_gnome_keyring-description-password"> + + <title>Password Management Module</title> + + <para> + The Gnome Keyring password module allows changing password for login + keyring. If no old password was obtained by previous module in the stack, this + module is ignored. On the other hand, when no new password was obtained, this + module will prompt for one. Gnome Keyring daemon will be started if not already + running and stopped after concluding operation if it was not running before. + </para> + + <para> + The following options may be passed to password management module: + </para> + + <variablelist> + <varlistentry> + <term> + <option>auto_start</option> + </term> + <listitem> + <para> + Keep daemon running even when started by this module. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>only_if=service</option> + </term> + <listitem> + <para> + List of services to handle. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>use_authtok</option> + </term> + <listitem> + <para> + Do not prompt for new password. If not provided, return error. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + </refsect1> + + <refsect1 id='pam_gnome_keyring-files'> + + <title>FILES</title> + + <variablelist> + <varlistentry> + <term> + $HOME/.local/share/keyrings/login.keyring + </term> + <listitem> + <para> + Encrypted login keyring. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1 id='pam_gnome_keyring-examples'> + + <title>EXAMPLES</title> + + <para> + The following example of file /etc/pam.d/gdm configures gdm service to + use standard UNIX authentication, as well as start and unlock Gnome + Keyring. Rest of configuration is inherited from login service + configuration. + </para> + + <programlisting> +auth required pam_unix.so +auth optional pam_gnome_keyring.so +account include login +session include login +session optional pam_gnome_keyring.so auto_start +password include login + </programlisting> + + <para> + The following example of file /etc/pam.d/passwd configures passwd program + to update keyring password along with user's system password: + </para> + + <programlisting> +password required pam_unix.so +password optional pam_gnome_keyring.so + </programlisting> + + </refsect1> + + <refsect1 id='pam_gnome_keyring-notes'> + <title>NOTES</title> + <para> + Gnome Keyring implements its own SSH agent, therefore you should not stack + it with pam_ssh for session management. + </para> + </refsect1> + + <refsect1 id='pam_gnome_keyring-see_also'> + <title>SEE ALSO</title> + <para> + <citerefentry> + <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>auditctl</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>auditd</refentrytitle><manvolnum>8</manvolnum> + </citerefentry> + </para> + </refsect1> + + <refsect1 id='pam_gnome_keyring-author'> + <title>AUTHOR</title> + <para> + pam_gnome_keyring was written by Stef Walter <stef@thewalter.net> + </para> + </refsect1> + +</refentry>
