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 iden‐
63 tity on the local machine), and, if necessary, prompt for a
64 password and an account with which to login. To override the
65 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
346 can 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
430 null string; otherwise it is replaced by seq2. For example,
431 the 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 is “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 command-spe‐
608 cific basis). Remote FTP commands known to support options
609 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 site [arg ...]
682 The arguments specified are sent, verbatim, to the remote FTP
683 server as a SITE command.
684 size remote-file
686 Return size of remote-file on remote machine.
687 sndbuf size
689 Set the size of the socket send buffer to size.
690 status Show the current status of tnftp.
692 struct struct-name
694 Set the file transfer structure to struct-name. The default
695 (and only supported) structure is “file”.
696 sunique Toggle storing of files on remote machine under unique file
698 names. The remote FTP server must support FTP protocol STOU
699 command for successful completion. The remote server will
700 report unique name. Default value is off.
701 system Show the type of operating system running on the remote ma‐
703 chine.
704 tenex Set the file transfer type to that needed to talk to TENEX
706 machines.
707 throttle A synonym for rate.
709 trace Toggle packet tracing.
711 type [type-name]
713 Set the file transfer type to type-name. If no type is spec‐
714 ified, the current type is printed. The default type is net‐
715 work ASCII.
716 umask [newmask]
718 Set the default umask on the remote server to newmask. If
719 newmask is omitted, the current umask is printed.
720 unset option
722 Unset option. Refer to set for more information.
723 usage command
725 Print the usage message for command.
726 user user-name [password [account]]
728 Identify yourself to the remote FTP server. If the password
729 is not specified and the server requires it, tnftp will
730 prompt the user for it (after disabling local echo). If an
731 account field is not specified, and the FTP server requires
732 it, the user will be prompted for it. If an account field is
733 specified, an account command will be relayed to the remote
734 server after the login sequence is completed if the remote
735 server did not require it for logging in. Unless tnftp is
736 invoked with “auto-login” disabled, this process is done au‐
737 tomatically on initial connection to the FTP server.
738 verbose Toggle verbose mode. In verbose mode, all responses from the
740 FTP server are displayed to the user. In addition, if ver‐
741 bose is on, when a file transfer completes, statistics re‐
742 garding the efficiency of the transfer are reported. By de‐
743 fault, verbose is on.
744 xferbuf size
746 Set the size of the socket send and receive buffers to size.
747 ? [command]
749 A synonym for help.
750 Command arguments which have embedded spaces may be quoted with quote ‘"’
752 marks.
753 Commands which toggle settings can take an explicit on or off argument to
755 force the setting appropriately.
756 Commands which take a byte count as an argument (e.g., hash, rate, and
758 xferbuf) support an optional suffix on the argument which changes the in‐
759 terpretation of the argument. Supported suffixes are:
760 b Causes no modification. (Optional)
761 k Kilo; multiply the argument by 1024
762 m Mega; multiply the argument by 1048576
763 g Giga; multiply the argument by 1073741824
764 If tnftp receives a SIGINFO (see the status argument of stty(1)) or
766 SIGQUIT signal whilst a transfer is in progress, the current transfer
767 rate statistics will be written to the standard error output, in the same
768 format as the standard completion message.
769
771 In addition to standard commands, this version of tnftp supports an auto-
772 fetch feature. To enable auto-fetch, simply pass the list of host‐
773 names/files on the command line.
774 The following formats are valid syntax for an auto-fetch element:
776 [user@]host:[path][/]
778 “Classic” FTP format.
779 If path contains a glob character and globbing is enabled, (see
781 glob), then the equivalent of ‘mget path’ is performed.
782 If the directory component of path contains no globbing characters,
784 it is stored locally with the name basename (see basename(1)) of
785 path, in the current directory. Otherwise, the full remote name is
786 used as the local name, relative to the local root directory.
787 ftp://[user[:password]@]host[:port]/path[/][;type=type]
789 An FTP URL, retrieved using the FTP protocol if set ftp_proxy isn't
790 defined. Otherwise, transfer the URL using HTTP via the proxy de‐
791 fined in set ftp_proxy. If set ftp_proxy isn't defined and user is
792 given, login as user. In this case, use password if supplied, oth‐
793 erwise prompt the user for one.
794 If a suffix of ‘;type=A’ or ‘;type=I’ is supplied, then the trans‐
796 fer type will take place as ascii or binary (respectively). The
797 default transfer type is binary.
798 In order to be compliant with RFC 3986, tnftp interprets the path
800 part of an ‘ftp://’ auto-fetch URL as follows:
801 • The ‘/’ immediately after the host[:port] is interpreted as a
803 separator before the path, and not as part of the path itself.
804 • The path is interpreted as a ‘/’-separated list of name compo‐
806 nents. For all but the last such component, tnftp performs the
807 equivalent of a cd command. For the last path component, tnftp
808 performs the equivalent of a get command.
809 • Empty name components, which result from ‘//’ within the path,
811 or from an extra ‘/’ at the beginning of the path, will cause
812 the equivalent of a cd command without a directory name. This
813 is unlikely to be useful.
814 • Any ‘%XX’ codes (per RFC 3986) within the path components are
816 decoded, with XX representing a character code in hexadecimal.
817 This decoding takes place after the path has been split into
818 components, but before each component is used in the equivalent
819 of a cd or get command. Some often-used codes are ‘%2F’ (which
820 represents ‘/’) and ‘%7E’ (which represents ‘~’).
821 The above interpretation has the following consequences:
823 • The path is interpreted relative to the default login directory
825 of the specified user or of the ‘anonymous’ user. If the / di‐
826 rectory is required, use a leading path of ‘%2F’. If a user's
827 home directory is required (and the remote server supports the
828 syntax), use a leading path of ‘%7Euser/’. For example, to re‐
829 trieve /etc/motd from ‘localhost’ as the user ‘myname’ with the
830 password ‘mypass’, use
831 ‘ftp://myname:mypass@localhost/%2fetc/motd’
832 • The exact cd and get commands can be controlled by careful
834 choice of where to use ‘/’ and where to use ‘%2F’ (or ‘%2f’).
835 For example, the following URLs correspond to the equivalents
836 of the indicated commands:
837 ftp://host/dir1/dir2/file “cd dir1”, “cd dir2”, “get
839 file”.
840 ftp://host/%2Fdir1/dir2/file “cd /dir1”, “cd dir2”, “get
842 file”.
843 ftp://host/dir1%2Fdir2/file “cd dir1/dir2”, “get file”.
845 ftp://host/%2Fdir1%2Fdir2/file “cd /dir1/dir2”, “get file”.
847 ftp://host/dir1%2Fdir2%2Ffile “get dir1/dir2/file”.
849 ftp://host/%2Fdir1%2Fdir2%2Ffile “get /dir1/dir2/file”.
851 • You must have appropriate access permission for each of the in‐
853 termediate directories that is used in the equivalent of a cd
854 command.
855 http://[user[:password]@]host[:port]/path
857 An HTTP URL, retrieved using the HTTP protocol. If set http_proxy
858 is defined, it is used as a URL to an HTTP proxy server. If HTTP
859 authorization is required to retrieve path, and user (and option‐
860 ally password) is in the URL, use them for the first attempt to au‐
861 thenticate.
862 https://[user[:password]@]host[:port]/path
864 An HTTPS URL, retrieved using the HTTPS protocol. If set
865 https_proxy is defined, it is used as a URL to an HTTPS proxy
866 server. If HTTPS authorization is required to retrieve path, and
867 user (and optionally password) is in the URL, use them for the
868 first attempt to authenticate. There is currently no certificate
869 validation and verification.
870 file:///path
872 A local URL, copied from /path on the local host.
873 about:topic
875 Display information regarding topic; no file is retrieved for this
876 auto-fetched element. Supported values include:
877 about:ftp Information about tnftp.
879 about:version The version of tnftp. Useful to provide when re‐
881 porting problems.
882 Unless noted otherwise above, and -o output is not given, the file is
884 stored in the current directory as the basename(1) of path. Note that if
885 a HTTP redirect is received, the fetch is retried using the new target
886 URL supplied by the server, with a corresponding new path. Using an ex‐
887 plicit -o output is recommended, to avoid writing to unexpected file
888 names.
889 If a classic format or an FTP URL format has a trailing ‘/’ or an empty
891 path component, then tnftp will connect to the site and cd to the direc‐
892 tory given as the path, and leave the user in interactive mode ready for
893 further input. This will not work if set ftp_proxy is being used.
894 Direct HTTP transfers use HTTP 1.1. Proxied FTP and HTTP transfers use
896 HTTP 1.0.
897 If -R is given, all auto-fetches that don't go via the FTP or HTTP prox‐
899 ies will be restarted. For FTP, this is implemented by using reget in‐
900 stead of get. For HTTP, this is implemented by using the ‘Range: bytes=’
901 HTTP/1.1 directive.
902 If WWW or proxy WWW authentication is required, you will be prompted to
904 enter a username and password to authenticate with.
905 When specifying IPv6 numeric addresses in a URL, you need to surround the
907 address in square brackets. E.g.: ‘ftp://[::1]:21/’. This is because
908 colons are used in IPv6 numeric address as well as being the separator
909 for the port number.
910
912 To abort a file transfer, use the terminal interrupt key (usually Ctrl-
913 C). Sending transfers will be immediately halted. Receiving transfers
914 will be halted by sending an FTP protocol ABOR command to the remote
915 server, and discarding any further data received. The speed at which
916 this is accomplished depends upon the remote server's support for ABOR
917 processing. If the remote server does not support the ABOR command, the
918 prompt will not appear until the remote server has completed sending the
919 requested file.
920 If the terminal interrupt key sequence is used whilst tnftp is awaiting a
922 reply from the remote server for the ABOR processing, then the connection
923 will be closed. This is different from the traditional behaviour (which
924 ignores the terminal interrupt during this phase), but is considered more
925 useful.
926
928 Files specified as arguments to tnftp commands are processed according to
929 the following rules.
930 1. If the file name ‘-’ is specified, the stdin (for reading) or stdout
932 (for writing) is used.
933 2. If the first character of the file name is ‘|’, the remainder of the
935 argument is interpreted as a shell command. tnftp then forks a
936 shell, using popen(3) with the argument supplied, and reads (writes)
937 from the stdout (stdin). If the shell command includes spaces, the
938 argument must be quoted; e.g. ‘"| ls -lt"’. A particularly useful
939 example of this mechanism is: ‘dir "" |more’.
940 3. Failing the above checks, if globbing is enabled, local file names
942 are expanded according to the rules used in the csh(1); see the glob
943 command. If the tnftp command expects a single local file (e.g.
944 put), only the first filename generated by the globbing operation is
945 used.
946 4. For mget commands and get commands with unspecified local file
948 names, the local filename is the remote filename, which may be al‐
949 tered by a case, ntrans, or nmap setting. The resulting filename
950 may then be altered if runique is on.
951 5. For mput commands and put commands with unspecified remote file
953 names, the remote filename is the local filename, which may be al‐
954 tered by a ntrans or nmap setting. The resulting filename may then
955 be altered by the remote server if sunique is on.
956
958 The FTP specification specifies many parameters which may affect a file
959 transfer. The type may be one of “ascii”, “image” (binary), “ebcdic”,
960 and “local byte size” (for PDP-10's and PDP-20's mostly). tnftp supports
961 the ascii and image types of file transfer, plus local byte size 8 for
962 tenex mode transfers.
963 tnftp supports only the default values for the remaining file transfer
965 parameters: mode, form, and struct.
966
968 The .netrc file contains login and initialization information used by the
969 auto-login process. It resides in the user's home directory, unless
970 overridden with the -N netrc option, or specified in the NETRC environ‐
971 ment variable. The following tokens are recognized; they may be sepa‐
972 rated by spaces, tabs, or new-lines:
973 machine name
975 Identify a remote machine name. The auto-login process
976 searches the .netrc file for a machine token that matches the
977 remote machine specified on the tnftp command line or as an
978 open command argument. Once a match is made, the subsequent
979 .netrc tokens are processed, stopping when the end of file is
980 reached or another machine or a default token is encountered.
981 default This is the same as machine name except that default matches
983 any name. There can be only one default token, and it must be
984 after all machine tokens. This is normally used as:
985 default login anonymous password user@site
987 thereby giving the user an automatic anonymous FTP login to ma‐
989 chines not specified in .netrc. This can be overridden by us‐
990 ing the -n flag to disable auto-login.
991 login name
993 Identify a user on the remote machine. If this token is
994 present, the auto-login process will initiate a login using the
995 specified name.
996 password string
998 Supply a password. If this token is present, the auto-login
999 process will supply the specified string if the remote server
1000 requires a password as part of the login process. Note that if
1001 this token is present in the .netrc file for any user other
1002 than anonymous, tnftp will abort the auto-login process if the
1003 .netrc is readable by anyone besides the user.
1004 account string
1006 Supply an additional account password. If this token is
1007 present, the auto-login process will supply the specified
1008 string if the remote server requires an additional account
1009 password, or the auto-login process will initiate an ACCT com‐
1010 mand if it does not.
1011 macdef name
1013 Define a macro. This token functions like the tnftp macdef
1014 command functions. A macro is defined with the specified name;
1015 its contents begin with the next .netrc line and continue until
1016 a blank line (consecutive new-line characters) is encountered.
1017 Like the other tokens in the .netrc file, a macdef is applica‐
1018 ble only to the machine definition preceding it. A macdef en‐
1019 try cannot be used by multiple machine definitions; rather, it
1020 must be defined following each machine it is intended to be
1021 used with. If a macro named init is defined, it is automati‐
1022 cally executed as the last step in the auto-login process. For
1023 example,
1024 default
1026 macdef init
1027 epsv4 off
1028 followed by a blank line.
1030
1032 tnftp supports interactive command line editing, via the editline(3) li‐
1033 brary. It is enabled with the edit command, and is enabled by default if
1034 input is from a tty. Previous lines can be recalled and edited with the
1035 arrow keys, and other GNU Emacs-style editing keys may be used as well.
1036 The editline(3) library is configured with a .editrc file — refer to
1038 editrc(5) for more information.
1039 An extra key binding is available to tnftp to provide context sensitive
1041 command and filename completion (including remote file completion). To
1042 use this, bind a key to the editline(3) command ftp-complete. By de‐
1043 fault, this is bound to the TAB key.
1044
1046 By default, tnftp displays a command line prompt of ‘ftp> ’ to the user.
1047 This can be changed with the set prompt command.
1048 A prompt can be displayed on the right side of the screen (after the com‐
1050 mand input) with the set rprompt command.
1051 The following formatting sequences are replaced by the given information:
1053 %/ The current remote working directory.
1055 %c[[0]n], %.[[0]n]
1057 The trailing component of the current remote working direc‐
1058 tory, or n trailing components if a digit n is given. If n
1059 begins with ‘0’, the number of skipped components precede the
1060 trailing component(s) in the format “/<number>trailing” (for
1061 ‘%c’) or “...trailing” (for ‘%.’).
1062 %M The remote host name.
1064 %m The remote host name, up to the first dot ‘.’.
1066 %n The remote user name.
1068 %% A single percent character ‘%’.
1070
1072 tnftp uses the following environment variables.
1073 FTPANONPASS Password to send in an anonymous FTP transfer. Defaults
1075 to “`whoami`@”.
1076 FTPMODE Overrides the default operation mode. Support values are:
1078 active active mode FTP only
1080 auto automatic determination of passive or active
1082 (this is the default)
1083 gate gate-ftp mode
1085 passive passive mode FTP only
1087 FTPPROMPT Command-line prompt to use. Defaults to ‘ftp> ’. Refer
1089 to COMMAND LINE PROMPT for more information.
1090 FTPRPROMPT Command-line right side prompt to use. Defaults to empty
1092 string. Refer to COMMAND LINE PROMPT for more informa‐
1093 tion.
1094 FTPSERVER Host to use as gate-ftp server when gate is enabled.
1096 FTPSERVERPORT Port to use when connecting to gate-ftp server when gate
1098 is enabled. Default is port returned by a
1099 getservbyname(3) lookup of “ftpgate/tcp”.
1100 FTPUSERAGENT The value to send for the HTTP User-Agent header.
1102 HOME For default location of a .netrc file, if one exists.
1104 NETRC An alternate location of the .netrc file.
1106 PAGER Used by various commands to display files. Defaults to
1108 more(1) if empty or not set.
1109 SHELL For default shell.
1111 ftp_proxy URL of FTP proxy to use when making FTP URL requests (if
1113 not defined, use the standard FTP protocol).
1114 See http_proxy for further notes about proxy use.
1116 http_proxy URL of HTTP proxy to use when making HTTP URL requests.
1118 If proxy authentication is required and there is a user‐
1119 name and password in this URL, they will automatically be
1120 used in the first attempt to authenticate to the proxy.
1121 If “unsafe” URL characters are required in the username or
1123 password (for example ‘@’ or ‘/’), encode them with RFC
1124 3986 ‘%XX’ encoding.
1125 Note that the use of a username and password in ftp_proxy
1127 and http_proxy may be incompatible with other programs
1128 that use it (such as lynx(1)).
1129 NOTE: this is not used for interactive sessions, only for
1131 command-line fetches.
1132 https_proxy URL of HTTPS proxy to use when making HTTPS URL requests.
1134 See http_proxy for further notes about proxy use.
1136 no_proxy A space or comma separated list of hosts (or domains) for
1138 which proxying is not to be used. Each entry may have an
1139 optional trailing ‘:port’, which restricts the matching to
1140 connections to that port.
1141
1143 Some firewall configurations do not allow tnftp to use extended passive
1144 mode. If you find that even a simple ls appears to hang after printing a
1145 message such as this:
1146 229 Entering Extended Passive Mode (|||58551|)
1148 then you will need to disable extended passive mode with epsv4 off. See
1150 the above section The .netrc File for an example of how to make this au‐
1151 tomatic.
1152
1154 getservbyname(3), editrc(5), services(5), ftpd(8)
1155
1157 tnftp attempts to be compliant with:
1158 RFC 959 File Transfer Protocol
1160 RFC 1123 Requirements for Internet Hosts - Application and Support
1162 RFC 1635 How to Use Anonymous FTP
1164 RFC 2389 Feature negotiation mechanism for the File Transfer
1166 Protocol
1167 RFC 2428 FTP Extensions for IPv6 and NATs
1169 RFC 2616 Hypertext Transfer Protocol -- HTTP/1.1
1171 RFC 2822 Internet Message Format
1173 RFC 3659 Extensions to FTP
1175 RFC 3986 Uniform Resource Identifier (URI)
1177
1179 The tnftp command appeared in 4.2BSD.
1180 Various features such as command line editing, context sensitive command
1182 and file completion, dynamic progress bar, automatic fetching of files
1183 and URLs, modification time preservation, transfer rate throttling, con‐
1184 figurable command line prompt, and other enhancements over the standard
1185 BSD tnftp were implemented in NetBSD 1.3 and later releases by Luke
1186 Mewburn ⟨lukem@NetBSD.org⟩.
1187 IPv6 support was added by the WIDE/KAME project (but may not be present
1189 in all non-NetBSD versions of this program, depending if the operating
1190 system supports IPv6 in a similar manner to KAME).
1191
1193 Correct execution of many commands depends upon proper behavior by the
1194 remote server.
1195 An error in the treatment of carriage returns in the 4.2BSD ascii-mode
1197 transfer code has been corrected. This correction may result in incor‐
1198 rect transfers of binary files to and from 4.2BSD servers using the ascii
1199 type. Avoid this problem by using the binary image type.
1200 tnftp assumes that all IPv4 mapped addresses (IPv6 addresses with a form
1202 like ::ffff:10.1.1.1) indicate IPv4 destinations which can be handled by
1203 AF_INET sockets. However, in certain IPv6 network configurations, this
1204 assumption is not true. In such an environment, IPv4 mapped addresses
1205 must be passed to AF_INET6 sockets directly. For example, if your site
1206 uses a SIIT translator for IPv6-to-IPv4 translation, tnftp is unable to
1207 support your configuration.
1208BSD April 25, 2021 BSD