libexec/ftp-proxy/ftp-proxy.8

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