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 en‐
58 abled, 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 be‐
69 low. 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 op‐
101 tional target filename for single file uploads), and file is
102 one or more local files to be uploaded.
103 -V Disable verbose and progress, overriding the default of en‐
105 abled 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 de‐
147 fault 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 re‐
179 trieval. 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 di‐
197 rectory 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 ma‐
237 chine, 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 in‐
314 voke 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 ma‐
373 chine, 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 re‐
404 mote 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 de‐
416 termine 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 se‐
422 quence “$0” is replaced by the original filename. Addition‐
423 ally, the sequence “[seq1, seq2]” is replaced by [seq1] if
424 seq1 is not a null string; otherwise it is replaced by seq2.
425 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 in‐
432 put 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 lo‐
445 cal 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 re‐
477 quired to support the PASV command by RFC 1123, some do not.)
478 pdir [remote-path]
480 Perform dir [remote-path], and display the result with the
481 program specified by the set pager option.
482 pls [remote-path]
484 Perform ls [remote-path], and display the result with the
485 program specified by the set pager option.
486 pmlsd [remote-path]
488 Perform mlsd [remote-path], and display the result with the
489 program specified by the set pager option.
490 preserve Toggle preservation of modification times on retrieved files.
492 progress Toggle display of transfer progress bar. The progress bar
494 will be disabled for a transfer that has local-file as ‘-’ or
495 a command that starts with ‘|’. Refer to FILE NAMING
496 CONVENTIONS for more information. Enabling progress disables
497 hash.
498 prompt Toggle interactive prompting. Interactive prompting occurs
500 during multiple file transfers to allow the user to selec‐
501 tively retrieve or store files. If prompting is turned off
502 (default is on), any mget or mput will transfer all files,
503 and any mdelete will delete all files.
504 When prompting is on, the following commands are available at
506 a prompt:
507 a Answer ‘yes’ to the current file, and automatically
509 answer ‘yes’ to any remaining files for the current
510 command.
511 n Answer ‘no’, and do not transfer the file.
513 p Answer ‘yes’ to the current file, and turn off
515 prompt mode (as is “prompt off” had been given).
516 q Terminate the current operation.
518 y Answer ‘yes’, and transfer the file.
520 ? Display a help message.
522 Any other response will answer ‘yes’ to the current file.
524 proxy ftp-command
526 Execute an ftp command on a secondary control connection.
527 This command allows simultaneous connection to two remote FTP
528 servers for transferring files between the two servers. The
529 first proxy command should be an open, to establish the sec‐
530 ondary control connection. Enter the command "proxy ?" to
531 see other FTP commands executable on the secondary connec‐
532 tion. The following commands behave differently when pref‐
533 aced by proxy: open will not define new macros during the
534 auto-login process, close will not erase existing macro defi‐
535 nitions, get and mget transfer files from the host on the
536 primary control connection to the host on the secondary con‐
537 trol connection, and put, mput, and append transfer files
538 from the host on the secondary control connection to the host
539 on the primary control connection. Third party file trans‐
540 fers depend upon support of the FTP protocol PASV command by
541 the server on the secondary control connection.
542 put local-file [remote-file]
544 Store a local file on the remote machine. If remote-file is
545 left unspecified, the local file name is used after process‐
546 ing according to any ntrans or nmap settings in naming the
547 remote file. File transfer uses the current settings for
548 type, format, mode, and structure.
549 pwd Print the name of the current working directory on the remote
551 machine.
552 quit A synonym for bye.
554 quote arg1 arg2 ...
556 The arguments specified are sent, verbatim, to the remote FTP
557 server.
558 rate direction [maximum [increment]]
560 Throttle the maximum transfer rate to maximum bytes/second.
561 If maximum is 0, disable the throttle.
562 direction may be one of:
564 all Both directions.
565 get Incoming transfers.
566 put Outgoing transfers.
567 maximum can be modified on the fly by increment bytes (de‐
569 fault: 1024) each time a given signal is received:
570 SIGUSR1 Increment maximum by increment bytes.
572 SIGUSR2 Decrement maximum by increment bytes. The re‐
574 sult must be a positive number.
575 If maximum is not supplied, the current throttle rates are
577 displayed.
578 Note: rate is not yet implemented for ascii mode transfers.
580 rcvbuf size
582 Set the size of the socket receive buffer to size.
583 recv remote-file [local-file]
585 A synonym for get.
586 reget remote-file [local-file]
588 reget acts like get, except that if local-file exists and is
589 smaller than remote-file, local-file is presumed to be a par‐
590 tially transferred copy of remote-file and the transfer is
591 continued from the apparent point of failure. This command
592 is useful when transferring very large files over networks
593 that are prone to dropping connections.
594 remopts command [command-options]
596 Set options on the remote FTP server for command to
597 command-options (whose absence is handled on a command-spe‐
598 cific basis). Remote FTP commands known to support options
599 include: ‘MLST’ (used for MLSD and MLST).
600 rename [from [to]]
602 Rename the file from on the remote machine, to the file to.
603 reset Clear reply queue. This command re-synchronizes command/re‐
605 ply sequencing with the remote FTP server. Resynchronization
606 may be necessary following a violation of the FTP protocol by
607 the remote server.
608 restart marker
610 Restart the immediately following get or put at the indicated
611 marker. On UNIX systems, marker is usually a byte offset
612 into the file.
613 rhelp [command-name]
615 Request help from the remote FTP server. If a command-name
616 is specified it is supplied to the server as well.
617 rmdir directory-name
619 Delete a directory on the remote machine.
620 rstatus [remote-file]
622 With no arguments, show status of remote machine. If
623 remote-file is specified, show status of remote-file on re‐
624 mote machine.
625 runique Toggle storing of files on the local system with unique file‐
627 names. If a file already exists with a name equal to the
628 target local filename for a get or mget command, a ".1" is
629 appended to the name. If the resulting name matches another
630 existing file, a ".2" is appended to the original name. If
631 this process continues up to ".99", an error message is
632 printed, and the transfer does not take place. The generated
633 unique filename will be reported. Note that runique will not
634 affect local files generated from a shell command (see be‐
635 low). The default value is off.
636 send local-file [remote-file]
638 A synonym for put.
639 sendport Toggle the use of PORT commands. By default, ftp will at‐
641 tempt to use a PORT command when establishing a connection
642 for each data transfer. The use of PORT commands can prevent
643 delays when performing multiple file transfers. If the PORT
644 command fails, ftp will use the default data port. When the
645 use of PORT commands is disabled, no attempt will be made to
646 use PORT commands for each data transfer. This is useful for
647 certain FTP implementations which do ignore PORT commands
648 but, incorrectly, indicate they've been accepted.
649 set [option value]
651 Set option to value. If option and value are not given, dis‐
652 play all of the options and their values. The currently sup‐
653 ported options are:
654 anonpass Defaults to $FTPANONPASS
656 ftp_proxy Defaults to $ftp_proxy.
658 http_proxy Defaults to $http_proxy.
660 https_proxy Defaults to $https_proxy.
662 no_proxy Defaults to $no_proxy.
664 pager Defaults to $PAGER.
666 prompt Defaults to $FTPPROMPT.
668 rprompt Defaults to $FTPRPROMPT.
670 site arg1 arg2 ...
672 The arguments specified are sent, verbatim, to the remote FTP
673 server as a SITE command.
674 size remote-file
676 Return size of remote-file on remote machine.
677 sndbuf size
679 Set the size of the socket send buffer to size.
680 status Show the current status of ftp.
682 struct struct-name
684 Set the file transfer structure to struct-name. The default
685 (and only supported) structure is “file”.
686 sunique Toggle storing of files on remote machine under unique file
688 names. The remote FTP server must support FTP protocol STOU
689 command for successful completion. The remote server will
690 report unique name. Default value is off.
691 system Show the type of operating system running on the remote ma‐
693 chine.
694 tenex Set the file transfer type to that needed to talk to TENEX
696 machines.
697 throttle A synonym for rate.
699 trace Toggle packet tracing.
701 type [type-name]
703 Set the file transfer type to type-name. If no type is spec‐
704 ified, the current type is printed. The default type is net‐
705 work ASCII.
706 umask [newmask]
708 Set the default umask on the remote server to newmask. If
709 newmask is omitted, the current umask is printed.
710 unset option
712 Unset option. Refer to set for more information.
713 usage command
715 Print the usage message for command.
716 user user-name [password [account]]
718 Identify yourself to the remote FTP server. If the password
719 is not specified and the server requires it, ftp will prompt
720 the user for it (after disabling local echo). If an account
721 field is not specified, and the FTP server requires it, the
722 user will be prompted for it. If an account field is speci‐
723 fied, an account command will be relayed to the remote server
724 after the login sequence is completed if the remote server
725 did not require it for logging in. Unless ftp is invoked
726 with “auto-login” disabled, this process is done automati‐
727 cally on initial connection to the FTP server.
728 verbose Toggle verbose mode. In verbose mode, all responses from the
730 FTP server are displayed to the user. In addition, if ver‐
731 bose is on, when a file transfer completes, statistics re‐
732 garding the efficiency of the transfer are reported. By de‐
733 fault, verbose is on.
734 xferbuf size
736 Set the size of the socket send and receive buffers to size.
737 ? [command]
739 A synonym for help.
740 Command arguments which have embedded spaces may be quoted with quote ‘"’
742 marks.
743 Commands which toggle settings can take an explicit on or off argument to
745 force the setting appropriately.
746 Commands which take a byte count as an argument (e.g., hash, rate, and
748 xferbuf) support an optional suffix on the argument which changes the in‐
749 terpretation of the argument. Supported suffixes are:
750 b Causes no modification. (Optional)
751 k Kilo; multiply the argument by 1024
752 m Mega; multiply the argument by 1048576
753 g Giga; multiply the argument by 1073741824
754 If ftp receives a SIGINFO (see the “status” argument of stty(1)) or
756 SIGQUIT signal whilst a transfer is in progress, the current transfer
757 rate statistics will be written to the standard error output, in the same
758 format as the standard completion message.
759
761 In addition to standard commands, this version of ftp supports an auto-
762 fetch feature. To enable auto-fetch, simply pass the list of host‐
763 names/files on the command line.
764 The following formats are valid syntax for an auto-fetch element:
766 [user@]host:[path][/]
768 “Classic” FTP format.
769 If path contains a glob character and globbing is enabled, (see
771 glob), then the equivalent of ‘mget path’ is performed.
772 If the directory component of path contains no globbing characters,
774 it is stored locally with the name basename (see basename(1)) of
775 path, in the current directory. Otherwise, the full remote name is
776 used as the local name, relative to the local root directory.
777 ftp://[user[:password]@]host[:port]/path[/][;type=X]
779 An FTP URL, retrieved using the FTP protocol if set ftp_proxy isn't
780 defined. Otherwise, transfer the URL using HTTP via the proxy de‐
781 fined in set ftp_proxy. If set ftp_proxy isn't defined and user is
782 given, login as user. In this case, use password if supplied, oth‐
783 erwise prompt the user for one.
784 If a suffix of ‘;type=A’ or ‘;type=I’ is supplied, then the trans‐
786 fer type will take place as ascii or binary (respectively). The
787 default transfer type is binary.
788 In order to be compliant with RFC 3986, ftp interprets the path
790 part of an “ftp://” auto-fetch URL as follows:
791 • The ‘/’ immediately after the host[:port] is interpreted as a
793 separator before the path, and not as part of the path itself.
794 • The path is interpreted as a ‘/’-separated list of name compo‐
796 nents. For all but the last such component, ftp performs the
797 equivalent of a cd command. For the last path component, ftp
798 performs the equivalent of a get command.
799 • Empty name components, which result from ‘//’ within the path,
801 or from an extra ‘/’ at the beginning of the path, will cause
802 the equivalent of a cd command without a directory name. This
803 is unlikely to be useful.
804 • Any ‘%XX’ codes (per RFC 3986) within the path components are
806 decoded, with XX representing a character code in hexadecimal.
807 This decoding takes place after the path has been split into
808 components, but before each component is used in the equivalent
809 of a cd or get command. Some often-used codes are ‘%2F’ (which
810 represents ‘/’) and ‘%7E’ (which represents ‘~’).
811 The above interpretation has the following consequences:
813 • The path is interpreted relative to the default login directory
815 of the specified user or of the ‘anonymous’ user. If the / di‐
816 rectory is required, use a leading path of “%2F”. If a user's
817 home directory is required (and the remote server supports the
818 syntax), use a leading path of “%7Euser/”. For example, to re‐
819 trieve /etc/motd from ‘localhost’ as the user ‘myname’ with the
820 password ‘mypass’, use
821 “ftp://myname:mypass@localhost/%2fetc/motd”
822 • The exact cd and get commands can be controlled by careful
824 choice of where to use ‘/’ and where to use ‘%2F’ (or ‘%2f’).
825 For example, the following URLs correspond to the equivalents
826 of the indicated commands:
827 ftp://host/dir1/dir2/file “cd dir1”, “cd dir2”, “get
829 file”.
830 ftp://host/%2Fdir1/dir2/file “cd /dir1”, “cd dir2”, “get
832 file”.
833 ftp://host/dir1%2Fdir2/file “cd dir1/dir2”, “get file”.
835 ftp://host/%2Fdir1%2Fdir2/file “cd /dir1/dir2”, “get file”.
837 ftp://host/dir1%2Fdir2%2Ffile “get dir1/dir2/file”.
839 ftp://host/%2Fdir1%2Fdir2%2Ffile “get /dir1/dir2/file”.
841 • You must have appropriate access permission for each of the in‐
843 termediate directories that is used in the equivalent of a cd
844 command.
845 http://[user[:password]@]host[:port]/path
847 An HTTP URL, retrieved using the HTTP protocol. If set http_proxy
848 is defined, it is used as a URL to an HTTP proxy server. If HTTP
849 authorization is required to retrieve path, and ‘user’ (and option‐
850 ally ‘password’) is in the URL, use them for the first attempt to
851 authenticate.
852 https://[user[:password]@]host[:port]/path
854 An HTTPS URL, retrieved using the HTTPS protocol. If set
855 https_proxy is defined, it is used as a URL to an HTTPS proxy
856 server. If HTTPS authorization is required to retrieve path, and
857 ‘user’ (and optionally ‘password’) is in the URL, use them for the
858 first attempt to authenticate. There is currently no certificate
859 validation and verification.
860 file:///path
862 A local URL, copied from /path on the local host.
863 about:topic
865 Display information regarding topic; no file is retrieved for this
866 auto-fetched element. Supported values include:
867 about:ftp Information about ftp.
869 about:version The version of ftp. Useful to provide when report‐
871 ing problems.
872 Unless noted otherwise above, and -o output is not given, the file is
874 stored in the current directory as the basename(1) of path. Note that if
875 a HTTP redirect is received, the fetch is retried using the new target
876 URL supplied by the server, with a corresponding new path. Using an ex‐
877 plicit -o output is recommended, to avoid writing to unexpected file
878 names.
879 If a classic format or an FTP URL format has a trailing ‘/’ or an empty
881 path component, then ftp will connect to the site and cd to the directory
882 given as the path, and leave the user in interactive mode ready for fur‐
883 ther input. This will not work if set ftp_proxy is being used.
884 Direct HTTP transfers use HTTP 1.1. Proxied FTP and HTTP transfers use
886 HTTP 1.0.
887 If -R is given, all auto-fetches that don't go via the FTP or HTTP prox‐
889 ies will be restarted. For FTP, this is implemented by using reget in‐
890 stead of get. For HTTP, this is implemented by using the ‘Range: bytes=’
891 HTTP/1.1 directive.
892 If WWW or proxy WWW authentication is required, you will be prompted to
894 enter a username and password to authenticate with.
895 When specifying IPv6 numeric addresses in a URL, you need to surround the
897 address in square brackets. E.g.: “ftp://[::1]:21/”. This is because
898 colons are used in IPv6 numeric address as well as being the separator
899 for the port number.
900
902 To abort a file transfer, use the terminal interrupt key (usually Ctrl-
903 C). Sending transfers will be immediately halted. Receiving transfers
904 will be halted by sending an FTP protocol ABOR command to the remote
905 server, and discarding any further data received. The speed at which
906 this is accomplished depends upon the remote server's support for ABOR
907 processing. If the remote server does not support the ABOR command, the
908 prompt will not appear until the remote server has completed sending the
909 requested file.
910 If the terminal interrupt key sequence is used whilst ftp is awaiting a
912 reply from the remote server for the ABOR processing, then the connection
913 will be closed. This is different from the traditional behaviour (which
914 ignores the terminal interrupt during this phase), but is considered more
915 useful.
916
918 Files specified as arguments to ftp commands are processed according to
919 the following rules.
920 1. If the file name ‘-’ is specified, the stdin (for reading) or stdout
922 (for writing) is used.
923 2. If the first character of the file name is ‘|’, the remainder of the
925 argument is interpreted as a shell command. ftp then forks a shell,
926 using popen(3) with the argument supplied, and reads (writes) from
927 the stdout (stdin). If the shell command includes spaces, the argu‐
928 ment must be quoted; e.g. “"| ls -lt"”. A particularly useful ex‐
929 ample of this mechanism is: “dir "" |more”.
930 3. Failing the above checks, if “globbing” is enabled, local file names
932 are expanded according to the rules used in the csh(1); see the glob
933 command. If the ftp command expects a single local file (e.g.
934 put), only the first filename generated by the "globbing" operation
935 is used.
936 4. For mget commands and get commands with unspecified local file
938 names, the local filename is the remote filename, which may be al‐
939 tered by a case, ntrans, or nmap setting. The resulting filename
940 may then be altered if runique is on.
941 5. For mput commands and put commands with unspecified remote file
943 names, the remote filename is the local filename, which may be al‐
944 tered by a ntrans or nmap setting. The resulting filename may then
945 be altered by the remote server if sunique is on.
946
948 The FTP specification specifies many parameters which may affect a file
949 transfer. The type may be one of “ascii”, “image” (binary), “ebcdic”,
950 and “local byte size” (for PDP-10's and PDP-20's mostly). ftp supports
951 the ascii and image types of file transfer, plus local byte size 8 for
952 tenex mode transfers.
953 ftp supports only the default values for the remaining file transfer pa‐
955 rameters: mode, form, and struct.
956
958 The .netrc file contains login and initialization information used by the
959 auto-login process. It resides in the user's home directory, unless
960 overridden with the -N netrc option, or specified in the NETRC environ‐
961 ment variable. The following tokens are recognized; they may be sepa‐
962 rated by spaces, tabs, or new-lines:
963 machine name
965 Identify a remote machine name. The auto-login process
966 searches the .netrc file for a machine token that matches the
967 remote machine specified on the ftp command line or as an open
968 command argument. Once a match is made, the subsequent .netrc
969 tokens are processed, stopping when the end of file is reached
970 or another machine or a default token is encountered.
971 default This is the same as machine name except that default matches
973 any name. There can be only one default token, and it must be
974 after all machine tokens. This is normally used as:
975 default login anonymous password user@site
977 thereby giving the user an automatic anonymous FTP login to ma‐
979 chines not specified in .netrc. This can be overridden by us‐
980 ing the -n flag to disable auto-login.
981 login name
983 Identify a user on the remote machine. If this token is
984 present, the auto-login process will initiate a login using the
985 specified name.
986 password string
988 Supply a password. If this token is present, the auto-login
989 process will supply the specified string if the remote server
990 requires a password as part of the login process. Note that if
991 this token is present in the .netrc file for any user other
992 than anonymous, ftp will abort the auto-login process if the
993 .netrc is readable by anyone besides the user.
994 account string
996 Supply an additional account password. If this token is
997 present, the auto-login process will supply the specified
998 string if the remote server requires an additional account
999 password, or the auto-login process will initiate an ACCT com‐
1000 mand if it does not.
1001 macdef name
1003 Define a macro. This token functions like the ftp macdef com‐
1004 mand functions. A macro is defined with the specified name;
1005 its contents begin with the next .netrc line and continue until
1006 a blank line (consecutive new-line characters) is encountered.
1007 Like the other tokens in the .netrc file, a macdef is applica‐
1008 ble only to the machine definition preceding it. A macdef en‐
1009 try cannot be used by multiple machine definitions; rather, it
1010 must be defined following each machine it is intended to be
1011 used with. If a macro named init is defined, it is automati‐
1012 cally executed as the last step in the auto-login process. For
1013 example,
1014 default
1016 macdef init
1017 epsv4 off
1018 followed by a blank line.
1020
1022 ftp supports interactive command line editing, via the editline(3) li‐
1023 brary. It is enabled with the edit command, and is enabled by default if
1024 input is from a tty. Previous lines can be recalled and edited with the
1025 arrow keys, and other GNU Emacs-style editing keys may be used as well.
1026 The editline(3) library is configured with a .editrc file - refer to
1028 editrc(5) for more information.
1029 An extra key binding is available to ftp to provide context sensitive
1031 command and filename completion (including remote file completion). To
1032 use this, bind a key to the editline(3) command ftp-complete. By de‐
1033 fault, this is bound to the TAB key.
1034
1036 By default, ftp displays a command line prompt of “ftp> ” to the user.
1037 This can be changed with the set prompt command.
1038 A prompt can be displayed on the right side of the screen (after the com‐
1040 mand input) with the set rprompt command.
1041 The following formatting sequences are replaced by the given information:
1043 %/ The current remote working directory.
1045 %c[[0]n],%.[[0]n]
1047 The trailing component of the current remote working direc‐
1048 tory, or n trailing components if a digit n is given. If n
1049 begins with ‘0’, the number of skipped components precede the
1050 trailing component(s) in the format “/<number>trailing” (for
1051 ‘%c’) or “...trailing” (for ‘%.’).
1052 %M The remote host name.
1054 %m The remote host name, up to the first ‘.’.
1056 %n The remote user name.
1058 %% A single ‘%’.
1060
1062 ftp uses the following environment variables.
1063 FTPANONPASS Password to send in an anonymous FTP transfer. Defaults
1065 to “`whoami`@”.
1066 FTPMODE Overrides the default operation mode. Support values are:
1068 active active mode FTP only
1070 auto automatic determination of passive or active
1072 (this is the default)
1073 gate gate-ftp mode
1075 passive passive mode FTP only
1077 FTPPROMPT Command-line prompt to use. Defaults to “ftp> ”. Refer
1079 to COMMAND LINE PROMPT for more information.
1080 FTPRPROMPT Command-line right side prompt to use. Defaults to “”.
1082 Refer to COMMAND LINE PROMPT for more information.
1083 FTPSERVER Host to use as gate-ftp server when gate is enabled.
1085 FTPSERVERPORT Port to use when connecting to gate-ftp server when gate
1087 is enabled. Default is port returned by a getservbyname()
1088 lookup of “ftpgate/tcp”.
1089 FTPUSERAGENT The value to send for the HTTP User-Agent header.
1091 HOME For default location of a .netrc file, if one exists.
1093 NETRC An alternate location of the .netrc file.
1095 PAGER Used by various commands to display files. Defaults to
1097 more(1) if empty or not set.
1098 SHELL For default shell.
1100 ftp_proxy URL of FTP proxy to use when making FTP URL requests (if
1102 not defined, use the standard FTP protocol).
1103 See http_proxy for further notes about proxy use.
1105 http_proxy URL of HTTP proxy to use when making HTTP URL requests.
1107 If proxy authentication is required and there is a user‐
1108 name and password in this URL, they will automatically be
1109 used in the first attempt to authenticate to the proxy.
1110 If “unsafe” URL characters are required in the username or
1112 password (for example ‘@’ or ‘/’), encode them with RFC
1113 3986 ‘%XX’ encoding.
1114 Note that the use of a username and password in ftp_proxy
1116 and http_proxy may be incompatible with other programs
1117 that use it (such as lynx(1)).
1118 NOTE: this is not used for interactive sessions, only for
1120 command-line fetches.
1121 no_proxy A space or comma separated list of hosts (or domains) for
1123 which proxying is not to be used. Each entry may have an
1124 optional trailing ":port", which restricts the matching to
1125 connections to that port.
1126
1128 Some firewall configurations do not allow ftp to use extended passive
1129 mode. If you find that even a simple ls appears to hang after printing a
1130 message such as this:
1131 229 Entering Extended Passive Mode (|||58551|)
1133 then you will need to disable extended passive mode with epsv4 off. See
1135 the above section The .netrc File for an example of how to make this au‐
1136 tomatic.
1137
1139 getservbyname(3), editrc(5), services(5), ftpd(8)
1140
1142 ftp attempts to be compliant with:
1143 RFC 959 File Transfer Protocol
1145 RFC 1123 Requirements for Internet Hosts - Application and Support
1147 RFC 1635 How to Use Anonymous FTP
1149 RFC 2389 Feature negotiation mechanism for the File Transfer
1151 Protocol
1152 RFC 2428 FTP Extensions for IPv6 and NATs
1154 RFC 2616 Hypertext Transfer Protocol -- HTTP/1.1
1156 RFC 2822 Internet Message Format
1158 RFC 3659 Extensions to FTP
1160 RFC 3986 Uniform Resource Identifier (URI)
1162
1164 The ftp command appeared in 4.2BSD.
1165 Various features such as command line editing, context sensitive command
1167 and file completion, dynamic progress bar, automatic fetching of files
1168 and URLs, modification time preservation, transfer rate throttling, con‐
1169 figurable command line prompt, and other enhancements over the standard
1170 BSD ftp were implemented in NetBSD 1.3 and later releases by Luke Mewburn
1171 ⟨lukem@NetBSD.org⟩.
1172 IPv6 support was added by the WIDE/KAME project (but may not be present
1174 in all non-NetBSD versions of this program, depending if the operating
1175 system supports IPv6 in a similar manner to KAME).
1176
1178 Correct execution of many commands depends upon proper behavior by the
1179 remote server.
1180 An error in the treatment of carriage returns in the 4.2BSD ascii-mode
1182 transfer code has been corrected. This correction may result in incor‐
1183 rect transfers of binary files to and from 4.2BSD servers using the ascii
1184 type. Avoid this problem by using the binary image type.
1185 ftp assumes that all IPv4 mapped addresses (IPv6 addresses with a form
1187 like ::ffff:10.1.1.1) indicate IPv4 destinations which can be handled by
1188 AF_INET sockets. However, in certain IPv6 network configurations, this
1189 assumption is not true. In such an environment, IPv4 mapped addresses
1190 must be passed to AF_INET6 sockets directly. For example, if your site
1191 uses a SIIT translator for IPv6-to-IPv4 translation, ftp is unable to
1192 support your configuration.
1193BSD April 24, 2015 BSD