1FTP(1) BSD General Commands Manual FTP(1)
2
4 ftp — Internet file transfer program
5
7 ftp [-46AadefginpRtVv] [-N netrc] [-o output] [-P port] [-q quittime]
8 [-r retry] [-s srcaddr] [-T dir,max[,inc]] [-x xferbufsize]
9 [[user@]host [port]] [[user@]host:[path][/]] [file:///path]
10 [ftp://[user[:password]@]host[:port]/path[/][;type=X]]
11 [http://[user[:password]@]host[:port]/path] [...]
12 ftp -u URL file [...]
13
15 ftp is the user interface to the Internet standard File Transfer Proto‐
16 col. The program allows a user to transfer files to and from a remote
17 network site.
18 The last five arguments will fetch a file using the FTP or HTTP proto‐
20 cols, or by direct copying, into the current directory. This is ideal
21 for scripts. Refer to AUTO-FETCHING FILES below for more information.
22 Options may be specified at the command line, or to the command inter‐
24 preter.
25 -4 Forces ftp to only use IPv4 addresses.
27 -6 Forces ftp to only use IPv6 addresses.
29 -A Force active mode ftp. By default, ftp will try to use pas‐
31 sive mode ftp and fall back to active mode if passive is not
32 supported by the server. This option causes ftp to always
33 use an active connection. It is only useful for connecting
34 to very old servers that do not implement passive mode prop‐
35 erly.
36 -a Causes ftp to bypass normal login procedure, and use an
38 anonymous login instead.
39 -d Enables debugging.
41 -e Disables command line editing. This is useful for Emacs
43 ange-ftp mode.
44 -f Forces a cache reload for transfers that go through the FTP
46 or HTTP proxies.
47 -g Disables file name globbing.
49 -i Turns off interactive prompting during multiple file trans‐
51 fers.
52 -N netrc Use netrc instead of ~/.netrc. Refer to THE .netrc FILE for
54 more information.
55 -n Restrains ftp from attempting “auto-login” upon initial con‐
57 nection for non auto-fetch transfers. If auto-login is
58 enabled, ftp will check the .netrc (see below) file in the
59 user's home directory for an entry describing an account on
60 the remote machine. If no entry exists, ftp will prompt for
61 the remote machine login name (default is the user identity
62 on the local machine), and, if necessary, prompt for a pass‐
63 word and an account with which to login. To override the
64 auto-login for auto-fetch transfers, specify the username
65 (and optionally, password) as appropriate.
66 -o output When auto-fetching files, save the contents in output.
68 output is parsed according to the FILE NAMING CONVENTIONS
69 below. If output is not ‘-’ or doesn't start with ‘|’, then
70 only the first file specified will be retrieved into output;
71 all other files will be retrieved into the basename of their
72 remote name.
73 -P port Sets the port number to port.
75 -p Enable passive mode operation for use behind connection fil‐
77 tering firewalls. This option has been deprecated as ftp now
78 tries to use passive mode by default, falling back to active
79 mode if the server does not support passive connections.
80 -q quittime
82 Quit if the connection has stalled for quittime seconds.
83 -R Restart all non-proxied auto-fetches.
85 -r wait Retry the connection attempt if it failed, pausing for wait
87 seconds.
88 -s srcaddr Uses srcaddr as the local IP address for all connections.
90 -t Enables packet tracing.
92 -T direction,maximum[,increment]
94 Set the maximum transfer rate for direction to maximum
95 bytes/second, and if specified, the increment to increment
96 bytes/second. Refer to rate for more information.
97 -u URL file [...]
99 Upload files on the command line to URL where URL is one of
100 the ftp URL types as supported by auto-fetch (with an
101 optional target filename for single file uploads), and file
102 is one or more local files to be uploaded.
103 -V Disable verbose and progress, overriding the default of
105 enabled when output is to a terminal.
106 -v Enable verbose and progress. This is the default if output
108 is to a terminal (and in the case of progress, ftp is the
109 foreground process). Forces ftp to show all responses from
110 the remote server, as well as report on data transfer statis‐
111 tics.
112 -x xferbufsize
114 Set the size of the socket send and receive buffers to
115 xferbufsize. Refer to xferbuf for more information.
116 The client host with which ftp is to communicate may be specified on the
118 command line. If this is done, ftp will immediately attempt to establish
119 a connection to an FTP server on that host; otherwise, ftp will enter its
120 command interpreter and await instructions from the user. When ftp is
121 awaiting commands from the user the prompt ‘ftp>’ is provided to the
122 user. The following commands are recognized by ftp:
123 ! [command [args]]
125 Invoke an interactive shell on the local machine. If there
126 are arguments, the first is taken to be a command to execute
127 directly, with the rest of the arguments as its arguments.
128 $ macro-name [args]
130 Execute the macro macro-name that was defined with the macdef
131 command. Arguments are passed to the macro unglobbed.
132 account [passwd]
134 Supply a supplemental password required by a remote system
135 for access to resources once a login has been successfully
136 completed. If no argument is included, the user will be
137 prompted for an account password in a non-echoing input mode.
138 append local-file [remote-file]
140 Append a local file to a file on the remote machine. If
141 remote-file is left unspecified, the local file name is used
142 in naming the remote file after being altered by any ntrans
143 or nmap setting. File transfer uses the current settings for
144 type, format, mode, and structure.
145 ascii Set the file transfer type to network ASCII. This is the
147 default type.
148 bell Arrange that a bell be sounded after each file transfer com‐
150 mand is completed.
151 binary Set the file transfer type to support binary image transfer.
153 bye Terminate the FTP session with the remote server and exit
155 ftp. An end of file will also terminate the session and
156 exit.
157 case Toggle remote computer file name case mapping during get,
159 mget and mput commands. When case is on (default is off),
160 remote computer file names with all letters in upper case are
161 written in the local directory with the letters mapped to
162 lower case.
163 cd remote-directory
165 Change the working directory on the remote machine to
166 remote-directory.
167 cdup Change the remote machine working directory to the parent of
169 the current remote machine working directory.
170 chmod mode remote-file
172 Change the permission modes of the file remote-file on the
173 remote system to mode.
174 close Terminate the FTP session with the remote server, and return
176 to the command interpreter. Any defined macros are erased.
177 cr Toggle carriage return stripping during ascii type file
179 retrieval. Records are denoted by a carriage return/linefeed
180 sequence during ascii type file transfer. When cr is on (the
181 default), carriage returns are stripped from this sequence to
182 conform with the UNIX single linefeed record delimiter.
183 Records on non-UNIX remote systems may contain single line‐
184 feeds; when an ascii type transfer is made, these linefeeds
185 may be distinguished from a record delimiter only when cr is
186 off.
187 delete remote-file
189 Delete the file remote-file on the remote machine.
190 dir [remote-path [local-file]]
192 Print a listing of the contents of a directory on the remote
193 machine. The listing includes any system-dependent informa‐
194 tion that the server chooses to include; for example, most
195 UNIX systems will produce output from the command ‘ls -l’.
196 If remote-path is left unspecified, the current working
197 directory is used. If interactive prompting is on, ftp will
198 prompt the user to verify that the last argument is indeed
199 the target local file for receiving dir output. If no local
200 file is specified, or if local-file is ‘-’, the output is
201 sent to the terminal.
202 disconnect A synonym for close.
204 edit Toggle command line editing, and context sensitive command
206 and file completion. This is automatically enabled if input
207 is from a terminal, and disabled otherwise.
208 epsv epsv4 epsv6
210 Toggle the use of the extended EPSV and EPRT commands on all
211 IP, IPv4, and IPv6 connections respectively. First try EPSV
212 / EPRT, and then PASV / PORT. This is enabled by default.
213 If an extended command fails then this option will be tempo‐
214 rarily disabled for the duration of the current connection,
215 or until epsv, epsv4, or epsv6 is executed again.
216 exit A synonym for bye.
218 features Display what features the remote server supports (using the
220 FEAT command).
221 fget localfile
223 Retrieve the files listed in localfile, which has one line
224 per filename.
225 form format
227 Set the file transfer form to format. The default (and only
228 supported) format is “non-print”.
229 ftp host [port]
231 A synonym for open.
232 ftp_debug [ftp_debug-value]
234 Toggle debugging mode. If an optional ftp_debug-value is
235 specified it is used to set the debugging level. When debug‐
236 ging is on, ftp prints each command sent to the remote
237 machine, preceded by the string ‘-->’.
238 gate [host [port]]
240 Toggle gate-ftp mode, which used to connect through the TIS
241 FWTK and Gauntlet ftp proxies. This will not be permitted if
242 the gate-ftp server hasn't been set (either explicitly by the
243 user, or from the FTPSERVER environment variable). If host
244 is given, then gate-ftp mode will be enabled, and the gate-
245 ftp server will be set to host. If port is also given, that
246 will be used as the port to connect to on the gate-ftp
247 server.
248 get remote-file [local-file]
250 Retrieve the remote-file and store it on the local machine.
251 If the local file name is not specified, it is given the same
252 name it has on the remote machine, subject to alteration by
253 the current case, ntrans, and nmap settings. The current
254 settings for type, form, mode, and structure are used while
255 transferring the file.
256 glob Toggle filename expansion for mdelete, mget, mput, and
258 mreget. If globbing is turned off with glob, the file name
259 arguments are taken literally and not expanded. Globbing for
260 mput is done as in csh(1). For mdelete, mget, and mreget,
261 each remote file name is expanded separately on the remote
262 machine and the lists are not merged. Expansion of a direc‐
263 tory name is likely to be different from expansion of the
264 name of an ordinary file: the exact result depends on the
265 foreign operating system and ftp server, and can be previewed
266 by doing ‘mls remote-files -’ Note: mget, mput and mreget are
267 not meant to transfer entire directory subtrees of files.
268 That can be done by transferring a tar(1) archive of the sub‐
269 tree (in binary mode).
270 hash [size]
272 Toggle hash-sign (‘#’) printing for each data block trans‐
273 ferred. The size of a data block defaults to 1024 bytes.
274 This can be changed by specifying size in bytes. Enabling
275 hash disables progress.
276 help [command]
278 Print an informative message about the meaning of command.
279 If no argument is given, ftp prints a list of the known com‐
280 mands.
281 idle [seconds]
283 Set the inactivity timer on the remote server to seconds sec‐
284 onds. If seconds is omitted, the current inactivity timer is
285 printed.
286 image A synonym for binary.
288 lcd [directory]
290 Change the working directory on the local machine. If no
291 directory is specified, the user's home directory is used.
292 less file A synonym for page.
294 lpage local-file
296 Display local-file with the program specified by the set
297 pager option.
298 lpwd Print the working directory on the local machine.
300 ls [remote-path [local-file]]
302 A synonym for dir.
303 macdef macro-name
305 Define a macro. Subsequent lines are stored as the macro
306 macro-name; a null line (consecutive newline characters in a
307 file or carriage returns from the terminal) terminates macro
308 input mode. There is a limit of 16 macros and 4096 total
309 characters in all defined macros. Macro names can be a maxi‐
310 mum of 8 characters. Macros are only applicable to the cur‐
311 rent session they are defined within (or if defined outside a
312 session, to the session invoked with the next open command),
313 and remain defined until a close command is executed. To
314 invoke a macro, use the $ command (see above).
315 The macro processor interprets ‘$’ and ‘\’ as special charac‐
317 ters. A ‘$’ followed by a number (or numbers) is replaced by
318 the corresponding argument on the macro invocation command
319 line. A ‘$’ followed by an ‘i’ signals the macro processor
320 that the executing macro is to be looped. On the first pass
321 “$i” is replaced by the first argument on the macro invoca‐
322 tion command line, on the second pass it is replaced by the
323 second argument, and so on. A ‘\’ followed by any character
324 is replaced by that character. Use the ‘\’ to prevent spe‐
325 cial treatment of the ‘$’.
326 mdelete [remote-files]
328 Delete the remote-files on the remote machine.
329 mdir remote-files local-file
331 Like dir, except multiple remote files may be specified. If
332 interactive prompting is on, ftp will prompt the user to ver‐
333 ify that the last argument is indeed the target local file
334 for receiving mdir output.
335 mget remote-files
337 Expand the remote-files on the remote machine and do a get
338 for each file name thus produced. See glob for details on
339 the filename expansion. Resulting file names will then be
340 processed according to case, ntrans, and nmap settings.
341 Files are transferred into the local working directory, which
342 can be changed with ‘lcd directory’; new local directories
343 can be created with ‘! mkdir directory’.
344 mkdir directory-name
346 Make a directory on the remote machine.
347 mls remote-files local-file
349 Like ls, except multiple remote files may be specified, and
350 the local-file must be specified. If interactive prompting
351 is on, ftp will prompt the user to verify that the last argu‐
352 ment is indeed the target local file for receiving mls out‐
353 put.
354 mlsd [remote-path]
356 Display the contents of remote-path (which should default to
357 the current directory if not given) in a machine-parsable
358 form, using MLSD. The format of display can be changed with
359 ‘remopts mlst ...’.
360 mlst [remote-path]
362 Display the details about remote-path (which should default
363 to the current directory if not given) in a machine-parsable
364 form, using MLST. The format of display can be changed with
365 ‘remopts mlst ...’.
366 mode mode-name
368 Set the file transfer mode to mode-name. The default (and
369 only supported) mode is “stream”.
370 modtime remote-file
372 Show the last modification time of the file on the remote
373 machine, in RFC 2822 format.
374 more file A synonym for page.
376 mput local-files
378 Expand wild cards in the list of local files given as argu‐
379 ments and do a put for each file in the resulting list. See
380 glob for details of filename expansion. Resulting file names
381 will then be processed according to ntrans and nmap settings.
382 mreget remote-files
384 As per mget, but performs a reget instead of get.
385 msend local-files
387 A synonym for mput.
388 newer remote-file [local-file]
390 Get the file only if the modification time of the remote file
391 is more recent that the file on the current system. If the
392 file does not exist on the current system, the remote file is
393 considered newer. Otherwise, this command is identical to
394 get.
395 nlist [remote-path [local-file]]
397 A synonym for ls.
398 nmap [inpattern outpattern]
400 Set or unset the filename mapping mechanism. If no arguments
401 are specified, the filename mapping mechanism is unset. If
402 arguments are specified, remote filenames are mapped during
403 mput commands and put commands issued without a specified
404 remote target filename. If arguments are specified, local
405 filenames are mapped during mget commands and get commands
406 issued without a specified local target filename. This com‐
407 mand is useful when connecting to a non-UNIX remote computer
408 with different file naming conventions or practices. The
409 mapping follows the pattern set by inpattern and outpattern.
410 [Inpattern] is a template for incoming filenames (which may
411 have already been processed according to the ntrans and case
412 settings). Variable templating is accomplished by including
413 the sequences “$1”, “$2”, ... “$9” in inpattern. Use ‘\’ to
414 prevent this special treatment of the ‘$’ character. All
415 other characters are treated literally, and are used to
416 determine the nmap [inpattern] variable values. For example,
417 given inpattern $1.$2 and the remote file name "mydata.data",
418 $1 would have the value "mydata", and $2 would have the value
419 "data". The outpattern determines the resulting mapped file‐
420 name. The sequences “$1”, “$2”, ... “$9” are replaced by
421 any value resulting from the inpattern template. The
422 sequence “$0” is replaced by the original filename. Addi‐
423 tionally, the sequence “[seq1, seq2]” is replaced by [seq1]
424 if seq1 is not a null string; otherwise it is replaced by
425 seq2. For example, the command
426 nmap $1.$2.$3 [$1,$2].[$2,file]
428 would yield the output filename "myfile.data" for input file‐
430 names "myfile.data" and "myfile.data.old", "myfile.file" for
431 the input filename "myfile", and "myfile.myfile" for the
432 input filename ".myfile". Spaces may be included in
433 outpattern, as in the example:
434 nmap $1 sed s/ *$// > $1
435 Use the ‘\’ character to prevent special treatment of the
436 ‘$’, ‘[’, ‘]’, and ‘,’ characters.
437 ntrans [inchars [outchars]]
439 Set or unset the filename character translation mechanism.
440 If no arguments are specified, the filename character trans‐
441 lation mechanism is unset. If arguments are specified, char‐
442 acters in remote filenames are translated during mput com‐
443 mands and put commands issued without a specified remote tar‐
444 get filename. If arguments are specified, characters in
445 local filenames are translated during mget commands and get
446 commands issued without a specified local target filename.
447 This command is useful when connecting to a non-UNIX remote
448 computer with different file naming conventions or practices.
449 Characters in a filename matching a character in inchars are
450 replaced with the corresponding character in outchars. If
451 the character's position in inchars is longer than the length
452 of outchars, the character is deleted from the file name.
453 open host [port]
455 Establish a connection to the specified host FTP server. An
456 optional port number may be supplied, in which case, ftp will
457 attempt to contact an FTP server at that port. If the set
458 auto-login option is on (default), ftp will also attempt to
459 automatically log the user in to the FTP server (see below).
460 page file Retrieve file and display with the program specified by the
462 set pager option.
463 passive [auto]
465 Toggle passive mode (if no arguments are given). If auto is
466 given, act as if FTPMODE is set to ‘auto’. If passive mode
467 is turned on (default), ftp will send a PASV command for all
468 data connections instead of a PORT command. The PASV command
469 requests that the remote server open a port for the data con‐
470 nection and return the address of that port. The remote
471 server listens on that port and the client connects to it.
472 When using the more traditional PORT command, the client lis‐
473 tens on a port and sends that address to the remote server,
474 who connects back to it. Passive mode is useful when using
475 ftp through a gateway router or host that controls the direc‐
476 tionality of traffic. (Note that though FTP servers are
477 required to support the PASV command by RFC 1123, some do
478 not.)
479 pdir [remote-path]
481 Perform dir [remote-path], and display the result with the
482 program specified by the set pager option.
483 pls [remote-path]
485 Perform ls [remote-path], and display the result with the
486 program specified by the set pager option.
487 pmlsd [remote-path]
489 Perform mlsd [remote-path], and display the result with the
490 program specified by the set pager option.
491 preserve Toggle preservation of modification times on retrieved files.
493 progress Toggle display of transfer progress bar. The progress bar
495 will be disabled for a transfer that has local-file as ‘-’ or
496 a command that starts with ‘|’. Refer to FILE NAMING
497 CONVENTIONS for more information. Enabling progress disables
498 hash.
499 prompt Toggle interactive prompting. Interactive prompting occurs
501 during multiple file transfers to allow the user to selec‐
502 tively retrieve or store files. If prompting is turned off
503 (default is on), any mget or mput will transfer all files,
504 and any mdelete will delete all files.
505 When prompting is on, the following commands are available at
507 a prompt:
508 a Answer ‘yes’ to the current file, and automatically
510 answer ‘yes’ to any remaining files for the current
511 command.
512 n Answer ‘no’, and do not transfer the file.
514 p Answer ‘yes’ to the current file, and turn off
516 prompt mode (as is “prompt off” had been given).
517 q Terminate the current operation.
519 y Answer ‘yes’, and transfer the file.
521 ? Display a help message.
523 Any other response will answer ‘yes’ to the current file.
525 proxy ftp-command
527 Execute an ftp command on a secondary control connection.
528 This command allows simultaneous connection to two remote FTP
529 servers for transferring files between the two servers. The
530 first proxy command should be an open, to establish the sec‐
531 ondary control connection. Enter the command "proxy ?" to
532 see other FTP commands executable on the secondary connec‐
533 tion. The following commands behave differently when pref‐
534 aced by proxy: open will not define new macros during the
535 auto-login process, close will not erase existing macro defi‐
536 nitions, get and mget transfer files from the host on the
537 primary control connection to the host on the secondary con‐
538 trol connection, and put, mput, and append transfer files
539 from the host on the secondary control connection to the host
540 on the primary control connection. Third party file trans‐
541 fers depend upon support of the FTP protocol PASV command by
542 the server on the secondary control connection.
543 put local-file [remote-file]
545 Store a local file on the remote machine. If remote-file is
546 left unspecified, the local file name is used after process‐
547 ing according to any ntrans or nmap settings in naming the
548 remote file. File transfer uses the current settings for
549 type, format, mode, and structure.
550 pwd Print the name of the current working directory on the remote
552 machine.
553 quit A synonym for bye.
555 quote arg1 arg2 ...
557 The arguments specified are sent, verbatim, to the remote FTP
558 server.
559 rate direction [maximum [increment]]
561 Throttle the maximum transfer rate to maximum bytes/second.
562 If maximum is 0, disable the throttle.
563 direction may be one of:
565 all Both directions.
566 get Incoming transfers.
567 put Outgoing transfers.
568 maximum can be modified on the fly by increment bytes
570 (default: 1024) each time a given signal is received:
571 SIGUSR1 Increment maximum by increment bytes.
573 SIGUSR2 Decrement maximum by increment bytes. The
575 result must be a positive number.
576 If maximum is not supplied, the current throttle rates are
578 displayed.
579 Note: rate is not yet implemented for ascii mode transfers.
581 rcvbuf size
583 Set the size of the socket receive buffer to size.
584 recv remote-file [local-file]
586 A synonym for get.
587 reget remote-file [local-file]
589 reget acts like get, except that if local-file exists and is
590 smaller than remote-file, local-file is presumed to be a par‐
591 tially transferred copy of remote-file and the transfer is
592 continued from the apparent point of failure. This command
593 is useful when transferring very large files over networks
594 that are prone to dropping connections.
595 remopts command [command-options]
597 Set options on the remote FTP server for command to
598 command-options (whose absence is handled on a command-spe‐
599 cific basis). Remote FTP commands known to support options
600 include: ‘MLST’ (used for MLSD and MLST).
601 rename [from [to]]
603 Rename the file from on the remote machine, to the file to.
604 reset Clear reply queue. This command re-synchronizes com‐
606 mand/reply sequencing with the remote FTP server. Resynchro‐
607 nization may be necessary following a violation of the FTP
608 protocol by the remote server.
609 restart marker
611 Restart the immediately following get or put at the indicated
612 marker. On UNIX systems, marker is usually a byte offset
613 into the file.
614 rhelp [command-name]
616 Request help from the remote FTP server. If a command-name
617 is specified it is supplied to the server as well.
618 rmdir directory-name
620 Delete a directory on the remote machine.
621 rstatus [remote-file]
623 With no arguments, show status of remote machine. If
624 remote-file is specified, show status of remote-file on
625 remote machine.
626 runique Toggle storing of files on the local system with unique file‐
628 names. If a file already exists with a name equal to the
629 target local filename for a get or mget command, a ".1" is
630 appended to the name. If the resulting name matches another
631 existing file, a ".2" is appended to the original name. If
632 this process continues up to ".99", an error message is
633 printed, and the transfer does not take place. The generated
634 unique filename will be reported. Note that runique will not
635 affect local files generated from a shell command (see
636 below). The default value is off.
637 send local-file [remote-file]
639 A synonym for put.
640 sendport Toggle the use of PORT commands. By default, ftp will
642 attempt to use a PORT command when establishing a connection
643 for each data transfer. The use of PORT commands can prevent
644 delays when performing multiple file transfers. If the PORT
645 command fails, ftp will use the default data port. When the
646 use of PORT commands is disabled, no attempt will be made to
647 use PORT commands for each data transfer. This is useful for
648 certain FTP implementations which do ignore PORT commands
649 but, incorrectly, indicate they've been accepted.
650 set [option value]
652 Set option to value. If option and value are not given, dis‐
653 play all of the options and their values. The currently sup‐
654 ported options are:
655 anonpass Defaults to $FTPANONPASS
657 ftp_proxy Defaults to $ftp_proxy.
659 http_proxy Defaults to $http_proxy.
661 https_proxy Defaults to $https_proxy.
663 no_proxy Defaults to $no_proxy.
665 pager Defaults to $PAGER.
667 prompt Defaults to $FTPPROMPT.
669 rprompt Defaults to $FTPRPROMPT.
671 site arg1 arg2 ...
673 The arguments specified are sent, verbatim, to the remote FTP
674 server as a SITE command.
675 size remote-file
677 Return size of remote-file on remote machine.
678 sndbuf size
680 Set the size of the socket send buffer to size.
681 status Show the current status of ftp.
683 struct struct-name
685 Set the file transfer structure to struct-name. The default
686 (and only supported) structure is “file”.
687 sunique Toggle storing of files on remote machine under unique file
689 names. The remote FTP server must support FTP protocol STOU
690 command for successful completion. The remote server will
691 report unique name. Default value is off.
692 system Show the type of operating system running on the remote
694 machine.
695 tenex Set the file transfer type to that needed to talk to TENEX
697 machines.
698 throttle A synonym for rate.
700 trace Toggle packet tracing.
702 type [type-name]
704 Set the file transfer type to type-name. If no type is spec‐
705 ified, the current type is printed. The default type is net‐
706 work ASCII.
707 umask [newmask]
709 Set the default umask on the remote server to newmask. If
710 newmask is omitted, the current umask is printed.
711 unset option
713 Unset option. Refer to set for more information.
714 usage command
716 Print the usage message for command.
717 user user-name [password [account]]
719 Identify yourself to the remote FTP server. If the password
720 is not specified and the server requires it, ftp will prompt
721 the user for it (after disabling local echo). If an account
722 field is not specified, and the FTP server requires it, the
723 user will be prompted for it. If an account field is speci‐
724 fied, an account command will be relayed to the remote server
725 after the login sequence is completed if the remote server
726 did not require it for logging in. Unless ftp is invoked
727 with “auto-login” disabled, this process is done automati‐
728 cally on initial connection to the FTP server.
729 verbose Toggle verbose mode. In verbose mode, all responses from the
731 FTP server are displayed to the user. In addition, if ver‐
732 bose is on, when a file transfer completes, statistics
733 regarding the efficiency of the transfer are reported. By
734 default, verbose is on.
735 xferbuf size
737 Set the size of the socket send and receive buffers to size.
738 ? [command]
740 A synonym for help.
741 Command arguments which have embedded spaces may be quoted with quote ‘"’
743 marks.
744 Commands which toggle settings can take an explicit on or off argument to
746 force the setting appropriately.
747 Commands which take a byte count as an argument (e.g., hash, rate, and
749 xferbuf) support an optional suffix on the argument which changes the
750 interpretation of the argument. Supported suffixes are:
751 b Causes no modification. (Optional)
752 k Kilo; multiply the argument by 1024
753 m Mega; multiply the argument by 1048576
754 g Giga; multiply the argument by 1073741824
755 If ftp receives a SIGINFO (see the “status” argument of stty(1)) or
757 SIGQUIT signal whilst a transfer is in progress, the current transfer
758 rate statistics will be written to the standard error output, in the same
759 format as the standard completion message.
760
762 In addition to standard commands, this version of ftp supports an auto-
763 fetch feature. To enable auto-fetch, simply pass the list of host‐
764 names/files on the command line.
765 The following formats are valid syntax for an auto-fetch element:
767 [user@]host:[path][/]
769 “Classic” FTP format.
770 If path contains a glob character and globbing is enabled, (see
772 glob), then the equivalent of ‘mget path’ is performed.
773 If the directory component of path contains no globbing characters,
775 it is stored locally with the name basename (see basename(1)) of
776 path, in the current directory. Otherwise, the full remote name is
777 used as the local name, relative to the local root directory.
778 ftp://[user[:password]@]host[:port]/path[/][;type=X]
780 An FTP URL, retrieved using the FTP protocol if set ftp_proxy isn't
781 defined. Otherwise, transfer the URL using HTTP via the proxy
782 defined in set ftp_proxy. If set ftp_proxy isn't defined and user
783 is given, login as user. In this case, use password if supplied,
784 otherwise prompt the user for one.
785 If a suffix of ‘;type=A’ or ‘;type=I’ is supplied, then the trans‐
787 fer type will take place as ascii or binary (respectively). The
788 default transfer type is binary.
789 In order to be compliant with RFC 3986, ftp interprets the path
791 part of an “ftp://” auto-fetch URL as follows:
792 · The ‘/’ immediately after the host[:port] is interpreted as a
794 separator before the path, and not as part of the path itself.
795 · The path is interpreted as a ‘/’-separated list of name compo‐
797 nents. For all but the last such component, ftp performs the
798 equivalent of a cd command. For the last path component, ftp
799 performs the equivalent of a get command.
800 · Empty name components, which result from ‘//’ within the path,
802 or from an extra ‘/’ at the beginning of the path, will cause
803 the equivalent of a cd command without a directory name. This
804 is unlikely to be useful.
805 · Any ‘%XX’ codes (per RFC 3986) within the path components are
807 decoded, with XX representing a character code in hexadecimal.
808 This decoding takes place after the path has been split into
809 components, but before each component is used in the equivalent
810 of a cd or get command. Some often-used codes are ‘%2F’ (which
811 represents ‘/’) and ‘%7E’ (which represents ‘~’).
812 The above interpretation has the following consequences:
814 · The path is interpreted relative to the default login directory
816 of the specified user or of the ‘anonymous’ user. If the /
817 directory is required, use a leading path of “%2F”. If a
818 user's home directory is required (and the remote server sup‐
819 ports the syntax), use a leading path of “%7Euser/”. For exam‐
820 ple, to retrieve /etc/motd from ‘localhost’ as the user
821 ‘myname’ with the password ‘mypass’, use
822 “ftp://myname:mypass@localhost/%2fetc/motd”
823 · The exact cd and get commands can be controlled by careful
825 choice of where to use ‘/’ and where to use ‘%2F’ (or ‘%2f’).
826 For example, the following URLs correspond to the equivalents
827 of the indicated commands:
828 ftp://host/dir1/dir2/file “cd dir1”, “cd dir2”, “get
830 file”.
831 ftp://host/%2Fdir1/dir2/file “cd /dir1”, “cd dir2”, “get
833 file”.
834 ftp://host/dir1%2Fdir2/file “cd dir1/dir2”, “get file”.
836 ftp://host/%2Fdir1%2Fdir2/file “cd /dir1/dir2”, “get file”.
838 ftp://host/dir1%2Fdir2%2Ffile “get dir1/dir2/file”.
840 ftp://host/%2Fdir1%2Fdir2%2Ffile “get /dir1/dir2/file”.
842 · You must have appropriate access permission for each of the
844 intermediate directories that is used in the equivalent of a cd
845 command.
846 http://[user[:password]@]host[:port]/path
848 An HTTP URL, retrieved using the HTTP protocol. If set http_proxy
849 is defined, it is used as a URL to an HTTP proxy server. If HTTP
850 authorization is required to retrieve path, and ‘user’ (and option‐
851 ally ‘password’) is in the URL, use them for the first attempt to
852 authenticate.
853 https://[user[:password]@]host[:port]/path
855 An HTTPS URL, retrieved using the HTTPS protocol. If set
856 https_proxy is defined, it is used as a URL to an HTTPS proxy
857 server. If HTTPS authorization is required to retrieve path, and
858 ‘user’ (and optionally ‘password’) is in the URL, use them for the
859 first attempt to authenticate. There is currently no certificate
860 validation and verification.
861 file:///path
863 A local URL, copied from /path on the local host.
864 about:topic
866 Display information regarding topic; no file is retrieved for this
867 auto-fetched element. Supported values include:
868 about:ftp Information about ftp.
870 about:version The version of ftp. Useful to provide when report‐
872 ing problems.
873 Unless noted otherwise above, and -o output is not given, the file is
875 stored in the current directory as the basename(1) of path. Note that if
876 a HTTP redirect is received, the fetch is retried using the new target
877 URL supplied by the server, with a corresponding new path. Using an
878 explicit -o output is recommended, to avoid writing to unexpected file
879 names.
880 If a classic format or an FTP URL format has a trailing ‘/’ or an empty
882 path component, then ftp will connect to the site and cd to the directory
883 given as the path, and leave the user in interactive mode ready for fur‐
884 ther input. This will not work if set ftp_proxy is being used.
885 Direct HTTP transfers use HTTP 1.1. Proxied FTP and HTTP transfers use
887 HTTP 1.0.
888 If -R is given, all auto-fetches that don't go via the FTP or HTTP prox‐
890 ies will be restarted. For FTP, this is implemented by using reget
891 instead of get. For HTTP, this is implemented by using the ‘Range:
892 bytes=’ HTTP/1.1 directive.
893 If WWW or proxy WWW authentication is required, you will be prompted to
895 enter a username and password to authenticate with.
896 When specifying IPv6 numeric addresses in a URL, you need to surround the
898 address in square brackets. E.g.: “ftp://[::1]:21/”. This is because
899 colons are used in IPv6 numeric address as well as being the separator
900 for the port number.
901
903 To abort a file transfer, use the terminal interrupt key (usually Ctrl-
904 C). Sending transfers will be immediately halted. Receiving transfers
905 will be halted by sending an FTP protocol ABOR command to the remote
906 server, and discarding any further data received. The speed at which
907 this is accomplished depends upon the remote server's support for ABOR
908 processing. If the remote server does not support the ABOR command, the
909 prompt will not appear until the remote server has completed sending the
910 requested file.
911 If the terminal interrupt key sequence is used whilst ftp is awaiting a
913 reply from the remote server for the ABOR processing, then the connection
914 will be closed. This is different from the traditional behaviour (which
915 ignores the terminal interrupt during this phase), but is considered more
916 useful.
917
919 Files specified as arguments to ftp commands are processed according to
920 the following rules.
921 1. If the file name ‘-’ is specified, the stdin (for reading) or stdout
923 (for writing) is used.
924 2. If the first character of the file name is ‘|’, the remainder of the
926 argument is interpreted as a shell command. ftp then forks a shell,
927 using popen(3) with the argument supplied, and reads (writes) from
928 the stdout (stdin). If the shell command includes spaces, the argu‐
929 ment must be quoted; e.g. “"| ls -lt"”. A particularly useful
930 example of this mechanism is: “dir "" |more”.
931 3. Failing the above checks, if “globbing” is enabled, local file names
933 are expanded according to the rules used in the csh(1); see the glob
934 command. If the ftp command expects a single local file (e.g.
935 put), only the first filename generated by the "globbing" operation
936 is used.
937 4. For mget commands and get commands with unspecified local file
939 names, the local filename is the remote filename, which may be
940 altered by a case, ntrans, or nmap setting. The resulting filename
941 may then be altered if runique is on.
942 5. For mput commands and put commands with unspecified remote file
944 names, the remote filename is the local filename, which may be
945 altered by a ntrans or nmap setting. The resulting filename may
946 then be altered by the remote server if sunique is on.
947
949 The FTP specification specifies many parameters which may affect a file
950 transfer. The type may be one of “ascii”, “image” (binary), “ebcdic”,
951 and “local byte size” (for PDP-10's and PDP-20's mostly). ftp supports
952 the ascii and image types of file transfer, plus local byte size 8 for
953 tenex mode transfers.
954 ftp supports only the default values for the remaining file transfer
956 parameters: mode, form, and struct.
957
959 The .netrc file contains login and initialization information used by the
960 auto-login process. It resides in the user's home directory, unless
961 overridden with the -N netrc option, or specified in the NETRC environ‐
962 ment variable. The following tokens are recognized; they may be sepa‐
963 rated by spaces, tabs, or new-lines:
964 machine name
966 Identify a remote machine name. The auto-login process
967 searches the .netrc file for a machine token that matches the
968 remote machine specified on the ftp command line or as an open
969 command argument. Once a match is made, the subsequent .netrc
970 tokens are processed, stopping when the end of file is reached
971 or another machine or a default token is encountered.
972 default This is the same as machine name except that default matches
974 any name. There can be only one default token, and it must be
975 after all machine tokens. This is normally used as:
976 default login anonymous password user@site
978 thereby giving the user an automatic anonymous FTP login to
980 machines not specified in .netrc. This can be overridden by
981 using the -n flag to disable auto-login.
982 login name
984 Identify a user on the remote machine. If this token is
985 present, the auto-login process will initiate a login using the
986 specified name.
987 password string
989 Supply a password. If this token is present, the auto-login
990 process will supply the specified string if the remote server
991 requires a password as part of the login process. Note that if
992 this token is present in the .netrc file for any user other
993 than anonymous, ftp will abort the auto-login process if the
994 .netrc is readable by anyone besides the user.
995 account string
997 Supply an additional account password. If this token is
998 present, the auto-login process will supply the specified
999 string if the remote server requires an additional account
1000 password, or the auto-login process will initiate an ACCT com‐
1001 mand if it does not.
1002 macdef name
1004 Define a macro. This token functions like the ftp macdef com‐
1005 mand functions. A macro is defined with the specified name;
1006 its contents begin with the next .netrc line and continue until
1007 a blank line (consecutive new-line characters) is encountered.
1008 Like the other tokens in the .netrc file, a macdef is applica‐
1009 ble only to the machine definition preceding it. A macdef
1010 entry cannot be used by multiple machine definitions; rather,
1011 it must be defined following each machine it is intended to be
1012 used with. If a macro named init is defined, it is automati‐
1013 cally executed as the last step in the auto-login process. For
1014 example,
1015 default
1017 macdef init
1018 epsv4 off
1019 followed by a blank line.
1021
1023 ftp supports interactive command line editing, via the editline(3)
1024 library. It is enabled with the edit command, and is enabled by default
1025 if input is from a tty. Previous lines can be recalled and edited with
1026 the arrow keys, and other GNU Emacs-style editing keys may be used as
1027 well.
1028 The editline(3) library is configured with a .editrc file - refer to
1030 editrc(5) for more information.
1031 An extra key binding is available to ftp to provide context sensitive
1033 command and filename completion (including remote file completion). To
1034 use this, bind a key to the editline(3) command ftp-complete. By
1035 default, this is bound to the TAB key.
1036
1038 By default, ftp displays a command line prompt of “ftp> ” to the user.
1039 This can be changed with the set prompt command.
1040 A prompt can be displayed on the right side of the screen (after the com‐
1042 mand input) with the set rprompt command.
1043 The following formatting sequences are replaced by the given information:
1045 %/ The current remote working directory.
1047 %c[[0]n],%.[[0]n]
1049 The trailing component of the current remote working direc‐
1050 tory, or n trailing components if a digit n is given. If n
1051 begins with ‘0’, the number of skipped components precede the
1052 trailing component(s) in the format “/<number>trailing” (for
1053 ‘%c’) or “...trailing” (for ‘%.’).
1054 %M The remote host name.
1056 %m The remote host name, up to the first ‘.’.
1058 %n The remote user name.
1060 %% A single ‘%’.
1062
1064 ftp uses the following environment variables.
1065 FTPANONPASS Password to send in an anonymous FTP transfer. Defaults
1067 to “`whoami`@”.
1068 FTPMODE Overrides the default operation mode. Support values are:
1070 active active mode FTP only
1072 auto automatic determination of passive or active
1074 (this is the default)
1075 gate gate-ftp mode
1077 passive passive mode FTP only
1079 FTPPROMPT Command-line prompt to use. Defaults to “ftp> ”. Refer
1081 to COMMAND LINE PROMPT for more information.
1082 FTPRPROMPT Command-line right side prompt to use. Defaults to “”.
1084 Refer to COMMAND LINE PROMPT for more information.
1085 FTPSERVER Host to use as gate-ftp server when gate is enabled.
1087 FTPSERVERPORT Port to use when connecting to gate-ftp server when gate
1089 is enabled. Default is port returned by a getservbyname()
1090 lookup of “ftpgate/tcp”.
1091 FTPUSERAGENT The value to send for the HTTP User-Agent header.
1093 HOME For default location of a .netrc file, if one exists.
1095 NETRC An alternate location of the .netrc file.
1097 PAGER Used by various commands to display files. Defaults to
1099 more(1) if empty or not set.
1100 SHELL For default shell.
1102 ftp_proxy URL of FTP proxy to use when making FTP URL requests (if
1104 not defined, use the standard FTP protocol).
1105 See http_proxy for further notes about proxy use.
1107 http_proxy URL of HTTP proxy to use when making HTTP URL requests.
1109 If proxy authentication is required and there is a user‐
1110 name and password in this URL, they will automatically be
1111 used in the first attempt to authenticate to the proxy.
1112 If “unsafe” URL characters are required in the username or
1114 password (for example ‘@’ or ‘/’), encode them with RFC
1115 3986 ‘%XX’ encoding.
1116 Note that the use of a username and password in ftp_proxy
1118 and http_proxy may be incompatible with other programs
1119 that use it (such as lynx(1)).
1120 NOTE: this is not used for interactive sessions, only for
1122 command-line fetches.
1123 no_proxy A space or comma separated list of hosts (or domains) for
1125 which proxying is not to be used. Each entry may have an
1126 optional trailing ":port", which restricts the matching to
1127 connections to that port.
1128
1130 Some firewall configurations do not allow ftp to use extended passive
1131 mode. If you find that even a simple ls appears to hang after printing a
1132 message such as this:
1133 229 Entering Extended Passive Mode (|||58551|)
1135 then you will need to disable extended passive mode with epsv4 off. See
1137 the above section The .netrc File for an example of how to make this
1138 automatic.
1139
1141 getservbyname(3), editrc(5), services(5), ftpd(8)
1142
1144 ftp attempts to be compliant with:
1145 RFC 959 File Transfer Protocol
1147 RFC 1123 Requirements for Internet Hosts - Application and Support
1149 RFC 1635 How to Use Anonymous FTP
1151 RFC 2389 Feature negotiation mechanism for the File Transfer
1153 Protocol
1154 RFC 2428 FTP Extensions for IPv6 and NATs
1156 RFC 2616 Hypertext Transfer Protocol -- HTTP/1.1
1158 RFC 2822 Internet Message Format
1160 RFC 3659 Extensions to FTP
1162 RFC 3986 Uniform Resource Identifier (URI)
1164
1166 The ftp command appeared in 4.2BSD.
1167 Various features such as command line editing, context sensitive command
1169 and file completion, dynamic progress bar, automatic fetching of files
1170 and URLs, modification time preservation, transfer rate throttling, con‐
1171 figurable command line prompt, and other enhancements over the standard
1172 BSD ftp were implemented in NetBSD 1.3 and later releases by Luke Mewburn
1173 ⟨lukem@NetBSD.org⟩.
1174 IPv6 support was added by the WIDE/KAME project (but may not be present
1176 in all non-NetBSD versions of this program, depending if the operating
1177 system supports IPv6 in a similar manner to KAME).
1178
1180 Correct execution of many commands depends upon proper behavior by the
1181 remote server.
1182 An error in the treatment of carriage returns in the 4.2BSD ascii-mode
1184 transfer code has been corrected. This correction may result in incor‐
1185 rect transfers of binary files to and from 4.2BSD servers using the ascii
1186 type. Avoid this problem by using the binary image type.
1187 ftp assumes that all IPv4 mapped addresses (IPv6 addresses with a form
1189 like ::ffff:10.1.1.1) indicate IPv4 destinations which can be handled by
1190 AF_INET sockets. However, in certain IPv6 network configurations, this
1191 assumption is not true. In such an environment, IPv4 mapped addresses
1192 must be passed to AF_INET6 sockets directly. For example, if your site
1193 uses a SIIT translator for IPv6-to-IPv4 translation, ftp is unable to
1194 support your configuration.
1195BSD April 24, 2015 BSD