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