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

   1 .\"     $OpenBSD: ftp-proxy.8,v 1.10 2007/08/01 15:45:41 jmc 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 .Dd September 9, 2010
  18 .Dt FTP-PROXY 8
  19 .Os
  20 .Sh NAME
  21 .Nm ftp-proxy
  22 .Nd Internet File Transfer Protocol proxy daemon
  23 .Sh SYNOPSIS
  24 .Nm
  25 .Bk -words
  26 .Op Fl 6Adrv
  27 .Op Fl a Ar address
  28 .Op Fl b Ar address
  29 .Op Fl D Ar level
  30 .Op Fl m Ar maxsessions
  31 .Op Fl P Ar port
  32 .Op Fl p Ar port
  33 .Op Fl q Ar queue
  34 .Op Fl R Ar address
  35 .Op Fl T Ar tag
  36 .Op Fl t Ar timeout
  37 .Ek
  38 .Sh DESCRIPTION
  39 .Nm
  40 is a proxy for the Internet File Transfer Protocol.
  41 FTP control connections should be redirected into the proxy using the
  42 .Xr pf 4
  43 .Ar rdr
  44 command, after which the proxy connects to the server on behalf of
  45 the client.
  46 .Pp
  47 The proxy allows data connections to pass, rewriting and redirecting
  48 them so that the right addresses are used.
  49 All connections from the client to the server have their source
  50 address rewritten so they appear to come from the proxy.
  51 Consequently, all connections from the server to the proxy have
  52 their destination address rewritten, so they are redirected to the
  53 client.
  54 The proxy uses the
  55 .Xr pf 4
  56 .Ar anchor
  57 facility for this.
  58 .Pp
  59 Assuming the FTP control connection is from $client to $server, the
  60 proxy connected to the server using the $proxy source address, and
  61 $port is negotiated, then
  62 .Nm
  63 adds the following rules to the various anchors.
  64 (These example rules use inet, but the proxy also supports inet6.)
  65 .Pp
  66 In case of active mode (PORT or EPRT):
  67 .Bd -literal -offset 2n
  68 rdr from $server to $proxy port $port -> $client
  69 pass quick inet proto tcp \e
  70     from $server to $client port $port
  71 .Ed
  72 .Pp
  73 In case of passive mode (PASV or EPSV):
  74 .Bd -literal -offset 2n
  75 nat from $client to $server port $port -> $proxy
  76 pass in quick inet proto tcp \e
  77     from $client to $server port $port
  78 pass out quick inet proto tcp \e
  79     from $proxy to $server port $port
  80 .Ed
  81 .Pp
  82 The options are as follows:
  83 .Bl -tag -width Ds
  84 .It Fl 6
  85 IPv6 mode.
  86 The proxy will expect and use IPv6 addresses for all communication.
  87 Only the extended FTP modes EPSV and EPRT are allowed with IPv6.
  88 The proxy is in IPv4 mode by default.
  89 .It Fl A
  90 Only permit anonymous FTP connections.
  91 Either user "ftp" or user "anonymous" is allowed.
  92 .It Fl a Ar address
  93 The proxy will use this as the source address for the control
  94 connection to a server.
  95 .It Fl b Ar address
  96 Address where the proxy will listen for redirected control connections.
  97 The default is 127.0.0.1, or ::1 in IPv6 mode.
  98 .It Fl D Ar level
  99 Debug level, ranging from 0 to 7.
 100 Higher is more verbose.
 101 The default is 5.
 102 (These levels correspond to the
 103 .Xr syslog 3
 104 levels.)
 105 .It Fl d
 106 Do not daemonize.
 107 The process will stay in the foreground, logging to standard error.
 108 .It Fl m Ar maxsessions
 109 Maximum number of concurrent FTP sessions.
 110 When the proxy reaches this limit, new connections are denied.
 111 The default is 100 sessions.
 112 The limit can be lowered to a minimum of 1, or raised to a maximum of 500.
 113 .It Fl P Ar port
 114 Fixed server port.
 115 Only used in combination with
 116 .Fl R .
 117 The default is port 21.
 118 .It Fl p Ar port
 119 Port where the proxy will listen for redirected connections.
 120 The default is port 8021.
 121 .It Fl q Ar queue
 122 Create rules with queue
 123 .Ar queue
 124 appended, so that data connections can be queued.
 125 .It Fl R Ar address
 126 Fixed server address, also known as reverse mode.
 127 The proxy will always connect to the same server, regardless of
 128 where the client wanted to connect to (before it was redirected).
 129 Use this option to proxy for a server behind NAT, or to forward all
 130 connections to another proxy.
 131 .It Fl r
 132 Rewrite sourceport to 20 in active mode to suit ancient clients that insist
 133 on this RFC property.
 134 .It Fl T Ar tag
 135 Automatically tag packets passing through the
 136 .Xr pf 4
 137 rule with the name supplied.
 138 .It Fl t Ar timeout
 139 Number of seconds that the control connection can be idle, before the
 140 proxy will disconnect.
 141 The maximum is 86400 seconds, which is also the default.
 142 Do not set this too low, because the control connection is usually
 143 idle when large data transfers are taking place.
 144 .It Fl v
 145 Set the 'log' flag on pf rules committed by
 146 .Nm .
 147 Use twice to set the 'log-all' flag.
 148 The pf rules do not log by default.
 149 .El
 150 .Sh CONFIGURATION
 151 To make use of the proxy,
 152 .Xr pf.conf 5
 153 needs the following rules.
 154 All anchors are mandatory.
 155 Adjust the rules as needed.
 156 .Pp
 157 In the NAT section:
 158 .Bd -literal -offset 2n
 159 nat-anchor "ftp-proxy/*"
 160 rdr-anchor "ftp-proxy/*"
 161 rdr pass on $int_if proto tcp from $lan to any port 21 -> \e
 162     127.0.0.1 port 8021
 163 .Ed
 164 .Pp
 165 In the rule section:
 166 .Bd -literal -offset 2n
 167 anchor "ftp-proxy/*"
 168 pass out proto tcp from $proxy to any port 21
 169 .Ed
 170 .Sh SEE ALSO
 171 .Xr ftp 1 ,
 172 .Xr pf 4 ,
 173 .Xr pf.conf 5
 174 .Sh CAVEATS
 175 .Xr pf 4
 176 does not allow the ruleset to be modified if the system is running at a
 177 securelevel
 178 .\".Xr securelevel 7
 179 higher than 1.
 180 At that level
 181 .Nm
 182 cannot add rules to the anchors and FTP data connections may get blocked.
 183 .Pp
 184 Negotiated data connection ports below 1024 are not allowed.
 185 .Pp
 186 The negotiated IP address for active modes is ignored for security
 187 reasons.
 188 This makes third party file transfers impossible.
 189 .Pp
 190 .Nm
 191 chroots to "/var/empty" and changes to user "proxy" to drop privileges.