1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/CONFIG	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,181 @@
     1.4 +/* ========================================================================
     1.5 + * Copyright 1988-2006 University of Washington
     1.6 + *
     1.7 + * Licensed under the Apache License, Version 2.0 (the "License");
     1.8 + * you may not use this file except in compliance with the License.
     1.9 + * You may obtain a copy of the License at
    1.10 + *
    1.11 + *     http://www.apache.org/licenses/LICENSE-2.0
    1.12 + *
    1.13 + * 
    1.14 + * ========================================================================
    1.15 + */
    1.16 +
    1.17 +		       UNIX Configuration Notes
    1.18 +
    1.19 +     The IMAP and POP3 servers are plug-and-play on standard UNIX
    1.20 +systems.  There is no special configuration needed.  Please ignore all
    1.21 +rumors to the effect that you need to create an IMAP configuration
    1.22 +file.
    1.23 +
    1.24 +     If your system is non-standard, virtually everything that you are
    1.25 +likely to want to modify can be found in the source file
    1.26 +	.../src/osdep/unix/env_unix.c
    1.27 +In particular, special attention should be given to the routines:
    1.28 + env_init()		initialize c-client environment variables,
    1.29 +			especially the user name and home directory
    1.30 + sysinbox()		return the UNIX path of the INBOX in which
    1.31 +			mail delivery will place mail
    1.32 + mailboxdir()		translate a mailbox name into the associated
    1.33 +			UNIX directory for listing
    1.34 + mailboxfile()		translate a mailbox name into the associated
    1.35 +			UNIX file for opening
    1.36 +
    1.37 +     There are also build options in the top-level makefile which you
    1.38 +can give on the command line when building the software.  The most
    1.39 +common build options are "SSLTYPE=unix", to build the software with SSL,
    1.40 +and "SSLTYPE=nopwd", to build the software with SSL and disable plaintext
    1.41 +authentication unless the session is encrypted.
    1.42 +
    1.43 +     You should modify these routines as necessary for local policy.
    1.44 +The most common modifications are to env_init(), to modify the
    1.45 +software's idea of the home directory (which is used everywhere as the
    1.46 +default directory), and to sysinbox(), to modify where the software
    1.47 +looks for newly-delivered mail.
    1.48 +
    1.49 +     Example 1: suppose your mailer delivers mail to file ".mailbox"
    1.50 +in the user's home directory instead of the default UNIX mail spool
    1.51 +directory.  You will want to change routine sysinbox(), changing the
    1.52 +line that reads:
    1.53 +
    1.54 +    sprintf (tmp,"%s/%s",MAILSPOOL,myusername ());
    1.55 +to be:
    1.56 +    sprintf (tmp,"%s/.mailbox",myhomedir ());
    1.57 +
    1.58 +     Example 2: suppose you want to change c-client's idea of the
    1.59 +user's mailbox directory to be the "mail" subdirectory of the user's
    1.60 +home directory instead of the user's home directory.  You will want to
    1.61 +change variable mailsubdir, changing the line that reads:
    1.62 +
    1.63 +static char *mailsubdir = NIL;	/* mail subdirectory name */
    1.64 + to be:
    1.65 +static char *mailsubdir = "mail";/* mail subdirectory name */
    1.66 +
    1.67 +     Example 3: suppose you want to disable plaintext authentication in
    1.68 +the IMAP and POP servers.  If you want to disable plaintext authentication
    1.69 +in unencrypted sessions but permit it in encrypted sessions, you should use
    1.70 +"SSLTYPE=nopwd" in the make command line when building the software.  For
    1.71 +example, to do this on a Linux system with PAM authentication, do:
    1.72 +	make lnp SSLTYPE=nopwd
    1.73 +If you want to disable plaintext authentication under all circumstances
    1.74 +(including SSL or TLS encrypted sessions), use "PASSWDTYPE=nul", e.g.:
    1.75 +	make lnx EXTRAAUTHENTICATORS=gss PASSWDTYPE=nul
    1.76 +which will make it impossible to log in except via Kerberos.
    1.77 +
    1.78 +     Example 4: suppose you want the IMAP and POP servers to do a chroot()
    1.79 +to the user's home directory.  This is not recommended; there are known
    1.80 +ways of attacking chroot() based security mechanisms.  Furthermore, if you
    1.81 +do this you can not use a traditional UNIX format INBOX in the mail spool
    1.82 +directory, since chroot() will prevent access to that directory.  If you
    1.83 +really want to do this, you need to change variable closedBox, changing
    1.84 +the line which reads:
    1.85 +
    1.86 +static short closedBox = NIL;	/* is a closed box */
    1.87 + to be:
    1.88 +static short closedBox = T;	/* is a closed box */
    1.89 +
    1.90 +     Example 5: suppose you want to disable non-namespace access to the
    1.91 +filesystem root and other users' names, but do not want to go to the
    1.92 +extreme of chroot() and you want to allow access to a traditional UNIX
    1.93 +format INBOX in the mail spool directory.  You need to change variable
    1.94 +restrictBox, changing the line which reads:
    1.95 +
    1.96 +static short restrictBox = NIL;	/* is a restricted box */
    1.97 + to be:
    1.98 +static short restrictBox = -1;	/* is a restricted box */
    1.99 +
   1.100 +Other values to set in restrictBox can be found in env_unix.h.
   1.101 +
   1.102 +     Ignore all references in env_unix.c to a configuration file; that
   1.103 +code is for UW-internal use only.  It is extremely unlikely that that
   1.104 +facility will work usefully for you; it is extremely likely that you
   1.105 +will shoot yourself in the foot by using; and it frequently changes in
   1.106 +an incompatible manner.
   1.107 +
   1.108 +     There are two other build-time configuration issues which you may
   1.109 +need to consider: drivers and authenticators.  Both of these are set
   1.110 +up in the top-level Makefile -- in particular, by the EXTRADRIVERS and
   1.111 +EXTRAAUTHENTICATORS variables.
   1.112 +
   1.113 +     Drivers are code modules that support different mailbox storage
   1.114 +technologies.  By default, all drivers are enabled.  There is little
   1.115 +benefit to be gained by disabling a driver, with one exception.  The
   1.116 +mbox driver implements the behavior of automatically moving new mail
   1.117 +from the spool directory to the "mbox" file on the user's home
   1.118 +directory, if and *only* if the "mbox" exists and is in mailbox
   1.119 +format.  The mbox driver is listed under EXTRADRIVERS; if you wish to
   1.120 +disable it just remove it from that list and rebuild.
   1.121 +
   1.122 +     Authenticators are code modules that support authentication
   1.123 +technology for the server (password file lookup, Kerberos, S/Key,
   1.124 +etc.).  EXTRAAUTHENTICATORS is used to add an authenticator.  This
   1.125 +subject can be complex; find a wizard if you can't figure it out.
   1.126 +
   1.127 +     It is also possible to add your own drivers and authenticators.
   1.128 +This is a topic for wizards, and is beyond the scope of this text.
   1.129 +
   1.130 +			NT Configuration Notes
   1.131 +
   1.132 +     This software is not plug-and-play on NT.  If you're not a hacker
   1.133 +and/or are unwilling to invest the time to do some programming, you
   1.134 +probably want to buy a commercial server for NT.
   1.135 +
   1.136 +     The primary issue that you need to deal with is the format of
   1.137 +mail, where the INBOX is located, and where secondary folders are
   1.138 +located.  As distributed, the software supports mail in the default
   1.139 +format used on UNIX (unix format) as well as mbx, mtx, and tenex
   1.140 +formats.  mbx format is encouraged if at all possible; mtx and tenex
   1.141 +format are for compatibility with the past.  However, it all depends
   1.142 +upon how and where your SMTP server delivers mail.
   1.143 +
   1.144 +     To change the default mailbox format, edit the symbol
   1.145 +DEFAULTDRIVER in:
   1.146 +	../src/osdep/nt/makefile.nt
   1.147 +or
   1.148 +	../src/osdep/nt/makefile.ntk
   1.149 +To change the default location of INBOX, edit the file:
   1.150 +	../src/osdep/nt/mailfile.h
   1.151 +Virtually everything else having to do with environment that you are
   1.152 +likely to want to modify can be found in the source file:
   1.153 +	.../src/osdep/nt/env_nt.c
   1.154 +In particular, special attention should be given to the routines:
   1.155 + env_init()		initialize c-client environment variables,
   1.156 +			especially the user name and home directory
   1.157 + sysinbox()		return the NT path of the INBOX in which
   1.158 +			mail delivery will place mail
   1.159 + mailboxdir()		translate a mailbox name into the associated
   1.160 +			NT directory for listing
   1.161 + mailboxfile()		translate a mailbox name into the associated
   1.162 +			NT file for opening
   1.163 +
   1.164 +     You should modify these routines as necessary.  The most common
   1.165 +modifications are to env_init(), to modify the software's idea of the
   1.166 +home directory (which is used everywhere as the default directory),
   1.167 +and to sysinbox(), to modify where the software looks for
   1.168 +newly-delivered mail.
   1.169 +
   1.170 +     There are two other build-time configuration issues which you may
   1.171 +need to consider: drivers and authenticators.  Both of these are set
   1.172 +up in the top-level Makefile -- in particular, by the EXTRADRIVERS and
   1.173 +EXTRAAUTHENTICATORS variables.
   1.174 +
   1.175 +     Drivers are code modules that support different mailbox storage
   1.176 +technologies.  By default, all drivers are enabled.  There is little
   1.177 +benefit to be gained by disabling a driver.
   1.178 +
   1.179 +     Authenticators are code modules that support authentication
   1.180 +technology for the server (password file lookup, Kerberos, S/Key,
   1.181 +etc.).  EXTRAAUTHENTICATORS is used to add an authenticator.  This
   1.182 +subject can be complex; find a wizard if you can't figure it out.
   1.183 +
   1.184 +     It is also possible to add your own drivers and authenticators.