usr.bin/tftp/tftp.1

   1 .\"     $NetBSD: tftp.1,v 1.19 2006/07/23 17:52:24 jmcneill Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1993, 1994
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)tftp.1      8.2 (Berkeley) 4/18/94
  31 .\"
  32 .Dd July 23, 2006
  33 .Dt TFTP 1
  34 .Os
  35 .Sh NAME
  36 .Nm tftp
  37 .Nd trivial file transfer program
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl e
  41 .Op Ar host
  42 .Op Ar port
  43 .Sh DESCRIPTION
  44 .Nm
  45 is the user interface to the Internet
  46 .Tn TFTP
  47 (Trivial File Transfer Protocol),
  48 which allows users to transfer files to and from a remote machine.
  49 The remote
  50 .Ar host
  51 (and optional
  52 .Ar port )
  53 may be specified on the command line, in which case
  54 .Nm
  55 uses
  56 .Ar host
  57 (and
  58 .Ar port )
  59 as the default for future transfers (see the
  60 .Cm connect
  61 command below).
  62 .Pp
  63 The optional
  64 .Fl e
  65 argument sets a binary transfer mode as well as setting the extended options
  66 as if
  67 .Cm tout ,
  68 .Cm tsize ,
  69 and
  70 .Cm blksize 65464 ,
  71 had been given.
  72 .Pp
  73 The Multicast TFTP option is supported in open-loop (i.e., "slave-only") mode
  74 based on IETF draft-dion-tftp-multicast-option-01.txt (May 2002), which in
  75 turn was based on RFC2026.
  76 .Sh COMMANDS
  77 Once
  78 .Nm
  79 is running, it issues the prompt
  80 .Ql tftp\*[Gt]
  81 and recognizes the following commands:
  82 .Pp
  83 .Bl -tag -width verbose -compact
  84 .It Cm \&? Ar command-name ...
  85 Print help information.
  86 .Pp
  87 .It Cm ascii
  88 Shorthand for "mode ascii"
  89 .Pp
  90 .It Cm binary
  91 Shorthand for "mode binary"
  92 .Pp
  93 .It Cm blksize Ar blk-size
  94 Set the tftp blksize option to
  95 .Ar blk-size
  96 octets (8-bit bytes).  Since the number of blocks in a tftp
  97 .Cm get
  98 or
  99 .Cm put
 100 is 65535, the default block size of 512 bytes only allows a maximum of
 101 just under 32 megabytes to be transferred.  The value given for
 102 .Ar blk-size
 103 must be between 8 and 65464, inclusive.
 104 Note that many servers will not respect this option.
 105 .Pp
 106 .It Cm connect Ar host-name Op Ar port
 107 Set the
 108 .Ar host
 109 (and optionally
 110 .Ar port )
 111 for transfers.
 112 Note that the
 113 .Tn TFTP
 114 protocol, unlike the
 115 .Tn FTP
 116 protocol,
 117 does not maintain connections between transfers; thus, the
 118 .Cm connect
 119 command does not actually create a connection,
 120 but merely remembers what host is to be used for transfers.
 121 You do not have to use the
 122 .Cm connect
 123 command; the remote host can be specified as part of the
 124 .Cm get
 125 or
 126 .Cm put
 127 commands.
 128 .Pp
 129 .It Cm get Ar filename
 130 .It Cm get Ar remotename localname
 131 .It Cm get Ar file1 file2 ...  fileN
 132 Get a file or set of files from the specified
 133 .Ar sources .
 134 .Ar Source
 135 can be in one of two forms:
 136 a filename on the remote host, if the host has already been specified,
 137 or a string of the form
 138 .Ar hosts:filename
 139 to specify both a host and filename at the same time.
 140 If the latter form is used,
 141 the last hostname specified becomes the default for future transfers.
 142 .Pp
 143 .It Cm mode Ar transfer-mode
 144 Set the mode for transfers;
 145 .Ar transfer-mode
 146 may be one of
 147 .Em ascii
 148 or
 149 .Em binary .
 150 The default is
 151 .Em ascii .
 152 .Pp
 153 .It Cm put Ar file
 154 .It Cm put Ar localfile remotefile
 155 .It Cm put Ar file1 file2 ... fileN remote-directory
 156 Put a file or set of files to the specified
 157 remote file or directory.
 158 The destination
 159 can be in one of two forms:
 160 a filename on the remote host, if the host has already been specified,
 161 or a string of the form
 162 .Ar hosts:filename
 163 to specify both a host and filename at the same time.
 164 If the latter form is used,
 165 the hostname specified becomes the default for future transfers.
 166 If the remote-directory form is used, the remote host is
 167 assumed to be a
 168 .Ux
 169 machine.
 170 If you need to specify IPv6 numeric address to
 171 .Ar hosts ,
 172 wrap them using square bracket like
 173 .Ar [hosts]:filename
 174 to disambiguate the colon.
 175 .Pp
 176 .It Cm quit
 177 Exit
 178 .Nm .
 179 An end of file also exits.
 180 .Pp
 181 .It Cm rexmt Ar retransmission-timeout
 182 Set the per-packet retransmission timeout, in seconds.
 183 .Pp
 184 .It Cm status
 185 Show current status.
 186 .Pp
 187 .It Cm timeout Ar total-transmission-timeout
 188 Set the total transmission timeout, in seconds.
 189 .Pp
 190 .It Cm tout
 191 Toggle the tftp "timeout" option.  If enabled, the client will pass its
 192 .Ar retransmission-timeout
 193 to the server.
 194 Note that many servers will not respect this option.
 195 .Pp
 196 .It Cm trace
 197 Toggle packet tracing.
 198 .Pp
 199 .It Cm tsize
 200 Toggle the tftp "tsize" option.  If enabled, the client will pass and
 201 request the filesize of a file at the beginning of a file transfer.
 202 Note that many servers will not respect this option.
 203 .Pp
 204 .It Cm verbose
 205 Toggle verbose mode.
 206 .El
 207 .Sh HISTORY
 208 The
 209 .Nm
 210 command appeared in
 211 .Bx 4.3 .
 212 IPv6 support was implemented by WIDE/KAME project in 1999.
 213 TFTP options were implemented by Wasabi Systems, Inc., in 2003,
 214 and first appeared in
 215 .Nx 2.0 .
 216 Multicast TFTP was implemented by
 217 .An Jared D. McNeill
 218 in 2006, and first appeared in
 219 .Nx 4.0 .
 220 .Sh SECURITY CONSIDERATIONS
 221 Because there is no user-login or validation within
 222 the
 223 .Tn TFTP
 224 protocol, the remote site will probably have some
 225 sort of file-access restrictions in place.
 226 The exact methods are specific to each site and therefore
 227 difficult to document here.