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 specification.

       pop3.proxy is usually started from a TCP superserver  like
       inetd(1) or multiproxy(1).

   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  authentication
       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.

   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 without
       forwarding the command to the server.  A maximum  number
       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.


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.

       -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).

       -v prefix
              set  a  different  variable prefix for the acp than
              PROXY_.


EXAMPLES
       To start pop3.proxy from inetd you can add a line like

            pop3 stream tcp nowait nobody  pop3.proxy  pop3.proxy
            server

       to  /etc/inetd.conf.   Notice  that  the  packed  makefile
       install 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  multiproxy  because
       here  you  can configure service commands depending on the
       interface.
       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 multiproxy.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 multiproxy multiproxy

       to do the job.

   Access control
       Since access control uses  an  external  program  you  can
       grant or deny access on almost everthing.

             #!/bin/akanga -p
             #
             # access control program for POP3 proxy
             #

             #
             # Simply allow connections from outside.
             #
             if (~ $PROXY_INTERFACE 140.77.194.1)
                 exit 0

             #
             # Important users have the IP numbers
             # 192.168.1.10,11,45, allow them.
             #
             if (~ $PROXY_CLIENT *.10 *.11 *.45)
                 exit 0

             #
             # Get the current hour.
             #
             now = `{ date +'%H' }

             if (~ $PROXY_SERVER *.yahoo.com *.hotmail.*) {
                 #
                 # Private usage, restriced to lunch breaks
                 # from 12:00 to 13:00.
                 #
                 if (! ~ $now 12) {
                      echo -ERR try later again
                      echo private usage: $PROXY_SERVER >[1=2]
                      exit 1
                      }
                 }

             #
             # For some reason the outgoing POP3 proxy is only
             # available during working
             # hours.
             #
             if (! ~ $now 08 09 10 11 12 13 14 15 16 17 18) {
                 echo -ERR server not available
                 echo out of time window >[1=2]
                 exit 1
                 }

             exit 0

       Notice  that  the example above is an akanga script.  This
       shell uses different syntax than the `*sh' shells.

SEE ALSO
       inetd(1), multiproxy(1).

