usr.bin/tftp/tftp.1

   1 .\" Copyright (c) 1990, 1993, 1994
   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 .\" 4. 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 .\"     @(#)tftp.1      8.2 (Berkeley) 4/18/94
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd June 22, 2011
  32 .Dt TFTP 1
  33 .Os
  34 .Sh NAME
  35 .Nm tftp
  36 .Nd trivial file transfer program
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Ar host Op Ar port
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 utility is the user interface to the Internet
  44 .Tn TFTP
  45 (Trivial File Transfer Protocol),
  46 which allows users to transfer files to and from a remote machine.
  47 The remote
  48 .Ar host
  49 may be specified on the command line, in which case
  50 .Nm
  51 uses
  52 .Ar host
  53 as the default host for future transfers (see the
  54 .Cm connect
  55 command below).
  56 .Sh COMMANDS
  57 Once
  58 .Nm
  59 is running, it issues the prompt
  60 .Dq Li tftp>
  61 and recognizes the following commands:
  62 .Pp
  63 .Bl -tag -width verbose -compact
  64 .It Cm \&? Ar command-name ...
  65 Print help information.
  66 .Pp
  67 .It Cm ascii
  68 Shorthand for "mode ascii"
  69 .Pp
  70 .It Cm binary
  71 Shorthand for "mode binary"
  72 .Pp
  73 .It Cm blocksize Ar [size]
  74 Sets the TFTP blksize option in TFTP Read Request or Write Request packets
  75 to
  76 .Ar [size]
  77 as specified in RFC 2348.  Valid values are between 8 and 65464.
  78 If no blocksize is specified, then by default a blocksize of 512 bytes
  79 will be used.
  80 .Pp
  81 .It Cm blocksize2 Ar [size]
  82 Sets the TFTP blksize2 option in TFTP Read Request or Write Request packets
  83 to
  84 .Ar [size] .
  85 Values are restricted to powers of 2 between 8 and 32768.  This is a
  86 non-standard TFTP option.
  87 .Pp
  88 .It Cm connect Ar host Op Ar port
  89 Set the
  90 .Ar host
  91 (and optionally
  92 .Ar port )
  93 for transfers.
  94 Note that the
  95 .Tn TFTP
  96 protocol, unlike the
  97 .Tn FTP
  98 protocol,
  99 does not maintain connections between transfers; thus, the
 100 .Cm connect
 101 command does not actually create a connection,
 102 but merely remembers what host is to be used for transfers.
 103 You do not have to use the
 104 .Cm connect
 105 command; the remote host can be specified as part of the
 106 .Cm get
 107 or
 108 .Cm put
 109 commands.
 110 .Pp
 111 .It Cm debug Ar level
 112 Enable or disable debugging levels during verbose output.  The value of
 113 .Ar level
 114 can be one of
 115 .Cm packet , simple , options ,
 116 or
 117 .Cm access .
 118 .Pp
 119 .It Cm get Oo Ar host : Oc Ns Ar file Op Ar localname
 120 .It Cm get Xo
 121 .Oo Ar host1 : Oc Ns Ar file1
 122 .Oo Ar host2 : Oc Ns Ar file2 ...
 123 .Oo Ar hostN : Oc Ns Ar fileN
 124 .Xc
 125 Get one or more files from the remote host.
 126 When using the
 127 .Ar host
 128 argument, the
 129 .Ar host
 130 will be used as default host for future transfers.
 131 If
 132 .Ar localname
 133 is specified, the file is stored locally as
 134 .Ar localname ,
 135 otherwise the original filename is used.
 136 Note that it is not possible to download two files at a time, only
 137 one, three, or more than three files, at a time.
 138 .Pp
 139 To specify an IPv6 numeric address for a host, wrap it using square
 140 brackets like
 141 .Dq Li [3ffe:2900:e00c:ffee::1234] : Ns Ar file
 142 to disambiguate the
 143 colons used in the IPv6 address from the colon separating the host and
 144 the filename.
 145 .Pp
 146 .It Cm mode Ar transfer-mode
 147 Set the mode for transfers;
 148 .Ar transfer-mode
 149 may be one of
 150 .Em ascii
 151 or
 152 .Em binary .
 153 The default is
 154 .Em ascii .
 155 .Pp
 156 .It Cm packetdrop [arg]
 157 Randomly drop
 158 .Ar arg
 159 out of 100 packets during a transfer.  This is a debugging feature.
 160 .Pp
 161 .It Cm put Ar file Op Oo Ar host : Oc Ns Ar remotename
 162 .It Cm put Ar file1 file2 ... fileN Op Oo Ar host : Oc Ns Ar remote-directory
 163 Put a file or set of files to the remote host.
 164 When
 165 .Ar remotename
 166 is specified, the file is stored remotely as
 167 .Ar remotename ,
 168 otherwise the original filename is used.
 169 If the
 170 .Ar remote-directory
 171 argument is used, the remote host is assumed to be a
 172 .Ux
 173 machine.
 174 To specify an IPv6 numeric address for a
 175 .Ar host ,
 176 see the example under the
 177 .Cm get
 178 command.
 179 .Pp
 180 .It Cm options Ar [arg]
 181 Enable or disable support for TFTP options.  The valid values of
 182 .Ar arg
 183 are
 184 .Cm on
 185 (enable RFC 2347 options),
 186 .Cm off
 187 (disable RFC 2347 options), and
 188 .Cm extra
 189 (toggle support for non-RFC defined options).
 190 .Pp
 191 .It Cm quit
 192 Exit
 193 .Nm .
 194 An end of file also exits.
 195 .Pp
 196 .It Cm rexmt Ar retransmission-timeout
 197 Set the per-packet retransmission timeout, in seconds.
 198 .Pp
 199 .It Cm rollover [arg]
 200 Specify the rollover option in TFTP Read Request or Write
 201 Request packets.  After 65535 packets have been transmitted, set the block
 202 counter to
 203 .Ar arg .
 204 Valid values of
 205 .Ar arg
 206 are 0 and 1.  This is a non-standard TFTP option.
 207 .Pp
 208 .It Cm status
 209 Show current status.
 210 .Pp
 211 .It Cm timeout Ar total-transmission-timeout
 212 Set the total transmission timeout, in seconds.
 213 .Pp
 214 .It Cm trace
 215 Toggle packet tracing.
 216 .Pp
 217 .It Cm verbose
 218 Toggle verbose mode.
 219 .El
 220 .Sh SEE ALSO
 221 .Xr tftpd 8
 222 .Pp
 223 The following RFC's are supported:
 224 .Rs
 225 .%T RFC 1350: The TFTP Protocol (Revision 2)
 226 .Re
 227 .Rs
 228 .%T RFC 2347: TFTP Option Extension
 229 .Re
 230 .Rs
 231 .%T RFC 2348: TFTP Blocksize Option
 232 .Re
 233 .Rs
 234 .%T RFC 2349: TFTP Timeout Interval and Transfer Size Options
 235 .Re
 236 .Rs
 237 .%T RFC 3617: Uniform Resource Identifier (URI) Scheme and Applicability Statement for the Trivial File Transfer Protocol (TFTP)
 238 .Re
 239 .Pp
 240 The non-standard
 241 .Cm rollover
 242 and
 243 .Cm blksize2
 244 TFTP options are mentioned here:
 245 .Rs
 246 .%T Extending TFTP
 247 .%U http://www.compuphase.com/tftp.htm
 248 .Re
 249 .Sh HISTORY
 250 The
 251 .Nm
 252 command appeared in
 253 .Bx 4.3 .
 254 .Pp
 255 Edwin Groothuis <edwin@FreeBSD.org> performed a major rewrite of the
 256 .Xr tftpd 8
 257 and
 258 .Nm
 259 code to support RFC2348.
 260 .Sh NOTES
 261 Because there is no user-login or validation within
 262 the
 263 .Tn TFTP
 264 protocol, the remote site will probably have some
 265 sort of file-access restrictions in place.
 266 The
 267 exact methods are specific to each site and therefore
 268 difficult to document here.
 269 .Pp
 270 Files larger than 33488896 octets (65535 blocks) cannot be transferred
 271 without client and server supporting the TFTP blocksize option (RFC2348),
 272 or the non-standard TFTP rollover option.