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