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