+subject: pop3.proxy - POP3 proxy server
POP3.PROXY(1) POP3.PROXY(1)
NAME
pop3.proxy - POP3 proxy server
SYNOPSIS
pop3.proxy [options] server
DESCRIPTION
pop3.proxy is a proxy server for the POP3 protocol. It
forwards traffic between a client and a server watching
that client and server fullfill the protocol specifica-
tion.
pop3.proxy is usually started from a TCP superserver like
inetd(1) or tcpproxy(1).
Protocol Support
pop3.proxy supports the following POP3 commands:
USER, PASS
LIST, STAT, RETR, UIDL, DELE, TOP, LAST
NOOP, RSET, QUIT
Unsupported POP3 commands result in a syslog message with-
out forwarding the command to the server. A maximum num-
ber of 5 unsupported commands per session is allowed
before the connection is terminated by the proxy. This
happens also in case of an invalid login.
If the server doesn't respond with either an `+OK' or
`-ERR' the connection is immediatly terminated.
Server Selection
If the -e switch is given on the command line the proxy
allows the client to select the POP3 server by supplying a
login username of the form
user@server
In this case the server from the command line is ignored
(it's used if the client doesn't specify the server) and
the server from the USER command is used instead. If no
default server is available or supported `-' should be
used as server name.
The set of available servers might be restricted with the
-s option. This option defines a comma separated list of
selectable servers. To match a server on the list the
client has to supply the name as it's on the list. If a
server is defined by it's IP number the IP number must be
also used in the USER command. pop3.proxy won't do any
lookup to see if a given IP number matches a server name
on the list.
A different set of username/server delimetes can be set
with the -c option.
Access Control
An external access control program (acp) can be set with
the -a switch. If set it is called immediatly before the
connection to the server is made. The program receives
the following environment variables:
PROXY_INTERFACE, PROXY_PORT
interface and port where the client is connected to
the proxy.
PROXY_CLIENT
IP number of the connected client.
PROXY_SERVER, PROXY_SERVERPORT
POP3 server name and port as given by the client.
PROXY_SERVERLOGIN
the supplied username for the POP3 server.
PROXY_USERNAME, PROXY_PASSWD
supplied username and password for usage of the
proxy server.
The values for PROXY_USERNAME and PROXY_PASSWD are taken
from the supplied remote username and password if they
contain a colon `:'. In this case the local authentica-
tion data is taken from the left side of the colon and the
remaining right side is passed on to the server.
The acp's standard output is connected to the POP3 client
and it's stderr goes to the syslog. The acp should return
an exit code of zero to grant and any other to deny access
for the client.
Proxy Authentication
pop3.proxy supports proxy authentication in conjunction
with an acp. Login information of the form
USER proxy-user:server-user[@server]
PASS proxy-pass:server-pass
is processed in the obious way and given to the acp which
has to verify the proxy login.
Client Logging
Beside of the messages that go to syslog pop3.proxy can
record the last succesful login from a client in the
directory given with the -l option. This file contains
the time, client, username and POP3 server of the last
succesful server login. These files can be either used
for quick debugging or in conjunction with smtp.proxy(1)
to grant access to the SMTP service.
Virus Scanning
pop3.proxy scans every e-mails using clamav as scan engine
if the -z option is set. In this mode pop3.proxy spools
first every e-mail from the server to a temporary file
which is scanned by clamd. If it's clean it's sent to the
client and replaced with a short virus notification other-
wise. If pop3.proxy can't connect to clamd or clamd
behaves strange, pop3.proxy refuses to work.
To configure virus scanning clamav's scan daemon clamd
must run and listen on the local TCP/IP port 3310 for ser-
vice requests. Furthermore pop3.proxy must be started
with the -z option. The -u option can be used to start
pop3.proxy with the same user as clamd to give the scanner
read access to the temporary mail file.
Daemon Mode
pop3.proxy can run as standalone daemon (binding and
listening on the service port on it's own) if the -D
option is set. If -D is given twice the service port can
be set on the command line. When running in daemon mode
pop3.proxy forks automatically into the background if the
debug -d option is not set.
Logging
The way pop3.proxy writes it's syslog has changed in ver-
sion 1.3.0. Prior version wrote their log data always to
syslog. Since version 1.3.0 the loglines are written to
stderr if pop3.proxy runs in debug mode and to syslog
else.
OPTIONS
The following options are available:
-a acp set pathname of the access control program.
-c charset
define charset for the username/server delimeter,
default is `@'.
-e enables server selection by the client.
-l dir if the client logs succesfully into the server
pop3.proxy creates the file dir/clientip.
Notice that dir must be writable be the userid
under which pop3.proxy is started. If pop3.proxy
is started by root it will change it's uid/gid to
65535/65534.
-m reduce the number of syslog messages.
-q srcip
sets the source IP-number of the outgoing connec-
tion to the POP3 server.
-s serverlist
defines a comma separated list of POP3 servers that
can be selected by the client. The characters `?'
and `*' may be used as wildcards. -e must also be
specified.
-t timeout
specify a different POP3 timeout in seconds than
the default of 600 (10 minutes).
-u user
sets the username under which pop3.proxy should
run. The default is `nobody'.
-v prefix
sets a different variable prefix for the acp than
PROXY_.
-z turns virus scanning on.
-D | -DD [interface:]port
starts pop3.proxy as standalone server. If -D is
given twice pop3.proxy expects the server port
where it should listen for incoming requests.
EXAMPLES
To start pop3.proxy from inetd you can add a line like
pop3 stream tcp nowait nobody \
/usr/local/sbin/pop3.proxy pop3.proxy server
to /etc/inetd.conf. Notice that the packed makefile
installs pop3.proxy under /usr/local/sbin. In this case
you have to put the full path into inetd.conf.
If you are running an application gateway firewall and you
have local users connecting to external POP3 servers and
external users connecting to local POP3 servers you might
want to prefer to start pop3.proxy from tcpproxy (or
another superserver with interface depending configura-
tion) to define different proxy configurations for differ-
ent interfaces.
If your local interface has the IP number 192.168.1.1 and
your external is 140.77.194.1 you can set up your tcp-
proxy.conf like
port 110
interface 192.168.1.1
exec /usr/local/sbin/pop3.proxy -e
interface 140.77.194.1
exec /usr/local/sbin/pop3.proxy local-pop3
and configure inetd with
pop3 stream tcp nowait nobody tcpproxy tcpproxy
to do the job.
Daemon Mode
Type
pop3.proxy -D
at the command prompt to start pop3.proxy as standalone
daemon listening on POP3's standard port 110.
pop3.proxy -d -D
starts pop3.proxy in debug mode.
SEE ALSO
inetd(1), tcpproxy(1).
05 December 1999 POP3.PROXY(1)
