1.\" $OpenBSD: ftp.1,v 1.81 2010/07/26 21:31:34 jmc Exp $ 2.\" $NetBSD: ftp.1,v 1.22 1997/08/18 10:20:22 lukem Exp $ 3.\" 4.\" Copyright (c) 1985, 1989, 1990, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)ftp.1 8.3 (Berkeley) 10/9/94 32.\" 33.Dd $Mdocdate: July 26 2010 $ 34.Dt FTP 1 35.Os 36.Sh NAME 37.Nm ftp 38.Nd ARPANET file transfer program 39.Sh SYNOPSIS 40.Nm ftp 41.Op Fl 46AadEegimnptVv 42.Op Fl k Ar seconds 43.Op Fl P Ar port 44.Op Fl r Ar seconds 45.Op Ar host Op Ar port 46.Nm ftp 47.Op Fl C 48.Op Fl o Ar output 49.Sm off 50.No ftp:// Oo Ar user : password No @ 51.Oc Ar host Oo : Ar port 52.Oc No / Ar file Oo / 53.Oc 54.Sm on 55.Ar ... 56.Nm ftp 57.Op Fl C 58.Op Fl c Ar cookie 59.Op Fl o Ar output 60.Sm off 61.No http:// Ar host Oo : Ar port 62.Oc No / Ar file 63.Sm on 64.Ar ... 65.Nm ftp 66.Op Fl C 67.Op Fl c Ar cookie 68.Op Fl o Ar output 69.Sm off 70.No https:// Ar host Oo : Ar port 71.Oc No / Ar file 72.Sm on 73.Ar ... 74.Nm ftp 75.Op Fl C 76.Op Fl o Ar output 77.Sm off 78.No file: Ar file 79.Sm on 80.Ar ... 81.Nm ftp 82.Op Fl C 83.Op Fl o Ar output 84.Sm off 85.Ar host : No / Ar file Oo / 86.Oc 87.Sm on 88.Ar ... 89.Sh DESCRIPTION 90.Nm 91is the user interface to the 92.Tn ARPANET 93standard File Transfer Protocol (FTP). 94The program allows a user to transfer files to and from a 95remote network site. 96.Pp 97The latter five usage formats will fetch a file using either the 98FTP, HTTP, or HTTPS protocols into the current directory. 99This is ideal for scripts. 100Refer to 101.Sx AUTO-FETCHING FILES 102below for more information. 103.Pp 104The options are as follows: 105.Bl -tag -width Ds 106.It Fl 4 107Forces 108.Nm 109to use IPv4 addresses only. 110.It Fl 6 111Forces 112.Nm 113to use IPv6 addresses only. 114.It Fl A 115Force active mode FTP. 116By default, 117.Nm 118will try to use passive mode FTP and fall back to active mode 119if passive is not supported by the server. 120This option causes 121.Nm 122to always use an active connection. 123It is only useful for connecting 124to very old servers that do not implement passive mode properly. 125.It Fl a 126Causes 127.Nm 128to bypass the normal login procedure and use an anonymous login instead. 129.It Fl C 130Continue a previously interrupted file transfer. 131.Nm 132will continue transferring from an offset equal to the length of 133.Ar file . 134.Pp 135Resuming HTTP(S) transfers are only supported 136if the remote server supports the 137.Dq Range 138header. 139.It Fl c Ar cookie 140Load a Netscape-like cookiejar file 141for HTTP and HTTPS transfers. 142With this option relevant cookies from the jar are sent with each HTTP(S) 143request. 144Setting the 145.Ev http_cookies 146environment variable has the same effect. 147If both the 148.Ev http_cookies 149environment variable is set and the 150.Fl c 151argument is given, the latter takes precedence. 152.It Fl d 153Enables debugging. 154.It Fl E 155Disables EPSV/EPRT command on IPv4 connections. 156.It Fl e 157Disables command line editing. 158Useful for Emacs ange-ftp. 159.It Fl g 160Disables file name globbing. 161.It Fl i 162Turns off interactive prompting during 163multiple file transfers. 164.It Fl k Ar seconds 165When greater than zero, 166sends a byte after each 167.Ar seconds 168period over the control connection during long transfers, 169so that incorrectly configured network equipment won't 170aggressively drop it. 171The FTP protocol supports a 172.Dv NOOP 173command that can be used for that purpose. 174This assumes the FTP server can deal with extra commands coming over 175the control connection during a transfer. 176Well-behaved servers queue those commands, and process them after the 177transfer. 178By default, 179.Nm 180will send a byte every 60 seconds. 181.It Fl m 182Causes 183.Nm 184to always display the progress meter in cases where it would not do 185so by default. 186.It Fl n 187Restrains 188.Nm 189from attempting 190.Dq auto-login 191upon initial connection. 192If auto-login is enabled, 193.Nm 194will check the 195.Pa .netrc 196file (see below) in the user's home directory for an entry describing 197an account on the remote machine. 198If no entry exists, 199.Nm 200will prompt for the remote machine login name (default is the user 201identity on the local machine), and, if necessary, prompt for a password 202and an account with which to log in. 203.It Fl o Ar output 204When fetching a single file or URL, save the contents in 205.Ar output . 206To make the contents go to stdout, 207use 208.Sq - 209for 210.Ar output . 211.It Fl P Ar port 212Sets the port number to 213.Ar port . 214.It Fl p 215Enable passive mode operation for use behind connection filtering firewalls. 216This option has been deprecated as 217.Nm 218now tries to use passive mode by default, falling back to active mode 219if the server does not support passive connections. 220.It Fl r Ar seconds 221Retry to connect if failed, pausing for number of 222.Ar seconds . 223.It Fl t 224Enables packet tracing. 225.It Fl V 226Disable verbose mode, overriding the default of enabled when input 227is from a terminal. 228.It Fl v 229Enable verbose mode. 230This is the default if input is from a terminal. 231Forces 232.Nm 233to show all responses from the remote server, as well 234as report on data transfer statistics. 235.El 236.Pp 237The host with which 238.Nm 239is to communicate may be specified on the command line. 240If this is done, 241.Nm 242will immediately attempt to establish a connection to an 243FTP server on that host; otherwise, 244.Nm 245will enter its command interpreter and await instructions 246from the user. 247When 248.Nm 249is awaiting commands, the prompt 250.Dq ftp\*(Gt 251is provided to the user. 252The following commands are recognized 253by 254.Nm : 255.Bl -tag -width Fl 256.It Ic \&! Oo Ar command 257.Op Ar arg ... 258.Oc 259Invoke an interactive shell on the local machine. 260If there are arguments, the first is taken to be a command to execute 261directly, with the rest of the arguments as its arguments. 262.It Ic \&$ Ar macro-name Op Ar arg ... 263Execute the macro 264.Ar macro-name 265that was defined with the 266.Ic macdef 267command. 268Arguments are passed to the macro unglobbed. 269.It Ic \&? Op Ar command 270A synonym for 271.Ic help . 272.It Ic account Op Ar password 273Supply a supplemental password required by a remote system for access 274to resources once a login has been successfully completed. 275If no argument is included, the user will be prompted for an account 276password in a non-echoing input mode. 277.It Ic append Ar local-file Op Ar remote-file 278Append a local file to a file on the remote machine. 279If 280.Ar remote-file 281is left unspecified, the local file name is used in naming the 282remote file after being altered by any 283.Ic ntrans 284or 285.Ic nmap 286setting. 287File transfer uses the current settings for 288.Ic type , 289.Ic format , 290.Ic mode , 291and 292.Ic structure . 293.It Ic ascii 294Set the file transfer 295.Ic type 296to network 297.Tn ASCII . 298.It Ic bell Op Ic on | off 299Arrange that a bell be sounded after each file transfer 300command is completed. 301.It Ic binary 302Set the file transfer 303.Ic type 304to support binary image transfer. 305This is the default type. 306.It Ic bye 307Terminate the FTP session with the remote server and exit 308.Nm . 309An end-of-file will also terminate the session and exit. 310.It Ic case Op Ic on | off 311Toggle remote computer file name case mapping during 312.Ic mget 313commands. 314When 315.Ic case 316is on (default is off), remote computer file names with all letters in 317upper case are written in the local directory with the letters mapped 318to lower case. 319.It Ic cd Ar remote-directory 320Change the working directory on the remote machine 321to 322.Ar remote-directory . 323.It Ic cdup 324Change the remote machine working directory to the parent of the 325current remote machine working directory. 326.It Ic chmod Ar mode file 327Change the permission modes of 328.Ar file 329on the remote 330system to 331.Ar mode . 332.It Ic close 333Terminate the FTP session with the remote server and 334return to the command interpreter. 335Any defined macros are erased. 336.It Ic cr Op Ic on | off 337Toggle carriage return stripping during 338ASCII type file retrieval. 339Records are denoted by a carriage return/linefeed sequence 340during ASCII type file transfer. 341When 342.Ic cr 343is on (the default), carriage returns are stripped from this 344sequence to conform with the 345.Ux 346single linefeed record delimiter. 347Records on non-UNIX 348remote systems may contain single linefeeds; 349when an ASCII type transfer is made, these linefeeds may be 350distinguished from a record delimiter only when 351.Ic cr 352is off. 353.It Ic debug Oo Ic on | off | 354.Ar debuglevel 355.Oc 356Toggle debugging mode. 357If an optional 358.Ar debuglevel 359is specified, it is used to set the debugging level. 360When debugging is on, 361.Nm 362prints each command sent to the remote machine, 363preceded by the string 364.Ql --\*(Gt . 365.It Ic delete Ar remote-file 366Delete the file 367.Ar remote-file 368on the remote machine. 369.It Ic dir Op Ar remote-directory Op Ar local-file 370A synonym for 371.Ic ls . 372.It Ic disconnect 373A synonym for 374.Ic close . 375.It Ic edit Op Ic on | off 376Toggle command line editing, and context sensitive command and file 377completion. 378This is automatically enabled if input is from a terminal, and 379disabled otherwise. 380.It Ic epsv4 Op Ic on | off 381Toggle use of EPSV/EPRT command on IPv4 connection. 382.It Ic exit 383A synonym for 384.Ic bye . 385.It Ic form Ar format 386Set the file transfer 387.Ic form 388to 389.Ar format . 390The default format is 391.Dq file . 392.It Ic ftp Ar host Op Ar port 393A synonym for 394.Ic open . 395.It Ic gate Oo Ic on | off | 396.Ar host Op Ar port 397.Oc 398Toggle gate-ftp mode. 399This will not be permitted if the gate-ftp server hasn't been set 400(either explicitly by the user, or from the 401.Ev FTPSERVER 402environment variable). 403If 404.Ar host 405is given, 406then gate-ftp mode will be enabled, and the gate-ftp server will be set to 407.Ar host . 408If 409.Ar port 410is also given, that will be used as the port to connect to on the 411gate-ftp server. 412.It Ic get Ar remote-file Op Ar local-file 413Retrieve the 414.Ar remote-file 415and store it on the local machine. 416If the local 417file name is not specified, it is given the same 418name it has on the remote machine, subject to 419alteration by the current 420.Ic case , 421.Ic ntrans , 422and 423.Ic nmap 424settings. 425The current settings for 426.Ic type , 427.Ic form , 428.Ic mode , 429and 430.Ic structure 431are used while transferring the file. 432.It Ic glob Op Ic on | off 433Toggle filename expansion for 434.Ic mdelete , 435.Ic mget 436and 437.Ic mput . 438If globbing is turned off with 439.Ic glob , 440the file name arguments 441are taken literally and not expanded. 442Globbing for 443.Ic mput 444is done as in 445.Xr csh 1 . 446For 447.Ic mdelete 448and 449.Ic mget , 450each remote file name is expanded 451separately on the remote machine and the lists are not merged. 452Expansion of a directory name is likely to be 453different from expansion of the name of an ordinary file: 454the exact result depends on the foreign operating system and FTP server, 455and can be previewed by doing 456.Dq mls remote-files - . 457Note: 458.Ic mget 459and 460.Ic mput 461are not meant to transfer 462entire directory subtrees of files. 463That can be done by 464transferring a 465.Xr tar 1 466archive of the subtree (in binary mode). 467.It Ic hash Oo Ic on | off | 468.Ar size 469.Oc 470Toggle hash mark 471.Pq Ql # 472printing for each data block transferred. 473The size of a data block defaults to 1024 bytes. 474This can be changed by specifying 475.Ar size 476in bytes. 477.It Ic help Op Ar command 478Print an informative message about the meaning of 479.Ar command . 480If no argument is given, 481.Nm 482prints a list of the known commands. 483.It Ic idle Op Ar seconds 484Set the inactivity timer on the remote server to 485.Ar seconds 486seconds. 487If 488.Ar seconds 489is omitted, the current inactivity timer is printed. 490.It Ic lcd Op Ar local-directory 491Change the working directory on the local machine. 492If 493no 494.Ar local-directory 495is specified, the user's home directory is used. 496.It Ic less Ar file 497A synonym for 498.Ic page . 499.It Ic lpwd 500Print the working directory on the local machine. 501.It Ic ls Op Ar remote-directory Op Ar local-file 502Print a listing of the contents of a directory on the remote machine. 503The listing includes any system-dependent information that the server 504chooses to include; for example, most 505.Ux 506systems will produce output from the command 507.Ql ls -l . 508If 509.Ar remote-directory 510is left unspecified, the current working directory is used. 511If interactive prompting is on, 512.Nm 513will prompt the user to verify that the last argument is indeed the 514target local file for receiving 515.Ic ls 516output. 517If no local file is specified, or if 518.Ar local-file 519is 520.Sq - , 521the output is sent to the terminal. 522.It Ic macdef Ar macro-name 523Define a macro. 524Subsequent lines are stored as the macro 525.Ar macro-name ; 526a null line (consecutive newline characters 527in a file or 528carriage returns from the terminal) terminates macro input mode. 529There is a limit of 16 macros and 4096 total characters in all 530defined macros. 531Macro names can be a maximum of 8 characters. 532Macros are only applicable to the current session they are 533defined in (or if defined outside a session, to the session 534invoked with the next 535.Ic open 536command), and remain defined until a 537.Ic close 538command is executed. 539To invoke a macro, 540use the 541.Ic $ 542command (see above). 543.Pp 544The macro processor interprets 545.Ql $ 546and 547.Ql \e 548as special characters. 549A 550.Ql $ 551followed by a number (or numbers) is replaced by the 552corresponding argument on the macro invocation command line. 553A 554.Ql $ 555followed by an 556.Sq i 557tells the macro processor that the 558executing macro is to be looped. 559On the first pass 560.Ql $i 561is 562replaced by the first argument on the macro invocation command line, 563on the second pass it is replaced by the second argument, and so on. 564A 565.Ql \e 566followed by any character is replaced by that character. 567Use the 568.Ql \e 569to prevent special treatment of the 570.Ql $ . 571.It Ic mdelete Op Ar remote-files 572Delete the 573.Ar remote-files 574on the remote machine. 575.It Ic mdir Ar remote-files local-file 576A synonym for 577.Ic mls . 578.It Xo Ic mget 579.Op Fl cnr 580.Op Fl d Ar depth 581.Ar remote-files 582.Xc 583Expand the 584.Ar remote-files 585on the remote machine 586and do a 587.Ic get 588for each file name thus produced. 589See 590.Ic glob 591for details on the filename expansion. 592Resulting file names will then be processed according to 593.Ic case , 594.Ic ntrans , 595and 596.Ic nmap 597settings. 598Files are transferred into the local working directory, 599which can be changed with 600.Ql lcd directory ; 601new local directories can be created with 602.Ql "\&! mkdir directory" . 603.Pp 604The options are as follows: 605.Bl -tag -width Ds 606.It Fl c 607Use 608.Ic reget 609instead of 610.Ic get . 611.It Fl d Ar depth 612Specify the maximum recursion level 613.Ar depth . 614The default is 0, which means unlimited. 615.It Fl n 616Use 617.Ic newer 618instead of 619.Ic get . 620.It Fl r 621Recursively descend the directory tree, transferring all files and 622directories. 623.El 624.It Ic mkdir Ar directory-name 625Make a directory on the remote machine. 626.It Ic mls Ar remote-files local-file 627Like 628.Ic ls , 629except multiple remote files may be specified, 630and the 631.Ar local-file 632must be specified. 633If interactive prompting is on, 634.Nm 635will prompt the user to verify that the last argument is indeed the 636target local file for receiving 637.Ic mls 638output. 639.It Ic mode Op Ar mode-name 640Set the file transfer 641.Ic mode 642to 643.Ar mode-name . 644The default mode is 645.Dq stream 646mode. 647.It Ic modtime Ar file 648Show the last modification time of 649.Ar file 650on the remote machine. 651.It Ic more Ar file 652A synonym for 653.Ic page . 654.It Xo Ic mput 655.Op Fl c 656.Ar local-files 657.Xc 658Expand wild cards in the list of local files given as arguments 659and do a 660.Ic put 661for each file in the resulting list. 662See 663.Ic glob 664for details of filename expansion. 665Resulting file names will then be processed according to 666.Ic ntrans 667and 668.Ic nmap 669settings. 670.Pp 671If the 672.Fl c 673flag is specified then 674.Ic reput 675is used instead of 676.Ic put . 677.It Xo Ic msend 678.Op Fl c 679.Ar local-files 680.Xc 681A synonym for 682.Ic mput . 683.It Ic newer Ar remote-file Op Ar local-file 684Get the file only if the modification time of the remote file is more 685recent than the file on the current system. 686If the file does not 687exist on the current system, the remote file is considered 688.Ic newer . 689Otherwise, this command is identical to 690.Ar get . 691.It Ic nlist Op Ar remote-directory Op Ar local-file 692Print a list of the files in a 693directory on the remote machine. 694If 695.Ar remote-directory 696is left unspecified, the current working directory is used. 697If interactive prompting is on, 698.Nm 699will prompt the user to verify that the last argument is indeed the 700target local file for receiving 701.Ic nlist 702output. 703If no local file is specified, or if 704.Ar local-file 705is 706.Sq - , 707the output is sent to the terminal. 708Note that on some servers, the 709.Ic nlist 710command will only return information on normal files (not directories 711or special files). 712.It Ic nmap Op Ar inpattern outpattern 713Set or unset the filename mapping mechanism. 714If no arguments are specified, the filename mapping mechanism is unset. 715If arguments are specified, remote filenames are mapped during 716.Ic mput 717commands and 718.Ic put 719commands issued without a specified remote target filename. 720If arguments are specified, local filenames are mapped during 721.Ic mget 722commands and 723.Ic get 724commands issued without a specified local target filename. 725This command is useful when connecting to a non-UNIX remote computer 726with different file naming conventions or practices. 727.Pp 728The mapping follows the pattern set by 729.Ar inpattern 730and 731.Ar outpattern . 732.Ar inpattern 733is a template for incoming filenames (which may have already been 734processed according to the 735.Ic ntrans 736and 737.Ic case 738settings). 739Variable templating is accomplished by including the 740sequences 741.Ql $1 , 742.Ql $2 , 743\&..., 744.Ql $9 745in 746.Ar inpattern . 747Use 748.Ql \e 749to prevent this special treatment of the 750.Ql $ 751character. 752All other characters are treated literally, and are used to determine the 753.Ic nmap 754.Ar inpattern 755variable values. 756.Pp 757For example, given 758.Ar inpattern 759$1.$2 and the remote file name "mydata.data", $1 would have the value 760"mydata", and $2 would have the value "data". 761The 762.Ar outpattern 763determines the resulting mapped filename. 764The sequences 765.Ql $1 , 766.Ql $2 , 767\&..., 768.Ql $9 769are replaced by any value resulting from the 770.Ar inpattern 771template. 772The sequence 773.Ql $0 774is replaced by the original filename. 775Additionally, the sequence 776.Sq Op Ar seq1 , Ar seq2 777is replaced by 778.Ar seq1 779if 780.Ar seq1 781is not a null string; otherwise it is replaced by 782.Ar seq2 . 783For example: 784.Pp 785.Dl nmap $1.$2.$3 [$1,$2].[$2,file] 786.Pp 787This command would yield the output filename 788.Pa myfile.data 789for input filenames 790.Pa myfile.data 791and 792.Pa myfile.data.old ; 793.Pa myfile.file 794for the input filename 795.Pa myfile ; 796and 797.Pa myfile.myfile 798for the input filename 799.Pa .myfile . 800Spaces may be included in 801.Ar outpattern 802by quoting them, 803as in the following example: 804.Bd -literal -offset indent 805nmap $1.$2 "$1 $2" 806.Ed 807.Pp 808Use the 809.Ql \e 810character to prevent special treatment 811of the 812.Ql $ , 813.Ql \&[ , 814.Ql \&] , 815and 816.Ql \&, 817characters. 818.It Ic ntrans Op Ar inchars Op Ar outchars 819Set or unset the filename character translation mechanism. 820If no arguments are specified, the filename character 821translation mechanism is unset. 822If arguments are specified, characters in 823remote filenames are translated during 824.Ic mput 825commands and 826.Ic put 827commands issued without a specified remote target filename. 828If arguments are specified, characters in 829local filenames are translated during 830.Ic mget 831commands and 832.Ic get 833commands issued without a specified local target filename. 834This command is useful when connecting to a non-UNIX remote computer 835with different file naming conventions or practices. 836Characters in a filename matching a character in 837.Ar inchars 838are replaced with the corresponding character in 839.Ar outchars . 840If the character's position in 841.Ar inchars 842is longer than the length of 843.Ar outchars , 844the character is deleted from the file name. 845.It Ic open Ar host Op Ar port 846Establish a connection to the specified 847.Ar host 848FTP server. 849An optional port number may be supplied, 850in which case 851.Nm 852will attempt to contact an FTP server at that port. 853If the 854.Ic auto-login 855option is on (default), 856.Nm 857will also attempt to automatically log the user in to 858the FTP server (see below). 859.It Ic page Ar file 860Retrieve 861.Ic file 862and display with the program defined in 863.Ev PAGER 864(defaulting to 865.Xr more 1 866if 867.Ev PAGER 868is null or not defined). 869.It Ic passive Op Ic on | off 870Toggle passive mode. 871If passive mode is turned on (default is on), 872.Nm 873will send a 874.Dv EPSV 875command for all data connections instead of the usual 876.Dv PORT 877command. 878The 879.Dv PASV 880command requests that the remote server open a port for the data connection 881and return the address of that port. 882The remote server listens on that port and the client connects to it. 883When using the more traditional 884.Dv PORT 885command, the client listens on a port and sends that address to the remote 886server, who connects back to it. 887Passive mode is useful when using 888.Nm 889through a gateway router or host that controls the directionality of 890traffic. 891(Note that though FTP servers are required to support the 892.Dv PASV 893command by RFC 1123, some do not.) 894.It Ic preserve Op Ic on | off 895Toggle preservation of modification times on retrieved files. 896.It Ic progress Op Ic on | off 897Toggle display of transfer progress bar. 898The progress bar will be disabled for a transfer that has 899.Ar local-file 900as 901.Sq - 902or a command that starts with 903.Sq \&| . 904Refer to 905.Sx FILE NAMING CONVENTIONS 906for more information. 907.It Ic prompt Op Ic on | off 908Toggle interactive prompting. 909Interactive prompting 910occurs during multiple file transfers to allow the 911user to selectively retrieve or store files. 912If prompting is turned off (default is on), any 913.Ic mget 914or 915.Ic mput 916will transfer all files, and any 917.Ic mdelete 918will delete all files. 919.Pp 920When prompting is on, the following commands are available at a prompt: 921.Bl -tag -width 2n -offset indent 922.It Ic ?\& 923Print help message. 924.It Ic a 925Answer 926.Dq yes 927to the current file and automatically answer 928.Dq yes 929to any remaining files for the current command. 930.It Ic n 931Do not transfer the file. 932.It Ic p 933Answer 934.Dq yes 935to the current file and turn off prompt mode 936(as if 937.Dq prompt off 938had been given). 939.It Ic q 940Answer 941.Dq no 942to the current file and automatically answer 943.Dq no 944to any remaining files for the current command. 945.It Ic y 946Transfer the file. 947.El 948.It Ic proxy Ar command 949Execute an FTP command on a secondary control connection. 950This command allows simultaneous connection to two remote FTP 951servers for transferring files between the two servers. 952The first 953.Ic proxy 954command should be an 955.Ic open , 956to establish the secondary control connection. 957Enter the command 958.Ic proxy ?\& 959to see other FTP commands executable on the 960secondary connection. 961The following commands behave differently when prefaced by 962.Ic proxy : 963.Ic open 964will not define new macros during the auto-login process; 965.Ic close 966will not erase existing macro definitions; 967.Ic get 968and 969.Ic mget 970transfer files from the host on the primary control connection 971to the host on the secondary control connection; and 972.Ic put , 973.Ic mput , 974and 975.Ic append 976transfer files from the host on the secondary control connection 977to the host on the primary control connection. 978Third party file transfers depend upon support of the FTP protocol 979.Dv PASV 980command by the server on the secondary control connection. 981.It Ic put Ar local-file Op Ar remote-file 982Store a local file on the remote machine. 983If 984.Ar remote-file 985is left unspecified, the local file name is used 986after processing according to any 987.Ic ntrans 988or 989.Ic nmap 990settings 991in naming the remote file. 992File transfer uses the 993current settings for 994.Ic type , 995.Ic format , 996.Ic mode , 997and 998.Ic structure . 999.It Ic pwd 1000Print the name of the current working directory on the remote 1001machine. 1002.It Ic quit 1003A synonym for 1004.Ic bye . 1005.It Ic quote Ar arg ... 1006The arguments specified are sent, verbatim, to the remote FTP server. 1007.It Ic recv Ar remote-file Op Ar local-file 1008A synonym for 1009.Ic get . 1010.It Ic reget Ar remote-file Op Ar local-file 1011Reget acts like get, except that if 1012.Ar local-file 1013exists and is 1014smaller than 1015.Ar remote-file , 1016.Ar local-file 1017is presumed to be 1018a partially transferred copy of 1019.Ar remote-file 1020and the transfer 1021is continued from the apparent point of failure. 1022This command 1023is useful when transferring very large files over networks that 1024are prone to dropping connections. 1025.It Ic rename Ar from-name to-name 1026Rename the file 1027.Ar from-name 1028on the remote machine to the file 1029.Ar to-name . 1030.It Ic reput Ar local-file Op Ar remote-file 1031Reput acts like put, except that if 1032.Ar remote-file 1033exists and is 1034smaller than 1035.Ar local-file , 1036.Ar remote-file 1037is presumed to be 1038a partially transferred copy of 1039.Ar local-file 1040and the transfer 1041is continued from the apparent point of failure. 1042This command 1043is useful when transferring very large files over networks that 1044are prone to dropping connections. 1045.It Ic reset 1046Clear reply queue. 1047This command re-synchronizes command/reply sequencing with the remote 1048FTP server. 1049Resynchronization may be necessary following a violation of the FTP protocol 1050by the remote server. 1051.It Ic restart Ar marker 1052Restart the immediately following 1053.Ic get 1054or 1055.Ic put 1056at the 1057indicated 1058.Ar marker . 1059On 1060.Ux 1061systems, 1062.Ar marker 1063is usually a byte 1064offset into the file. 1065.It Ic rhelp Op Ar command-name 1066Request help from the remote FTP server. 1067If a 1068.Ar command-name 1069is specified, it is supplied to the server as well. 1070.It Ic rmdir Ar directory-name 1071Delete a directory on the remote machine. 1072.It Ic rstatus Op Ar file 1073With no arguments, show status of remote machine. 1074If 1075.Ar file 1076is specified, show status of 1077.Ar file 1078on remote machine. 1079.It Ic runique Op Ic on | off 1080Toggle storing of files on the local system with unique filenames. 1081If a file already exists with a name equal to the target 1082local filename for a 1083.Ic get 1084or 1085.Ic mget 1086command, a 1087.Dq .1 1088is appended to the name. 1089If the resulting name matches another existing file, 1090a 1091.Dq .2 1092is appended to the original name. 1093If this process continues up to 1094.Dq .99 , 1095an error message is printed, and the transfer does not take place. 1096The generated unique filename will be reported. 1097Note that 1098.Ic runique 1099will not affect local files generated from a shell command 1100(see below). 1101The default value is off. 1102.It Ic send Ar local-file Op Ar remote-file 1103A synonym for 1104.Ic put . 1105.It Ic sendport Op Ic on | off 1106Toggle the use of 1107.Dv PORT 1108commands. 1109By default, 1110.Nm 1111will attempt to use a 1112.Dv PORT 1113command when establishing 1114a connection for each data transfer. 1115The use of 1116.Dv PORT 1117commands can prevent delays 1118when performing multiple file transfers. 1119If the 1120.Dv PORT 1121command fails, 1122.Nm 1123will use the default data port. 1124When the use of 1125.Dv PORT 1126commands is disabled, no attempt will be made to use 1127.Dv PORT 1128commands for each data transfer. 1129This is useful for certain FTP implementations which do ignore 1130.Dv PORT 1131commands but, incorrectly, indicate they've been accepted. 1132.It Ic site Ar arg ... 1133The arguments specified are sent, verbatim, to the remote FTP server as a 1134.Dv SITE 1135command. 1136.It Ic size Ar file 1137Return size of 1138.Ar file 1139on remote machine. 1140.It Ic status 1141Show the current status of 1142.Nm . 1143.\" .It Ic struct Op Ar struct-name 1144.\" Set the file transfer 1145.\" .Ar structure 1146.\" to 1147.\" .Ar struct-name . 1148.\" By default, 1149.\" .Dq file 1150.\" structure is used. 1151.It Ic sunique Op Ic on | off 1152Toggle storing of files on remote machine under unique file names. 1153The remote FTP server must support the FTP protocol 1154.Dv STOU 1155command for 1156successful completion. 1157The remote server will report the unique name. 1158Default value is off. 1159.It Ic system 1160Show the type of operating system running on the remote machine. 1161.It Ic tenex 1162Set the file transfer type to that needed to 1163talk to 1164.Tn TENEX 1165machines. 1166.It Ic trace Op Ic on | off 1167Toggle packet tracing. 1168.It Ic type Op Ar type-name 1169Set the file transfer 1170.Ic type 1171to 1172.Ar type-name . 1173If no type is specified, the current type 1174is printed. 1175The default type is 1176.Dq binary . 1177.It Ic umask Op Ar newmask 1178Set the default umask on the remote server to 1179.Ar newmask . 1180If 1181.Ar newmask 1182is omitted, the current umask is printed. 1183.It Xo 1184.Ic user Ar username 1185.Op Ar password Op Ar account 1186.Xc 1187Identify yourself to the remote FTP server. 1188If the 1189.Ar password 1190is not specified and the server requires it, 1191.Nm 1192will prompt the user for it (after disabling local echo). 1193If an 1194.Ar account 1195field is not specified, and the FTP server requires it, 1196the user will be prompted for it. 1197If an 1198.Ar account 1199field is specified, an account command will 1200be relayed to the remote server after the login sequence 1201is completed if the remote server did not require it 1202for logging in. 1203Unless 1204.Nm 1205is invoked with 1206.Dq auto-login 1207disabled, this process is done automatically on initial connection to the 1208FTP server. 1209.It Ic verbose Op Ic on | off 1210Toggle verbose mode. 1211In verbose mode, all responses from 1212the FTP server are displayed to the user. 1213In addition, 1214if verbose is on, when a file transfer completes, statistics 1215regarding the efficiency of the transfer are reported. 1216By default, 1217verbose is on. 1218.El 1219.Pp 1220Command arguments which have embedded spaces may be quoted with 1221quote 1222.Pq Ql \&" 1223marks. 1224.Pp 1225Commands which toggle settings can take an explicit 1226.Ic on 1227or 1228.Ic off 1229argument to force the setting appropriately. 1230.Pp 1231If 1232.Nm 1233receives a 1234.Dv SIGINFO 1235(see the 1236.Dq status 1237argument of 1238.Xr stty 1 ) 1239signal whilst a transfer is in progress, the current transfer rate 1240statistics will be written to the standard error output, in the 1241same format as the standard completion message. 1242.Sh AUTO-FETCHING FILES 1243In addition to standard commands, this version of 1244.Nm 1245supports an auto-fetch feature. 1246To enable auto-fetch, simply pass the list of hostnames/files 1247on the command line. 1248.Pp 1249The following formats are valid syntax for an auto-fetch element: 1250.Bl -tag -width Ds 1251.It host:/file[/] 1252.Dq Classic 1253.Nm 1254format. 1255.It ftp://[user:password@]host[:port]/file[/] 1256An FTP URL, retrieved using the FTP protocol if 1257.Ev ftp_proxy 1258isn't defined. 1259Otherwise, transfer using HTTP via the proxy defined in 1260.Ev ftp_proxy . 1261If 1262.Ar user : Ns Ar password Ns @ 1263is given and 1264.Ev ftp_proxy 1265isn't defined, log in as 1266.Ar user 1267with a password of 1268.Ar password . 1269.It http://host[:port]/file 1270An HTTP URL, retrieved using the HTTP protocol. 1271If 1272.Ev http_proxy 1273is defined, it is used as a URL to an HTTP proxy server. 1274.It https://host[:port]/file 1275An HTTPS URL, retrieved using the HTTPS protocol. 1276If 1277.Ev http_proxy 1278is defined, this HTTPS proxy server will be used to fetch the 1279file using the CONNECT method. 1280.It file:file 1281.Ar file 1282is retrieved from a mounted file system. 1283.El 1284.Pp 1285If a classic format or an FTP URL format has a trailing 1286.Sq / , 1287then 1288.Nm 1289will connect to the site and 1290.Ic cd 1291to the directory given as the path, and leave the user in interactive 1292mode ready for further input. 1293.Pp 1294If successive auto-fetch FTP elements refer to the same host, then 1295the connection is maintained between transfers, reducing overhead on 1296connection creation and deletion. 1297.Pp 1298If 1299.Ar file 1300contains a glob character and globbing is enabled 1301(see 1302.Ic glob ) , 1303then the equivalent of 1304.Ic mget Ar file 1305is performed. 1306.Pp 1307If no 1308.Fl o 1309option is specified, and 1310the directory component of 1311.Ar file 1312contains no globbing characters, 1313then 1314it is stored in the current directory as the 1315.Xr basename 1 1316of 1317.Ar file . 1318If 1319.Fl o Ar output 1320is specified, then 1321.Ar file 1322is stored as 1323.Ar output . 1324Otherwise, the remote name is used as the local name. 1325.Sh ABORTING A FILE TRANSFER 1326To abort a file transfer, use the terminal interrupt key 1327(usually Ctrl-C). 1328Sending transfers will be immediately halted. 1329Receiving transfers will be halted by sending an FTP protocol 1330.Dv ABOR 1331command to the remote server, and discarding any further data received. 1332The speed at which this is accomplished depends upon the remote 1333server's support for 1334.Dv ABOR 1335processing. 1336If the remote server does not support the 1337.Dv ABOR 1338command, an 1339.Ql ftp\*(Gt 1340prompt will not appear until the remote server has completed 1341sending the requested file. 1342.Pp 1343The terminal interrupt key sequence will be ignored when 1344.Nm 1345has completed any local processing and is awaiting a reply 1346from the remote server. 1347A long delay in this mode may result from the ABOR processing described 1348above, or from unexpected behavior by the remote server, including 1349violations of the FTP protocol. 1350If the delay results from unexpected remote server behavior, the local 1351.Nm 1352program must be killed by hand. 1353.Sh FILE NAMING CONVENTIONS 1354Files specified as arguments to 1355.Nm 1356commands are processed according to the following rules. 1357.Bl -enum 1358.It 1359If the file name 1360.Sq - 1361is specified, the standard input (for reading) 1362or standard output (for writing) 1363is used. 1364.It 1365If the first character of the file name is 1366.Sq \&| , 1367the 1368remainder of the argument is interpreted as a shell command. 1369.Nm 1370then forks a shell, using 1371.Xr popen 3 1372with the argument supplied, and reads (writes) from the standard output 1373(standard input). 1374If the shell command includes spaces, the argument 1375must be quoted; e.g., 1376.Qq ls -lt . 1377A particularly 1378useful example of this mechanism is: 1379.Qq dir |more . 1380.It 1381Failing the above checks, if 1382.Dq globbing 1383is enabled, 1384local file names are expanded 1385according to the rules used in the 1386.Xr csh 1 ; 1387c.f. the 1388.Ic glob 1389command. 1390If the 1391.Nm 1392command expects a single local file (e.g., 1393.Ic put ) , 1394only the first filename generated by the 1395.Dq globbing 1396operation is used. 1397.It 1398For 1399.Ic mget 1400commands and 1401.Ic get 1402commands with unspecified local file names, the local filename is 1403the remote filename, which may be altered by a 1404.Ic case , 1405.Ic ntrans , 1406or 1407.Ic nmap 1408setting. 1409The resulting filename may then be altered if 1410.Ic runique 1411is on. 1412.It 1413For 1414.Ic mput 1415commands and 1416.Ic put 1417commands with unspecified remote file names, the remote filename is 1418the local filename, which may be altered by a 1419.Ic ntrans 1420or 1421.Ic nmap 1422setting. 1423The resulting filename may then be altered by the remote server if 1424.Ic sunique 1425is on. 1426.El 1427.Sh FILE TRANSFER PARAMETERS 1428The FTP specification specifies many parameters which may 1429affect a file transfer. 1430The 1431.Ic type 1432may be one of 1433.Dq ascii , 1434.Dq binary , 1435.Dq image , 1436.Dq ebcdic 1437.Pq currently not supported 1438or 1439.Dq tenex 1440(local byte size 8, for PDP-10's and PDP-20's mostly). 1441.Nm 1442supports the ASCII and image types of file transfer, 1443plus local byte size 8 for 1444.Ic tenex 1445mode transfers. 1446.Pp 1447.Nm 1448supports only the default values for the remaining 1449file transfer parameters: 1450.Ic mode , 1451.Ic form , 1452and 1453.Ic struct . 1454.Sh THE .netrc FILE 1455The 1456.Pa .netrc 1457file contains login and initialization information 1458used by the auto-login process. 1459It resides in the user's home directory. 1460The following tokens are recognized; they may be separated by spaces, 1461tabs, or new-lines: 1462.Bl -tag -width password 1463.It Ic machine Ar name 1464Identify a remote machine 1465.Ar name . 1466The auto-login process searches the 1467.Pa .netrc 1468file for a 1469.Ic machine 1470token that matches the remote machine specified on the 1471.Nm 1472command line or as an 1473.Ic open 1474command argument. 1475Once a match is made, the subsequent 1476.Pa .netrc 1477tokens are processed, 1478stopping when the end of file is reached or another 1479.Ic machine 1480or a 1481.Ic default 1482token is encountered. 1483.It Ic default 1484This is the same as 1485.Ic machine 1486.Ar name 1487except that 1488.Ic default 1489matches any name. 1490There can be only one 1491.Ic default 1492token, and it must be after all 1493.Ic machine 1494tokens. 1495This is normally used as: 1496.Pp 1497.Dl default login anonymous password user@site 1498.Pp 1499thereby giving the user 1500.Ar automatic 1501anonymous FTP login to 1502machines not specified in 1503.Pa .netrc . 1504This can be overridden 1505by using the 1506.Fl n 1507flag to disable auto-login. 1508.It Ic login Ar name 1509Identify a user on the remote machine. 1510If this token is present, the auto-login process will initiate 1511a login using the specified 1512.Ar name . 1513.It Ic password Ar string 1514Supply a password. 1515If this token is present, the auto-login process will supply the 1516specified string if the remote server requires a password as part 1517of the login process. 1518Note that if this token is present in the 1519.Pa .netrc 1520file for any user other 1521than 1522.Ar anonymous , 1523.Nm 1524will abort the auto-login process if the 1525.Pa .netrc 1526is readable by 1527anyone besides the user. 1528.It Ic account Ar string 1529Supply an additional account password. 1530If this token is present, the auto-login process will supply the 1531specified string if the remote server requires an additional 1532account password, or the auto-login process will initiate an 1533.Dv ACCT 1534command if it does not. 1535.It Ic macdef Ar name 1536Define a macro. 1537This token functions like the 1538.Nm 1539.Ic macdef 1540command functions. 1541A macro is defined with the specified name; its contents begin with the 1542next 1543.Pa .netrc 1544line and continue until a null line (consecutive new-line 1545characters) is encountered. 1546Like the other tokens in the 1547.Pa .netrc 1548file, a 1549.Ic macdef 1550is applicable only to the 1551.Ic machine 1552definition preceding it. 1553A 1554.Ic macdef 1555entry cannot be utilized by multiple 1556.Ic machine 1557definitions; rather, it must be defined following each 1558.Ic machine 1559it is intended to be used with. 1560If a macro named 1561.Ic init 1562is defined, it is automatically executed as the last step in the 1563auto-login process. 1564.El 1565.Sh COMMAND LINE EDITING 1566.Nm 1567supports interactive command line editing, via the 1568.Xr editline 3 1569library. 1570It is enabled with the 1571.Ic edit 1572command, and is enabled by default if input is from a tty. 1573Previous lines can be recalled and edited with the arrow keys, 1574and other GNU Emacs-style editing keys may be used as well. 1575.Pp 1576The 1577.Xr editline 3 1578library is configured with a 1579.Pa .editrc 1580file \- refer to 1581.Xr editrc 5 1582for more information. 1583.Pp 1584An extra key binding is available to 1585.Nm 1586to provide context sensitive command and filename completion 1587(including remote file completion). 1588To use this, bind a key to the 1589.Xr editline 3 1590command 1591.Ic ftp-complete . 1592By default, this is bound to the TAB key. 1593.Sh ENVIRONMENT 1594.Nm 1595utilizes the following environment variables: 1596.Bl -tag -width "FTPSERVERPORT" 1597.It Ev FTPMODE 1598Overrides the default operation mode. 1599Recognized values are: 1600.Pp 1601.Bl -tag -width "passive " -offset indent -compact 1602.It passive 1603passive mode FTP only 1604.It active 1605active mode FTP only 1606.It auto 1607automatic determination of passive or active (this is the default) 1608.It gate 1609gate-ftp mode 1610.El 1611.It Ev FTPSERVER 1612Host to use as gate-ftp server when 1613.Ic gate 1614is enabled. 1615.It Ev FTPSERVERPORT 1616Port to use when connecting to gate-ftp server when 1617.Ic gate 1618is enabled. 1619Default is port returned by a 1620.Fn getservbyname 1621lookup of 1622.Dq ftpgate/tcp . 1623.It Ev HOME 1624For default location of a 1625.Pa .netrc 1626file, if one exists. 1627.It Ev PAGER 1628Used by 1629.Ic page 1630to display files. 1631.It Ev SHELL 1632For default shell. 1633.It Ev TMPDIR 1634Directory in which temporary files are stored. 1635.It Ev ftp_proxy 1636URL of FTP proxy to use when making FTP URL requests 1637(if not defined, use the standard FTP protocol). 1638.It Ev http_proxy 1639URL of HTTP proxy to use when making HTTP or HTTPS URL requests. 1640.It Ev http_cookies 1641Path of a Netscape-like cookiejar file to use when making 1642HTTP or HTTPS URL requests. 1643.El 1644.Sh PORT ALLOCATION 1645For active mode data connections, 1646.Nm 1647will listen to a random high TCP port. 1648The interval of ports used are configurable using 1649.Xr sysctl 8 1650variables 1651.Va net.inet.ip.porthifirst 1652and 1653.Va net.inet.ip.porthilast . 1654.Sh SEE ALSO 1655.Xr basename 1 , 1656.Xr csh 1 , 1657.Xr more 1 , 1658.Xr stty 1 , 1659.Xr tar 1 , 1660.Xr tftp 1 , 1661.Xr editline 3 , 1662.Xr getservbyname 3 , 1663.Xr popen 3 , 1664.Xr editrc 5 , 1665.Xr services 5 , 1666.Xr ftp-proxy 8 , 1667.Xr ftpd 8 1668.Sh HISTORY 1669The 1670.Nm 1671command appeared in 1672.Bx 4.2 . 1673.Sh BUGS 1674Correct execution of many commands depends upon proper behavior 1675by the remote server. 1676.Pp 1677An error in the treatment of carriage returns 1678in the 1679.Bx 4.2 1680ASCII-mode transfer code 1681has been corrected. 1682This correction may result in incorrect transfers of binary files 1683to and from 1684.Bx 4.2 1685servers using the ASCII type. 1686Avoid this problem by using the binary image type. 1687.Pp 1688In the recursive mode of 1689.Ic mget , 1690files and directories starting with whitespace are ignored 1691because the list cannot be parsed any other way. 1692