| 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 . |