first cut of a manpage for pam-auth-update

1 files changed, 101 insertions, 0 deletions

diff --git a/debian/local/pam-auth-update.8 b/debian/local/pam-auth-update.8
new file mode 100644
index 00000000..fd5e2ad4
--- /dev/null
+++ b/debian/local/pam-auth-update.8
@@ -0,0 +1,101 @@
+.\" Copyright (C) 2008 Canonical Ltd.
+.\"
+.\" Author: Steve Langasek <steve.langasek@canonical.com>
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of version 3 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\"
+.\" .\" This program 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 General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program; if not, write to the Free Software
+.\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301,
+.\" USA.
+.TH "PAM\-AUTH\-UPDATE" "8" "08/23/2008" "Debian"
+.SH NAME
+pam\-auth\-update - manage PAM configuration using packaged profiles
+.SH SYNOPSIS
+.B pam\-auth\-update
+.RB [ \-\-package " [" \-\-remove
+.IR profile " [" profile\fR... "]]]"
+.RB [ \-\-force ]
+.SH DESCRIPTION
+.I pam\-auth\-update
+is a utility that permits configuring the central authentication policy
+for the system using pre-defined profiles as supplied by PAM module
+packages.
+Profiles shipped in the 
+.I /usr/share/pam\-configs/
+directory specify the modules, with options, to enable; the preferred
+ordering with respect to other profiles; and whether a profile should be
+enabled by default.
+Packages providing PAM modules register their profiles at install time
+by calling
+.BR "pam\-auth\-update \-\-package" .
+Selection of profiles is done using the standard debconf interface.
+The profile selection question will be asked at `medium' priority when
+packages are added or removed, so no user interaction is required by
+default.
+Users may invoke
+.B pam\-auth\-update
+directly to change their authentication configuration.
+.PP
+The script makes every effort to respect local changes to
+.IR "/etc/pam.d/common-*".
+Local modifications to the list of module options will be preserved, and
+additions of modules within the managed portion of the stack will cause
+.B pam\-auth\-update
+to treat the config files as locally modified and not make further
+changes to the config files unless given the
+.B \-\-force
+option.
+.PP
+If the user specifies that
+.B pam\-auth\-update
+should override local configuration changes, the locally-modified files
+will be saved in
+.I /etc/pam.d/
+with a suffix of
+.IR "\.pam\-old" .
+.SH OPTIONS
+.TP
+.B \-\-package
+Indicate that the caller is a package maintainer script; lowers the
+priority of debconf questions to `medium' so that the user is not
+prompted by default.
+.TP
+.B \-\-remove \fIprofile \fR[\fIprofile\fR...]
+Remove the specified profiles from the system configuration.
+.B pam\-auth\-update \-\-remove
+should be used to remove profiles from the configuration before the
+modules they reference are removed from disk, to ensure that PAM is in a
+consistent and usable state at all times during package upgrades or
+removals.
+.TP
+.B \-\-force
+Overwrite the current PAM configuration, without prompting.
+This option
+.B must not
+be used by package maintainer scripts; it is intended for use by
+administrators only.
+.SH FILES
+.PP
+.I /etc/pam.d/common\-*
+.RS 4
+Global configuration of PAM, affecting all installed services.
+.RE
+.PP
+.I /usr/share/pam\-configs/
+.RS 4
+Package-supplied authentication profiles.
+.RE
+.SH AUTHOR
+Steve Langasek <steve.langasek@canonical.com>
+.SH COPYRIGHT
+Copyright (C) 2008 Canonical Ltd.
+.SH "SEE ALSO"
+PAM(7), pam.d(5), debconf(7)