	In Short
	--------

unpack the tarball
cd into imapproxy-X.X
autoconf
./configure
make
make a configfile
start the program

	Unpacking
	---------

After you download the package, unpack it.

localhost:~$ tar -xzf imapproxy-X.X.tar.gz

This will create a directory called imapproxy-X.X, 
where X.X is the version number.

	Adjust
	------

"cd" into the directory, where you will find a directory include.
In this include directory, there is a file called defines.h.
This file contains default values used in the program, and will be compiled 
into the program.

Many of these values can be configured from the configfile, so you may as 
well leave defines.h untouched.

	Generate Makefile
	-----------------

Run the configure script in the main directory. This will create a Makefile.

localhost:~/imapproxy-X.X$ autoconf
localhost:~/imapproxy-X.X$ ./configure

	Compilation
	-----------

If all goes well, you can now invoke make

localhost:~/imapproxy-X.X$ make

This will start the compilation.
If you find any errors, please notify me.

	Installation
	------------

After compilation, an executable called imapproxy will be in the 
main directory. You may copy it anywhere you like.

	Configuration
	-------------

By default, imapproxy reads a config file called ".imapproxy" in the 
current working directory.
Another configfile can be specified at the commandline (or you can change 
the default configfile in defines.h)

An example config file named "example.conf" is provided with this package.

The configfile consists of keyword/value pairs.
Comments start with #, and are obviously discarded.
Tabs and spaces are used as delimiters.
Leading and trailing delimiter characters, are ignored.

The keywords are :
	user_name :
		the user name you wish to run imapproxy [default nobody].

	group_name :
		the group name to run imapproxy [default nogroup].
	local_address, remote_address : 
		the local address to bind to (or "*" without the quotes, 
		to bind to every address), and the remote address to connect to.
		Both can be an address in IP notation or a FQDN.

	local_port, remote_port :
		the local port to bind to (the port to listen on), 
		and the remote port to connect to (most likely 143).
		Both should be numbers.
		
	debug :
		turns debug on or off. possible values are "on" and "off",
		without the quotes.
		I recommend turning this option off, as it generates 
		lots of messages.
		
	logging :
		turns logging on or off. possible values are "on" and "off",
		without the quotes.
		Imapproxy uses syslog for logging.
		
	log_facility :
		specifies the log_facility to use. Possible values are 
		"LOG_AUTH", "LOG_AUTHPRIV", "LOG_CRON", "LOG_DAEMON", 
		"LOG_KERN", "LOG_LOCAL0", "LOG_LOCAL1", "LOG_LOCAL2", 
		"LOG_LOCAL3", "LOG_LOCAL4", "LOG_LOCAL5", "LOG_LOCAL6", 
		"LOG_LOCAL7", "LOG_LPR", "LOG_MAIL", "LOG_NEWS", "LOG_SYSLOG",
		"LOG_USER" and "LOG_UUCP", without the quotes.
				
	keepalive :
		specifies the keepalive frequency in seconds.
		When a connection to the server is inactive, a NOOP is sent 
		regulary, to keep the connection alive. The period between 
		2 NOOP's is the keepalive frequency.
		
	client_timeout :
		period in seconds, after which an idle non-authenticated 
		client, is disconnected.
		
	server_timeout :
		period in seconds, after which an inactive connection to 
		the server is closed. This keeps users from staying logged 
		into the imap-server forever.

	max_reuse :
		number of times an inactive record can be reactivated before
		it is removed. This enforces aging. The default is -1, which
		means there is no aging, and the record can be reused infinitely
		(assuming that it doesn't time out of course)
		ATTENTION: setting this to 0, really means: never use this record again.
		This would make imapproxy completely useless.

	stats_frequency :
		interval in seconds after which a status message is logged. 
		This message contains the amount of records that are temporary,
		active, inactive and unknown. When set to 0, stats logging is 
		disabled.

	Accesslist:
		imapproxy has a built-in accesslist that provides control 
		over who is allowed to connect.
		The default action is to drop all connections, 
		so you will need to provide at least one entry !

		The accesslist is defined as a list of rules.
		On every incoming connection, the accesslist is searched 
		untill a rule matches. If no rule matches, the connection 
		is closed.
		
		Rules are specified as key/value pairs.
		
		accept :
			the connection is accepted if it matches this rule.
		deny :
			the connection is closed if it matches this rule.

		The values for both accept and deny, are addresses in 
		IP notation, with indication of netmask 
		(e.g. accept 127.0.0.0/255.0.0.0 or 127.0.0.0/8)
		If no netmask is given, a default of 255.255.255.255 is 
		assumed.

		I advise you to only specify the address of the IMP server
		in your access list.
			eg. accept 192.168.1.2
			where 192.168.1.2 is the IP address of the IMP server

You do not need to specify all of these keywords and their values. 
A default will be used if the keyword/value pair is not found in the configfile.

The parsed configuration can be displayed with the "-c" flag.

	Running the program
	-------------------

*****************************************************************
* IT IS STRONGLY RECOMMENDED THAT YOU DO *NOT* RUN THIS PROGRAM *
*                 AS ANY PRIVILEGED USER                        *
*****************************************************************

Usage:
        imapproxy     -v -d -h -c -f <file>

	-v      Print version information and exit.
	-d      Switch on debugging from the start (can always be unset in the configfile).
	-h      Print this help screen and exit.
	-c      Print parsed configfile and exit.
	-f file Read "file" as the config file.

The program will go in the background when started.
It will reload the configfile when it receives a SIGHUP.
All config options in a running program can be changed this way, except for 
the local_address and local_port options.

        System Specific Issues
	----------------------
If you have a high load, you may find that imapproxy causes the system, or
the imapproxy process, to exceed the limit for open files.  If so, you will
need to raise these limits.  How to raise them is system dependent. 

If you get the error 
  parent_conversate(): Couldn't create ipc pipe Too many open files
the process ran out of open files.  You might be able to fix this by
setting the open file limit via the limit or ulimit commands.  This
could be done, for example, in the startup file for imapproxy.

$Horde: imapproxy/docs/INSTALL,v 1.6 2003/02/10 16:53:22 ericr Exp $
