| blob | ea1697ca0e415891f37cb6edff768e1bdf3fd8aa |
1 .\" -*- nroff -*- --------------------------------------------------------- *
2 .\" $Id$
3 .\"
4 .\" Copyright (c) 1990, 1993, 1994
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" Copyright 2001 H. Peter Anvin - All Rights Reserved
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. Neither the name of the University nor the names of its contributors
18 .\" may be used to endorse or promote products derived from this software
19 .\" without specific prior written permission.
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" SUCH DAMAGE.
32 .\"
33 .\"----------------------------------------------------------------------- */
34 .TH TFTPD 8 "16 February 2006" "tftp-hpa @@VERSION@@" "System Manager's Manual"
35 .SH NAME
36 .B tftpd
37 \- IPv4 Trivial File Transfer Protocol server
38 .SH SYNOPSIS
39 .B in.tftpd
40 .RI [ options... ]
41 .I directory...
42 .SH DESCRIPTION
43 .B tftpd
44 is a server for the IPv4 Trivial File Transfer Protocol. The TFTP
45 protocol is extensively used to support remote booting of diskless
46 devices. The server is normally started by
47 .BR inetd ,
48 but can also run standalone.
49 .PP
50 .SH OPTIONS
51 .TP
52 .B \-l
53 Run the server in standalone (listen) mode, rather than run from
54 .BR inetd .
55 In listen mode, the
56 .B \-t
57 option is ignored, and the
58 .B \-a
59 option can be used to specify a specific local address or port to
60 listen to.
61 .TP
62 \fB\-a\fP \fI[address][:port]\fP
63 Specify a specific
64 .I address
65 and
66 .I port
67 to listen to when called with the
68 .B \-l
69 option. The default is to listen to the
70 .I tftp
71 port specified in
72 .I /etc/services
73 on all local addresses.
74 .TP
75 .B \-c
76 Allow new files to be created. By default,
77 .B tftpd
78 will only allow upload of files that already exist. Files are created
79 with default permissions allowing anyone to read or write them, unless
80 the
81 .B \-p
82 or
83 .B \-U
84 options are specified.
85 .TP
86 .B \-s
87 Change root directory on startup. This means the remote host does not
88 need to pass along the directory as part of the transfer, and may add
89 security. When
90 .B \-s
91 is specified, exactly one
92 .I directory
93 should be specified on the command line. The use of this option is
94 recommended for security as well as compatibility with some boot ROMs
95 which cannot be easily made to include a directory name in its request.
96 .TP
97 \fB\-u\fP \fIusername\fP
98 Specify the username which
99 .B tftpd
100 will run as; the default is "nobody". The user ID, group ID, and (if
101 possible on the platform) the supplementary group IDs will be set to
102 the ones specified in the system permission database for this
103 username.
104 .TP
105 \fB\-U\fP \fIumask\fP
106 Sets the \fIumask\fP for newly created files to the specified value.
107 The default is zero (anyone can read or write) if the
108 .B \-p
109 option is not specified, or inherited from the invoking process if
110 .B \-p
111 is specified.
112 .TP
113 .B \-p
114 Perform no additional permissions checks above the normal
115 system-provided access controls for the user specified via the
116 .B \-u
117 option.
118 .TP
119 \fB\-t\fP \fItimeout\fP
120 When run from
121 .B inetd
122 this specifies how long, in seconds, to wait for a second connection
123 before terminating the server.
124 .B inetd
125 will then respawn the server when another request comes in. The
126 default is 900 (15 minutes.)
127 .TP
128 \fB\-T\fP \fItimeout\fP
129 Determine the default timeout, in microseconds, before the first
130 packet is retransmitted. This can be modified by the client if the
131 .B timeout
132 or
133 .B utimeout
134 option is negotiated. The default is 1000000 (1 second.)
135 .TP
136 \fB\-m\fP \fIremap-file\fP
137 Specify the use of filename remapping. The
138 .I remap-file
139 is a file containing the remapping rules. See the section on filename
140 remapping below. This option may not be compiled in, see the output of
141 .B "in.tftpd \-V"
142 to verify whether or not it is available.
143 .TP
144 .B \-v
145 Increase the logging verbosity of
146 .BR tftpd .
147 This flag can be specified multiple times for even higher verbosity.
148 .TP
149 \fB\-r\fP \fItftp-option\fP
150 Indicate that a specific RFC 2347 TFTP option should never be
151 accepted.
152 .TP
153 \fB\-B\fP \fImax-block-size\fP
154 Specifies the maximum permitted block size. The permitted range for
155 this parameter is from 512 to 65464. Some embedded clients request
156 large block sizes and yet do not handle fragmented packets correctly;
157 for these clients, it is recommended to set this value to the smallest
158 MTU on your network minus 32 bytes (20 bytes for IP, 8 for UDP, and 4
159 for TFTP; less if you use IP options on your network.) For example,
160 on a standard Ethernet (MTU 1500) a value of 1468 is reasonable.
161 .TP
162 \fB\-R\fP \fIport:port\fP
163 Force the server port number (the Transaction ID) to be in the
164 specified range of port numbers.
165 .TP
166 .B \-V
167 Print the version number and configuration to standard output, then
168 exit gracefully.
169 .SH "RFC 2347 OPTION NEGOTIATION"
170 This version of
171 .B tftpd
172 supports RFC 2347 option negotation. Currently implemented options
173 are:
174 .TP
175 \fBblksize\fP (RFC 2348)
176 Set the transfer block size to anything less than or equal to the
177 specified option. This version of
178 .B tftpd
179 can support any block size up to the theoretical maximum of 65464
180 bytes.
181 .TP
182 \fBblksize2\fP (nonstandard)
183 Set the transfer block size to anything less than or equal to the
184 specified option, but restrict the possible responses to powers of 2.
185 The maximum is 32768 bytes (the largest power of 2 less than or equal
186 to 65464.)
187 .TP
188 \fBtsize\fP (RFC 2349)
189 Report the size of the file that is about to be transferred. This
190 version of
191 .B tftpd
192 only supports the
193 .B tsize
194 option for binary (octet) mode transfers.
195 .TP
196 \fBtimeout\fP (RFC 2349)
197 Set the time before the server retransmits a packet, in seconds.
198 .TP
199 \fButimeout\fP (nonstandard)
200 Set the time before the server retransmits a packet, in microseconds.
201 .PP
202 The
203 .B \-r
204 option can be used to disable specific options; this may be necessary
205 to work around bugs in specific TFTP client implementations. For
206 example, some TFTP clients have been found to request the
207 .B blksize
208 option, but crash with an error if they actually get the option
209 accepted by the server.
210 .SH "FILENAME REMAPPING"
211 The
212 .B \-m
213 option specifies a file which contains filename remapping rules. Each
214 non-comment line (comments begin with hash marks,
215 .BR # )
216 contains an
217 .IR operation ,
218 specified below; a
219 .IR regex ,
220 a regular expression in the style of
221 .BR egrep ;
222 and optionally a
223 .IR "replacement pattern" .
224 The operation indicated by
225 .I operation
226 is performed if the
227 .I regex
228 matches all or part of the filename. Rules are processed from the top
229 down, and by default, all rules are processed even if there is a
230 match.
231 .PP
232 The
233 .I operation
234 can be any combination of the following letters:
235 .TP
236 .B r
237 Replace the substring matched by
238 .I regex
239 by the
240 .IR "replacement pattern" .
241 The replacement pattern may contain escape sequences; see below.
242 .TP
243 .B g
244 Repeat this rule until it no longer matches. This is always used with
245 .BR r .
246 .TP
247 .B i
248 Match the
249 .I regex
250 case-insensitively. By default it is case sensitive.
251 .TP
252 .B e
253 If this rule matches, end rule processing after executing the rule.
254 .TP
255 .B s
256 If this rule matches, start rule processing over from the very first
257 rule after executing this rule.
258 .TP
259 .B a
260 If this rule matches, refuse the request and send an access denied
261 error to the client.
262 .TP
263 .B G
264 This rule applies to GET (RRQ) requests only.
265 .TP
266 .B P
267 This rule applies to PUT (WRQ) requests only.
268 .TP
269 .B ~
270 Inverse the sense of this rule, i.e. execute the
271 .I operation
272 only if the
273 .I regex
274 .I doesn't
275 match. Cannot used together with
276 .BR r .
277 .PP
278 The following escape sequences are recognized as part of the
279 .IR "replacement pattern" :
280 .TP
281 \fB\\0\fP
282 The entire string matched by the
283 .IR regex .
284 .TP
285 \fB\\1\fP to \fB\\9\fP
286 The strings matched by each of the first nine parenthesized
287 subexpressions, \\( ... \\), of the
288 .I regex
289 pattern.
290 .TP
291 \fB\\i\fP
292 The IP address of the requesting host, in dotted-quad notation
293 (e.g. 192.0.2.169).
294 .TP
295 \fB\\x\fP
296 The IP address of the requesting host, in hexadecimal notation
297 (e.g. C00002A9).
298 .TP
299 \fB\\\\\fP
300 Literal backslash.
301 .TP
302 \fB\\\fP\fIwhitespace\fP
303 Literal whitespace.
304 .TP
305 \fB\\#\fP
306 Literal hash mark.
307 .TP
308 \fB\\U\fP
309 Turns all subsequent letters to upper case.
310 .TP
311 \fB\\L\fP
312 Turns all subsequent letters to lower case.
313 .TP
314 \fB\\E\fP
315 Cancels the effect of \fB\\U\fP or \fB\\L\fP.
316 .PP
317 If the mapping file is changed, you need to send
318 .B SIGHUP
319 to any outstanding
320 .B tftpd
321 process.
322 .SH "SECURITY"
323 The use of TFTP services does not require an account or password on
324 the server system. Due to the lack of authentication information,
325 .B tftpd
326 will allow only publicly readable files (o+r) to be accessed, unless the
327 .B \-p
328 option is specified. Files may be written only if they already exist
329 and are publicly writable, unless the
330 .B \-c
331 option is specified. Note that this extends the concept of ``public''
332 to include all users on all hosts that can be reached through the
333 network; this may not be appropriate on all systems, and its
334 implications should be considered before enabling TFTP service.
335 Typically, some kind of firewall or packet-filter solution should be
336 employed. If appropriately compiled (see the output of
337 .BR "in.tftpd \-V" )
338 .B tftpd
339 will query the
340 .BR hosts_access (5)
341 database for access control information. This may be slow; sites
342 requiring maximum performance may want to compile without this option
343 and rely on firewalling or kernel-based packet filters instead.
344 .PP
345 The server should be set to run as the user with the lowest possible
346 privilege; please see the
347 .B \-u
348 flag. It is probably a good idea to set up a specific user account for
349 .BR tftpd ,
350 rather than letting it run as "nobody", to guard against privilege
351 leaks between applications.
352 .PP
353 Access to files can, and should, be restricted by invoking
354 .B tftpd
355 with a list of directories by including pathnames as server program
356 arguments on the command line. In this case access is restricted to
357 files whole names are prefixed by one of the given directories. If
358 possible, it is recommended that the
359 .B \-s
360 flag is used to set up a chroot() environment for the server to run in
361 once a connection has been set up.
362 .PP
363 Finally, the filename remapping
364 .RB ( \-m
365 flag) support can be used to provide a limited amount of additional
366 access control.
367 .SH "CONFORMING TO"
368 RFC 1123,
369 .IR "Requirements for Internet Hosts \- Application and Support" .
370 .br
371 RFC 1350,
372 .IR "The TFTP Protocol (revision 2)" .
373 .br
374 RFC 2347,
375 .IR "TFTP Option Extension" .
376 .br
377 RFC 2348,
378 .IR "TFTP Blocksize Option" .
379 .br
380 RFC 2349,
381 .IR "TFTP Timeout Interval and Transfer Size Options" .
382 .SH "AUTHOR"
383 This version of
384 .B tftpd
385 is maintained by H. Peter Anvin <hpa@zytor.com>. It was derived from,
386 but has substantially diverged from, an OpenBSD source base, with
387 added patches by Markus Gutschke and Gero Kulhman.
388 .SH "SEE ALSO"
389 .BR tftp (1),
390 .BR egrep (1),
391 .BR umask (2),
392 .BR hosts_access (5),
393 .BR regex (7),
394 .BR inetd (8).