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 for basic authentication, follow the
instructions below.  See the FORM_AUTH instructions for notes on using it
with other forms of authentication.

 (1)  Install mod_auth_external or mod_authnz_external in Apache.  This
      version of pwauth requires mod_auth_external version 2.1.1 or later.
      You can either recompile Apache with the new modules, or install them
      as dynamically loaded modules.  See the module installation instructions
      for detail.

 (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)  If you are using PAM on Linux, you could be missing the header files
      you need to compile the auth_pam.c file.  You may need to load some
      sort of PAM development module this isn't part of the standard install
      to get these headers.

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

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

 (6)  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.  The contents of this file are going to be
      entirely different for different versions of Unix, since there is
      no standardization here.  Your best bet is probably to take
      an existing file in that directory and modify it.  The few
      ancient examples listed below should be taken more as examples of
      the general appearance of these things than as useful prototypes.

      To authenticate out of the Unix Shadow file under Redhat 6.x, the
      /etc/pam.d/pwauth file would 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

      Under OS X 10.4.11, the following is reported to work (possibly
      the pam_securityserver line should be removed):

        auth       required     pam_nologin.so
	auth       sufficient   pam_securityserver.so
	auth       sufficient   pam_unix.so
	auth       required     pam_deny.so
	account    required     pam_permit.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.

 (7)  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"  in sh:  "echo $?").  It should
      be 0 for correct login/password pairs and 1 otherwise.

 (8)  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.  That is, the
      file should be owned by root, and you should do "chmod u+s pwauth" on
      it.  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.

      On OpenBSD the master password database is readable (but not writable)
      to group _shadow, so you should be able to install it sgid to group
      "_shadow" instead of suid root.  However, I've not been able to make
      this work.

 (8)  If you are using pwauth with mod_auth_external, 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 using mod_auth_external would look like:

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

      A typical .htaccess file using mod_authnz_external would look like:

	 AuthType Basic
	 AuthName Your-Site-Name
	 AuthBasicProvider external
	 AuthExternal pwauth
	 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 (for some configurations) incorrect
	      password.

        2  -  Incorrect password (for some configurations).

	3  -  Uid number is below MIN_UNIX_UID value configured in config.h.

	4 -   Login ID has expired.

	5 -   Login's password has expired.

	6 -   Logins to system have been turned off (usually by /etc/nologin
	      file).

	7 -   Limit on number of bad logins exceeded.

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

        51 -  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.

        52 -  one of several possible internal errors occured.  You'll have
	      to read the source code to figure these out.

	53 -  pwauth was not able to read the password database.  Usually
	      this means it is not running as root.  (PAM and login.conf
	      configurations will return 1 in this case.)

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.  If you are using mod_authnz_external, a better approach
is to use mod_authz_unixgroup.  This will not only allow you to restrict
logins to users in particular groups, but restrict access to individual
files based on group ownership of the files, if used with the standard Apache
module mod_authz_owner.