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

     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.

     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 .../src/osdep/unix/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.
								19970209
			How to configure Postilion

   TkRat software and its included text is Copyright 1996,1997
   by Martin Forssn.

   WMRat and Postilion software and its included text is Copyright 1997, 
   1998, 1999 by Nic Bernstein
  
   The full text of the legal notices is contained in the files called
   COPYING, COPYRIGHT.images and COPYRIGHT.TkRat, included with this 
   distribution.


	WHAT GOES INTO THE FILES

You can set a lot of options for Postilion via a couple of configuration
files, but you don't have to. Reasonable (hopefully) defaults to all
options are written into the program.
It is however recommended that the site administrator changes the site
defaults in the configuration file in the SITE directory (see below). The
user can then later do their own customizations from inside the program.
These user changes are saved in the users '~/.postilion/postilionrc' file.


	LOCATION OF CONFIGURATION FILES

The configuration files are first read from the SITE directory and then from
the users ~/.postilion directory. The configuration file is called 'postilionrc'.
The default SITE directory is /usr/local/lib/postilion. This will change
if you give a --prefix argument to configure. The SITE directory is
actually defined as ${prefix}/lib/postilion .


	SYNTAX OF CONFIGURATION FILES

The configuration files are read via the tcl source command which means that
they can have any valid tcl syntax. Postilion defines a 'RatLock' command which
locks a given variable so that it may not be changed anymore. An example of
an configuration file follows:

    # This is a comment line.
    # The lines below sets our domain to 'dtek.chalmers.se' and locks
    # the value so that the users can't change it.
    set option(domain) dtek.chalmers.se
    RatLock option(domain)

    # Set the default editor
    set option(editor) "xterm -e vi %s"


	OPTIONS

Below follows a list of the options a site administrator normally might want
to set in the site-specific configuration file. To set option NAME in the
file you should use 'set option(NAME) VALUE'.

    NAME		DESCRIPTION
    language		The default language of the user interface. Currently
			the only possible values are 'en', 'sv' and 'it'
			(English, Swedish and Italian). The default is English.

    default_folder	The definition of the folder that gets opened when
			the program is started for the first time. It will
			then be written into the users vfolderlist and this
			variable does not modify it any more. It defaults to
			the /usr/spool/mail/$USER file. See FOLDER DEFINITIONS
			below for more details.

    editor		The default editor. The editor will NOT be run in a
    			terminal window. A '%s' must be included and will
			be expanded to the name of the file to edit. This
			defaults to 'emacs %s'.

    masquerade_as	If this option is set all messages sent (ie the From
			address) will look as if they came from the specified
			domain (ie the value of the option). No hostname will
			be included in the address. The default is no value.

    domain		The domain this host resides in. This option will be
			ignored if masquerade_as has a value.

    use_from		If this is true then the user may specify the address
			that goes on the From: line. If it is off then Postilion
			generates an address automatically. If the user
			specifies an address which the program doesn't think
			points to the user a Sender: line is added.

    sendprot		Which protocol to use to send messages. Valid values
			are 'smtp' and 'prog'. The default is 'smtp'.

    smtp_hosts		A list of hosts that will be used to send messages
			via SMTP. The system will first try the first host,
			if that fails the second and so on. The default is
			'localhost'.

    sendprog		Which program to use if we are sending messages with
    			the 'prog' protocol. The program will be called with
			the recipients as arguments and the message on stdin.
			Default is '/usr/lib/sendmail'.

    sendprog_8bit	This option can be either 'true' or 'false' and
			indicates whether the sendprog can handle characters
			with the eight bit set. This defaults to 'false'.

    charset		The charset the machine uses. Currently  the only
			safe values are iso-8859-[1-10] and us-ascii. This
			defaults to 'iso-8859-1'.

    lookup_name		If this is set to "true" then Postilion will look in
			the local passwd-file for the full names of users
			when addressing messages. This might be time consuming
			so some sites might want to disable it by default. The
			default is "true".

    mail_steal		If this is true then we should check for mail
			that netscape has stolen from the inbox every time
			we start the application. The default is true.

    icon		This defines which icon bitmap the program should
			install. The possible values are: "normal" (a 64x64
			bitmap), "small" (50x50) and none. Default is normal.

    system_aliases	The identification of a system-wide address book.
			This should be a list with three elements:
				{NAME tkrat PATH}
			NAME is the name the user should see, tkrat is
			a keyword which says this file is in the tkrat-
			format (other values are pine, mail and elm). The
			last value is the path to teh address book

    use_system_aliases	Set this to 1 if the system aliases book should be
			used (by default) or 0 if is should not.

This is just a subset of the options. For a full list check the options.tcl
file in the postilion subdirectory. Beware that many of the options have special
syntax and meanings. It is strongly recommended that you use the preferences
window in Postilion to change the options.


	FOLDER DEFINITIONS

Each folder is defined by a tcl list. For example the default value of default_
folder is "INBOX file {} /usr/spool/mail/$env(USER)". This is a list of three
elements, the first is the symbolic name of the folder, the second is the
type of folder and the third is the actual file. To set a value like this
in a configuration file you write:

    set option(default_folder) "INBOX file {} /var/spool/mail/$env(USER)"

There are three different types of folders one might have as inboxes. The
syntax for them are (values written in capital letters should be customized,
other characters must be exactly as written):

File folders:	"NAME file {} FILENAME"
POP3 folders:	"NAME pop3 {} {{{HOST:PORT/pop3}}} USER"
IMAP folders:	"NAME imap {} {{{HOST:PORT/imap}MAILBOX}} USER"

Note that the :PORT part is optional. But highly recommended for imap folders.


	FONTS

As shipped Postilion will use fonts from the courier family. For exact names see
postilion/options.tcl. You can modify this list via the configuration files. To
remove a font from the list just add a line "RemoveFonts FONTNAME" where
FONTNAME is a tcl regexp ('.*' matches everything).

You can also add fonts via the following command:
    AddFont ENCODING SIZE ATTRIBUTES NAME
where ENCODING is the encoding of the font for example "iso-8859-1".
ATTRIBUTES is a list of attributes, the only used attributes are "bold"
and "italic". Finally the NAME is the official name of this font. Examples:
    # Add the standard 12 points font
    AddFont iso-8859-1 12 {} *-courier-medium-r-normal-*-12-*
    # Add an bold and italic 14 points font
    AddFont iso-8859-1 14 {bold italic} *-courier-bold-o-normal-*-14-*


	CHARACTER SET ALIASES

You can instruct Postilion that one character set name really means another
character set. This is useful when dealing with software that is improperly
configured and therefore emits strange character set names. Postilion contains
a number of such aliases when shipped but each site may want to extend the
list to cover more names. 

To add more aliases you must create a charsetAliases file in any of the
configuration directories. This file should have lines in the following format:

set charsetAlias(ALIAS) NAME

This line says that ALIAS is an alias and the real name is NAME. I would also
appreciate if you notified me (nic@postilion.org) of any aliases you think
should be built in into the release.