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