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