Add the first cut at a manual page

diff --git a/.gitignore b/.gitignore
index 2b53aa3f9e8db91afef4ebaf2e9701ff812c26d7..ddcfea19504a4fcbd3935db637bf12c147f6b762 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,7 @@
 /m4/ltsugar.m4
 /m4/ltversion.m4
 /m4/lt~obsolete.m4
+/pam_webauth_otp.5
 /pam-webauth-otp-*
 /stamp-h1
 .deps/

diff --git a/Makefile.am b/Makefile.am
index f3e88b1183163aa2c1fc53b5990b3fa7c475d9b5..8a04d26b963489ddf0712a4ac25854ea5ecf4d0c 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -31,6 +31,7 @@ pam_webauth_otp_la_LDFLAGS = -module -shared -avoid-version \
        $(VERSION_LDFLAGS) $(KRB5_LDFLAGS) $(AM_LDFLAGS)
 pam_webauth_otp_la_LIBADD = pam-util/libpamutil.la portable/libportable.la \
        -lwebauth $(KRB5_LIBS)
+dist_man_MANS = pam_webauth_otp.5
 
 # Work around a misfeature of the GNU Coding Standards and really clean all
 # the build machinery.

diff --git a/autogen b/autogen
index 0142b78e75ad0af0bc36b1ce954c359824f10d80..634a111d3f70ea306d8e787a046b8ecc66f8bc4f 100755 (executable)
--- a/autogen
+++ b/autogen
@@ -3,4 +3,11 @@
 # Run this shell script to bootstrap as necessary after a fresh checkout.
 
 set -e
+
+# Regenerate all the autotools files.
 autoreconf -i --force
+
+# Generate manual pages.
+version=`grep '^pam-webauth-otp' NEWS | head -1 | cut -d' ' -f2`
+pod2man --release="$version" --center="pam-webauth-otp" --section=5 \
+    pam_webauth_otp.pod > pam_webauth_otp.5

diff --git a/pam_webauth_otp.pod b/pam_webauth_otp.pod
new file mode 100644 (file)
index 0000000..86113cb
--- /dev/null
+++ b/pam_webauth_otp.pod
@@ -0,0 +1,126 @@
+=head1 NAME
+
+pam_webauth_otp - OTP PAM module for WebAuth user information service
+
+=head1 SYNOPSIS
+
+  auth  required  pam_webauth_otp.so
+
+=head1 DESCRIPTION
+
+WebAuth is a site-wide web authentication system that uses a central login
+server.  That login server supports multifactor authentication (and other
+features) via a user information service provided by the local site.
+OTP-based multifactor authentication is validated by WebAuth via calls to
+the validate function in that user information service.
+
+pam_webauth_otp is a PAM authentication module that performs the same API
+calls as the WebAuth login server, allowing the same infrastructure and
+OTP database to be used to secure authentications that use PAM.  The user
+is prompted for an OTP code, which is then validated by a call to the
+validate function of a WebAuth user information service.  Any middleware
+that speaks the WebAuth user information service protocol can be used,
+whether or not it is also used for a WebAuth deployment.
+
+This module currently only supports OTP mechanisms where the user can
+supply a code without any further interaction.  SMS, which requires a call
+to send the SMS message before prompting the user, is not currently
+supported.
+
+pam_webauth_otp only provides the authentication API and should only be
+put in the auth stack.  It is not meaningful for the other PAM stacks.
+It is normally used in conjunction with another C<required> module to
+provide multifactor authentication.
+
+=head1 CONFIGURATION
+
+pam_webauth_otp supports the following configuration options, which may be
+set in the PAM configuration as arguments listed after
+C<pam_webauth_otp.so> or (if the module was built with Kerberos support)
+in the system F<krb5.conf>.
+
+To set an option that takes an argument in the PAM configuration, follow
+the option name with an equal sign (C<=>) and the value, with no
+separating whitespace.  Whitespace in option arguments is not supported in
+the PAM configuration files of most PAM implementations.
+
+To set an option for the PAM module in the system F<krb5.conf> file, put
+that option in the [appdefaults] section.  pam_webauth_otp will look for
+options either at the top level of the C<[appdefaults]> section or in a
+subsection named C<pam-webauth-otp>.  Currently, realm-specific
+configuration is not checked.  For example, the following fragment of a
+F<krb5.conf> file would set I<server> to C<userinfo.example.com> and
+I<command> to C<webkdc>:
+
+    [appdefaults]
+        server = userinfo.example.com
+        pam-webauth-otp = {
+            command = webkdc
+        }
+
+There is no difference to the PAM module whether options are specified at
+the top level or in a C<pam-webauth-otp> section, but always using that
+section is recommended since the options are otherwise rather generic and
+may interfere with other programs.  For more information on the syntax of
+F<krb5.conf>, see krb5.conf(5).
+
+If the same option is set in F<krb5.conf> and in the PAM configuration,
+the latter takes precedent.
+
+=over 4
+
+=item command=I<command>
+
+Sets the command prefix used when making user information service calls.
+This should be the same string as the final component of the URL set in
+the mod_webkdc WebKdcUserInfoURL Apache directive.  It is sent as the
+command portion of the remctl call.  This option must be set.
+
+=item host=I<hostname>
+
+The hostname of the WebAuth information service against which to validate
+the OTP code.  This host, at least currently, must provide the WebAuth
+user information service (at least the C<webkdc-validate> command) via
+remctl.  The principal used for authentication will be the default host
+principal for that host, as determined by remctl's normal principal
+derivation algorithm.  This option must be set.
+
+=item keytab=I<path>
+
+Use the specified keytab to authenticate to the WebAuth information
+service.  The first principal found in the keytab will be used as the
+client identity.  The default, if not set, is F</etc/krb5.keytab>, which
+will generally use the local system host credentials.
+
+=item timeout=I<timeout>
+
+How long to wait, in seconds, for a reply from the WebAuth user
+information service before giving up and failing the authentication.  This
+should generally be less than 60 seconds, since many PAM applications will
+time out themselves if a PAM authentication takes longer than that.  The
+default, if not set, is 30 seconds.
+
+=back
+
+=head1 AUTHOR
+
+Russ Allbery <rra@stanford.edu>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2013 The Board of Trustees of the Leland Stanford Junior
+University
+
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any
+warranty.
+
+=head1 SEE ALSO
+
+krb5.conf(5), remctl(1)
+
+The current version of this PAM module is available from its web page at
+L<http://www.eyrie.org/~eagle/software/pam-webauth-otp/>.
+
+=cut