1TNFTP(1) BSD General Commands Manual TNFTP(1)
2
4 tnftp — Internet file transfer program
5
7 tnftp [-46AadefginpRtVv?] [-N netrc] [-o output] [-P port] [-q quittime]
8 [-r retry] [-s srcaddr] [-T dir,max[,inc]] [-x xfersize]
9 [[user@]host [port]] [[user@]host:[path][/]] [file:///path]
10 [ftp://[user[:password]@]host[:port]/path[/][;type=type]]
11 [http://[user[:password]@]host[:port]/path]
12 [https://[user[:password]@]host[:port]/path] ...
13 tnftp -u url file ...
14
16 tnftp is the user interface to the Internet standard File Transfer Proto‐
17 col. The program allows a user to transfer files to and from a remote
18 network site.
19 The last five arguments will fetch a file using the FTP or HTTP proto‐
21 cols, or by direct copying, into the current directory. This is ideal
22 for scripts. Refer to AUTO-FETCHING FILES below for more information.
23 Options may be specified at the command line, or to the command inter‐
25 preter.
26 -4 Forces tnftp to only use IPv4 addresses.
28 -6 Forces tnftp to only use IPv6 addresses.
30 -A Force active mode FTP. By default, tnftp will try to use
32 passive mode FTP and fall back to active mode if passive is
33 not supported by the server. This option causes tnftp to al‐
34 ways use an active connection. It is only useful for con‐
35 necting to very old servers that do not implement passive
36 mode properly.
37 -a Causes tnftp to bypass normal login procedure, and use an
39 anonymous login instead.
40 -d Enables debugging.
42 -e Disables command line editing. This is useful for Emacs
44 ange-ftp mode.
45 -f Forces a cache reload for transfers that go through the FTP
47 or HTTP proxies.
48 -g Disables file name globbing.
50 -i Turns off interactive prompting during multiple file trans‐
52 fers.
53 -N netrc Use netrc instead of ~/.netrc. Refer to THE .netrc FILE for
55 more information.
56 -n Restrains tnftp from attempting “auto-login” upon initial
58 connection for non auto-fetch transfers. If auto-login is
59 enabled, tnftp will check the .netrc (see below) file in the
60 user's home directory for an entry describing an account on
61 the remote machine. If no entry exists, tnftp will prompt
62 for the remote machine login name (default is the user
63 identity on the local machine), and, if necessary, prompt for
64 a password and an account with which to login. To override
65 the auto-login for auto-fetch transfers, specify the username
66 (and optionally, password) as appropriate.
67 -o output When auto-fetching files, save the contents in output.
69 output is parsed according to the FILE NAMING CONVENTIONS be‐
70 low. If output is not ‘-’ or doesn't start with ‘|’, then
71 only the first file specified will be retrieved into output;
72 all other files will be retrieved into the basename of their
73 remote name.
74 -P port Sets the port number to port.
76 -p Enable passive mode operation for use behind connection fil‐
78 tering firewalls. This option has been deprecated as tnftp
79 now tries to use passive mode by default, falling back to ac‐
80 tive mode if the server does not support passive connections.
81 -q quittime
83 Quit if the connection has stalled for quittime seconds.
84 -R Restart all non-proxied auto-fetches.
86 -r wait Retry the connection attempt if it failed, pausing for wait
88 seconds.
89 -s srcaddr Uses srcaddr as the local IP address for all connections.
91 -t Enables packet tracing.
93 -T direction,maximum[,increment]
95 Set the maximum transfer rate for direction to maximum
96 bytes/second, and if specified, the increment to increment
97 bytes/second. Refer to rate for more information.
98 -u url file ...
100 Upload files on the command line to url where url is one of
101 the ‘ftp://’ URL types as supported by auto-fetch (with an
102 optional target filename for single file uploads), and file
103 is one or more local files to be uploaded.
104 -V Disable verbose and progress, overriding the default of en‐
106 abled when output is to a terminal.
107 -v Enable verbose and progress. This is the default if output
109 is to a terminal (and in the case of progress, tnftp is the
110 foreground process). Forces tnftp to show all responses from
111 the remote server, as well as report on data transfer statis‐
112 tics.
113 -x xfersize
115 Set the size of the socket send and receive buffers to
116 xfersize. Refer to xferbuf for more information.
117 -? Display help to stdout, and exit.
119 The client host with which tnftp is to communicate may be specified on
121 the command line. If this is done, tnftp will immediately attempt to es‐
122 tablish a connection to an FTP server on that host; otherwise, tnftp will
123 enter its command interpreter and await instructions from the user. When
124 tnftp is awaiting commands from the user the prompt ‘ftp>’ is provided to
125 the user. The following commands are recognized by tnftp:
126 ! [command [args]]
128 Invoke an interactive shell on the local machine. If there
129 are arguments, the first is taken to be a command to execute
130 directly, with the rest of the arguments as its arguments.
131 $ macro-name [args]
133 Execute the macro macro-name that was defined with the macdef
134 command. Arguments are passed to the macro unglobbed.
135 account [passwd]
137 Supply a supplemental password required by a remote system
138 for access to resources once a login has been successfully
139 completed. If no argument is included, the user will be
140 prompted for an account password in a non-echoing input mode.
141 append local-file [remote-file]
143 Append a local file to a file on the remote machine. If
144 remote-file is left unspecified, the local file name is used
145 in naming the remote file after being altered by any ntrans
146 or nmap setting. File transfer uses the current settings for
147 type, format, mode, and structure.
148 ascii Set the file transfer type to network ASCII. This is the de‐
150 fault type.
151 bell Arrange that a bell be sounded after each file transfer com‐
153 mand is completed.
154 binary Set the file transfer type to support binary image transfer.
156 bye Terminate the FTP session with the remote server and exit
158 tnftp. An end of file will also terminate the session and
159 exit.
160 case Toggle remote computer file name case mapping during get,
162 mget and mput commands. When case is on (default is off),
163 remote computer file names with all letters in upper case are
164 written in the local directory with the letters mapped to
165 lower case.
166 cd remote-directory
168 Change the working directory on the remote machine to
169 remote-directory.
170 cdup Change the remote machine working directory to the parent of
172 the current remote machine working directory.
173 chmod mode remote-file
175 Change the permission modes of the file remote-file on the
176 remote system to mode.
177 close Terminate the FTP session with the remote server, and return
179 to the command interpreter. Any defined macros are erased.
180 cr Toggle carriage return stripping during ascii type file re‐
182 trieval. Records are denoted by a carriage return/linefeed
183 sequence during ascii type file transfer. When cr is on (the
184 default), carriage returns are stripped from this sequence to
185 conform with the UNIX single linefeed record delimiter.
186 Records on non-UNIX remote systems may contain single line‐
187 feeds; when an ascii type transfer is made, these linefeeds
188 may be distinguished from a record delimiter only when cr is
189 off.
190 debug [debug-value]
192 Toggle debugging mode. If an optional debug-value is speci‐
193 fied it is used to set the debugging level. When debugging
194 is on, tnftp prints each command sent to the remote machine,
195 preceded by the string ‘-->’.
196 delete remote-file
198 Delete the file remote-file on the remote machine.
199 dir [remote-path [local-file]]
201 Print a listing of the contents of a directory on the remote
202 machine. The listing includes any system-dependent informa‐
203 tion that the server chooses to include; for example, most
204 UNIX systems will produce output from the command ‘ls -l’.
205 If remote-path is left unspecified, the current working di‐
206 rectory is used. If interactive prompting is on, tnftp will
207 prompt the user to verify that the last argument is indeed
208 the target local file for receiving dir output. If no local
209 file is specified, or if local-file is ‘-’, the output is
210 sent to the terminal.
211 disconnect A synonym for close.
213 edit Toggle command line editing, and context sensitive command
215 and file completion. This is automatically enabled if input
216 is from a terminal, and disabled otherwise.
217 epsv, epsv4, epsv6
219 Toggle the use of the extended EPSV and EPRT commands on all
220 IP, IPv4, and IPv6 connections respectively. First try
221 EPSV/EPRT, and then PASV/PORT. This is enabled by default.
222 If an extended command fails then this option will be tempo‐
223 rarily disabled for the duration of the current connection,
224 or until epsv, epsv4, or epsv6 is executed again.
225 exit A synonym for bye.
227 features Display what features the remote server supports (using the
229 FEAT command).
230 fget localfile
232 Retrieve the files listed in localfile, which has one line
233 per filename.
234 form format
236 Set the file transfer form to format. The default (and only
237 supported) format is ‘non-print’.
238 ftp host [port]
240 A synonym for open.
241 gate [host [port]]
243 Toggle gate-ftp mode, which used to connect through the TIS
244 FWTK and Gauntlet FTP proxies. This will not be permitted if
245 the gate-ftp server hasn't been set (either explicitly by the
246 user, or from the FTPSERVER environment variable). If host
247 is given, then gate-ftp mode will be enabled, and the gate-
248 ftp server will be set to host. If port is also given, that
249 will be used as the port to connect to on the gate-ftp
250 server.
251 get remote-file [local-file]
253 Retrieve the remote-file and store it on the local machine.
254 If the local file name is not specified, it is given the same
255 name it has on the remote machine, subject to alteration by
256 the current case, ntrans, and nmap settings. The current
257 settings for type, form, mode, and structure are used while
258 transferring the file.
259 glob Toggle filename expansion for mdelete, mget, mput, and
261 mreget. If globbing is turned off with glob, the file name
262 arguments are taken literally and not expanded. Globbing for
263 mput is done as in csh(1). For mdelete, mget, and mreget,
264 each remote file name is expanded separately on the remote
265 machine and the lists are not merged. Expansion of a direc‐
266 tory name is likely to be different from expansion of the
267 name of an ordinary file: the exact result depends on the
268 foreign operating system and FTP server, and can be previewed
269 by doing ‘mls remote-files -’. Note: mget, mput and mreget
270 are not meant to transfer entire directory subtrees of files.
271 That can be done by transferring a tar(1) archive of the sub‐
272 tree (in binary mode).
273 hash [size]
275 Toggle hash-sign (‘#’) printing for each data block trans‐
276 ferred. The size of a data block defaults to 1024 bytes.
277 This can be changed by specifying size in bytes. Enabling
278 hash disables progress.
279 help [command]
281 Print an informative message about the meaning of command.
282 If no argument is given, tnftp prints a list of the known
283 commands.
284 idle [seconds]
286 Set the inactivity timer on the remote server to seconds sec‐
287 onds. If seconds is omitted, the current inactivity timer is
288 printed.
289 image A synonym for binary.
291 lcd [directory]
293 Change the working directory on the local machine. If no
294 directory is specified, the user's home directory is used.
295 less file A synonym for page.
297 lpage local-file
299 Display local-file with the program specified by the set
300 pager option.
301 lpwd Print the working directory on the local machine.
303 ls [remote-path [local-file]]
305 A synonym for dir.
306 macdef macro-name
308 Define a macro. Subsequent lines are stored as the macro
309 macro-name; a null line (consecutive newline characters in a
310 file or carriage returns from the terminal) terminates macro
311 input mode. There is a limit of 16 macros and 4096 total
312 characters in all defined macros. Macro names can be a maxi‐
313 mum of 8 characters. Macros are only applicable to the cur‐
314 rent session they are defined within (or if defined outside a
315 session, to the session invoked with the next open command),
316 and remain defined until a close command is executed. To in‐
317 voke a macro, use the $ command (see above).
318 The macro processor interprets ‘$’ and ‘\’ as special charac‐
320 ters. A ‘$’ followed by a number (or numbers) is replaced by
321 the corresponding argument on the macro invocation command
322 line. A ‘$’ followed by an ‘i’ signals the macro processor
323 that the executing macro is to be looped. On the first pass
324 ‘$i’ is replaced by the first argument on the macro invoca‐
325 tion command line, on the second pass it is replaced by the
326 second argument, and so on. A ‘\’ followed by any character
327 is replaced by that character. Use the ‘\’ to prevent spe‐
328 cial treatment of the ‘$’.
329 mdelete [remote-files]
331 Delete the remote-files on the remote machine.
332 mdir remote-files local-file
334 Like dir, except multiple remote files may be specified. If
335 interactive prompting is on, tnftp will prompt the user to
336 verify that the last argument is indeed the target local file
337 for receiving mdir output.
338 mget remote-files
340 Expand the remote-files on the remote machine and do a get
341 for each file name thus produced. See glob for details on
342 the filename expansion. Resulting file names will then be
343 processed according to case, ntrans, and nmap settings.
344 Files are transferred into the local working directory, which
345 can be changed with lcd directory; new local directories can
346 be created with ! mkdir directory.
347 mkdir directory-name
349 Make a directory on the remote machine.
350 mls remote-files local-file
352 Like ls, except multiple remote files may be specified, and
353 the local-file must be specified. If interactive prompting
354 is on, tnftp will prompt the user to verify that the last ar‐
355 gument is indeed the target local file for receiving mls out‐
356 put.
357 mlsd [remote-path]
359 Display the contents of remote-path (which should default to
360 the current directory if not given) in a machine-parsable
361 form, using MLSD. The format of display can be changed with
362 ‘remopts mlst ...’.
363 mlst [remote-path]
365 Display the details about remote-path (which should default
366 to the current directory if not given) in a machine-parsable
367 form, using MLST. The format of display can be changed with
368 ‘remopts mlst ...’.
369 mode mode-name
371 Set the file transfer mode to mode-name. The default (and
372 only supported) mode is ‘stream’.
373 modtime remote-file
375 Show the last modification time of the file on the remote ma‐
376 chine, in RFC 2822 format.
377 more file A synonym for page.
379 mput local-files
381 Expand wild cards in the list of local files given as argu‐
382 ments and do a put for each file in the resulting list. See
383 glob for details of filename expansion. Resulting file names
384 will then be processed according to ntrans and nmap settings.
385 mreget remote-files
387 As per mget, but performs a reget instead of get.
388 msend local-files
390 A synonym for mput.
391 newer remote-file [local-file]
393 Get the file only if the modification time of the remote file
394 is more recent that the file on the current system. If the
395 file does not exist on the current system, the remote file is
396 considered newer. Otherwise, this command is identical to
397 get.
398 nlist [remote-path [local-file]]
400 A synonym for ls.
401 nmap [inpattern outpattern]
403 Set or unset the filename mapping mechanism. If no arguments
404 are specified, the filename mapping mechanism is unset. If
405 arguments are specified, remote filenames are mapped during
406 mput commands and put commands issued without a specified re‐
407 mote target filename. If arguments are specified, local
408 filenames are mapped during mget commands and get commands
409 issued without a specified local target filename. This com‐
410 mand is useful when connecting to a non-UNIX remote computer
411 with different file naming conventions or practices. The
412 mapping follows the pattern set by inpattern and outpattern.
413 inpattern is a template for incoming filenames (which may
415 have already been processed according to the ntrans and case
416 settings). Variable templating is accomplished by including
417 the sequences ‘$1’, ‘$2’, ..., ‘$9’ in inpattern. Use ‘\’ to
418 prevent this special treatment of the ‘$’ character. All
419 other characters are treated literally, and are used to de‐
420 termine the nmap [inpattern] variable values. For example,
421 given inpattern ‘$1.$2’ and the remote file name
422 ‘mydata.data’, ‘$1’ would have the value ‘mydata’, and ‘$2’
423 would have the value ‘data’.
424 The outpattern determines the resulting mapped filename. The
426 sequences ‘$1’, ‘$2’, ..., ‘$9’ are replaced by any value re‐
427 sulting from the inpattern template. The sequence ‘$0’ is
428 replaced by the original filename. Additionally, the se‐
429 quence [seq1,seq2] is replaced by seq1 if seq1 is not a null
430 string; otherwise it is replaced by seq2. For example, the
431 command
432 nmap $1.$2.$3 [$1,$2].[$2,file]
434 would yield the output filename ‘myfile.data’ for input file‐
436 names ‘myfile.data’ and ‘myfile.data.old’, ‘myfile.file’ for
437 the input filename ‘myfile’, and ‘myfile.myfile’ for the in‐
438 put filename ‘.myfile’. Spaces may be included in
439 outpattern, as in the example:
440 nmap $1 sed s/ *$// > $1
442 Use the ‘\’ character to prevent special treatment of the
444 ‘$’, ‘[’, ‘]’, and ‘,’ characters.
445 ntrans [inchars [outchars]]
447 Set or unset the filename character translation mechanism.
448 If no arguments are specified, the filename character trans‐
449 lation mechanism is unset. If arguments are specified, char‐
450 acters in remote filenames are translated during mput com‐
451 mands and put commands issued without a specified remote tar‐
452 get filename. If arguments are specified, characters in lo‐
453 cal filenames are translated during mget commands and get
454 commands issued without a specified local target filename.
455 This command is useful when connecting to a non-UNIX remote
456 computer with different file naming conventions or practices.
457 Characters in a filename matching a character in inchars are
458 replaced with the corresponding character in outchars. If
459 the character's position in inchars is longer than the length
460 of outchars, the character is deleted from the file name.
461 open host [port]
463 Establish a connection to the specified host FTP server. An
464 optional port number may be supplied, in which case, tnftp
465 will attempt to contact an FTP server at that port. If the
466 set auto-login option is on (default), tnftp will also at‐
467 tempt to automatically log the user in to the FTP server (see
468 below).
469 page file Retrieve file and display with the program specified by the
471 set pager option.
472 passive [auto]
474 Toggle passive mode (if no arguments are given). If auto is
475 given, act as if FTPMODE is set to ‘auto’. If passive mode
476 is turned on (default), tnftp will send a PASV command for
477 all data connections instead of a PORT command. The PASV
478 command requests that the remote server open a port for the
479 data connection and return the address of that port. The re‐
480 mote server listens on that port and the client connects to
481 it. When using the more traditional PORT command, the client
482 listens on a port and sends that address to the remote
483 server, who connects back to it. Passive mode is useful when
484 using tnftp through a gateway router or host that controls
485 the directionality of traffic. (Note that though FTP servers
486 are required to support the PASV command by RFC 1123, some do
487 not.)
488 pdir [remote-path]
490 Perform dir [remote-path], and display the result with the
491 program specified by the set pager option.
492 pls [remote-path]
494 Perform ls [remote-path], and display the result with the
495 program specified by the set pager option.
496 pmlsd [remote-path]
498 Perform mlsd [remote-path], and display the result with the
499 program specified by the set pager option.
500 preserve Toggle preservation of modification times on retrieved files.
502 progress Toggle display of transfer progress bar. The progress bar
504 will be disabled for a transfer that has local-file as ‘-’ or
505 a command that starts with ‘|’. Refer to FILE NAMING
506 CONVENTIONS for more information. Enabling progress disables
507 hash.
508 prompt Toggle interactive prompting. Interactive prompting occurs
510 during multiple file transfers to allow the user to selec‐
511 tively retrieve or store files. If prompting is turned off
512 (default is on), any mget or mput will transfer all files,
513 and any mdelete will delete all files.
514 When prompting is on, the following commands are available at
516 a prompt:
517 a Answer ‘yes’ to the current file, and automatically
519 answer ‘yes’ to any remaining files for the current
520 command.
521 n Answer ‘no’, and do not transfer the file.
523 p Answer ‘yes’ to the current file, and turn off
525 prompt mode (as if prompt off had been given).
526 q Terminate the current operation.
528 y Answer ‘yes’, and transfer the file.
530 ? Display a help message.
532 Any other response will answer ‘yes’ to the current file.
534 proxy ftp-command
536 Execute an FTP command on a secondary control connection.
537 This command allows simultaneous connection to two remote FTP
538 servers for transferring files between the two servers. The
539 first proxy command should be an open, to establish the sec‐
540 ondary control connection. Enter the command ‘proxy ?’ to
541 see other FTP commands executable on the secondary connec‐
542 tion. The following commands behave differently when pref‐
543 aced by proxy: open will not define new macros during the
544 auto-login process, close will not erase existing macro defi‐
545 nitions, get and mget transfer files from the host on the
546 primary control connection to the host on the secondary con‐
547 trol connection, and put, mput, and append transfer files
548 from the host on the secondary control connection to the host
549 on the primary control connection. Third party file trans‐
550 fers depend upon support of the FTP protocol PASV command by
551 the server on the secondary control connection.
552 put local-file [remote-file]
554 Store a local file on the remote machine. If remote-file is
555 left unspecified, the local file name is used after process‐
556 ing according to any ntrans or nmap settings in naming the
557 remote file. File transfer uses the current settings for
558 type, format, mode, and structure.
559 pwd Print the name of the current working directory on the remote
561 machine.
562 quit A synonym for bye.
564 quote [arg ...]
566 The arguments specified are sent, verbatim, to the remote FTP
567 server.
568 rate direction [maximum [increment]]
570 Throttle the maximum transfer rate to maximum bytes/second.
571 If maximum is 0, disable the throttle.
572 direction may be one of:
574 all Both directions.
575 get Incoming transfers.
576 put Outgoing transfers.
577 maximum can be modified on the fly by increment bytes (de‐
579 fault: 1024) each time a given signal is received:
580 SIGUSR1 Increment maximum by increment bytes.
582 SIGUSR2 Decrement maximum by increment bytes. The re‐
584 sult must be a positive number.
585 If maximum is not supplied, the current throttle rates are
587 displayed.
588 Note: rate is not yet implemented for ascii mode transfers.
590 rcvbuf size
592 Set the size of the socket receive buffer to size.
593 recv remote-file [local-file]
595 A synonym for get.
596 reget remote-file [local-file]
598 reget acts like get, except that if local-file exists and is
599 smaller than remote-file, local-file is presumed to be a par‐
600 tially transferred copy of remote-file and the transfer is
601 continued from the apparent point of failure. This command
602 is useful when transferring very large files over networks
603 that are prone to dropping connections.
604 remopts command [command-options]
606 Set options on the remote FTP server for command to
607 command-options (whose absence is handled on a
608 command-specific basis). Remote FTP commands known to sup‐
609 port options include: MLST (used for MLSD and MLST).
610 rename [from [to]]
612 Rename the file from on the remote machine, to the file to.
613 reset Clear reply queue. This command re-synchronizes command/re‐
615 ply sequencing with the remote FTP server. Resynchronization
616 may be necessary following a violation of the FTP protocol by
617 the remote server.
618 restart marker
620 Restart the immediately following get or put at the indicated
621 marker. On UNIX systems, marker is usually a byte offset
622 into the file.
623 rhelp [command-name]
625 Request help from the remote FTP server. If a command-name
626 is specified it is supplied to the server as well.
627 rmdir directory-name
629 Delete a directory on the remote machine.
630 rstatus [remote-file]
632 With no arguments, show status of remote machine. If
633 remote-file is specified, show status of remote-file on re‐
634 mote machine.
635 runique Toggle storing of files on the local system with unique file‐
637 names. If a file already exists with a name equal to the
638 target local filename for a get or mget command, a ‘.1’ is
639 appended to the name. If the resulting name matches another
640 existing file, a ‘.2’ is appended to the original name. If
641 this process continues up to ‘.99’, an error message is
642 printed, and the transfer does not take place. The generated
643 unique filename will be reported. Note that runique will not
644 affect local files generated from a shell command (see be‐
645 low). The default value is off.
646 send local-file [remote-file]
648 A synonym for put.
649 sendport Toggle the use of PORT commands. By default, tnftp will at‐
651 tempt to use a PORT command when establishing a connection
652 for each data transfer. The use of PORT commands can prevent
653 delays when performing multiple file transfers. If the PORT
654 command fails, tnftp will use the default data port. When
655 the use of PORT commands is disabled, no attempt will be made
656 to use PORT commands for each data transfer. This is useful
657 for certain FTP implementations which do ignore PORT commands
658 but, incorrectly, indicate they've been accepted.
659 set [option value]
661 Set option to value. If option and value are not given, dis‐
662 play all of the options and their values. The currently sup‐
663 ported options are:
664 anonpass Defaults to $FTPANONPASS
666 ftp_proxy Defaults to $ftp_proxy.
668 http_proxy Defaults to $http_proxy.
670 https_proxy Defaults to $https_proxy.
672 no_proxy Defaults to $no_proxy.
674 pager Defaults to $PAGER.
676 prompt Defaults to $FTPPROMPT.
678 rprompt Defaults to $FTPRPROMPT.
680 sslnoverify Defaults to $FTPSSLNOVERIFY.
682 site [arg ...]
684 The arguments specified are sent, verbatim, to the remote FTP
685 server as a SITE command.
686 size remote-file
688 Return size of remote-file on remote machine.
689 sndbuf size
691 Set the size of the socket send buffer to size.
692 status Show the current status of tnftp.
694 struct struct-name
696 Set the file transfer structure to struct-name. The default
697 (and only supported) structure is ‘file’.
698 sunique Toggle storing of files on remote machine under unique file
700 names. The remote FTP server must support FTP protocol STOU
701 command for successful completion. The remote server will
702 report unique name. Default value is off.
703 system Show the type of operating system running on the remote ma‐
705 chine.
706 tenex Set the file transfer type to that needed to talk to TENEX
708 machines.
709 throttle A synonym for rate.
711 trace Toggle packet tracing.
713 type [type-name]
715 Set the file transfer type to type-name. If no type is spec‐
716 ified, the current type is printed. The default type is net‐
717 work ASCII.
718 umask [newmask]
720 Set the default umask on the remote server to newmask. If
721 newmask is omitted, the current umask is printed.
722 unset option
724 Unset option. Refer to set for more information.
725 usage command
727 Print the usage message for command.
728 user user-name [password [account]]
730 Identify yourself to the remote FTP server. If the password
731 is not specified and the server requires it, tnftp will
732 prompt the user for it (after disabling local echo). If an
733 account field is not specified, and the FTP server requires
734 it, the user will be prompted for it. If an account field is
735 specified, an account command will be relayed to the remote
736 server after the login sequence is completed if the remote
737 server did not require it for logging in. Unless tnftp is
738 invoked with “auto-login” disabled, this process is done au‐
739 tomatically on initial connection to the FTP server.
740 verbose Toggle verbose mode. In verbose mode, all responses from the
742 FTP server are displayed to the user. In addition, if ver‐
743 bose is on, when a file transfer completes, statistics re‐
744 garding the efficiency of the transfer are reported. By de‐
745 fault, verbose is on.
746 xferbuf size
748 Set the size of the socket send and receive buffers to size.
749 ? [command]
751 A synonym for help.
752 Command arguments which have embedded spaces may be quoted with quote ‘"’
754 marks.
755 Commands which toggle settings can take an explicit on or off argument to
757 force the setting appropriately.
758 Commands which take a byte count as an argument (e.g., hash, rate, and
760 xferbuf) support an optional suffix on the argument which changes the in‐
761 terpretation of the argument. Supported suffixes are:
762 b Causes no modification. (Optional)
763 k Kilo; multiply the argument by 1024
764 m Mega; multiply the argument by 1048576
765 g Giga; multiply the argument by 1073741824
766 If tnftp receives a SIGINFO (see the status argument of stty(1)) or
768 SIGQUIT signal whilst a transfer is in progress, the current transfer
769 rate statistics will be written to the standard error output, in the same
770 format as the standard completion message.
771
773 In addition to standard commands, this version of tnftp supports an auto-
774 fetch feature. To enable auto-fetch, simply pass the list of host‐
775 names/files on the command line.
776 The following formats are valid syntax for an auto-fetch element:
778 [user@]host:[path][/]
780 “Classic” FTP format.
781 If path contains a glob character and globbing is enabled, (see
783 glob), then the equivalent of mget path is performed.
784 If the directory component of path contains no globbing characters,
786 it is stored locally with the name basename (see basename(1)) of
787 path, in the current directory. Otherwise, the full remote name is
788 used as the local name, relative to the local root directory.
789 ftp://[user[:password]@]host[:port]/path[/][;type=type]
791 An FTP URL, retrieved using the FTP protocol if set ftp_proxy isn't
792 defined. Otherwise, transfer the URL using HTTP via the proxy de‐
793 fined in set ftp_proxy. If set ftp_proxy isn't defined and user is
794 given, login as user. In this case, use password if supplied, oth‐
795 erwise prompt the user for one.
796 If a suffix of ‘;type=A’ or ‘;type=I’ is supplied, then the trans‐
798 fer type will take place as ascii or binary (respectively). The
799 default transfer type is binary.
800 In order to be compliant with RFC 3986, tnftp interprets the path
802 part of an ‘ftp://’ auto-fetch URL as follows:
803 • The ‘/’ immediately after the host[:port] is interpreted as a
805 separator before the path, and not as part of the path itself.
806 • The path is interpreted as a ‘/’-separated list of name compo‐
808 nents. For all but the last such component, tnftp performs the
809 equivalent of a cd command. For the last path component, tnftp
810 performs the equivalent of a get command.
811 • Empty name components, which result from ‘//’ within the path,
813 or from an extra ‘/’ at the beginning of the path, will cause
814 the equivalent of a cd command without a directory name. This
815 is unlikely to be useful.
816 • Any ‘%XX’ codes (per RFC 3986) within the path components are
818 decoded, with XX representing a character code in hexadecimal.
819 This decoding takes place after the path has been split into
820 components, but before each component is used in the equivalent
821 of a cd or get command. Some often-used codes are ‘%2F’ (which
822 represents ‘/’) and ‘%7E’ (which represents ‘~’).
823 The above interpretation has the following consequences:
825 • The path is interpreted relative to the default login directory
827 of the specified user or of the ‘anonymous’ user. If the / di‐
828 rectory is required, use a leading path of ‘%2F’. If a user's
829 home directory is required (and the remote server supports the
830 syntax), use a leading path of ‘%7Euser/’. For example, to re‐
831 trieve /etc/motd from ‘localhost’ as the user ‘myname’ with the
832 password ‘mypass’, use
833 ‘ftp://myname:mypass@localhost/%2fetc/motd’
834 • The exact cd and get commands can be controlled by careful
836 choice of where to use ‘/’ and where to use ‘%2F’ (or ‘%2f’).
837 For example, the following URLs correspond to the equivalents
838 of the indicated commands:
839 ftp://host/dir1/dir2/file cd dir1, cd dir2, get file.
841 ftp://host/%2Fdir1/dir2/file cd /dir1, cd dir2, get file.
843 ftp://host/dir1%2Fdir2/file cd dir1/dir2, get file.
845 • You must have appropriate access permission for each of the in‐
847 termediate directories that is used in the equivalent of a cd
848 command.
849 http://[user[:password]@]host[:port]/path
851 An HTTP URL, retrieved using the HTTP protocol. If set http_proxy
852 is defined, it is used as a URL to an HTTP proxy server. If HTTP
853 authorization is required to retrieve path, and user (and option‐
854 ally password) is in the URL, use them for the first attempt to au‐
855 thenticate.
856 https://[user[:password]@]host[:port]/path
858 An HTTPS URL, retrieved using the HTTPS protocol. If set
859 https_proxy is defined, it is used as a URL to an HTTPS proxy
860 server. If HTTPS authorization is required to retrieve path, and
861 user (and optionally password) is in the URL, use them for the
862 first attempt to authenticate. There is currently no certificate
863 validation and verification.
864 file:///path
866 A local URL, copied from /path on the local host.
867 about:topic
869 Display information regarding topic; no file is retrieved for this
870 auto-fetched element. Supported values include:
871 about:ftp Information about tnftp.
873 about:version The version of tnftp. Useful to provide when re‐
875 porting problems.
876 Unless noted otherwise above, and -o output is not given, the file is
878 stored in the current directory as the basename(1) of path. Note that if
879 a HTTP redirect is received, the fetch is retried using the new target
880 URL supplied by the server, with a corresponding new path. Using an ex‐
881 plicit -o output is recommended, to avoid writing to unexpected file
882 names.
883 If a classic format or an FTP URL format has a trailing ‘/’ or an empty
885 path component, then tnftp will connect to the site and cd to the direc‐
886 tory given as the path, and leave the user in interactive mode ready for
887 further input. This will not work if set ftp_proxy is being used.
888 Direct HTTP transfers use HTTP 1.1. Proxied FTP and HTTP transfers use
890 HTTP 1.0.
891 If -R is given, all auto-fetches that don't go via the FTP or HTTP prox‐
893 ies will be restarted. For FTP, this is implemented by using reget in‐
894 stead of get. For HTTP, this is implemented by using the ‘Range: bytes=’
895 HTTP/1.1 directive.
896 If WWW or proxy WWW authentication is required, you will be prompted to
898 enter a username and password to authenticate with.
899 When specifying IPv6 numeric addresses in a URL, you need to surround the
901 address in square brackets. E.g.: ‘ftp://[::1]:21/’. This is because
902 colons are used in IPv6 numeric address as well as being the separator
903 for the port number.
904
906 To abort a file transfer, use the terminal interrupt key (usually Ctrl-
907 C). Sending transfers will be immediately halted. Receiving transfers
908 will be halted by sending an FTP protocol ABOR command to the remote
909 server, and discarding any further data received. The speed at which
910 this is accomplished depends upon the remote server's support for ABOR
911 processing. If the remote server does not support the ABOR command, the
912 prompt will not appear until the remote server has completed sending the
913 requested file.
914 If the terminal interrupt key sequence is used whilst tnftp is awaiting a
916 reply from the remote server for the ABOR processing, then the connection
917 will be closed. This is different from the traditional behaviour (which
918 ignores the terminal interrupt during this phase), but is considered more
919 useful.
920
922 Files specified as arguments to tnftp commands are processed according to
923 the following rules.
924 1. If the file name ‘-’ is specified, the stdin (for reading) or stdout
926 (for writing) is used.
927 2. If the first character of the file name is ‘|’, the remainder of the
929 argument is interpreted as a shell command. tnftp then forks a
930 shell, using popen(3) with the argument supplied, and reads (writes)
931 from the stdout (stdin). If the shell command includes spaces, the
932 argument must be quoted; e.g. ‘"| ls -lt"’. A particularly useful
933 example of this mechanism is: ‘dir "" |more’.
934 3. Failing the above checks, if globbing is enabled, local file names
936 are expanded according to the rules used in the csh(1); see the glob
937 command. If the tnftp command expects a single local file (e.g.
938 put), only the first filename generated by the globbing operation is
939 used.
940 4. For mget commands and get commands with unspecified local file
942 names, the local filename is the remote filename, which may be al‐
943 tered by a case, ntrans, or nmap setting. The resulting filename
944 may then be altered if runique is on.
945 5. For mput commands and put commands with unspecified remote file
947 names, the remote filename is the local filename, which may be al‐
948 tered by a ntrans or nmap setting. The resulting filename may then
949 be altered by the remote server if sunique is on.
950
952 The FTP specification specifies many parameters which may affect a file
953 transfer. The type may be one of “ascii”, “image” (binary), “ebcdic”,
954 and “local byte size” (for PDP-10's and PDP-20's mostly). tnftp supports
955 the ascii and image types of file transfer, plus local byte size 8 for
956 tenex mode transfers.
957 tnftp supports only the default values for the remaining file transfer
959 parameters: mode, form, and struct.
960
962 The .netrc file contains login and initialization information used by the
963 auto-login process. It resides in the user's home directory, unless
964 overridden with the -N netrc option, or specified in the NETRC environ‐
965 ment variable. The following tokens are recognized; they may be sepa‐
966 rated by spaces, tabs, or new-lines:
967 machine name
969 Identify a remote machine name. The auto-login process
970 searches the .netrc file for a machine token that matches the
971 remote machine specified on the tnftp command line or as an
972 open command argument. Once a match is made, the subsequent
973 .netrc tokens are processed, stopping when the end of file is
974 reached or another machine or a default token is encountered.
975 default This is the same as machine name except that default matches
977 any name. There can be only one default token, and it must be
978 after all machine tokens. This is normally used as:
979 default login anonymous password user@site
981 thereby giving the user an automatic anonymous FTP login to ma‐
983 chines not specified in .netrc. This can be overridden by us‐
984 ing the -n flag to disable auto-login.
985 login name
987 Identify a user on the remote machine. If this token is
988 present, the auto-login process will initiate a login using the
989 specified name.
990 password string
992 Supply a password. If this token is present, the auto-login
993 process will supply the specified string if the remote server
994 requires a password as part of the login process. Note that if
995 this token is present in the .netrc file for any user other
996 than anonymous, tnftp will abort the auto-login process if the
997 .netrc is readable by anyone besides the user.
998 account string
1000 Supply an additional account password. If this token is
1001 present, the auto-login process will supply the specified
1002 string if the remote server requires an additional account
1003 password, or the auto-login process will initiate an ACCT com‐
1004 mand if it does not.
1005 macdef name
1007 Define a macro. This token functions like the tnftp macdef
1008 command functions. A macro is defined with the specified name;
1009 its contents begin with the next .netrc line and continue until
1010 a blank line (consecutive new-line characters) is encountered.
1011 Like the other tokens in the .netrc file, a macdef is applica‐
1012 ble only to the machine definition preceding it. A macdef en‐
1013 try cannot be used by multiple machine definitions; rather, it
1014 must be defined following each machine it is intended to be
1015 used with. If a macro named init is defined, it is automati‐
1016 cally executed as the last step in the auto-login process. For
1017 example,
1018 default
1020 macdef init
1021 epsv4 off
1022 followed by a blank line.
1024
1026 tnftp supports interactive command line editing, via the editline(3) li‐
1027 brary. It is enabled with the edit command, and is enabled by default if
1028 input is from a tty. Previous lines can be recalled and edited with the
1029 arrow keys, and other GNU Emacs-style editing keys may be used as well.
1030 The editline(3) library is configured with a .editrc file — refer to
1032 editrc(5) for more information.
1033 An extra key binding is available to tnftp to provide context sensitive
1035 command and filename completion (including remote file completion). To
1036 use this, bind a key to the editline(3) command ftp-complete. By de‐
1037 fault, this is bound to the TAB key.
1038
1040 By default, tnftp displays a command line prompt of ‘ftp> ’ to the user.
1041 This can be changed with the set prompt command.
1042 A prompt can be displayed on the right side of the screen (after the com‐
1044 mand input) with the set rprompt command.
1045 The following formatting sequences are replaced by the given information:
1047 %/ The current remote working directory.
1049 %c[[0]n], %.[[0]n]
1051 The trailing component of the current remote working direc‐
1052 tory, or n trailing components if a digit n is given. If n
1053 begins with ‘0’, the number of skipped components precede the
1054 trailing component(s) in the format “/<number>trailing” (for
1055 ‘%c’) or “...trailing” (for ‘%.’).
1056 %M The remote host name.
1058 %m The remote host name, up to the first dot ‘.’.
1060 %n The remote user name.
1062 %% A single percent character ‘%’.
1064
1066 tnftp uses the following environment variables.
1067 FTPANONPASS Password to send in an anonymous FTP transfer. Defaults
1069 to “`whoami`@”.
1070 FTPMODE Overrides the default operation mode. Support values are:
1072 active active mode FTP only
1074 auto automatic determination of passive or active
1076 (this is the default)
1077 gate gate-ftp mode
1079 passive passive mode FTP only
1081 FTPPROMPT Command-line prompt to use. Defaults to ‘ftp> ’. Refer
1083 to COMMAND LINE PROMPT for more information.
1084 FTPRPROMPT Command-line right side prompt to use. Defaults to empty
1086 string. Refer to COMMAND LINE PROMPT for more informa‐
1087 tion.
1088 FTPSERVER Host to use as gate-ftp server when gate is enabled.
1090 FTPSERVERPORT Port to use when connecting to gate-ftp server when gate
1092 is enabled. Default is port returned by a
1093 getservbyname(3) lookup of “ftpgate/tcp”.
1094 FTPUSERAGENT The value to send for the HTTP User-Agent header.
1096 FTPSSLNOVERIFY
1098 Set to 1 to not verify SSL certificates.
1099 HOME For default location of a .netrc file, if one exists.
1101 NETRC An alternate location of the .netrc file.
1103 PAGER Used by various commands to display files. Defaults to
1105 more(1) if empty or not set.
1106 SHELL For default shell.
1108 ftp_proxy URL of FTP proxy to use when making FTP URL requests (if
1110 not defined, use the standard FTP protocol).
1111 See http_proxy for further notes about proxy use.
1113 http_proxy URL of HTTP proxy to use when making HTTP URL requests.
1115 If proxy authentication is required and there is a user‐
1116 name and password in this URL, they will automatically be
1117 used in the first attempt to authenticate to the proxy.
1118 If “unsafe” URL characters are required in the username or
1120 password (for example ‘@’ or ‘/’), encode them with RFC
1121 3986 ‘%XX’ encoding.
1122 Note that the use of a username and password in ftp_proxy
1124 and http_proxy may be incompatible with other programs
1125 that use it (such as lynx(1)).
1126 NOTE: this is not used for interactive sessions, only for
1128 command-line fetches.
1129 https_proxy URL of HTTPS proxy to use when making HTTPS URL requests.
1131 See http_proxy for further notes about proxy use.
1133 no_proxy A space or comma separated list of hosts (or domains) for
1135 which proxying is not to be used. Each entry may have an
1136 optional trailing ‘:port’, which restricts the matching to
1137 connections to that port.
1138
1140 Some firewall configurations do not allow tnftp to use extended passive
1141 mode. If you find that even a simple ls appears to hang after printing a
1142 message such as this:
1143 229 Entering Extended Passive Mode (|||58551|)
1145 then you will need to disable extended passive mode with epsv4 off. See
1147 the above section The .netrc File for an example of how to make this au‐
1148 tomatic.
1149
1151 getservbyname(3), editrc(5), services(5), ftpd(8)
1152
1154 tnftp attempts to be compliant with:
1155 RFC 959 File Transfer Protocol
1157 RFC 1123 Requirements for Internet Hosts - Application and Support
1159 RFC 1635 How to Use Anonymous FTP
1161 RFC 2389 Feature negotiation mechanism for the File Transfer
1163 Protocol
1164 RFC 2428 FTP Extensions for IPv6 and NATs
1166 RFC 2616 Hypertext Transfer Protocol -- HTTP/1.1
1168 RFC 2822 Internet Message Format
1170 RFC 3659 Extensions to FTP
1172 RFC 3986 Uniform Resource Identifier (URI)
1174
1176 The tnftp command appeared in 4.2BSD.
1177 Various features such as command line editing, context sensitive command
1179 and file completion, dynamic progress bar, automatic fetching of files
1180 and URLs, modification time preservation, transfer rate throttling, con‐
1181 figurable command line prompt, and other enhancements over the standard
1182 BSD tnftp were implemented in NetBSD 1.3 and later releases by Luke
1183 Mewburn ⟨lukem@NetBSD.org⟩.
1184 IPv6 support was added by the WIDE/KAME project (but may not be present
1186 in all non-NetBSD versions of this program, depending if the operating
1187 system supports IPv6 in a similar manner to KAME).
1188
1190 Correct execution of many commands depends upon proper behavior by the
1191 remote server.
1192 An error in the treatment of carriage returns in the 4.2BSD ascii-mode
1194 transfer code has been corrected. This correction may result in incor‐
1195 rect transfers of binary files to and from 4.2BSD servers using the ascii
1196 type. Avoid this problem by using the binary image type.
1197 tnftp assumes that all IPv4 mapped addresses (IPv6 addresses with a form
1199 like ::ffff:10.1.1.1) indicate IPv4 destinations which can be handled by
1200 AF_INET sockets. However, in certain IPv6 network configurations, this
1201 assumption is not true. In such an environment, IPv4 mapped addresses
1202 must be passed to AF_INET6 sockets directly. For example, if your site
1203 uses a SIIT translator for IPv6-to-IPv4 translation, tnftp is unable to
1204 support your configuration.
1205BSD February 25, 2023 BSD