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 .\"
  30 .Dd July 20, 2023
  31 .Dt TFTPD 8
  32 .Os
  33 .Sh NAME
  34 .Nm tftpd
  35 .Nd Internet Trivial File Transfer Protocol server
  36 .Sh SYNOPSIS
  37 .Nm tftpd
  38 .Op Fl cdClnow
  39 .Op Fl F Ar strftime-format
  40 .Op Fl s Ar directory
  41 .Op Fl u Ar user
  42 .Op Fl U Ar umask
  43 .Op Ar directory ...
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 utility is a server which supports the
  48 Internet Trivial File Transfer
  49 Protocol
  50 .Pq Tn RFC 1350 .
  51 The
  52 .Tn TFTP
  53 server operates
  54 at the port indicated in the
  55 .Ql tftp
  56 service description;
  57 see
  58 .Xr services 5 .
  59 The server is normally started by
  60 .Xr inetd 8 .
  61 .Pp
  62 The use of
  63 .Xr tftp 1
  64 does not require an account or password on the remote system.
  65 Due to the lack of authentication information,
  66 .Nm
  67 will allow only publicly readable files to be
  68 accessed.
  69 Files containing the string
  70 .Dq Li "/../"
  71 or starting with
  72 .Dq Li "../"
  73 are not allowed.
  74 Files may be written only if they already exist (unless the
  75 .Fl w
  76 option is used) and are publicly writable (unless chrooted and the
  77 .Fl S
  78 option is used).
  79 Note that this extends the concept of
  80 .Dq public
  81 to include
  82 all users on all hosts that can be reached through the network;
  83 this may not be appropriate on all systems, and its implications
  84 should be considered before enabling tftp service.
  85 The server should have the user ID with the lowest possible privilege.
  86 .Pp
  87 Access to files may be restricted by invoking
  88 .Nm
  89 with a list of directories by including up to 20 pathnames
  90 as server program arguments in
  91 .Xr inetd.conf 5 .
  92 In this case access is restricted to files whose
  93 names are prefixed by the one of the given directories.
  94 The given directories are also treated as a search path for
  95 relative filename requests.
  96 .Pp
  97 The
  98 .Fl s
  99 option provides additional security by changing
 100 the root directory of
 101 .Nm ,
 102 thereby prohibiting accesses to outside of the specified
 103 .Ar directory .
 104 Because
 105 .Xr chroot 2
 106 requires super-user privileges,
 107 .Nm
 108 must be run as
 109 .Li root .
 110 However, after performing the
 111 .Xr chroot 2
 112 call,
 113 .Nm
 114 will set its user ID to that of the specified
 115 .Ar user ,
 116 or
 117 .Dq Li nobody
 118 if no
 119 .Fl u
 120 option is specified.
 121 .Pp
 122 The options are:
 123 .Bl -tag -width Ds
 124 .It Fl c
 125 Changes the default root directory of a connecting host via
 126 .Xr chroot 2
 127 based on the connecting IP address.
 128 This prevents multiple clients from writing to the same file at the same time.
 129 If the directory does not exist, the client connection is refused.
 130 The
 131 .Fl s
 132 option is required for
 133 .Fl c
 134 and the specified
 135 .Ar directory
 136 is used as a base.
 137 .It Fl C
 138 Operates the same as
 139 .Fl c
 140 except it falls back to
 141 .Ar directory
 142 specified via
 143 .Fl s
 144 if a directory does not exist for the client's IP.
 145 .It Fl F
 146 Use this
 147 .Xr strftime 3
 148 compatible format string for the creation of the suffix if
 149 .Fl W
 150 is specified.
 151 By default the string "%Y%m%d" is used.
 152 .It Fl d, d Ar [value]
 153 Enables debug output.
 154 If
 155 .Ar value
 156 is not specified, then the debug level is increased by one
 157 for each instance of
 158 .Fl d
 159 which is specified.
 160 .Pp
 161 If
 162 .Ar value
 163 is specified, then the debug level is set to
 164 .Ar value .
 165 The debug level is a bitmask implemented in
 166 .Pa src/libexec/tftpd/tftp-utils.h .
 167 Valid values are 0 (DEBUG_NONE), 1 (DEBUG_PACKETS), 2, (DEBUG_SIMPLE),
 168 4 (DEBUG_OPTIONS), and 8 (DEBUG_ACCESS).  Multiple debug values can be combined
 169 in the bitmask by logically OR'ing the values.  For example, specifying
 170 .Fl d
 171 .Ar 15
 172 will enable all the debug values.
 173 .It Fl l
 174 Log all requests using
 175 .Xr syslog 3
 176 with the facility of
 177 .Dv LOG_FTP .
 178 .Sy Note :
 179 Logging of
 180 .Dv LOG_FTP
 181 messages
 182 must also be enabled in the syslog configuration file,
 183 .Xr syslog.conf 5 .
 184 .It Fl n
 185 Suppress negative acknowledgement of requests for nonexistent
 186 relative filenames.
 187 .It Fl o
 188 Disable support for RFC2347 style TFTP Options.
 189 .It Fl s Ar directory
 190 Cause
 191 .Nm
 192 to change its root directory to
 193 .Ar directory .
 194 After doing that but before accepting commands,
 195 .Nm
 196 will switch credentials to an unprivileged user.
 197 .It Fl S
 198 If
 199 .Nm
 200 runs chrooted, the option allows write requests according to generic
 201 file permissions, skipping requirement for files to be publicly writable.
 202 The option is ignored for non-chrooted run.
 203 .It Fl u Ar user
 204 Switch credentials to
 205 .Ar user
 206 (default
 207 .Dq Li nobody )
 208 when the
 209 .Fl s
 210 option is used.
 211 The user must be specified by name, not a numeric UID.
 212 .It Fl U Ar umask
 213 Set the
 214 .Ar umask
 215 for newly created files.
 216 The default is 022
 217 .Pq Dv S_IWGRP | S_IWOTH .
 218 .It Fl w
 219 Allow write requests to create new files.
 220 By default
 221 .Nm
 222 requires that the file specified in a write request exist.
 223 Note that this only works in directories writable by the user
 224 specified with
 225 .Fl u
 226 option
 227 .It Fl W
 228 As
 229 .Fl w
 230 but append a YYYYMMDD.nn sequence number to the end of the filename.
 231 Note that the string YYYYMMDD can be changed with the
 232 .Fl F
 233 option.
 234 .El
 235 .Sh SEE ALSO
 236 .Xr tftp 1 ,
 237 .Xr chroot 2 ,
 238 .Xr syslog 3 ,
 239 .Xr inetd.conf 5 ,
 240 .Xr services 5 ,
 241 .Xr syslog.conf 5 ,
 242 .Xr inetd 8
 243 .Pp
 244 The following RFC's are supported:
 245 .Rs
 246 .%T RFC 1350: The TFTP Protocol (Revision 2)
 247 .Re
 248 .Rs
 249 .%T RFC 2347: TFTP Option Extension
 250 .Re
 251 .Rs
 252 .%T RFC 2348: TFTP Blocksize Option
 253 .Re
 254 .Rs
 255 .%T RFC 2349: TFTP Timeout Interval and Transfer Size Options
 256 .Re
 257 .Rs
 258 .%T RFC 7440: TFTP Windowsize Option
 259 .Re
 260 .Pp
 261 The non-standard
 262 .Cm rollover
 263 and
 264 .Cm blksize2
 265 TFTP options are mentioned here:
 266 .Rs
 267 .%T Extending TFTP
 268 .%U http://www.compuphase.com/tftp.htm
 269 .Re
 270 .Sh HISTORY
 271 The
 272 .Nm
 273 utility appeared in
 274 .Bx 4.2 ;
 275 the
 276 .Fl s
 277 option was introduced in
 278 .Fx 2.2 ,
 279 the
 280 .Fl u
 281 option was introduced in
 282 .Fx 4.2 ,
 283 the
 284 .Fl c
 285 option was introduced in
 286 .Fx 4.3 ,
 287 the
 288 .Fl F
 289 and
 290 .Fl W
 291 options were introduced in
 292 .Fx 7.4 ,
 293 and the
 294 .Fl S
 295 option was introduced in
 296 .Fx 13.3 .
 297 .Pp
 298 Support for Timeout Interval and Transfer Size Options (RFC2349)
 299 was introduced in
 300 .Fx 5.0 ,
 301 support for the TFTP Blocksize Option (RFC2348) and the blksize2 option
 302 was introduced in
 303 .Fx 7.4 .
 304 .Pp
 305 Edwin Groothuis <edwin@FreeBSD.org> performed a major rewrite of the
 306 .Nm
 307 and
 308 .Xr tftp 1
 309 code to support RFC2348.
 310 .Pp
 311 Support for the windowsize option (RFC7440) was introduced in
 312 .Fx 13.0 .
 313 .Sh NOTES
 314 Files larger than 33,553,919 octets (65535 blocks, last one <512
 315 octets) cannot be correctly transferred without client and server
 316 supporting blocksize negotiation (RFCs 2347 and 2348),
 317 or the non-standard TFTP rollover option.
 318 As a kludge,
 319 .Nm
 320 accepts a sequence of block number which wrap to zero after 65535,
 321 even if the rollover option is not specified.
 322 .Pp
 323 Many tftp clients will not transfer files over 16,776,703 octets
 324 (32767 blocks), as they incorrectly count the block number using
 325 a signed rather than unsigned 16-bit integer.