libexec/ftp-proxy/ftp-proxy.8

   1 .\"     $OpenBSD: ftp-proxy.8,v 1.41 2004/07/06 19:49:11 dhartmei Exp $
   2 .\"     $DragonFly: src/libexec/ftp-proxy/ftp-proxy.8,v 1.2 2005/02/24 15:38:09 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 .Bk -words
  40 .Op Fl AnrVw
  41 .Op Fl a Ar address
  42 .Op Fl D Ar debuglevel
  43 .Op Fl g Ar group
  44 .Op Fl M Ar maxport
  45 .Op Fl m Ar minport
  46 .Op Fl R Ar address[:port]
  47 .Op Fl S Ar address
  48 .Op Fl t Ar timeout
  49 .Op Fl u Ar user
  50 .Ek
  51 .Sh DESCRIPTION
  52 .Nm
  53 is a proxy for the Internet File Transfer Protocol.
  54 The proxy uses
  55 .Xr pf 4
  56 and expects to have the FTP control connection as described in
  57 .Xr services 5
  58 redirected to it via a
  59 .Xr pf 4
  60 .Em rdr
  61 command.
  62 An example of how to do that is further down in this document.
  63 .Pp
  64 The options are as follows:
  65 .Bl -tag -width Ds
  66 .It Fl A
  67 Permit only anonymous FTP connections.
  68 The proxy will allow connections to log in to other sites as the user
  69 .Qq ftp
  70 or
  71 .Qq anonymous
  72 only.
  73 Any attempt to log in as another user will be blocked by the proxy.
  74 .It Fl a Ar address
  75 Specify the local IP address to use in
  76 .Xr bind 2
  77 as the source for connections made by
  78 .Nm ftp-proxy
  79 when connecting to destination FTP servers.
  80 This may be necessary if the interface address of
  81 your default route is not reachable from the destinations
  82 .Nm
  83 is attempting connections to, or this address is different from the one
  84 connections are being NATed to.
  85 In the usual case this means that
  86 .Ar address
  87 should be a publicly visible IP address assigned to one of
  88 the interfaces on the machine running
  89 .Nm
  90 and should be the same address to which you are translating traffic
  91 if you are using the
  92 .Fl n
  93 option.
  94 .It Fl D Ar debuglevel
  95 Specify a debug level, where the proxy emits verbose debug output
  96 into
  97 .Xr syslogd 8
  98 at level
  99 .Dv LOG_DEBUG .
 100 Meaningful values of debuglevel are 0-3, where 0 is no debug output and
 101 3 is lots of debug output, the default being 0.
 102 .It Fl g Ar group
 103 Specify the named group to drop group privileges to, after doing
 104 .Xr pf 4
 105 lookups which require root.
 106 By default,
 107 .Nm
 108 uses the default group of the user it drops privilege to.
 109 .It Fl M Ar maxport
 110 Specify the upper end of the port range the proxy will use for the
 111 data connections it establishes.
 112 The default is
 113 .Dv IPPORT_HILASTAUTO
 114 defined in
 115 .Aq Pa netinet/in.h
 116 as 65535.
 117 .It Fl m Ar minport
 118 Specify the lower end of the port range the proxy will use for all
 119 data connections it establishes.
 120 The default is
 121 .Dv IPPORT_HIFIRSTAUTO
 122 defined in
 123 .Aq Pa netinet/in.h
 124 as 49152.
 125 .It Fl n
 126 Activate network address translation
 127 .Pq NAT
 128 mode.
 129 In this mode, the proxy will not attempt to proxy passive mode
 130 .Pq PASV or EPSV
 131 data connections.
 132 In order for this to work, the machine running the proxy will need to
 133 be forwarding packets and doing network address translation to allow
 134 the outbound passive connections from the client to reach the server.
 135 See
 136 .Xr pf.conf 5
 137 for more details on NAT.
 138 The proxy only ignores passive mode data connections when using this flag;
 139 it will still proxy PORT and EPRT mode data connections.
 140 Without this flag,
 141 .Nm
 142 does not require any IP forwarding or NAT beyond the
 143 .Em rdr
 144 necessary to capture the FTP control connection.
 145 .It Fl R Ar address:[port]
 146 Reverse proxy mode for FTP servers running behind a NAT gateway.
 147 In this mode, no redirection is needed.
 148 The proxy is run from
 149 .Xr inetd 8
 150 on the port that external clients connect to (usually 21).
 151 Control connections and passive data connections are forwarded
 152 to the server.
 153 .It Fl r
 154 Use reverse host
 155 .Pq reverse DNS
 156 lookups for logging and libwrap use.
 157 By default,
 158 the proxy does not look up hostnames for libwrap or logging purposes.
 159 .It Fl S Ar address
 160 Source address to use for data connections made by the proxy.
 161 Useful when there are multiple addresses (aliases) available
 162 to the proxy.
 163 Clients may expect data connections to have the same source
 164 address as the control connections, and reject or drop other
 165 connections.
 166 .It Fl t Ar timeout
 167 Specifies a timeout, in seconds.
 168 The proxy will exit and close open connections if it sees no data
 169 for the duration of the timeout.
 170 The default is 0, which means the proxy will not time out.
 171 .It Fl u Ar user
 172 Specify the named user to drop privilege to, after doing
 173 .Xr pf 4
 174 lookups which require root privilege.
 175 By default,
 176 .Nm
 177 drops privilege to the user
 178 .Em proxy .
 179 .Pp
 180 Running as root means that the source of data connections the proxy makes
 181 for PORT and EPRT will be the RFC mandated port 20.
 182 When running as a non-root user, the source of the data connections from
 183 .Nm
 184 will be chosen randomly from the range
 185 .Ar minport
 186 to
 187 .Ar maxport
 188 as described above.
 189 .It Fl V
 190 Be verbose.
 191 With this option the proxy logs the control commands
 192 sent by clients and the replies sent by the servers to
 193 .Xr syslogd 8 .
 194 .It Fl w
 195 Use the tcp wrapper access control library
 196 .Xr hosts_access 3 ,
 197 allowing connections to be allowed or denied based on the tcp wrapper's
 198 .Xr hosts.allow 5
 199 and
 200 .Xr hosts.deny 5
 201 files.
 202 The proxy does libwrap operations after determining the destination
 203 of the captured control connection, so that tcp wrapper rules may
 204 be written based on the destination as well as the source of FTP connections.
 205 .El
 206 .Pp
 207 .Nm ftp-proxy
 208 is run from
 209 .Xr inetd 8
 210 and requires that FTP connections are redirected to it using a
 211 .Em rdr
 212 rule.
 213 A typical way to do this would be to use a
 214 .Xr pf.conf 5
 215 rule such as
 216 .Bd -literal -offset 2n
 217 int_if = \&"xl0\&"
 218 rdr pass on $int_if proto tcp from any to any port 21 -> 127.0.0.1 port 8021
 219 .Ed
 220 .Pp
 221 .Xr inetd 8
 222 must then be configured to run
 223 .Nm
 224 on the port from above using
 225 .Bd -literal -offset 2n
 226 127.0.0.1:8021 stream tcp nowait root /usr/libexec/ftp-proxy ftp-proxy
 227 .Ed
 228 .Pp
 229 in
 230 .Xr inetd.conf 5 .
 231 .Pp
 232 .Nm
 233 accepts the redirected control connections and forwards them
 234 to the server.
 235 The proxy replaces the address and port number that the client
 236 sends through the control connection to the server with its own
 237 address and proxy port, where it listens for the data connection.
 238 When the server opens the data connection back to this port, the
 239 proxy forwards it to the client.
 240 The
 241 .Xr pf.conf 5
 242 rules need to let pass connections to these proxy ports
 243 (see options
 244 .Fl u , m ,
 245 and
 246 .Fl M
 247 above) in on the external interface.
 248 The following example allows only ports 49152 to 65535 to pass in
 249 statefully:
 250 .Bd -literal -offset indent
 251 block in on $ext_if proto tcp all
 252 pass  in on $ext_if inet proto tcp from any to $ext_if \e
 253     port > 49151 keep state
 254 .Ed
 255 .Pp
 256 Alternatively, rules can make use of the fact that by default,
 257 .Nm
 258 runs as user
 259 .Qq proxy
 260 to allow the backchannel connections, as in the following example:
 261 .Bd -literal -offset indent
 262 block in on $ext_if proto tcp all
 263 pass  in on $ext_if inet proto tcp from any to $ext_if \e
 264     user proxy keep state
 265 .Ed
 266 .Pp
 267 These examples do not cover the connections from the proxy to the
 268 foreign FTP server.
 269 If one does not pass outgoing connections by default additional rules
 270 are needed.
 271 .Sh SEE ALSO
 272 .Xr ftp 1 ,
 273 .Xr pf 4 ,
 274 .Xr hosts.allow 5 ,
 275 .Xr hosts.deny 5 ,
 276 .Xr inetd.conf 5 ,
 277 .Xr pf.conf 5 ,
 278 .Xr inetd 8 ,
 279 .Xr pfctl 8 ,
 280 .Xr syslogd 8
 281 .Sh BUGS
 282 Extended Passive mode
 283 .Pq EPSV
 284 is not supported by the proxy and will not work unless the proxy is run
 285 in network address translation mode.
 286 When not in network address translation mode, the proxy returns an error
 287 to the client, hopefully forcing the client to revert to passive mode
 288 .Pq PASV
 289 which is supported.
 290 EPSV will work in network address translation mode, assuming a
 291 .Xr pf.conf 5
 292 setup which allows the EPSV connections through to their destinations.
 293 .Pp
 294 IPv6 is not yet supported.