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