Annotation of src/usr.bin/tftp/tftp.1, Revision 1.20
1.20 ! gsoares 1: .\" $OpenBSD: tftp.1,v 1.19 2012/03/01 03:47:19 dlg Exp $
1.1 deraadt 2: .\" $NetBSD: tftp.1,v 1.5 1995/08/18 14:45:44 pk Exp $
3: .\"
4: .\" Copyright (c) 1990, 1993, 1994
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.7 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
31: .\" @(#)tftp.1 8.2 (Berkeley) 4/18/94
32: .\"
1.20 ! gsoares 33: .Dd $Mdocdate: March 1 2012 $
1.1 deraadt 34: .Dt TFTP 1
1.4 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
37: .Nm tftp
38: .Nd trivial file transfer program
39: .Sh SYNOPSIS
40: .Nm tftp
1.9 jmc 41: .Op Ar host Oo Ar port Oc
1.1 deraadt 42: .Sh DESCRIPTION
1.6 aaron 43: .Nm
1.1 deraadt 44: is the user interface to the Internet
45: .Tn TFTP
46: (Trivial File Transfer Protocol),
47: which allows users to transfer files to and from a remote machine.
48: The remote
49: .Ar host
1.8 jmc 50: and
51: .Ar port
1.1 deraadt 52: may be specified on the command line, in which case
1.6 aaron 53: .Nm
1.8 jmc 54: uses them as the default for future transfers (see the
1.3 aaron 55: .Ic connect
1.1 deraadt 56: command below).
57: .Sh COMMANDS
58: Once
1.6 aaron 59: .Nm
1.1 deraadt 60: is running, it issues the prompt
1.10 jmc 61: .Ql tftp\*(Gt
1.1 deraadt 62: and recognizes the following commands:
63: .Pp
64: .Bl -tag -width verbose -compact
1.17 sobrado 65: .It Ic \&? Ar command-name ...
1.1 deraadt 66: Print help information.
67: .Pp
1.3 aaron 68: .It Ic ascii
69: Shorthand for
1.8 jmc 70: .Ic mode Ar ascii .
1.3 aaron 71: .Pp
72: .It Ic binary
73: Shorthand for
1.8 jmc 74: .Ic mode Ar binary .
1.1 deraadt 75: .Pp
1.13 jmc 76: .It Ic blksize Ar block-size
77: Set the block size in bytes for one packet.
78: The default value is 512 bytes.
79: Valid values are 8 bytes \(en 65464 bytes.
80: .Pp
1.3 aaron 81: .It Ic connect Ar host Op Ar port
1.1 deraadt 82: Set the
83: .Ar host
84: (and optionally
85: .Ar port )
86: for transfers.
87: Note that the
88: .Tn TFTP
89: protocol, unlike the
90: .Tn FTP
91: protocol,
92: does not maintain connections between transfers; thus, the
1.3 aaron 93: .Ic connect
1.1 deraadt 94: command does not actually create a connection,
95: but merely remembers what host is to be used for transfers.
1.4 aaron 96: You do not have to use the
1.3 aaron 97: .Ic connect
1.1 deraadt 98: command; the remote host can be specified as part of the
1.3 aaron 99: .Ic get
1.1 deraadt 100: or
1.3 aaron 101: .Ic put
1.1 deraadt 102: commands.
103: .Pp
1.8 jmc 104: .It Xo
1.10 jmc 105: .Ic get Oo Ar host : Oc Ns
1.8 jmc 106: .Ar file Op Ar localname
107: .Xc
108: .It Xo
1.10 jmc 109: .Ic get Oo Ar host1 : Oc Ns
1.8 jmc 110: .Ar file1
1.10 jmc 111: .Oo Ar host2 : Oc Ns
1.17 sobrado 112: .Ar file2 ...
1.10 jmc 113: .Oo Ar hostN : Oc Ns
1.8 jmc 114: .Ar fileN
115: .Xc
116: Get a file or set of files from the remote host.
117: When using the
118: .Ar host
119: argument, the
120: .Ar host
121: will be used as the default host for future transfers.
1.20 ! gsoares 122: IPv6 addresses can be specified by enclosing
! 123: .Ar host
! 124: in square brackets.
1.8 jmc 125: If
126: .Ar localname
127: is specified,
128: the file is stored locally as
129: .Ar localname ,
130: otherwise the original filename is used.
131: .Pp
132: Note that it is not possible to download two files at the same time;
133: only one, three, or more than three files
134: can be downloaded at the same time.
1.1 deraadt 135: .Pp
1.3 aaron 136: .It Ic mode Ar transfer-mode
1.4 aaron 137: Set the mode for transfers;
1.1 deraadt 138: .Ar transfer-mode
139: may be one of
1.8 jmc 140: .Ar ascii
1.1 deraadt 141: or
1.8 jmc 142: .Ar binary .
1.1 deraadt 143: The default is
1.8 jmc 144: .Ar ascii .
1.1 deraadt 145: .Pp
1.8 jmc 146: .It Xo
147: .Ic put Ar file
1.10 jmc 148: .Oo Oo Ar host : Oc Ns
1.8 jmc 149: .Ar remotename Oc
150: .Xc
151: .It Xo
152: .Ic put Ar file1 file2 ... fileN
1.10 jmc 153: .Oo Oo Ar host : Oc Ns
1.8 jmc 154: .Ar remote-directory Oc
155: .Xc
156: Put a file or set of files to the remote host.
157: When using the
158: .Ar host
159: argument, the
160: .Ar host
161: will be used as the default host for future transfers.
1.20 ! gsoares 162: IPv6 addresses can be specified by enclosing
! 163: .Ar host
! 164: in square brackets.
1.8 jmc 165: If
166: .Ar remotename
167: is specified, the file is stored remotely as
168: .Ar remotename ,
169: otherwise the original filename is used.
170: If the
171: .Ar remote-directory
172: argument is used, the remote host is assumed to be a
1.18 sobrado 173: .Ux
1.1 deraadt 174: machine.
175: .Pp
1.8 jmc 176: Note that files may only be written to if they already exist on the
177: remote host and are publicly writable.
178: See
179: .Xr tftpd 8
180: for further details.
181: .Pp
1.3 aaron 182: .It Ic quit
1.1 deraadt 183: Exit
1.10 jmc 184: .Nm .
1.3 aaron 185: An end-of-file also exits.
1.1 deraadt 186: .Pp
1.3 aaron 187: .It Ic rexmt Ar retransmission-timeout
1.13 jmc 188: Set the per-packet retransmission timeout, in seconds.
189: The default value is 5 seconds.
190: Valid values are 1 second \(en 255 seconds.
1.1 deraadt 191: .Pp
1.3 aaron 192: .It Ic status
1.1 deraadt 193: Show current status.
194: .Pp
1.3 aaron 195: .It Ic timeout Ar total-transmission-timeout
1.1 deraadt 196: Set the total transmission timeout, in seconds.
1.15 mglocker 197: The default value is 25 seconds.
198: Valid values are 1 second \(en 255 seconds.
1.1 deraadt 199: .Pp
1.13 jmc 200: .It Ic tout
201: Toggle the
202: .Ic tout
203: option.
1.19 dlg 204: This option delivers the retransmission timeout,
1.13 jmc 205: which is set by
206: .Ic rexmt ,
207: to the server,
1.14 jmc 208: so the server uses the same retransmission timeout as the client.
1.13 jmc 209: .Pp
210: .It Ic tsize
211: Toggle the
212: .Ic tsize
213: option.
214: This option delivers the total size of the file to be transferred.
215: With this value given, the client or server can decide
216: whether they are able to accept the file.
217: .Pp
1.3 aaron 218: .It Ic trace
1.1 deraadt 219: Toggle packet tracing.
220: .Pp
1.3 aaron 221: .It Ic verbose
1.1 deraadt 222: Toggle verbose mode.
223: .El
1.5 aaron 224: .Sh SEE ALSO
1.8 jmc 225: .Xr ftp 1 ,
1.11 jmc 226: .Xr tftp-proxy 8 ,
1.8 jmc 227: .Xr tftpd 8
1.5 aaron 228: .Sh HISTORY
229: The
230: .Nm
231: command appeared in
232: .Bx 4.3 .
1.1 deraadt 233: .Sh BUGS
1.3 aaron 234: Because there is no user login or validation within
1.1 deraadt 235: the
236: .Tn TFTP
237: protocol, the remote site will probably have some
1.6 aaron 238: sort of file access restrictions in place.
239: The exact methods are specific to each site and therefore
1.1 deraadt 240: difficult to document here.