Debian Codegraph @

upstream/debian-unstable/man8/in.tftpd.8

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