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