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