.TH FTP-GW 8 "March 2007" "OpenFWTK"
.SH NAME
ftp-gw \- FTP proxy
.SH SYNOPSIS
.B ftp-gw 
.RB "[-daemon <port>] "
.RB "[-fastdaemon <port>] [-as <tag>]"
.sp
.SH DESCRIPTION
.IX  "ftp-gw"  ""  "\(em FTP proxy"
The Firewall Toolkit FTP proxy is an application level proxy that provides
configurable access control, authentication and logging  mechanisms.
The FTP proxy, which runs on the firewall, passes FTP 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
FTP command (for example, STOR and RETR)
.PP
All packets, and therefore all application requests go to the
firewall.  On the firewall, the FTP 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
is passed at the application level.
.PP
The default configuration for the FTP proxy does not allow 
inbound connections from outside the defense perimeter to
inside.  This means that users must connect to the firewall,
authenticate, and then can FTP to the host inside the perimeter.
.PP
The FTP proxy
.RB "(" ftp-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/21, as indicated
in
.IR "/etc/services" 
,is reasonable default).
Whenever the system receives an FTP request on this port, the FTP
proxy checks its configuration information (in the
.IR "netperm-table" )
and determines whether the initiating host has permission to use
FTP. 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 authenticates the user (if
required), logs the transaction and passes the request to the
destination host.
.PP
.SH OPTIONS
.SS Command Line Options
The FTP 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 FTP proxy runs as a daemon, and the port (name
or number) on which the FTP 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 FTP proxy runs as a daemon, and the port (name
or number) on which the FTP 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 "ftp-gw" to any given 
string.
.SS Configuration Options
The FTP proxy reads configuration rules from the
.IR "/usr/local/etc/netperm-table" .
It reads all rules using the
.B ftp-gw
and
.B *
(wildcard) keywords. The FTP 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 FTP 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 FTP proxy recognizes the following attributes:
.TP
.BI "authserver " "host port"
Specifies the host running the authentication server (and the port
on which it runs) that the proxies use for authenticating users.
.RS
.TP
.I host
Specifies an IP address or host name.
.TP
.I port
Specifies a service name or port number.
.RE
.TP
.BI "denial-msg " file
Specifies the name of the file the FTP proxy displays when it denies
access to a user because they do not have permission to use the
FTP proxy.  If no file is specified, the FTP proxy generates a
default message.
.TP
.BI "denydest-msg " file
Specifies the name of the file the FTP proxy displays when it denies
access to a user because they are trying to access a destination
that they are not permitted to access.  If no file is specified,
the FTP proxy generates a default message.
.TP
.BI "user-limit " number
Specifies max permitted username length.
.TP
.BI "pass-limit " number
Specifies max permitted password length.
.TP
.BI "buf-limit " number
Specifies max permitted protocol line size (user command or response).
.TP
.B hosts host-pattern [host-pattern2...] [options]
rules specify host and access permissions. Typically, a
hosts rule will be in the form of:
.na
.sp 1
ftp-gw: deny-hosts unknown
.sp
ftp-gw: hosts 192.33.112.* 192.94.214.*  -log { retr stor }
.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
.B \-plug-to server-address
specifies that proxy is "hardwired" to a given server.
.IP
.B \-port server-port
overrides default ftp port for plug-to
.IP
.B \-log operation
.br
.B \-log { operation1 operation2 ... }
.br
specifies that a log entry to the system log should be made
whenever the listed operations are performed through the
proxy. (See
.B ftpd(8)
for a list of known FTP operations)
.IP
.B \-authall
specifies that the proxy should permit no operation (other
than the
.I quit
command) until the user has authenticated to the server.
.IP
.B \-auth operation
.br
.B \-auth { operation1 operation2 ... }
.br
specifies that the operations listed should not be permitted
until the user has authenticated to the server.
.IP
.B \-dest pattern
.br
.B \-dest { pattern1 pattern2 ... }
.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
.B \-deny operation
.br
.B \-deny { operation1 operation2 ... }
specifies a list of FTP operations to deny. By default, all
operations are permitted.
.IP
.B \-user username
.br
.B \-user { username1 username2 ... }
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
.B \-separator separator-char
specifies separator character used to distinguish user and host name
parts in non-transparent mode (instead of default `@').
.IP
.B \-clientcmd-dscp dscp-tag-name
.br
.B \-clientcmd-dscp dscp-hex-value
specifies diffserv codepoint (QoS/ToS mark) for client to proxy command
stream.
.IP
.B \-clientdata-dscp dscp-tag-name
.br
.B \-clientdata-dscp dscp-hex-value
specifies diffserv codepoint (QoS/ToS mark) for client to proxy data
stream.
.IP
.B \-servercmd-dscp dscp-tag-name
.br
.B \-servercmd-dscp dscp-hex-value
specifies diffserv codepoint (QoS/ToS mark) for proxy to server command
stream.
.IP
.B \-serverdata-dscp dscp-tag-name
.br
.B \-serverdata-dscp dscp-hex-value
specifies diffserv codepoint (QoS/ToS mark) for proxy to server data
stream.
.IP
.B \-keepalive-timeout timeout
specifies period to send "keepalive" packets while performing content
inspection to prevent peers from disconnecting due to inactivity.
.RE
.TP
.B content-type type/subtype [-milter filter-socket]
rules specify content type permissions. Typically, a
content-type rule will be in the form of:
.na
.sp 1
ftp-gw: deny-content-type application/x-dosexec 
.sp
ftp-gw: permit-content-type text/plain text.rtf image/*
.sp
ftp-gw: content-type application/msole -milter unix:/var/tmp/antivirus.sock
.ad
.sp 1
There may be several content-type patterns following the "content-type"
keyword, ending with the first optional parameter beginning
with '-'. At the moment only "-milter" parameter is supported,
specifying content inspection server (unix:/domain-path or inet:port@host
syntax).
.TP
.BI "directory " directory
Specifies the directory that the FTP proxy makes its root directory
before providing service.  This option is equivalent to the
.B chroot
option in previous versions.
.TP
.BI "groupid " group
Specifies the name of the group the FTP proxy uses when running.
.RS
.TP
.I group
Specifies either a name or numeric id from the
.I /etc/group
file.
.RE
.TP
.BI "help-msg " file
Specifies the name of the file the FTP proxy displays when the user
accesses the help command.  If no file is specified, the FTP proxy
displays a list of internal commands.
.TP
.BI "timeout " seconds
Specifies the number of seconds the FTP 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
.TP
.BI "welcome-msg " file
Specifies the name of the file the proxy displays as a welcome
banner upon successful connection to the proxy.  If no file is
specified, the proxy generates a default message.
.SS Proxy Commands
The FTP proxy recognizes all FTP server commands.  The following
ones are of special interest:
.TP
.B help
Displays a list of valid commands for the FTP server.
.TP
.B quit
Exits the FTP proxy.
.TP
.BI "quote " options
Sends the options verbatim to the remote FTP server.  This option
is useful when the FTP client does not have support for
authentication.  In order to authenticate to the FTP proxy, you
must use the
.BI "quote auth " username
command to send the user name and the
.BI "quote resp " password
command to send the password.  When using the
.B quote
command, all information (including passwords) is echoed to the
screen.
.TP
.BI "user " "username@host"
Connects to the remote host using the given user name and password.
.RS
.TP
.I username
Specifies the name of the user on the remote host.
.TP
.I host
Specifies the name of the remote host.
.PP
You must use
the
.B user
command to tell the proxy the name of the remote host to which you
wish to connect.
.RE
.TP
.B ?
Displays a list of valid commands for the FTP server.
.SH EXAMPLES
This example shows the configuration lines in the
.I netperm-table
that denies
.B ftp.bigu.edu
as a destination and sets the name of the file that the FTP proxy
displays when users try to access this site:
.sp 1
.nf
.na
.RS
#deny ftp.bigu.edu as a destination (by IP address)
ftp-gw: deny-destination 192.168.1.100
.sp 1
#file to display when users try to access a denied site
ftp-gw: denial-msg /usr/local/etc/ftp-deny.txt
.RE
.fa
.fi
.sp 1
A common policy for the FTP proxy is to authenticate all requests
from untrusted networks to or through the firewall.  This example
shows a sample FTP session from an untrusted network to a trusted
network, using S/Key authentication at the firewall:
.sp 1
.nf
.na
.RS
.RB "blaze.clientsite.com-27: " "ftp firewall.yoyodyne.com"
Connected to firewall.yoyodyne.com
220-Proxy first requires authentication
220 firewall.yoyodyne.com FTP proxy (Version 3.1) ready.
.RB "Name (firewall.yoyodyne.com:clancy): " clancy
331 Skey Challenge: s/key 653 fi19289
.RI "Password:                         " "password does not display"
230 User authenticated to proxy
.RB "ftp> " "user clancy@dimension"
331- (-----GATEWAY CONNECTED TO dimension----)
331- (220 dimension FTP server ready.)
331 Password required for clancy.
.RB "Password: " #########
230 User clancy logged in.
ftp>
.RE
.fa
.fi
.SH FILES
.IP /etc/rc.local
Command script that controls automatic reboot, and includes startup
information for the FTP proxy.
.IP /usr/local/etc/netperm-table
The network permissions file contains configuration information
for the Firewall Toolkit, including the FTP proxy.
.SH BUGS
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 FTP
proxy.
.SH AUTHOR
Alexei Kravchuk, based on "fk toolkit" ftp proxy by Matthew Kirkwood.
.SH SEE ALSO
.BR netperm-table "(5), " rc "(8), "authsrv "(8), "netacl "(8)"