Add basic_sasl_auth(8) manual

Based on removed README

diff --git a/helpers/basic_auth/SASL/Makefile.am b/helpers/basic_auth/SASL/Makefile.am
index fdab6cf6cdb885da403cf0985fc965c774897c48..0b322a62386a25cc7d20f005b6c8fdf3fb2b85bd 100644 (file)
--- a/helpers/basic_auth/SASL/Makefile.am
+++ b/helpers/basic_auth/SASL/Makefile.am
@@ -1,5 +1,6 @@
 include $(top_srcdir)/src/Common.am
 
+man_MANS = basic_sasl_auth.8
 libexec_PROGRAMS = basic_sasl_auth
 basic_sasl_auth_SOURCES = basic_sasl_auth.cc
 basic_sasl_auth_LDADD = \

diff --git a/helpers/basic_auth/SASL/README b/helpers/basic_auth/SASL/README
deleted file mode 100644 (file)
index 33a36e4..0000000
--- a/helpers/basic_auth/SASL/README
+++ /dev/null
@@ -1,49 +0,0 @@
-This program authenticates users using SASL (specifically the
-cyrus-sasl authentication method).
-
-SASL is configurable (somewhat like PAM). Each service authenticating
-against SASL identifies itself with an application name. Each 
-"application" can be configured independently by the SASL administrator.
-
-For this authenticator, the SASL application name is, by default,
-
-       basic_sasl_auth
-
-To configure the authentication method used the file "basic_sasl_auth.conf" 
-can be placed in the appropriate location, usually "/usr/lib/sasl".
-
-The authentication database is defined by the "pwcheck_method" parameter.
-Only the "PLAIN" authentication mechanism is used.
-
-Examples:
-
-pwcheck_method:sasldb
-       use sasldb - the default if no conf file is installed.
-pwcheck_method:pam
-       use PAM
-pwcheck_method:passwd
-     use traditional /etc/passwd
-pwcheck_method:shadow
-     use slightly less traditional /etc/shadow
-
-Others methods may be supported by your cyrus-sasl implementation - 
-consult your cyrus-sasl documentation for information.
-
-Typically the authentication database (/etc/sasldb, /etc/shadow, pam)
-can not be accessed by a "normal" user. You should use setuid/setgid
-and an appropriate user/group on the executable to allow the
-authenticator to access the appropriate password database. If the
-access to the database is not permitted then the authenticator
-will typically fail with "-1, generic error".
-
-       chown root.mail sasl_auth
-       chmod ug+s sasl_auth
-
-If the application name ("basic_sasl_auth") will also be used for the
-pam service name if pwcheck_method:pam is chosen. And example pam
-configuration file  "basic_sasl_auth.pam" is also included.
-
-
-Ian Castle
-ian.castle@coldcomfortfarm.net
-March 2002

diff --git a/helpers/basic_auth/SASL/basic_sasl_auth.8 b/helpers/basic_auth/SASL/basic_sasl_auth.8
new file mode 100644 (file)
index 0000000..ba33737
--- /dev/null
+++ b/helpers/basic_auth/SASL/basic_sasl_auth.8
@@ -0,0 +1,119 @@
+.if !'po4a'hide' .TH basic_sasl_auth 8
+.
+.SN NAME
+.if !'po4a'hide' .B basic_sasl_auth
+.if !'po4a'hide' \-
+Basic Authentication using SASL (specifically the cyrus-sasl authentication method)
+..PP
+Version 1.0
+.
+.SH SYNOPSIS
+.if !'po4a'hide' .B basic_sasl_auth
+.
+.SH DESCRIPTION
+.B basic_sasl_auth
+is an installed binary helper for Squid. SASL is configurable (somewhat like PAM).
+Each service authenticating against SASL identifies itself with an application name.
+Each application can be configured independently by the SASL administrator.
+.
+.SH CONFIGURATION
+To configure the authentication method used the file 
+.B basic_sasl_auth.conf
+can be placed in the appropriate location, usually
+.B /usr/lib/sasl.
+.PP
+The authentication database is defined by the 
+.B pwcheck_method 
+parameter.
+Only the 
+.B PLAIN 
+authentication mechanism is used.
+.PP
+Examples:
+.
+.if !'po4a'hide' .B pwcheck_method:sasldb
+use sasldb - the default if no conf file is installed.
+.if !'po4a'hide' .B pwcheck_method:pam
+ - use PAM authentication database
+.if !'po4a'hide' .B pwcheck_method:passwd
+ - use traditional 
+.B /etc/passwd
+.if !'po4a'hide' .B pwcheck_method:shadow
+ - use slightly less traditional /etc/shadow
+.PP
+Others methods may be supported by your cyrus-sasl implementation -
+consult your cyrus-sasl documentation for information.
+.PP
+Typically the authentication database (
+.B /etc/sasldb
+, 
+.B /etc/shadow
+, 
+.B PAM
+)
+can not be accessed by a normal user. You should use setuid/setgid
+and an appropriate user/group on the executable to allow the
+authenticator to access the appropriate password database. If the
+access to the database is not permitted then the authenticator
+will typically fail with "-1, generic error".
+.PP
+.if !'po4a'hide' .RS
+.if !'po4a'hide' .P
+.if !'po4a'hide' .B chown root.mail basic_sasl_auth
+.if !'po4a'hide' .br
+.if !'po4a'hide' .B chmod ug+s basic_sasl_auth
+.if !'po4a'hide' .RE
+.PP
+If the application name 
+.B basic_sasl_auth
+will also be used for the PAM service name if 
+.B pwcheck_method:pam
+is chosen. And example PAM configuration file 
+.B basic_sasl_auth.pam
+is also included.
+.
+.SH AUTHOR
+This program was written by
+.if !'po4a'hide' .I Ian Castle <ian.castle@coldcomfortfarm.net>
+.PP
+This manual was written by
+.if !'po4a'hide' .I Ian Castle <ian.castle@coldcomfortfarm.net>
+.if !'po4a'hide' .I Amos Jeffries <squid3@treenet.co.nz>
+.
+.SH COPYRIGHT
+This program and documentation is copyright to the authors named above.
+.PP
+Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
+.
+.SH QUESTIONS
+Questions on the usage of this program can be sent to the
+.I Squid Users mailing list
+.if !'po4a'hide' <squid-users@squid-cache.org>
+.
+.SH REPORTING BUGS
+Bug reports need to be made in English.
+See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
+.PP
+Report bugs or bug fixes using http://bugs.squid-cache.org/
+.PP
+Report serious security bugs to
+.I Squid Bugs <squid-bugs@squid-cache.org>
+.PP
+Report ideas for new improvements to the
+.I Squid Developers mailing list
+.if !'po4a'hide' <squid-dev@squid-cache.org>
+.
+.SH SEE ALSO
+.if !'po4a'hide' .BR squid "(8), "
+.if !'po4a'hide' .BR SASL "(3), "
+.if !'po4a'hide' .BR PAM "(7), "
+.if !'po4a'hide' .BR passwd "(1), "
+.if !'po4a'hide' .BR shadow "(5), "
+.if !'po4a'hide' .BR chown "(1), "
+.if !'po4a'hide' .BR chmod "(1), "
+.br
+The Squid FAQ wiki
+.if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
+.br
+The Squid Configuration Manual
+.if !'po4a'hide' http://www.squid-cache.org/Doc/config/