dist/pf/usr.sbin/ftp-proxy/ftp-proxy.8

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