.TH POP3-GW 8 "August 2007" "OpenFWTK"
.SH NAME
pop3-gw \- post office protocol version 3 proxy
.SH SYNOPSIS
.B pop3-gw 
.RB "[-daemon <port>] "
.RB "[-fastdaemon <port>] [-as <tag>]"
.sp
.SH DESCRIPTION
.IX  "pop3-gw"  ""  "\(em post office protocol version 3 proxy"
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:
.IP "\(bu" 4m
source IP address
.IP "\(bu" 4m
source host name
.IP "\(bu" 4m
destination IP address
.IP "\(bu" 4m
destination host name
.IP "\(bu" 4m
POP3 command (say, RETR or DELE)
.PP
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.
.PP
To use the proxy in non-transparent mode, 
.I POP3 
\'username\' part should be substituted with
.I username@host
where 
.I @ 
is separator symbol which may be configured otherwise.
.PP
The proxy uses APOP authentication to server even if
the client performs USER/PASS plaintext authentication.
.PP
The POP3 proxy
.RB "(" pop3-gw ")"
generally runs as a daemon (invoked from system startup script, p.e.
.IR "/etc/rc.local" )
and listens for requests on the specified port (tcp/110, as indicated
in
.IR "/etc/services" 
,is reasonable default).
Whenever the system receives an POP3 request on this port, the pop3
proxy checks its configuration information (in the
.IR "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.
.PP
The proxy may also be invoked from tcp/ip "superserver" (inetd or xinetd).
.IR "-daemon" 
parameter should be omitted in this case.
.PP
If the host has permission, the proxy 
logs the transaction and passes the request to the
destination host.
.PP
.SH OPTIONS
.SS Command Line Options
The POP3 proxy recognizes the following command line options (whether
started from the command line or from within
.IR /etc/rc.local ):
.TP
.BI "-daemon " port
Indicates that the POP3 proxy runs as a daemon, and the port (name
or number) on which the POP3 proxy listens. When 
.IR "-daemon" 
option is used, configuration is being read from
.IR netperm-table
for every new connection accepted by proxy.
.IP
.I port
Specifies either a numeric id or symbolic name from the
.I /etc/services
file.
.TP
.BI "-fastdaemon " port
Indicates that the POP3 proxy runs as a daemon, and the port (name
or number) on which the POP3 proxy listens. When
.IR "-fastdaemon" 
option is used, configuration is being read from
.IR netperm-table
once the daemon starts or if 
.IR SIGHUP 
is received.
.TP
.BI "-as " tag
Changes default application tag for 
.IR netperm-table 
from "pop3-gw" to any given 
string.
.SS Configuration Options
The POP3 proxy reads configuration rules from the
.IR "/usr/local/etc/netperm-table" .
It reads all rules using the
.B pop3-gw
and
.B *
(wildcard) keywords. The POP3 proxy reads the
.I 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
.BR "netperm-table"  (5)
for a more complete explanation of 
.I netperm-table
syntax and precedence.
.PP
The POP3 proxy recognizes the following attributes:
.TP
.BI "user-limit " number
Specifies max permitted username length.
.TP
.BI "pass-limit " number
Specifies max permitted password length.
.TP
.BI "hosts " "host-pattern [host-pattern...] [options]"
rules specify host and access permissions. Typically, a
hosts rule will be in the form of:
.na
.sp 1
pop3-gw: deny-hosts unknown
.sp
pop3-gw: hosts 192.33.112.* 192.94.214.* -fallback
.ad
.sp 1
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:
.IP
.IP
.B \-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. 
.IP
.BI "\-plug-to " server-address
specifies that proxy is "hardwired" to a given server.
.IP
.BI "\-port " server-port
overrides default pop3 port for plug-to
.IP
.B \-apop-only
Being used with -trasnparent or -plug-to, disallow user/pass
authentication on client side.
.IP
.B \-fallback
Permit fallback to insecure protocol.
.IP
.BI "\-log " operation
.br
.BI "\-log { " "operation [operation..]" }
.br
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:
.RS
.IP  \(bu 4n
STAT
.IP  \(bu 4n
LIST
.IP  \(bu 4n
RETR
.IP  \(bu 4n
DELE
.IP  \(bu 4n
NOOP
.IP  \(bu 4n
RSET
.IP  \(bu 4n
UIDL
.IP  \(bu 4n
TOP
.IP  \(bu 4n
LAST
.IP  \(bu 4n
QUIT
.RE
.IP
.BI "\-dest " pattern
.br
.BI "\-dest {" "pattern [pattern..]" }
.br
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:
.sp
.nf
.na
-dest !*.mit.edu -dest *
.fi
.ad
.sp
will permit hosts that are not in the domain "mit.edu" to be
connected to.
.IP
.BI "\-deny " operation
.br
.BI "\-deny {" "operation [operation..]" }
.br
specifies a list of POP3 operations to deny. By default, all
operations are permitted. 
.IP
.BI "\-user " username
.br
.BI "\-user {" "username [username..]" }
specifies a list of users allowed to authenticate to remote server. 
By default, all users are permitted.
.IP
.B \-extnd
specifies that the proxy should request per-operation permissions
from authsrv.
.IP
.BI "\-separator " separator-char
specifies separator character used to distinguish user and host name
parts in non-transparent mode (instead of default `@').
.IP
.BI "\-client-dscp " dscp-tag-name
.br
.BI "\-client-dscp " dscp-hex-value
specifies diffserv codepoint (QoS/ToS mark) for client to proxy connection.
.IP
.BI "\-server-dscp " dscp-tag-name
.br
.BI "\-server-dscp " dscp-hex-value
specifies diffserv codepoint (QoS/ToS mark) for proxy to server connection.
.TP
.BI "milter " filter
Defines content inspection filter socket address in unix:/domain-path 
or inet:port@host format.
.TP
.BI "milter-reject-policy " policy
Defines action if a message was rejected by content filter.
Valid values for
.I policy
are:
.RS
.IP  \(bu 4n
replace - replace message with notification
.IP  \(bu 4n
delete - delete message and send -ERR to client
.IP  \(bu 4n
keep - send -ERR to client but do not delete
.RE
.TP
.BI "directory " directory
Specifies the directory that the POP3 proxy makes its root directory
before providing service.  
.TP
.BI "groupid " group
Specifies the name of the group the POP3 proxy uses when running.
.RS
.TP
.I group
Specifies either a name or numeric id from the
.I /etc/group
file.
.RE
.TP
.BI "timeout " seconds
Specifies the number of seconds the POP3 proxy is idle (with no
network activity) before disconnecting
.TP
.BI "userid " user
Specifies the user ID the proxy uses when running.
.RS
.TP
.I user
Specifies either a name or numeric id from the
.I /etc/passwd
file. This option is equivalent to the
.B -user
command in previous versions.
.RE
.SH EXAMPLES
The following example defines simple pop3 access policy
.sp
.nf
.na
.RS
# 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
.RE
.fa
.fi
.sp
.SH FILES
.IP /etc/rc.local
Command script that controls automatic reboot, and includes startup
information for the POP3 proxy.
.IP /usr/local/etc/netperm-table
The network permissions file contains configuration information
for the Firewall Toolkit, including the POP3 proxy.
.SH BUGS
POP3 protocol is plaintext. Use content encryption (S/MIME, PGP) to
transmit sensitive information.
.sp
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.
.SH AUTHOR
ArkanoiD.
.SH SEE ALSO
.BR netperm-table "(5), " rc "(8), "authsrv "(8), "netacl "(8)"