Installation Notes for pwauth.c
-------------------------------

This program is designed to be used with Apache to authenticate users out
of the password file.  To use it:

 (1)  Compile Apache or later with the mod_auth_external.c version 2.1.1 or
      later.

 (2)  Edit the config.h file in this directory to set the configuration
      appropriate for your system.  There are lots of comments in the file.

 (3)  Edit the Makefile in this directory, setting appropriate CC, LIB and
      LOCALFLAGS variables.

 (4)  Do "make" to compile the program.

 (5)  If you are using PAM, you need to do some work on the configuration
      files.  Depending on your operating system, you'll either need to
      create a /etc/pam.d/pwauth file or edit the /etc/pam.conf file.

      If you have a /etc/pam.d directory, you need to create a file named
      "pwauth" inside it.  To authenticate out of the Unix Shadow file
      under Redhat 6.x, the /etc/pam.d/pwauth file should look something like
      this:

        auth       required     /lib/security/pam_pwdb.so shadow nullok
        auth       required     /lib/security/pam_nologin.so
        account    required     /lib/security/pam_pwdb.so

      If you have a /etc/pam.conf file instead of a /etc/pam.d directory,
      then you need to add appropriate lines to that instead.  For
      Solaris 2.6, you need to add lines like this to authenticate out
      of the shadow file:

        pwauth  auth     required  /lib/security/pam_unix.so
        pwauth  account  required  /lib/security/pam_unix.so

      You can authenticate from a SMB server if you have installed the pam_smb
      package (available from http://samba.org/samba).  On Solaris 2.6, the
      /etc/pam.conf lines to do this would be something like:

        pwauth  auth    required  /lib/security/pam_smb_auth.so.1

      You may want a "nolocal" flag on that line if you are authenticating from
      a remote server, or you may not.  Note that if you configure pam_smb so
      that root access isn't required, you should be able to use mod_auth_pam
      instead of mod_auth_external and pwauth and get faster authentications.

 (6)  Test the pwauth program.  As root, you can just run the thing, type
      in a login (hit return) and a password (hit return), and then check
      the exit code (in csh:  "echo $status").  It should be 0 for correct
      login/password pairs and 1 otherwise.

 (7)  Install it in some sensible place (say, /usr/local/libexec/pwauth).
      Unless you are doing SHADOW_NONE, it should be suid-root, so that
      it has the necessary access to read the shadow file.  After you've
      installed it, it is worth su-ing to whatever account your httpd runs
      under and testing pwauth again from that account.  This should confirm
      that all the uid's and suid-bits are configured correctly.

 (8)  Add to the Apache server configuration file directives that give the
      full path to wherever you installed this program and designate
      the pipe method for communicating with the authenticator.  For
      example:

	 AddExternalAuth pwauth /usr/local/libexec/pwauth
	 SetExternalAuthMethod pwauth pipe

      It is possible to use this module with the "environment" method
      instead of the "pipe" method by compiling it with the ENV_METHOD
      flag defined, however this has security problems on some Unixes.

 (9)  Put an .htaccess file in whatever directory you want to protect.
      (For .htaccess files to work, you may need to change some
      "AllowOverride None" directives in your httpd.conf file into
      "AllowOverride AuthConfig" directives).

      A typical .htaccess file would look like:

	 AuthExternal pwauth
	 AuthName Your-Site-Name
	 AuthType Basic
	 require valid-user

      Alternately, you can put a <Directory> block with the same directives
      in your httpd.conf file.

(10)  Test it by trying to access a file in the protected directory with your
      web browser.

      If it fails to accept correct logins, then check Apache's error log file.
      This should give some messages explaining why authentication failed.

      If it was unable to execute pwauth, check that the pathnames and
      permissions are all correct.

      If it says that pwauth failed, it will give the numeric return code.
      The numeric return codes returned by pwauth are as follows:

        0  -  Login OK.

        1  -  Nonexistant login or incorrect password.

        2  -  pwauth was not run with real uid SERVER_UID.  If you get this
              this error code, you probably have SERVER_UID set incorrectly
              in pwauth's config.h file.

        3  -  pwauth was not given a login & password to check.  The means
              the passing of data from mod_auth_external to pwauth is messed
              up.  Most likely one is trying to pass data via environment
              variables, while the other is trying to pass data via a pipe.

If you want to allow users of only certain groups to login, the perl
"unixgroup" command included in this directory will do the job, though not
very efficiently.  See the notes in the file for usage.