/* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * 
 * ========================================================================
 */

		       UNIX Configuration Notes

     The IMAP and POP3 servers are plug-and-play on standard UNIX
systems.  There is no special configuration needed.  Please ignore all
rumors to the effect that you need to create an IMAP configuration
file.

     If your system is non-standard, virtually everything that you are
likely to want to modify can be found in the source file
	.../src/osdep/unix/env_unix.c
In particular, special attention should be given to the routines:
 env_init()		initialize c-client environment variables,
			especially the user name and home directory
 sysinbox()		return the UNIX path of the INBOX in which
			mail delivery will place mail
 mailboxdir()		translate a mailbox name into the associated
			UNIX directory for listing
 mailboxfile()		translate a mailbox name into the associated
			UNIX file for opening

     There are also build options in the top-level makefile which you
can give on the command line when building the software.  The most
common build options are "SSLTYPE=unix", to build the software with SSL,
and "SSLTYPE=nopwd", to build the software with SSL and disable plaintext
authentication unless the session is encrypted.

     You should modify these routines as necessary for local policy.
The most common modifications are to env_init(), to modify the
software's idea of the home directory (which is used everywhere as the
default directory), and to sysinbox(), to modify where the software
looks for newly-delivered mail.

     Example 1: suppose your mailer delivers mail to file ".mailbox"
in the user's home directory instead of the default UNIX mail spool
directory.  You will want to change routine sysinbox(), changing the
line that reads:

    sprintf (tmp,"%s/%s",MAILSPOOL,myusername ());
to be:
    sprintf (tmp,"%s/.mailbox",myhomedir ());

     Example 2: suppose you want to change c-client's idea of the
user's mailbox directory to be the "mail" subdirectory of the user's
home directory instead of the user's home directory.  You will want to
change variable mailsubdir, changing the line that reads:

static char *mailsubdir = NIL;	/* mail subdirectory name */
 to be:
static char *mailsubdir = "mail";/* mail subdirectory name */

     Example 3: suppose you want to disable plaintext authentication in
the IMAP and POP servers.  If you want to disable plaintext authentication
in unencrypted sessions but permit it in encrypted sessions, you should use
"SSLTYPE=nopwd" in the make command line when building the software.  For
example, to do this on a Linux system with PAM authentication, do:
	make lnp SSLTYPE=nopwd
If you want to disable plaintext authentication under all circumstances
(including SSL or TLS encrypted sessions), use "PASSWDTYPE=nul", e.g.:
	make lnx EXTRAAUTHENTICATORS=gss PASSWDTYPE=nul
which will make it impossible to log in except via Kerberos.

     Example 4: suppose you want the IMAP and POP servers to do a chroot()
to the user's home directory.  This is not recommended; there are known
ways of attacking chroot() based security mechanisms.  Furthermore, if you
do this you can not use a traditional UNIX format INBOX in the mail spool
directory, since chroot() will prevent access to that directory.  If you
really want to do this, you need to change variable closedBox, changing
the line which reads:

static short closedBox = NIL;	/* is a closed box */
 to be:
static short closedBox = T;	/* is a closed box */

     Example 5: suppose you want to disable non-namespace access to the
filesystem root and other users' names, but do not want to go to the
extreme of chroot() and you want to allow access to a traditional UNIX
format INBOX in the mail spool directory.  You need to change variable
restrictBox, changing the line which reads:

static short restrictBox = NIL;	/* is a restricted box */
 to be:
static short restrictBox = -1;	/* is a restricted box */

Other values to set in restrictBox can be found in env_unix.h.

     Ignore all references in env_unix.c to a configuration file; that
code is for UW-internal use only.  It is extremely unlikely that that
facility will work usefully for you; it is extremely likely that you
will shoot yourself in the foot by using; and it frequently changes in
an incompatible manner.

     There are two other build-time configuration issues which you may
need to consider: drivers and authenticators.  Both of these are set
up in the top-level Makefile -- in particular, by the EXTRADRIVERS and
EXTRAAUTHENTICATORS variables.

     Drivers are code modules that support different mailbox storage
technologies.  By default, all drivers are enabled.  There is little
benefit to be gained by disabling a driver, with one exception.  The
mbox driver implements the behavior of automatically moving new mail
from the spool directory to the "mbox" file on the user's home
directory, if and *only* if the "mbox" exists and is in mailbox
format.  The mbox driver is listed under EXTRADRIVERS; if you wish to
disable it just remove it from that list and rebuild.

     Authenticators are code modules that support authentication
technology for the server (password file lookup, Kerberos, S/Key,
etc.).  EXTRAAUTHENTICATORS is used to add an authenticator.  This
subject can be complex; find a wizard if you can't figure it out.

     It is also possible to add your own drivers and authenticators.
This is a topic for wizards, and is beyond the scope of this text.

			NT Configuration Notes

     This software is not plug-and-play on NT.  If you're not a hacker
and/or are unwilling to invest the time to do some programming, you
probably want to buy a commercial server for NT.

     The primary issue that you need to deal with is the format of
mail, where the INBOX is located, and where secondary folders are
located.  As distributed, the software supports mail in the default
format used on UNIX (unix format) as well as mbx, mtx, and tenex
formats.  mbx format is encouraged if at all possible; mtx and tenex
format are for compatibility with the past.  However, it all depends
upon how and where your SMTP server delivers mail.

     To change the default mailbox format, edit the symbol
DEFAULTDRIVER in:
	../src/osdep/nt/makefile.nt
or
	../src/osdep/nt/makefile.ntk
To change the default location of INBOX, edit the file:
	../src/osdep/nt/mailfile.h
Virtually everything else having to do with environment that you are
likely to want to modify can be found in the source file:
	.../src/osdep/nt/env_nt.c
In particular, special attention should be given to the routines:
 env_init()		initialize c-client environment variables,
			especially the user name and home directory
 sysinbox()		return the NT path of the INBOX in which
			mail delivery will place mail
 mailboxdir()		translate a mailbox name into the associated
			NT directory for listing
 mailboxfile()		translate a mailbox name into the associated
			NT file for opening

     You should modify these routines as necessary.  The most common
modifications are to env_init(), to modify the software's idea of the
home directory (which is used everywhere as the default directory),
and to sysinbox(), to modify where the software looks for
newly-delivered mail.

     There are two other build-time configuration issues which you may
need to consider: drivers and authenticators.  Both of these are set
up in the top-level Makefile -- in particular, by the EXTRADRIVERS and
EXTRAAUTHENTICATORS variables.

     Drivers are code modules that support different mailbox storage
technologies.  By default, all drivers are enabled.  There is little
benefit to be gained by disabling a driver.

     Authenticators are code modules that support authentication
technology for the server (password file lookup, Kerberos, S/Key,
etc.).  EXTRAAUTHENTICATORS is used to add an authenticator.  This
subject can be complex; find a wizard if you can't figure it out.

     It is also possible to add your own drivers and authenticators.