POP3-GW(8)

NAME
pop3-gw - post office protocol version 3 proxy

SYNOPSIS
pop3-gw [-daemon <port>] [-fastdaemon <port>] [-as <tag>]

DESCRIPTION
The Firewall Toolkit POP3 proxy is an application level proxy that provides configurable access control, authentication and logging mechanisms. The POP3 proxy, which runs on the firewall, passes POP3 requests through the firewall (at the application level), using rules you supply. You can configure the proxies to allow connections based on:

•   source IP address

•   source host name

•   destination IP address

•   destination host name

•   POP3 command (say, RETR or DELE)

All packets, and therefore all application requests go to the firewall. On the firewall, the POP3 proxy software relays information from one side of the firewall to the other. The proxy prevents the applications on outside networks from talking directly with the applications on your inside network, and vice versa. No IP packets pass from one side of the firewall to the other. All data are passed at the application level.

To use the proxy in non-transparent mode, POP3 'username' part should be substituted with username@host where @ is separator symbol which may be configured otherwise.

The proxy uses APOP authentication to server even if the client performs USER/PASS plaintext authentication.

The POP3 proxy (pop3-gw) generally runs as a daemon (invoked from system startup script, p.e. /etc/rc.local) and listens for requests on the specified port (tcp/110, as indicated in /etc/services ,is reasonable default). Whenever the system receives an POP3 request on this port, the pop3 proxy checks its configuration information (in the netperm-table) and determines whether the initiating host has permission to use pop3. If the host does not have permission, the proxy logs the connection attempt and displays an error message.

The proxy may also be invoked from tcp/ip "superserver" (inetd or xinetd). -daemon parameter should be omitted in this case.

If the host has permission, the proxy logs the transaction and passes the request to the destination host.

OPTIONS

  Command Line Options
The POP3 proxy recognizes the following command line options (whether started from the command line or from within /etc/rc.local):

-daemon port
    Indicates that the POP3 proxy runs as a daemon, and the port (name or number) on which the POP3 proxy listens. When -daemon option is used, configuration is being read from netperm-table for every new connection accepted by proxy.

    port Specifies either a numeric id or symbolic name from the /etc/services file.

-fastdaemon port
    Indicates that the POP3 proxy runs as a daemon, and the port (name or number) on which the POP3 proxy listens. When -fastdaemon option is used, configuration is being read from netperm-table once the daemon starts or if SIGHUP is received.

-as tag
    Changes default application tag for netperm-table from "pop3-gw" to any given string.

  Configuration Options
The POP3 proxy reads configuration rules from the /usr/local/etc/netperm-table. It reads all rules using the pop3-gw and * (wildcard) keywords. The POP3 proxy reads the netperm-table from top to bottom. If there are multiple rules in the table that could apply for a particular attribute, the POP3 proxy uses the first one that it finds. See netperm-table(5) for a more complete explanation of netperm-table syntax and precedence.

The POP3 proxy recognizes the following attributes:

user-limit number
    Specifies max permitted username length.

pass-limit number
    Specifies max permitted password length.

hosts host-pattern [host-pattern...] [options]
    rules specify host and access permissions. Typically, a hosts rule will be in the form of:

    pop3-gw: deny-hosts unknown

    pop3-gw: hosts 192.33.112.* 192.94.214.* -fallback

    There may be several host patterns following the "hosts" keyword, ending with the first optional parameter beginning with '-'. Optional parameters permit the selective enabling or disabling of logging information, etc. Sub-options are:

    -transparent specifies that the proxy runs in transparent mode; see OS-specific details on how to setup transparent redirection. Proxy destination host is not extracted from username part but taken from connection properties instead. This makes proxy "transparent", so no special client setup is required.

    -plug-to server-address specifies that proxy is "hardwired" to a given server.

    -port server-port overrides default pop3 port for plug-to

    -apop-only Being used with -trasnparent or -plug-to, disallow user/pass authentication on client side.

    -fallback Permit fallback to insecure protocol.

    -log operation
    -log { operation [operation..]}
    specifies that a log entry to the system log should be made whenever the listed operations are performed through the proxy. Proxy recogizes following operations:

    •   STAT

    •   LIST

    •   RETR

    •   DELE

    •   NOOP

    •   RSET

    •   UIDL

    •   TOP

    •   LAST

    •   QUIT

    -dest pattern
    -dest {pattern [pattern..]}
    specifies a list of valid destinations. If no list is specified, all destinations are considered valid. The -dest list is processed in order as it appears on the options line. -dest entries preceeded with a '!' character are treated as negation entries. Therefore the rule:

    -dest !*.mit.edu -dest *

    will permit hosts that are not in the domain "mit.edu" to be connected to.

    -deny operation
    -deny {operation [operation..]}
    specifies a list of POP3 operations to deny. By default, all operations are permitted.

    -user username
    -user {username [username..]} specifies a list of users allowed to authenticate to remote server. By default, all users are permitted.

    -extnd specifies that the proxy should request per-operation permissions from authsrv.

    -separator separator-char specifies separator character used to distinguish user and host name parts in non-transparent mode (instead of default `@').

    -client-dscp dscp-tag-name
    -client-dscp dscp-hex-value specifies diffserv codepoint (QoS/ToS mark) for client to proxy connection.

    -server-dscp dscp-tag-name
    -server-dscp dscp-hex-value specifies diffserv codepoint (QoS/ToS mark) for proxy to server connection.

milter filter
    Defines content inspection filter socket address in unix:/domain-path or inet:port@host format.

milter-reject-policy policy
    Defines action if a message was rejected by content filter. Valid values for policy are:

    •   replace - replace message with notification

    •   delete - delete message and send -ERR to client

    •   keep - send -ERR to client but do not delete

directory directory
    Specifies the directory that the POP3 proxy makes its root directory before providing service.

groupid group
    Specifies the name of the group the POP3 proxy uses when running.

    group
        Specifies either a name or numeric id from the /etc/group file.

timeout seconds
    Specifies the number of seconds the POP3 proxy is idle (with no network activity) before disconnecting

userid user
    Specifies the user ID the proxy uses when running.

    user
        Specifies either a name or numeric id from the /etc/passwd file. This option is equivalent to the -user command in previous versions.

EXAMPLES
The following example defines simple pop3 access policy

    # permit workstations at LAN to access outside POP3 servers
    pop3-gw: permit-hosts 10.0.0.*
    # enable antivirus check
    pop3-gw: milter inet:5000@avserver.alpha.int
    pop3-gw: milter-reject-policy replace

FILES

/etc/rc.local
    Command script that controls automatic reboot, and includes startup information for the POP3 proxy.

/usr/local/etc/netperm-table
    The network permissions file contains configuration information for the Firewall Toolkit, including the POP3 proxy.

BUGS
POP3 protocol is plaintext. Use content encryption (S/MIME, PGP) to transmit sensitive information.

Report bugs to arkenoi@gmail.com or fwtk-users@buoy.com mailing list. Include a complete example, explaining what you expected to happen and what actually happened. Be sure to indicate the type of system (operating system, hardware, etc.) you are using, as well as the version of the pop3 proxy.

AUTHOR
ArkanoiD.

SEE ALSO
netperm-table(5), rc(8), authsrv(8), netacl(8)