tftpd/tftpd.8

   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 "13 November 2001" "tftp-hpa" "UNIX 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.
  80 .TP
  81 .B \-s
  82 Change root directory on startup.  This means the remote host does not
  83 need to pass along the directory as part of the transfer, and may add
  84 security.  When
  85 .B \-s
  86 is specified, exactly one
  87 .I directory
  88 should be specified on the command line.  The use of this option is
  89 recommended for security as well as compatibility with some boot ROMs
  90 which cannot be easily made to include a directory name in its request.
  91 .TP
  92 \fB\-u\fP \fIusername\fP
  93 Specify the username which
  94 .B tftpd
  95 will run as; the default is "nobody".
  96 .TP
  97 \fB\-t\fP \fItimeout\fP
  98 When run from
  99 .B inetd
 100 this specifies how long, in seconds, to wait for a second connection
 101 before terminating the server.
 102 .B inetd
 103 will then respawn the server when another request comes in.  The
 104 default is 900 (15 minutes.)
 105 .TP
 106 \fB\-m\fP \fIremap-file\fP
 107 Specify the use of filename remapping.  The
 108 .I remap-file
 109 is a file containing the remapping rules.  See the section on filename
 110 remapping below.  This option may not be compiled in, see
 111 .B "tftpd \-V"
 112 to verify whether or not it is available.
 113 .TP
 114 .B \-v
 115 Increase the logging verbosity of
 116 .BR tftpd .
 117 This flag can be specified multiple times for even higher verbosity.
 118 .TP
 119 \fB\-r\fP \fItftp-option\fP
 120 Indicate that a specific RFC 2347 TFTP option should never be
 121 accepted.
 122 .TP
 123 .B \-V
 124 Print the version number and configuration to standard output, then
 125 exit gracefully.
 126 .SH "RFC 2347 OPTION NEGOTIATION"
 127 This version of
 128 .B tftpd
 129 supports RFC 2347 option negotation.  Currently implemented options
 130 are
 131 .B blksize
 132 (RFC 2348),
 133 .B blksize2
 134 (nonstandard),
 135 .B tsize
 136 (RFC 2349), and
 137 .B timeout
 138 (RFC 2349).  The
 139 .B \-r
 140 option can be used to disable specific options; this may be necessary
 141 to work around bugs in specific TFTP client implementations.
 142 .SH "FILENAME REMAPPING"
 143 The
 144 .B \-m
 145 option specifies a file which contains filename remapping rules.  Each
 146 non-comment line (comments begin with hash marks,
 147 .BR # )
 148 contains an
 149 .IR operation ,
 150 specified below; a
 151 .IR regex ,
 152 a regular expression in the style of
 153 .BR egrep ;
 154 and optionally a
 155 .IR "replacement pattern" .
 156 The operation indicated by
 157 .I operation
 158 is performed if the
 159 .I regex
 160 matches all or part of the filename.  Rules are processed from the top
 161 down, and by default, all rules are processed even if there is a
 162 match.
 163 .PP
 164 The
 165 .I operation
 166 can be any combination of the following letters:
 167 .TP
 168 .B r
 169 Replace the substring matched by
 170 .I regex
 171 by the
 172 .IR "replacement pattern" .
 173 The escape sequence
 174 \\0
 175 can be used to copy the entire matched string, and the sequences
 176 \\1 to \\9
 177 copies parenthesized subexpressions.  To specify a backslash, white
 178 space or hash mark, you need to \\-escape it.
 179 .TP
 180 .B g
 181 Repeat this rule until it no longer matches.  This is always used with
 182 .BR r .
 183 .TP
 184 .B i
 185 Match the
 186 .I regex
 187 case-insensitively.  By default it is case sensitive.
 188 .TP
 189 .B e
 190 If this rule matches, end rule processing after executing the rule.
 191 .TP
 192 .B s
 193 If this rule matches, start rule processing over from the very first
 194 rule after executing this rule.
 195 .TP
 196 .B a
 197 If this rule matches, refuse the request and send an access denied
 198 error to the client.
 199 .TP
 200 .B G
 201 This rule applies to GET (RRQ) requests only.
 202 .TP
 203 .B P
 204 This rule applies to PUT (WRQ) requests only.
 205 .PP
 206 If the mapping file is changed, you need to send
 207 .B SIGHUP
 208 to any outstanding
 209 .B tftpd
 210 process.
 211 .SH "SECURITY"
 212 The use of TFTP services does not require an account or password on
 213 the server system.  Due to the lack of authentication information,
 214 .B tftpd
 215 will allow only publicly readable files (o+r) to be accessed.  Files
 216 may be written only if they already exist and are publicly writable,
 217 unless the
 218 .B \-c
 219 option is specified.  Note that this extends the concept of ``public''
 220 to include all users on all hosts that can be reached through the
 221 network; this may not be appropriate on all systems, and its
 222 implications should be considered before enabling TFTP service.
 223 Typically, some kind of firewall or packet-filter solution should be
 224 employed.  If appropriately compiled (see the output of
 225 .BR  "tftpd \-V" )
 226 .B tftpd
 227 will query the
 228 .BR hosts_access (5)
 229 database for access control information.  This may be slow; sites
 230 requiring maximum performance may want to compile without this option
 231 and rely on firewalling or kernel-based packet filters instead.
 232 .PP
 233 The server should be set to have the user ID with the lowest possible
 234 privilege; please see the
 235 .B \-u
 236 flag.
 237 .PP
 238 Access to files can, and should, be restricted by invoking
 239 .B tftpd
 240 with a list of directories by including pathnames as server program
 241 arguments on the command line.  In this case access is restricted to
 242 files whole names are prefixed by one of the given directories.  If
 243 possible, it is recommended that the
 244 .B \-s
 245 flag is used to set up a chroot() environment for the server to run in
 246 once a connection has been set up.
 247 .PP
 248 Finally, the filename remapping
 249 .RB ( \-m
 250 flag) support can be used to provide a limited amount of additional
 251 access control.
 252 .SH "BUGS"
 253 It is unclear at this point if the retransmission algorithm used is
 254 sufficient to satisfy the RFC 1123 requirement that TFTP
 255 implementations use adaptive retransmission timeout.  Furthermore, it
 256 is unclear how to combine the adaptive timeout of RFC 1123 with the
 257 .B timeout
 258 option specified by RFC 2349.
 259 .SH "CONFORMING TO"
 260 RFC 1123,
 261 .IR "Requirements for Internet Hosts \- Application and Support" .
 262 .br
 263 RFC 1350,
 264 .IR "The TFTP Protocol (revision 2)" .
 265 .br
 266 RFC 2347,
 267 .IR "TFTP Option Extension" .
 268 .br
 269 RFC 2348,
 270 .IR "TFTP Blocksize Option" .
 271 .br
 272 RFC 2349,
 273 .IR "TFTP Timeout Interval and Transfer Size Options" .
 274 .PP
 275 The nonstandard
 276 .B blksize2
 277 TFTP option is functionally identical to the
 278 .B blksize
 279 option specified in RFC 2349, with the additional constraint that the
 280 blocksize is constrained to be a power of 2.
 281 .SH "AUTHOR"
 282 This version of
 283 .B tftpd
 284 is maintained by H. Peter Anvin <hpa@zytor.com>.  It was derived from,
 285 but has substantially diverged from, an OpenBSD source base, with
 286 added patches by Markus Gutschke and Gero Kulhman.
 287 .SH "SEE ALSO"
 288 .BR tftp (1),
 289 .BR egrep (1),
 290 .BR hosts_access (5),
 291 .BR regex (7),
 292 .BR inetd (8).