Adding upstream version 2:4.17.12+dfsg.upstream/2%4.17.12+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 319 insertions, 0 deletions

diff --git a/docs-xml/manpages/pam_winbind.8.xml b/docs-xml/manpages/pam_winbind.8.xml
new file mode 100644
index 0000000..171bb40
--- /dev/null
+++ b/docs-xml/manpages/pam_winbind.8.xml
@@ -0,0 +1,319 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<refentry id="pam_winbind.8">
+
+<refmeta>
+	<refentrytitle>pam_winbind</refentrytitle>
+	<manvolnum>8</manvolnum>
+	<refmiscinfo class="source">Samba</refmiscinfo>
+	<refmiscinfo class="manual">8</refmiscinfo>
+	<refmiscinfo class="version">&doc.version;</refmiscinfo>
+</refmeta>
+
+
+<refnamediv>
+	<refname>pam_winbind</refname>
+	<refpurpose>PAM module for Winbind</refpurpose>
+</refnamediv>
+
+<refsect1>
+	<title>DESCRIPTION</title>
+
+	<para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
+	<manvolnum>7</manvolnum></citerefentry> suite.</para>
+
+	<para>
+	pam_winbind is a PAM module that can authenticate users against the local domain by talking to the Winbind daemon.
+	</para>
+
+</refsect1>
+
+<refsect1>
+	<title>SYNOPSIS</title>
+
+	<para>
+		Edit the PAM system config /etc/pam.d/service and modify it as the following example shows:
+		<programlisting>
+			    ...
+			    auth      required        pam_env.so
+			    auth      sufficient      pam_unix2.so
+			+++ auth      required        pam_winbind.so  use_first_pass
+			    account   requisite       pam_unix2.so
+			+++ account   required        pam_winbind.so  use_first_pass
+			+++ password  sufficient      pam_winbind.so
+			    password  requisite       pam_pwcheck.so  cracklib
+			    password  required        pam_unix2.so    use_authtok
+			    session   required        pam_unix2.so
+			+++ session   required        pam_winbind.so
+			    ...
+		</programlisting>
+
+		Make sure that pam_winbind is one of the first modules in the session part. It may retrieve
+		kerberos tickets which are needed by other modules.
+	</para>
+</refsect1>
+
+<refsect1>
+	<title>OPTIONS</title>
+	<para>
+	
+		pam_winbind supports several options which can either be set in
+		the PAM configuration files or in the pam_winbind configuration
+		file situated at
+		<filename>/etc/security/pam_winbind.conf</filename>. Options
+		from the PAM configuration file take precedence to those from
+		the configuration file. See
+		<citerefentry><refentrytitle>pam_winbind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+		for further details.
+
+		<variablelist>
+
+		<varlistentry>
+		<term>debug</term>
+		<listitem><para>Gives debugging output to syslog.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>debug_state</term>
+		<listitem><para>Gives detailed PAM state debugging output to syslog.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>require_membership_of=[SID or NAME]</term>
+		<listitem><para>
+		If this option is set, pam_winbind will only succeed if the user is a member of the given SID or NAME. A SID
+		can be either a group-SID, an alias-SID or even an user-SID. It is also possible to give a NAME instead of the
+		SID. That name must have the form: <parameter>MYDOMAIN\mygroup</parameter> or
+		<parameter>MYDOMAIN\myuser</parameter> (where '\' character corresponds to the value of
+		<parameter>winbind separator</parameter> parameter). It is also possible to use a UPN in the form
+		<parameter>user@REALM</parameter> or <parameter>group@REALM</parameter>. pam_winbind will, in that case, lookup
+		the SID internally. Note that NAME may not contain any spaces. It is thus recommended to only use SIDs. You can
+		verify the list of SIDs a user is a member of with <command>wbinfo --user-sids=SID</command>.
+		</para>
+
+		<para>
+		This option must only be specified on a auth
+		module declaration, as it only operates in conjunction
+		with password authentication.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>use_first_pass</term>
+		<listitem><para>
+		By default, pam_winbind tries to get the authentication token from a previous module. If no token is available
+		it asks the user for the old password. With this option, pam_winbind aborts with an error if no authentication
+		token from a previous module is available.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>try_first_pass</term>
+		<listitem><para>
+				Same as the use_first_pass option (previous item), except that if the primary password is not
+				valid, PAM will prompt for a password.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>use_authtok</term>
+		<listitem><para>
+		Set the new password to the one provided by the previously stacked password module. If this option is not set 
+		pam_winbind will ask the user for the new password.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>try_authtok</term>
+		<listitem><para>
+		Same as the use_authtok option (previous item), except that if the new password is not
+		valid, PAM will prompt for a password.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>krb5_auth</term>
+		<listitem><para>
+
+		pam_winbind can authenticate using Kerberos when winbindd is
+		talking to an Active Directory domain controller. Kerberos
+		authentication must be enabled with this parameter. When
+		Kerberos authentication can not succeed (e.g. due to clock
+		skew), winbindd will fallback to samlogon authentication over
+		MSRPC. When this parameter is used in conjunction with
+		<parameter>winbind refresh tickets</parameter>, winbind will
+		keep your Ticket Granting Ticket (TGT) up-to-date by refreshing
+		it whenever necessary.
+
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>krb5_ccache_type=[type]</term>
+		<listitem><para>
+
+		When pam_winbind is configured to try kerberos authentication
+		by enabling the <parameter>krb5_auth</parameter> option, it can
+		store the retrieved Ticket Granting Ticket (TGT) in a
+		credential cache. The type of credential cache can be
+		controlled with this option.  The supported values are:
+		<parameter>KCM</parameter> or <parameter>KEYRING</parameter>
+		(when supported by the system's Kerberos library and
+		operating system),
+		<parameter>FILE</parameter> and <parameter>DIR</parameter>
+		(when the DIR type is supported by the system's Kerberos
+		library). In case of FILE a credential cache in the form of
+		/tmp/krb5cc_UID will be created -  in case of DIR you NEED
+		to specify a directory which must exist, the UID directory
+		will be created in the specified directory.
+		In all cases UID is replaced with the numeric user id.
+		Check the details of the Kerberos implementation.</para>
+
+		<para>When using the KEYRING type, the supported mechanism is
+		<quote>KEYRING:persistent:UID</quote>, which uses the Linux
+		kernel keyring to store credentials on a per-UID basis.
+		KEYRING has limitations. For example, it is secure kernel memory,
+		so bulk storage of credentials is not possible.</para>
+
+		<para>When using the KCM type, the supported mechanism is
+		<quote>KCM:UID</quote>, which uses a Kerberos credential
+		manager to store credentials on a per-UID basis similar to
+		KEYRING. This is the recommended choice on latest Linux
+		distributions that offer a Kerberos Credential Manager. If not,
+		we suggest to use KEYRING, as those are the most secure and
+		predictable method.</para>
+
+		<para>It is also possible to define custom filepaths and use the "%u"
+		pattern in order to substitute the numeric user id.
+		Examples:</para>
+
+		<variablelist>
+			<varlistentry>
+				<term>krb5_ccache_type = DIR:/run/user/%u/krb5cc</term>
+					<listitem><para>This will create a credential cache file in the specified directory.</para></listitem>
+			</varlistentry>
+			<varlistentry>
+				<term>krb5_ccache_type = FILE:/tmp/krb5cc_%u</term>
+					<listitem><para>This will create a credential cache file.</para></listitem>
+			</varlistentry>
+		</variablelist>
+
+		<para>Leave empty to just do kerberos authentication without
+		having a ticket cache after the logon has succeeded.
+		This setting is empty by default.</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>cached_login</term>
+		<listitem><para>
+		Winbind allows one to logon using cached credentials when <parameter>winbind offline logon</parameter> is enabled. To use this feature from the PAM module this option must be set.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>silent</term>
+		<listitem><para>
+		Do not emit any messages.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>mkhomedir</term>
+		<listitem><para>
+		Create homedirectory for a user on-the-fly, option is valid in
+		PAM session block.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>warn_pwd_expire</term>
+		<listitem><para>
+		Defines number of days before pam_winbind starts to warn about passwords that are
+		going to expire. Defaults to 14 days.
+		</para></listitem>
+		</varlistentry>
+
+		</variablelist>
+
+	</para>
+
+</refsect1>
+
+<refsect1>
+	<title>PAM DATA EXPORTS</title>
+
+	<para>This section describes the data exported in the PAM stack which could be used in other PAM modules.</para>
+
+	<varlistentry>
+		<term>PAM_WINBIND_HOMEDIR</term>
+		<listitem>
+			<para>
+				This is the Windows Home Directory set in the profile tab in the user settings
+				on the Active Directory Server. This could be a local path or a directory on a
+				share mapped to a drive.
+			</para>
+		</listitem>
+	</varlistentry>
+	<varlistentry>
+		<term>PAM_WINBIND_LOGONSCRIPT</term>
+		<listitem>
+			<para>
+				The path to the logon script which should be executed if a user logs in. This is
+				normally a relative path to the script stored on the server.
+			</para>
+		</listitem>
+	</varlistentry>
+	<varlistentry>
+		<term>PAM_WINBIND_LOGONSERVER</term>
+		<listitem>
+			<para>
+				This exports the Active Directory server we are authenticating against. This can be
+				used as a variable later.
+			</para>
+		</listitem>
+	</varlistentry>
+	<varlistentry>
+		<term>PAM_WINBIND_PROFILEPATH</term>
+		<listitem>
+			<para>
+				This is the profile path set in the profile tab in the user settings. Normally
+				the home directory is synced with this directory on a share.
+			</para>
+		</listitem>
+	</varlistentry>
+</refsect1>
+
+<refsect1>
+	<title>SEE ALSO</title>
+	<para><citerefentry>
+	<refentrytitle>pam_winbind.conf</refentrytitle>
+	<manvolnum>5</manvolnum></citerefentry>, <citerefentry>
+	<refentrytitle>wbinfo</refentrytitle>
+	<manvolnum>1</manvolnum></citerefentry>, <citerefentry>
+	<refentrytitle>winbindd</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry>, <citerefentry>
+	<refentrytitle>smb.conf</refentrytitle>
+	<manvolnum>5</manvolnum></citerefentry></para>
+</refsect1>
+
+<refsect1>
+	<title>VERSION</title>
+
+	<para>This man page is part of version &doc.version; of Samba.</para>
+</refsect1>
+
+<refsect1>
+	<title>AUTHOR</title>
+	
+	<para>
+	The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by
+	the Samba Team as an Open Source project similar to the way the Linux kernel is developed.
+	</para>
+	
+	<para>This manpage was written by Jelmer Vernooij and Guenther Deschner.</para>
+
+</refsect1>
+
+</refentry>