contrib/pf/ftp-proxy/ftp-proxy.8

   1 .\"     $OpenBSD: ftp-proxy.8,v 1.11 2008/02/26 18:52:53 henning Exp $
   2 .\"
   3 .\" Copyright (c) 2004, 2005 Camiel Dobbelaar, <cd@sentia.nl>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .\" $FreeBSD$
  18 .\"
  19 .Dd February 26, 2008
  20 .Dt FTP-PROXY 8
  21 .Os
  22 .Sh NAME
  23 .Nm ftp-proxy
  24 .Nd Internet File Transfer Protocol proxy daemon
  25 .Sh SYNOPSIS
  26 .Nm
  27 .Bk -words
  28 .Op Fl 6Adrv
  29 .Op Fl a Ar address
  30 .Op Fl b Ar address
  31 .Op Fl D Ar level
  32 .Op Fl m Ar maxsessions
  33 .Op Fl P Ar port
  34 .Op Fl p Ar port
  35 .Op Fl q Ar queue
  36 .Op Fl R Ar address
  37 .Op Fl T Ar tag
  38 .Op Fl t Ar timeout
  39 .Ek
  40 .Sh DESCRIPTION
  41 .Nm
  42 is a proxy for the Internet File Transfer Protocol.
  43 FTP control connections should be redirected into the proxy using the
  44 .Xr pf 4
  45 .Ar rdr
  46 command, after which the proxy connects to the server on behalf of
  47 the client.
  48 .Pp
  49 The proxy allows data connections to pass, rewriting and redirecting
  50 them so that the right addresses are used.
  51 All connections from the client to the server have their source
  52 address rewritten so they appear to come from the proxy.
  53 Consequently, all connections from the server to the proxy have
  54 their destination address rewritten, so they are redirected to the
  55 client.
  56 The proxy uses the
  57 .Xr pf 4
  58 .Ar anchor
  59 facility for this.
  60 .Pp
  61 Assuming the FTP control connection is from $client to $server, the
  62 proxy connected to the server using the $proxy source address, and
  63 $port is negotiated, then
  64 .Nm
  65 adds the following rules to the various anchors.
  66 (These example rules use inet, but the proxy also supports inet6.)
  67 .Pp
  68 In case of active mode (PORT or EPRT):
  69 .Bd -literal -offset 2n
  70 rdr from $server to $proxy port $port -> $client
  71 pass quick inet proto tcp \e
  72     from $server to $client port $port
  73 .Ed
  74 .Pp
  75 In case of passive mode (PASV or EPSV):
  76 .Bd -literal -offset 2n
  77 nat from $client to $server port $port -> $proxy
  78 pass in quick inet proto tcp \e
  79     from $client to $server port $port
  80 pass out quick inet proto tcp \e
  81     from $proxy to $server port $port
  82 .Ed
  83 .Pp
  84 The options are as follows:
  85 .Bl -tag -width Ds
  86 .It Fl 6
  87 IPv6 mode.
  88 The proxy will expect and use IPv6 addresses for all communication.
  89 Only the extended FTP modes EPSV and EPRT are allowed with IPv6.
  90 The proxy is in IPv4 mode by default.
  91 .It Fl A
  92 Only permit anonymous FTP connections.
  93 Either user "ftp" or user "anonymous" is allowed.
  94 .It Fl a Ar address
  95 The proxy will use this as the source address for the control
  96 connection to a server.
  97 .It Fl b Ar address
  98 Address where the proxy will listen for redirected control connections.
  99 The default is 127.0.0.1, or ::1 in IPv6 mode.
 100 .It Fl D Ar level
 101 Debug level, ranging from 0 to 7.
 102 Higher is more verbose.
 103 The default is 5.
 104 (These levels correspond to the
 105 .Xr syslog 3
 106 levels.)
 107 .It Fl d
 108 Do not daemonize.
 109 The process will stay in the foreground, logging to standard error.
 110 .It Fl m Ar maxsessions
 111 Maximum number of concurrent FTP sessions.
 112 When the proxy reaches this limit, new connections are denied.
 113 The default is 100 sessions.
 114 The limit can be lowered to a minimum of 1, or raised to a maximum of 500.
 115 .It Fl P Ar port
 116 Fixed server port.
 117 Only used in combination with
 118 .Fl R .
 119 The default is port 21.
 120 .It Fl p Ar port
 121 Port where the proxy will listen for redirected connections.
 122 The default is port 8021.
 123 .It Fl q Ar queue
 124 Create rules with queue
 125 .Ar queue
 126 appended, so that data connections can be queued.
 127 .It Fl R Ar address
 128 Fixed server address, also known as reverse mode.
 129 The proxy will always connect to the same server, regardless of
 130 where the client wanted to connect to (before it was redirected).
 131 Use this option to proxy for a server behind NAT, or to forward all
 132 connections to another proxy.
 133 .It Fl r
 134 Rewrite sourceport to 20 in active mode to suit ancient clients that insist
 135 on this RFC property.
 136 .It Fl T Ar tag
 137 The filter rules will add tag
 138 .Ar tag
 139 to data connections, and not match quick.
 140 This way alternative rules that use the
 141 .Ar tagged
 142 keyword can be implemented following the
 143 .Nm
 144 anchor.
 145 These rules can use special
 146 .Xr pf 4
 147 features like route-to, reply-to, label, rtable, overload, etc. that
 148 .Nm
 149 does not implement itself.
 150 .It Fl t Ar timeout
 151 Number of seconds that the control connection can be idle, before the
 152 proxy will disconnect.
 153 The maximum is 86400 seconds, which is also the default.
 154 Do not set this too low, because the control connection is usually
 155 idle when large data transfers are taking place.
 156 .It Fl v
 157 Set the 'log' flag on pf rules committed by
 158 .Nm .
 159 Use twice to set the 'log-all' flag.
 160 The pf rules do not log by default.
 161 .El
 162 .Sh CONFIGURATION
 163 To make use of the proxy,
 164 .Xr pf.conf 5
 165 needs the following rules.
 166 All anchors are mandatory.
 167 Adjust the rules as needed.
 168 .Pp
 169 In the NAT section:
 170 .Bd -literal -offset 2n
 171 nat-anchor "ftp-proxy/*"
 172 rdr-anchor "ftp-proxy/*"
 173 rdr pass on $int_if proto tcp from $lan to any port 21 -> \e
 174     127.0.0.1 port 8021
 175 .Ed
 176 .Pp
 177 In the rule section:
 178 .Bd -literal -offset 2n
 179 anchor "ftp-proxy/*"
 180 pass out proto tcp from $proxy to any port 21
 181 .Ed
 182 .Sh SEE ALSO
 183 .Xr ftp 1 ,
 184 .Xr pf 4 ,
 185 .Xr pf.conf 5
 186 .Sh CAVEATS
 187 .Xr pf 4
 188 does not allow the ruleset to be modified if the system is running at a
 189 .Xr securelevel 7
 190 higher than 1.
 191 At that level
 192 .Nm
 193 cannot add rules to the anchors and FTP data connections may get blocked.
 194 .Pp
 195 Negotiated data connection ports below 1024 are not allowed.
 196 .Pp
 197 The negotiated IP address for active modes is ignored for security
 198 reasons.
 199 This makes third party file transfers impossible.
 200 .Pp
 201 .Nm
 202 chroots to "/var/empty" and changes to user "proxy" to drop privileges.