1.\" $OpenBSD: ftp-proxy.8,v 1.42 2004/11/19 00:47:23 jmc Exp $ 2.\" 3.\" Copyright (c) 1996-2001 4.\" Obtuse Systems Corporation, All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY OBTUSE SYSTEMS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL OBTUSE OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd August 17, 2001 33.Dt FTP-PROXY 8 34.Os 35.Sh NAME 36.Nm ftp-proxy 37.Nd Internet File Transfer Protocol proxy server 38.Sh SYNOPSIS 39.Nm ftp-proxy 40.Bk -words 41.Op Fl AnrVw 42.Op Fl a Ar address 43.Op Fl D Ar debuglevel 44.Op Fl g Ar group 45.Op Fl M Ar maxport 46.Op Fl m Ar minport 47.Op Fl R Ar address[:port] 48.Op Fl S Ar address 49.Op Fl t Ar timeout 50.Op Fl u Ar user 51.Ek 52.Sh DESCRIPTION 53.Nm 54is a proxy for the Internet File Transfer Protocol. 55The proxy uses 56.Xr pf 4 57and expects to have the FTP control connection as described in 58.Xr services 5 59redirected to it via a 60.Xr pf 4 61.Em rdr 62command. 63An example of how to do that is further down in this document. 64.Pp 65The options are as follows: 66.Bl -tag -width Ds 67.It Fl A 68Permit only anonymous FTP connections. 69The proxy will allow connections to log in to other sites as the user 70.Qq ftp 71or 72.Qq anonymous 73only. 74Any attempt to log in as another user will be blocked by the proxy. 75.It Fl a Ar address 76Specify the local IP address to use in 77.Xr bind 2 78as the source for connections made by 79.Nm ftp-proxy 80when connecting to destination FTP servers. 81This may be necessary if the interface address of 82your default route is not reachable from the destinations 83.Nm 84is attempting connections to, or this address is different from the one 85connections are being NATed to. 86In the usual case this means that 87.Ar address 88should be a publicly visible IP address assigned to one of 89the interfaces on the machine running 90.Nm 91and should be the same address to which you are translating traffic 92if you are using the 93.Fl n 94option. 95.It Fl D Ar debuglevel 96Specify a debug level, where the proxy emits verbose debug output 97into 98.Xr syslogd 8 99at level 100.Dv LOG_DEBUG . 101Meaningful values of debuglevel are 0-3, where 0 is no debug output and 1023 is lots of debug output, the default being 0. 103.It Fl g Ar group 104Specify the named group to drop group privileges to, after doing 105.Xr pf 4 106lookups which require root. 107By default, 108.Nm 109uses the default group of the user it drops privilege to. 110.It Fl M Ar maxport 111Specify the upper end of the port range the proxy will use for the 112data connections it establishes. 113The default is 114.Dv IPPORT_HILASTAUTO 115defined in 116.Aq Pa netinet/in.h 117as 65535. 118.It Fl m Ar minport 119Specify the lower end of the port range the proxy will use for all 120data connections it establishes. 121The default is 122.Dv IPPORT_HIFIRSTAUTO 123defined in 124.Aq Pa netinet/in.h 125as 49152. 126.It Fl n 127Activate network address translation 128.Pq NAT 129mode. 130In this mode, the proxy will not attempt to proxy passive mode 131.Pq PASV or EPSV 132data connections. 133In order for this to work, the machine running the proxy will need to 134be forwarding packets and doing network address translation to allow 135the outbound passive connections from the client to reach the server. 136See 137.Xr pf.conf 5 138for more details on NAT. 139The proxy only ignores passive mode data connections when using this flag; 140it will still proxy PORT and EPRT mode data connections. 141Without this flag, 142.Nm 143does not require any IP forwarding or NAT beyond the 144.Em rdr 145necessary to capture the FTP control connection. 146.It Fl R Ar address:[port] 147Reverse proxy mode for FTP servers running behind a NAT gateway. 148In this mode, no redirection is needed. 149The proxy is run from 150.Xr inetd 8 151on the port that external clients connect to (usually 21). 152Control connections and passive data connections are forwarded 153to the server. 154.It Fl r 155Use reverse host 156.Pq reverse DNS 157lookups for logging and libwrap use. 158By default, 159the proxy does not look up hostnames for libwrap or logging purposes. 160.It Fl S Ar address 161Source address to use for data connections made by the proxy. 162Useful when there are multiple addresses (aliases) available 163to the proxy. 164Clients may expect data connections to have the same source 165address as the control connections, and reject or drop other 166connections. 167.It Fl t Ar timeout 168Specifies a timeout, in seconds. 169The proxy will exit and close open connections if it sees no data 170for the duration of the timeout. 171The default is 0, which means the proxy will not time out. 172.It Fl u Ar user 173Specify the named user to drop privilege to, after doing 174.Xr pf 4 175lookups which require root privilege. 176By default, 177.Nm 178drops privilege to the user 179.Em proxy . 180.Pp 181Running as root means that the source of data connections the proxy makes 182for PORT and EPRT will be the RFC mandated port 20. 183When running as a non-root user, the source of the data connections from 184.Nm 185will be chosen randomly from the range 186.Ar minport 187to 188.Ar maxport 189as described above. 190.It Fl V 191Be verbose. 192With this option the proxy logs the control commands 193sent by clients and the replies sent by the servers to 194.Xr syslogd 8 . 195.It Fl w 196Use the tcp wrapper access control library 197.Xr hosts_access 3 , 198allowing connections to be allowed or denied based on the tcp wrapper's 199.Xr hosts.allow 5 200and 201.Xr hosts.deny 5 202files. 203The proxy does libwrap operations after determining the destination 204of the captured control connection, so that tcp wrapper rules may 205be written based on the destination as well as the source of FTP connections. 206.El 207.Pp 208.Nm ftp-proxy 209is run from 210.Xr inetd 8 211and requires that FTP connections are redirected to it using a 212.Em rdr 213rule. 214A typical way to do this would be to use a 215.Xr pf.conf 5 216rule such as 217.Bd -literal -offset 2n 218int_if = \&"xl0\&" 219rdr pass on $int_if proto tcp from any to any port 21 -> 127.0.0.1 port 8021 220.Ed 221.Pp 222.Xr inetd 8 223must then be configured to run 224.Nm 225on the port from above using 226.Bd -literal -offset 2n 227ftp-proxy stream tcp nowait root /usr/libexec/ftp-proxy ftp-proxy 228.Ed 229.Pp 230in 231.Xr inetd.conf 5 . 232.Pp 233.Nm 234accepts the redirected control connections and forwards them 235to the server. 236The proxy replaces the address and port number that the client 237sends through the control connection to the server with its own 238address and proxy port, where it listens for the data connection. 239When the server opens the data connection back to this port, the 240proxy forwards it to the client. 241The 242.Xr pf.conf 5 243rules need to let pass connections to these proxy ports 244(see options 245.Fl u , m , 246and 247.Fl M 248above) in on the external interface. 249The following example allows only ports 49152 to 65535 to pass in 250statefully: 251.Bd -literal -offset indent 252block in on $ext_if proto tcp all 253pass in on $ext_if inet proto tcp from any to $ext_if \e 254 port > 49151 keep state 255.Ed 256.Pp 257Alternatively, rules can make use of the fact that by default, 258.Nm 259runs as user 260.Qq proxy 261to allow the backchannel connections, as in the following example: 262.Bd -literal -offset indent 263block in on $ext_if proto tcp all 264pass in on $ext_if inet proto tcp from any to $ext_if \e 265 user proxy keep state 266.Ed 267.Pp 268These examples do not cover the connections from the proxy to the 269foreign FTP server. 270If one does not pass outgoing connections by default additional rules 271are needed. 272.Sh SEE ALSO 273.Xr ftp 1 , 274.Xr pf 4 , 275.Xr hosts.allow 5 , 276.Xr hosts.deny 5 , 277.Xr inetd.conf 5 , 278.Xr pf.conf 5 , 279.Xr inetd 8 , 280.Xr pfctl 8 , 281.Xr syslogd 8 282.Sh BUGS 283Extended Passive mode 284.Pq EPSV 285is not supported by the proxy and will not work unless the proxy is run 286in network address translation mode. 287When not in network address translation mode, the proxy returns an error 288to the client, hopefully forcing the client to revert to passive mode 289.Pq PASV 290which is supported. 291EPSV will work in network address translation mode, assuming a 292.Xr pf.conf 5 293setup which allows the EPSV connections through to their destinations. 294.Pp 295IPv6 is not yet supported. 296