libexec/tftpd/tftpd.8

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)tftpd.8     8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd June 22, 2011
  32 .Dt TFTPD 8
  33 .Os
  34 .Sh NAME
  35 .Nm tftpd
  36 .Nd Internet Trivial File Transfer Protocol server
  37 .Sh SYNOPSIS
  38 .Nm tftpd
  39 .Op Fl cdClnow
  40 .Op Fl F Ar strftime-format
  41 .Op Fl s Ar directory
  42 .Op Fl u Ar user
  43 .Op Fl U Ar umask
  44 .Op Ar directory ...
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility is a server which supports the
  49 Internet Trivial File Transfer
  50 Protocol
  51 .Pq Tn RFC 1350 .
  52 The
  53 .Tn TFTP
  54 server operates
  55 at the port indicated in the
  56 .Ql tftp
  57 service description;
  58 see
  59 .Xr services 5 .
  60 The server is normally started by
  61 .Xr inetd 8 .
  62 .Pp
  63 The use of
  64 .Xr tftp 1
  65 does not require an account or password on the remote system.
  66 Due to the lack of authentication information,
  67 .Nm
  68 will allow only publicly readable files to be
  69 accessed.
  70 Files containing the string
  71 .Dq Li "/../"
  72 or starting with
  73 .Dq Li "../"
  74 are not allowed.
  75 Files may be written only if they already exist and are publicly writable.
  76 Note that this extends the concept of
  77 .Dq public
  78 to include
  79 all users on all hosts that can be reached through the network;
  80 this may not be appropriate on all systems, and its implications
  81 should be considered before enabling tftp service.
  82 The server should have the user ID with the lowest possible privilege.
  83 .Pp
  84 Access to files may be restricted by invoking
  85 .Nm
  86 with a list of directories by including up to 20 pathnames
  87 as server program arguments in
  88 .Xr inetd.conf 5 .
  89 In this case access is restricted to files whose
  90 names are prefixed by the one of the given directories.
  91 The given directories are also treated as a search path for
  92 relative filename requests.
  93 .Pp
  94 The
  95 .Fl s
  96 option provides additional security by changing
  97 the root directory of
  98 .Nm ,
  99 thereby prohibiting accesses to outside of the specified
 100 .Ar directory .
 101 Because
 102 .Xr chroot 2
 103 requires super-user privileges,
 104 .Nm
 105 must be run as
 106 .Li root .
 107 However, after performing the
 108 .Xr chroot 2
 109 call,
 110 .Nm
 111 will set its user ID to that of the specified
 112 .Ar user ,
 113 or
 114 .Dq Li nobody
 115 if no
 116 .Fl u
 117 option is specified.
 118 .Pp
 119 The options are:
 120 .Bl -tag -width Ds
 121 .It Fl c
 122 Changes the default root directory of a connecting host via
 123 .Xr chroot 2
 124 based on the connecting IP address.
 125 This prevents multiple clients from writing to the same file at the same time.
 126 If the directory does not exist, the client connection is refused.
 127 The
 128 .Fl s
 129 option is required for
 130 .Fl c
 131 and the specified
 132 .Ar directory
 133 is used as a base.
 134 .It Fl C
 135 Operates the same as
 136 .Fl c
 137 except it falls back to
 138 .Ar directory
 139 specified via
 140 .Fl s
 141 if a directory does not exist for the client's IP.
 142 .It Fl F
 143 Use this
 144 .Xr strftime 3
 145 compatible format string for the creation of the suffix if
 146 .Fl W
 147 is specified.
 148 By default the string "%Y%m%d" is used.
 149 .It Fl d, d Ar [value]
 150 Enables debug output.
 151 If
 152 .Ar value
 153 is not specified, then the debug level is increased by one
 154 for each instance of
 155 .Fl d
 156 which is specified.
 157 .Pp
 158 If
 159 .Ar value
 160 is specified, then the debug level is set to
 161 .Ar value .
 162 The debug level is a bitmask implemented in
 163 .Pa src/libexec/tftpd/tftp-utils.h .
 164 Valid values are 0 (DEBUG_NONE), 1 (DEBUG_PACKETS), 2, (DEBUG_SIMPLE),
 165 4 (DEBUG_OPTIONS), and 8 (DEBUG_ACCESS).  Multiple debug values can be combined
 166 in the bitmask by logically OR'ing the values.  For example, specifying
 167 .Fl d
 168 .Ar 15
 169 will enable all the debug values.
 170 .It Fl l
 171 Log all requests using
 172 .Xr syslog 3
 173 with the facility of
 174 .Dv LOG_FTP .
 175 .Sy Note :
 176 Logging of
 177 .Dv LOG_FTP
 178 messages
 179 must also be enabled in the syslog configuration file,
 180 .Xr syslog.conf 5 .
 181 .It Fl n
 182 Suppress negative acknowledgement of requests for nonexistent
 183 relative filenames.
 184 .It Fl o
 185 Disable support for RFC2347 style TFTP Options.
 186 .It Fl s Ar directory
 187 Cause
 188 .Nm
 189 to change its root directory to
 190 .Ar directory .
 191 After doing that but before accepting commands,
 192 .Nm
 193 will switch credentials to an unprivileged user.
 194 .It Fl u Ar user
 195 Switch credentials to
 196 .Ar user
 197 (default
 198 .Dq Li nobody )
 199 when the
 200 .Fl s
 201 option is used.
 202 The user must be specified by name, not a numeric UID.
 203 .It Fl U Ar umask
 204 Set the
 205 .Ar umask
 206 for newly created files.
 207 The default is 022
 208 .Pq Dv S_IWGRP | S_IWOTH .
 209 .It Fl w
 210 Allow write requests to create new files.
 211 By default
 212 .Nm
 213 requires that the file specified in a write request exist.
 214 Note that this only works in directories writable by the user
 215 specified with
 216 .Fl u
 217 option
 218 .It Fl W
 219 As
 220 .Fl w
 221 but append a YYYYMMDD.nn sequence number to the end of the filename.
 222 Note that the string YYYYMMDD can be changed with the
 223 .Fl F
 224 option.
 225 .El
 226 .Sh SEE ALSO
 227 .Xr tftp 1 ,
 228 .Xr chroot 2 ,
 229 .Xr syslog 3 ,
 230 .Xr inetd.conf 5 ,
 231 .Xr services 5 ,
 232 .Xr syslog.conf 5 ,
 233 .Xr inetd 8
 234 .Pp
 235 The following RFC's are supported:
 236 .Rs
 237 .%T RFC 1350: The TFTP Protocol (Revision 2)
 238 .Re
 239 .Rs
 240 .%T RFC 2347: TFTP Option Extension
 241 .Re
 242 .Rs
 243 .%T RFC 2348: TFTP Blocksize Option
 244 .Re
 245 .Rs
 246 .%T RFC 2349: TFTP Timeout Interval and Transfer Size Options
 247 .Re
 248 .Pp
 249 The non-standard
 250 .Cm rollover
 251 and
 252 .Cm blksize2
 253 TFTP options are mentioned here:
 254 .Rs
 255 .%T Extending TFTP
 256 .%U http://www.compuphase.com/tftp.htm
 257 .Re
 258 .Sh HISTORY
 259 The
 260 .Nm
 261 utility appeared in
 262 .Bx 4.2 ;
 263 the
 264 .Fl s
 265 option was introduced in
 266 .Fx 2.2 ,
 267 the
 268 .Fl u
 269 option was introduced in
 270 .Fx 4.2 ,
 271 the
 272 .Fl c
 273 option was introduced in
 274 .Fx 4.3 ,
 275 and the
 276 .Fl F
 277 and
 278 .Fl W
 279 options were introduced in
 280 .Fx 7.4 .
 281 .Pp
 282 Support for Timeout Interval and Transfer Size Options (RFC2349)
 283 was introduced in
 284 .Fx 5.0 ,
 285 support for the TFTP Blocksize Option (RFC2348) and the blksize2 option
 286 was introduced in
 287 .Fx 7.4 .
 288 .Pp
 289 Edwin Groothuis <edwin@FreeBSD.org> performed a major rewrite of the
 290 .Nm
 291 and
 292 .Xr tftp 1
 293 code to support RFC2348.
 294 .Sh NOTES
 295 Files larger than 33,553,919 octets (65535 blocks, last one <512
 296 octets) cannot be correctly transferred without client and server
 297 supporting blocksize negotiation (RFCs 2347 and 2348),
 298 or the non-standard TFTP rollover option.
 299 As a kludge,
 300 .Nm
 301 accepts a sequence of block number which wrap to zero after 65535,
 302 even if the rollover option is not specified.
 303 .Pp
 304 Many tftp clients will not transfer files over 16,776,703 octets
 305 (32767 blocks), as they incorrectly count the block number using
 306 a signed rather than unsigned 16-bit integer.