1.\" $NetBSD: ftp.1,v 1.127 2008/09/30 03:41:53 lukem Exp $ 2.\" 3.\" Copyright (c) 1996-2008 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Luke Mewburn. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" 31.\" Copyright (c) 1985, 1989, 1990, 1993 32.\" The Regents of the University of California. All rights reserved. 33.\" 34.\" Redistribution and use in source and binary forms, with or without 35.\" modification, are permitted provided that the following conditions 36.\" are met: 37.\" 1. Redistributions of source code must retain the above copyright 38.\" notice, this list of conditions and the following disclaimer. 39.\" 2. Redistributions in binary form must reproduce the above copyright 40.\" notice, this list of conditions and the following disclaimer in the 41.\" documentation and/or other materials provided with the distribution. 42.\" 3. Neither the name of the University nor the names of its contributors 43.\" may be used to endorse or promote products derived from this software 44.\" without specific prior written permission. 45.\" 46.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 47.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 48.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 49.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 50.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 51.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 52.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 53.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 54.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 55.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 56.\" SUCH DAMAGE. 57.\" 58.\" @(#)ftp.1 8.3 (Berkeley) 10/9/94 59.\" 60.Dd May 10, 2008 61.Dt FTP 1 62.Os 63.Sh NAME 64.Nm ftp 65.Nd 66Internet file transfer program 67.Sh SYNOPSIS 68.Nm 69.Op Fl 46AadefginpRtVv 70.Bk -words 71.Op Fl N Ar netrc 72.Ek 73.Bk -words 74.Op Fl o Ar output 75.Ek 76.Bk -words 77.Op Fl P Ar port 78.Ek 79.Bk -words 80.Op Fl q Ar quittime 81.Ek 82.Bk -words 83.Op Fl r Ar retry 84.Ek 85.Op Fl s Ar srcaddr 86.Bk -words 87.\" [-T dir,max[,inc]] 88.Oo 89.Fl T Xo 90.Sm off 91.Ar dir , 92.Ar max 93.Op , Ar inc 94.Sm on 95.Xc 96.Oc 97.Ek 98.Bk -words 99.\" [[user@]host [port]] 100.Oo 101.Oo Ar user Ns Li \&@ Oc Ns Ar host 102.Op Ar port 103.Oc 104.Ek 105.Bk -words 106.\" [[user@]host:[path][/]] 107.Sm off 108.Oo 109.Op Ar user Li \&@ 110.Ar host Li \&: 111.Op Ar path 112.Op Li / 113.Oc 114.Sm on 115.Ek 116.Bk -words 117.\" [file:///path] 118.Sm off 119.Oo 120.Li file:/// Ar path 121.Oc 122.Sm on 123.Ek 124.Bk -words 125.\" [ftp://[user[:password]@]host[:port]/path[/]] 126.Sm off 127.Oo 128.Li ftp:// 129.Oo Ar user 130.Op Li \&: Ar password 131.Li \&@ Oc 132.Ar host Oo Li \&: Ar port Oc 133.Li / Ar path 134.Op Li / 135.Op Li ;type= Ar X 136.Oc 137.Sm on 138.Ek 139.Bk -words 140.\" [http://[user[:password]@]host[:port]/path] 141.Sm off 142.Oo 143.Li http:// 144.Oo Ar user 145.Op Li \&: Ar password 146.Li \&@ Oc 147.Ar host Oo Li \&: Ar port Oc 148.Li / Ar path 149.Oc 150.Sm on 151.Ek 152.Op Ar \&.\&.\&. 153.Nm 154.Bk -words 155.Fl u Ar URL Ar file 156.Ek 157.Op Ar \&.\&.\&. 158.Sh DESCRIPTION 159.Nm 160is the user interface to the Internet standard File Transfer Protocol. 161The program allows a user to transfer files to and from a 162remote network site. 163.Pp 164The last five arguments will fetch a file using the 165.Tn FTP 166or 167.Tn HTTP 168protocols, or by direct copying, into the current directory. 169This is ideal for scripts. 170Refer to 171.Sx AUTO-FETCHING FILES 172below for more information. 173.Pp 174Options may be specified at the command line, or to the 175command interpreter. 176.Bl -tag -width Fl 177.It Fl 4 178Forces 179.Nm 180to only use IPv4 addresses. 181.It Fl 6 182Forces 183.Nm 184to only use IPv6 addresses. 185.It Fl A 186Force active mode ftp. 187By default, 188.Nm 189will try to use passive mode ftp and fall back to active mode 190if passive is not supported by the server. 191This option causes 192.Nm 193to always use an active connection. 194It is only useful for connecting to very old servers that do not 195implement passive mode properly. 196.It Fl a 197Causes 198.Nm 199to bypass normal login procedure, and use an anonymous login instead. 200.It Fl d 201Enables debugging. 202.It Fl e 203Disables command line editing. 204This is useful for Emacs ange-ftp mode. 205.It Fl f 206Forces a cache reload for transfers that go through the 207.Tn FTP 208or 209.Tn HTTP 210proxies. 211.It Fl g 212Disables file name globbing. 213.It Fl i 214Turns off interactive prompting during 215multiple file transfers. 216.It Fl N Ar netrc 217Use 218.Ar netrc 219instead of 220.Pa ~/.netrc . 221Refer to 222.Sx THE .netrc FILE 223for more information. 224.It Fl n 225Restrains 226.Nm 227from attempting 228.Dq auto-login 229upon initial connection for non auto-fetch transfers. 230If auto-login is enabled, 231.Nm 232will check the 233.Pa .netrc 234(see below) file in the user's home directory for an entry describing 235an account on the remote machine. 236If no entry exists, 237.Nm 238will prompt for the remote machine login name (default is the user 239identity on the local machine), and, if necessary, prompt for a password 240and an account with which to login. 241To override the auto-login for auto-fetch transfers, specify the 242username (and optionally, password) as appropriate. 243.It Fl o Ar output 244When auto-fetching files, save the contents in 245.Ar output . 246.Ar output 247is parsed according to the 248.Sx FILE NAMING CONVENTIONS 249below. 250If 251.Ar output 252is not 253.Sq - 254or doesn't start with 255.Sq \&| , 256then only the first file specified will be retrieved into 257.Ar output ; 258all other files will be retrieved into the basename of their 259remote name. 260.It Fl P Ar port 261Sets the port number to 262.Ar port . 263.It Fl p 264Enable passive mode operation for use behind connection filtering firewalls. 265This option has been deprecated as 266.Nm 267now tries to use passive mode by default, falling back to active mode 268if the server does not support passive connections. 269.It Fl q Ar quittime 270Quit if the connection has stalled for 271.Ar quittime 272seconds. 273.It Fl R 274Restart all non-proxied auto-fetches. 275.It Fl r Ar wait 276Retry the connection attempt if it failed, pausing for 277.Ar wait 278seconds. 279.It Fl s Ar srcaddr 280Uses 281.Ar srcaddr 282as the local IP address for all connections. 283.It Fl t 284Enables packet tracing. 285.It Xo 286.Fl T 287.Sm off 288.Ar direction , 289.Ar maximum 290.Op , Ar increment 291.Sm on 292.Xc 293Set the maximum transfer rate for 294.Ar direction 295to 296.Ar maximum 297bytes/second, 298and if specified, the increment to 299.Ar increment 300bytes/second. 301Refer to 302.Ic rate 303for more information. 304.It Fl u Ar URL file Op \&.\&.\&. 305Upload files on the command line to 306.Ar URL 307where 308.Ar URL 309is one of the ftp URL types as supported by auto-fetch 310(with an optional target filename for single file uploads), and 311.Ar file 312is one or more local files to be uploaded. 313.It Fl V 314Disable 315.Ic verbose 316and 317.Ic progress , 318overriding the default of enabled when output is to a terminal. 319.It Fl v 320Enable 321.Ic verbose 322and 323.Ic progress . 324This is the default if output is to a terminal (and in the case of 325.Ic progress , 326.Nm 327is the foreground process). 328Forces 329.Nm 330to show all responses from the remote server, as well 331as report on data transfer statistics. 332.El 333.Pp 334The client host with which 335.Nm 336is to communicate may be specified on the command line. 337If this is done, 338.Nm 339will immediately attempt to establish a connection to an 340.Tn FTP 341server on that host; otherwise, 342.Nm 343will enter its command interpreter and await instructions 344from the user. 345When 346.Nm 347is awaiting commands from the user the prompt 348.Ql ftp\*[Gt] 349is provided to the user. 350The following commands are recognized 351by 352.Nm ftp : 353.Bl -tag -width Ic 354.It Ic \&! Op Ar command Op Ar args 355Invoke an interactive shell on the local machine. 356If there are arguments, the first is taken to be a command to execute 357directly, with the rest of the arguments as its arguments. 358.It Ic \&$ Ar macro-name Op Ar args 359Execute the macro 360.Ar macro-name 361that was defined with the 362.Ic macdef 363command. 364Arguments are passed to the macro unglobbed. 365.It Ic account Op Ar passwd 366Supply a supplemental password required by a remote system for access 367to resources once a login has been successfully completed. 368If no argument is included, the user will be prompted for an account 369password in a non-echoing input mode. 370.It Ic append Ar local-file Op Ar remote-file 371Append a local file to a file on the remote machine. 372If 373.Ar remote-file 374is left unspecified, the local file name is used in naming the 375remote file after being altered by any 376.Ic ntrans 377or 378.Ic nmap 379setting. 380File transfer uses the current settings for 381.Ic type , 382.Ic format , 383.Ic mode , 384and 385.Ic structure . 386.It Ic ascii 387Set the file transfer 388.Ic type 389to network 390.Tn ASCII . 391This is the default type. 392.It Ic bell 393Arrange that a bell be sounded after each file transfer 394command is completed. 395.It Ic binary 396Set the file transfer 397.Ic type 398to support binary image transfer. 399.It Ic bye 400Terminate the 401.Tn FTP 402session with the remote server 403and exit 404.Nm ftp . 405An end of file will also terminate the session and exit. 406.It Ic case 407Toggle remote computer file name case mapping during 408.Ic get , 409.Ic mget 410and 411.Ic mput 412commands. 413When 414.Ic case 415is on (default is off), remote computer file names with all letters in 416upper case are written in the local directory with the letters mapped 417to lower case. 418.It Ic \&cd Ar remote-directory 419Change the working directory on the remote machine 420to 421.Ar remote-directory . 422.It Ic cdup 423Change the remote machine working directory to the parent of the 424current remote machine working directory. 425.It Ic chmod Ar mode remote-file 426Change the permission modes of the file 427.Ar remote-file 428on the remote 429system to 430.Ar mode . 431.It Ic close 432Terminate the 433.Tn FTP 434session with the remote server, and 435return to the command interpreter. 436Any defined macros are erased. 437.It Ic \&cr 438Toggle carriage return stripping during 439ascii type file retrieval. 440Records are denoted by a carriage return/linefeed sequence 441during ascii type file transfer. 442When 443.Ic \&cr 444is on (the default), carriage returns are stripped from this 445sequence to conform with the 446.Ux 447single linefeed record 448delimiter. 449Records on 450.Pf non\- Ns Ux 451remote systems may contain single linefeeds; 452when an ascii type transfer is made, these linefeeds may be 453distinguished from a record delimiter only when 454.Ic \&cr 455is off. 456.It Ic delete Ar remote-file 457Delete the file 458.Ar remote-file 459on the remote machine. 460.It Ic dir Op Ar remote-path Op Ar local-file 461Print a listing of the contents of a 462directory on the remote machine. 463The listing includes any system-dependent information that the server 464chooses to include; for example, most 465.Ux 466systems will produce 467output from the command 468.Ql ls \-l . 469If 470.Ar remote-path 471is left unspecified, the current working directory is used. 472If interactive prompting is on, 473.Nm 474will prompt the user to verify that the last argument is indeed the 475target local file for receiving 476.Ic dir 477output. 478If no local file is specified, or if 479.Ar local-file 480is 481.Sq Fl , 482the output is sent to the terminal. 483.It Ic disconnect 484A synonym for 485.Ic close . 486.It Ic edit 487Toggle command line editing, and context sensitive command and file 488completion. 489This is automatically enabled if input is from a terminal, and 490disabled otherwise. 491.It Ic epsv epsv4 epsv6 492Toggle the use of the extended 493.Dv EPSV 494and 495.Dv EPRT 496commands on all IP, IPv4, and IPv6 connections respectively. First try 497.Dv EPSV / 498.Dv EPRT , 499and then 500.Dv PASV / 501.Dv PORT . 502This is enabled by default. 503If an extended command fails then this option will be temporarily 504disabled for the duration of the current connection, or until 505.Ic epsv , 506.Ic epsv4 , 507or 508.Ic epsv6 509is executed again. 510.It Ic exit 511A synonym for 512.Ic bye . 513.It Ic features 514Display what features the remote server supports (using the 515.Dv FEAT 516command). 517.It Ic fget Ar localfile 518Retrieve the files listed in 519.Ar localfile , 520which has one line per filename. 521.It Ic form Ar format 522Set the file transfer 523.Ic form 524to 525.Ar format . 526The default (and only supported) 527format is 528.Dq non-print . 529.It Ic ftp Ar host Op Ar port 530A synonym for 531.Ic open . 532.It Ic ftp_debug Op Ar ftp_debug-value 533Toggle debugging mode. 534If an optional 535.Ar ftp_debug-value 536is specified it is used to set the debugging level. 537When debugging is on, 538.Nm 539prints each command sent to the remote machine, preceded 540by the string 541.Ql \-\-\*[Gt] . 542.It Ic gate Op Ar host Op Ar port 543Toggle gate-ftp mode, which used to connect through the 544TIS FWTK and Gauntlet ftp proxies. 545This will not be permitted if the gate-ftp server hasn't been set 546(either explicitly by the user, or from the 547.Ev FTPSERVER 548environment variable). 549If 550.Ar host 551is given, 552then gate-ftp mode will be enabled, and the gate-ftp server will be set to 553.Ar host . 554If 555.Ar port 556is also given, that will be used as the port to connect to on the 557gate-ftp server. 558.It Ic get Ar remote-file Op Ar local-file 559Retrieve the 560.Ar remote-file 561and store it on the local machine. 562If the local 563file name is not specified, it is given the same 564name it has on the remote machine, subject to 565alteration by the current 566.Ic case , 567.Ic ntrans , 568and 569.Ic nmap 570settings. 571The current settings for 572.Ic type , 573.Ic form , 574.Ic mode , 575and 576.Ic structure 577are used while transferring the file. 578.It Ic glob 579Toggle filename expansion for 580.Ic mdelete , 581.Ic mget , 582.Ic mput , 583and 584.Ic mreget . 585If globbing is turned off with 586.Ic glob , 587the file name arguments 588are taken literally and not expanded. 589Globbing for 590.Ic mput 591is done as in 592.Xr csh 1 . 593For 594.Ic mdelete , 595.Ic mget , 596and 597.Ic mreget , 598each remote file name is expanded 599separately on the remote machine and the lists are not merged. 600Expansion of a directory name is likely to be 601different from expansion of the name of an ordinary file: 602the exact result depends on the foreign operating system and ftp server, 603and can be previewed by doing 604.Ql mls remote-files \- 605Note: 606.Ic mget , 607.Ic mput 608and 609.Ic mreget 610are not meant to transfer 611entire directory subtrees of files. 612That can be done by 613transferring a 614.Xr tar 1 615archive of the subtree (in binary mode). 616.It Ic hash Op Ar size 617Toggle hash-sign 618.Pq Sq # 619printing for each data block transferred. 620The size of a data block defaults to 1024 bytes. 621This can be changed by specifying 622.Ar size 623in bytes. 624Enabling 625.Ic hash 626disables 627.Ic progress . 628.It Ic help Op Ar command 629Print an informative message about the meaning of 630.Ar command . 631If no argument is given, 632.Nm 633prints a list of the known commands. 634.It Ic idle Op Ar seconds 635Set the inactivity timer on the remote server to 636.Ar seconds 637seconds. 638If 639.Ar seconds 640is omitted, the current inactivity timer is printed. 641.It Ic image 642A synonym for 643.Ic binary . 644.It Ic lcd Op Ar directory 645Change the working directory on the local machine. 646If 647no 648.Ar directory 649is specified, the user's home directory is used. 650.It Ic less Ar file 651A synonym for 652.Ic page . 653.It Ic lpage Ar local-file 654Display 655.Ar local-file 656with the program specified by the 657.Ic "set pager" 658option. 659.It Ic lpwd 660Print the working directory on the local machine. 661.It Ic \&ls Op Ar remote-path Op Ar local-file 662A synonym for 663.Ic dir . 664.It Ic macdef Ar macro-name 665Define a macro. 666Subsequent lines are stored as the macro 667.Ar macro-name ; 668a null line (consecutive newline characters in a file or carriage 669returns from the terminal) terminates macro input mode. 670There is a limit of 16 macros and 4096 total characters in all 671defined macros. 672Macro names can be a maximum of 8 characters. 673Macros are only applicable to the current session they are 674defined within (or if defined outside a session, to the session 675invoked with the next 676.Ic open 677command), and remain defined until a 678.Ic close 679command is executed. 680To invoke a macro, use the 681.Ic $ 682command (see above). 683.Pp 684The macro processor interprets 685.Sq $ 686and 687.Sq \e 688as special characters. 689A 690.Sq $ 691followed by a number (or numbers) is replaced by the 692corresponding argument on the macro invocation command line. 693A 694.Sq $ 695followed by an 696.Sq i 697signals the macro processor that the executing macro is to be 698looped. 699On the first pass 700.Dq $i 701is replaced by the first argument on the macro invocation command 702line, on the second pass it is replaced by the second argument, 703and so on. 704A 705.Sq \e 706followed by any character is replaced by that character. 707Use the 708.Sq \e 709to prevent special treatment of the 710.Sq $ . 711.It Ic mdelete Op Ar remote-files 712Delete the 713.Ar remote-files 714on the remote machine. 715.It Ic mdir Ar remote-files local-file 716Like 717.Ic dir , 718except multiple remote files may be specified. 719If interactive prompting is on, 720.Nm 721will prompt the user to verify that the last argument is indeed the 722target local file for receiving 723.Ic mdir 724output. 725.It Ic mget Ar remote-files 726Expand the 727.Ar remote-files 728on the remote machine 729and do a 730.Ic get 731for each file name thus produced. 732See 733.Ic glob 734for details on the filename expansion. 735Resulting file names will then be processed according to 736.Ic case , 737.Ic ntrans , 738and 739.Ic nmap 740settings. 741Files are transferred into the local working directory, 742which can be changed with 743.Ql lcd directory ; 744new local directories can be created with 745.Ql "\&! mkdir directory" . 746.It Ic mkdir Ar directory-name 747Make a directory on the remote machine. 748.It Ic mls Ar remote-files local-file 749Like 750.Ic ls , 751except multiple remote files may be specified, 752and the 753.Ar local-file 754must be specified. 755If interactive prompting is on, 756.Nm 757will prompt the user to verify that the last argument is indeed the 758target local file for receiving 759.Ic mls 760output. 761.It Ic mlsd Op Ar remote-path 762Display the contents of 763.Ar remote-path 764(which should default to the current directory if not given) 765in a machine-parsable form, using 766.Dv MLSD . 767The format of display can be changed with 768.Sq "remopts mlst ..." . 769.It Ic mlst Op Ar remote-path 770Display the details about 771.Ar remote-path 772(which should default to the current directory if not given) 773in a machine-parsable form, using 774.Dv MLST . 775The format of display can be changed with 776.Sq "remopts mlst ..." . 777.It Ic mode Ar mode-name 778Set the file transfer 779.Ic mode 780to 781.Ar mode-name . 782The default (and only supported) 783mode is 784.Dq stream . 785.It Ic modtime Ar remote-file 786Show the last modification time of the file on the remote machine, in 787.Li RFC2822 788format. 789.It Ic more Ar file 790A synonym for 791.Ic page . 792.It Ic mput Ar local-files 793Expand wild cards in the list of local files given as arguments 794and do a 795.Ic put 796for each file in the resulting list. 797See 798.Ic glob 799for details of filename expansion. 800Resulting file names will then be processed according to 801.Ic ntrans 802and 803.Ic nmap 804settings. 805.It Ic mreget Ar remote-files 806As per 807.Ic mget , 808but performs a 809.Ic reget 810instead of 811.Ic get . 812.It Ic msend Ar local-files 813A synonym for 814.Ic mput . 815.It Ic newer Ar remote-file Op Ar local-file 816Get the file only if the modification time of the remote file is more 817recent that the file on the current system. 818If the file does not 819exist on the current system, the remote file is considered 820.Ic newer . 821Otherwise, this command is identical to 822.Ar get . 823.It Ic nlist Op Ar remote-path Op Ar local-file 824A synonym for 825.Ic ls . 826.It Ic nmap Op Ar inpattern outpattern 827Set or unset the filename mapping mechanism. 828If no arguments are specified, the filename mapping mechanism is unset. 829If arguments are specified, remote filenames are mapped during 830.Ic mput 831commands and 832.Ic put 833commands issued without a specified remote target filename. 834If arguments are specified, local filenames are mapped during 835.Ic mget 836commands and 837.Ic get 838commands issued without a specified local target filename. 839This command is useful when connecting to a 840.No non\- Ns Ux 841remote computer 842with different file naming conventions or practices. 843The mapping follows the pattern set by 844.Ar inpattern 845and 846.Ar outpattern . 847.Op Ar Inpattern 848is a template for incoming filenames (which may have already been 849processed according to the 850.Ic ntrans 851and 852.Ic case 853settings). 854Variable templating is accomplished by including the 855sequences 856.Dq $1 , 857.Dq $2 , 858\&... 859.Dq $9 860in 861.Ar inpattern . 862Use 863.Sq \e 864to prevent this special treatment of the 865.Sq $ 866character. 867All other characters are treated literally, and are used to determine the 868.Ic nmap 869.Op Ar inpattern 870variable values. 871For example, given 872.Ar inpattern 873$1.$2 and the remote file name "mydata.data", $1 would have the value 874"mydata", and $2 would have the value "data". 875The 876.Ar outpattern 877determines the resulting mapped filename. 878The sequences 879.Dq $1 , 880.Dq $2 , 881\&... 882.Dq $9 883are replaced by any value resulting from the 884.Ar inpattern 885template. 886The sequence 887.Dq $0 888is replaced by the original filename. 889Additionally, the sequence 890.Dq Op Ar seq1 , Ar seq2 891is replaced by 892.Op Ar seq1 893if 894.Ar seq1 895is not a null string; otherwise it is replaced by 896.Ar seq2 . 897For example, the command 898.Pp 899.Bd -literal -offset indent -compact 900nmap $1.$2.$3 [$1,$2].[$2,file] 901.Ed 902.Pp 903would yield 904the output filename "myfile.data" for input filenames "myfile.data" and 905"myfile.data.old", "myfile.file" for the input filename "myfile", and 906"myfile.myfile" for the input filename ".myfile". 907Spaces may be included in 908.Ar outpattern , 909as in the example: 910.Dl nmap $1 sed "s/ *$//" \*[Gt] $1 911Use the 912.Sq \e 913character to prevent special treatment 914of the 915.Sq $ , 916.Sq \&[ , 917.Sq \&] , 918and 919.Sq \&, 920characters. 921.It Ic ntrans Op Ar inchars Op Ar outchars 922Set or unset the filename character translation mechanism. 923If no arguments are specified, the filename character 924translation mechanism is unset. 925If arguments are specified, characters in 926remote filenames are translated during 927.Ic mput 928commands and 929.Ic put 930commands issued without a specified remote target filename. 931If arguments are specified, characters in 932local filenames are translated during 933.Ic mget 934commands and 935.Ic get 936commands issued without a specified local target filename. 937This command is useful when connecting to a 938.No non\- Ns Ux 939remote computer 940with different file naming conventions or practices. 941Characters in a filename matching a character in 942.Ar inchars 943are replaced with the corresponding character in 944.Ar outchars . 945If the character's position in 946.Ar inchars 947is longer than the length of 948.Ar outchars , 949the character is deleted from the file name. 950.It Ic open Ar host Op Ar port 951Establish a connection to the specified 952.Ar host 953.Tn FTP 954server. 955An optional port number may be supplied, 956in which case, 957.Nm 958will attempt to contact an 959.Tn FTP 960server at that port. 961If the 962.Ic "set auto-login" 963option is on (default), 964.Nm 965will also attempt to automatically log the user in to 966the 967.Tn FTP 968server (see below). 969.It Ic page Ar file 970Retrieve 971.Ic file 972and display with the program specified by the 973.Ic "set pager" 974option. 975.It Ic passive Op Cm auto 976Toggle passive mode (if no arguments are given). 977If 978.Cm auto 979is given, act as if 980.Ev FTPMODE 981is set to 982.Sq auto . 983If passive mode is turned on (default), 984.Nm 985will send a 986.Dv PASV 987command for all data connections instead of a 988.Dv PORT 989command. 990The 991.Dv PASV 992command requests that the remote server open a port for the data connection 993and return the address of that port. 994The remote server listens on that port and the client connects to it. 995When using the more traditional 996.Dv PORT 997command, the client listens on a port and sends that address to the remote 998server, who connects back to it. 999Passive mode is useful when using 1000.Nm 1001through a gateway router or host that controls the directionality of 1002traffic. 1003(Note that though 1004.Tn FTP 1005servers are required to support the 1006.Dv PASV 1007command by 1008.Li RFC1123 , 1009some do not.) 1010.It Ic pdir Op Ar remote-path 1011Perform 1012.Ic dir 1013.Op Ar remote-path , 1014and display the result with the program specified by the 1015.Ic "set pager" 1016option. 1017.It Ic pls Op Ar remote-path 1018Perform 1019.Ic ls 1020.Op Ar remote-path , 1021and display the result with the program specified by the 1022.Ic "set pager" 1023option. 1024.It Ic pmlsd Op Ar remote-path 1025Perform 1026.Ic mlsd 1027.Op Ar remote-path , 1028and display the result with the program specified by the 1029.Ic "set pager" 1030option. 1031.It Ic preserve 1032Toggle preservation of modification times on retrieved files. 1033.It Ic progress 1034Toggle display of transfer progress bar. 1035The progress bar will be disabled for a transfer that has 1036.Ar local-file 1037as 1038.Sq Fl 1039or a command that starts with 1040.Sq \&| . 1041Refer to 1042.Sx FILE NAMING CONVENTIONS 1043for more information. 1044Enabling 1045.Ic progress 1046disables 1047.Ic hash . 1048.It Ic prompt 1049Toggle interactive prompting. 1050Interactive prompting 1051occurs during multiple file transfers to allow the 1052user to selectively retrieve or store files. 1053If prompting is turned off (default is on), any 1054.Ic mget 1055or 1056.Ic mput 1057will transfer all files, and any 1058.Ic mdelete 1059will delete all files. 1060.Pp 1061When prompting is on, the following commands are available at a prompt: 1062.Bl -tag -width 2n -offset indent 1063.It Cm a 1064Answer 1065.Sq yes 1066to the current file, and automatically answer 1067.Sq yes 1068to any remaining files for the current command. 1069.It Cm n 1070Answer 1071.Sq no , 1072and do not transfer the file. 1073.It Cm p 1074Answer 1075.Sq yes 1076to the current file, and turn off prompt mode 1077(as is 1078.Dq prompt off 1079had been given). 1080.It Cm q 1081Terminate the current operation. 1082.It Cm y 1083Answer 1084.Sq yes , 1085and transfer the file. 1086.It Cm \&? 1087Display a help message. 1088.El 1089.Pp 1090Any other response will answer 1091.Sq yes 1092to the current file. 1093.It Ic proxy Ar ftp-command 1094Execute an ftp command on a secondary control connection. 1095This command allows simultaneous connection to two remote 1096.Tn FTP 1097servers for transferring files between the two servers. 1098The first 1099.Ic proxy 1100command should be an 1101.Ic open , 1102to establish the secondary control connection. 1103Enter the command "proxy ?" to see other 1104.Tn FTP 1105commands executable on the secondary connection. 1106The following commands behave differently when prefaced by 1107.Ic proxy : 1108.Ic open 1109will not define new macros during the auto-login process, 1110.Ic close 1111will not erase existing macro definitions, 1112.Ic get 1113and 1114.Ic mget 1115transfer files from the host on the primary control connection 1116to the host on the secondary control connection, and 1117.Ic put , 1118.Ic mput , 1119and 1120.Ic append 1121transfer files from the host on the secondary control connection 1122to the host on the primary control connection. 1123Third party file transfers depend upon support of the 1124.Tn FTP 1125protocol 1126.Dv PASV 1127command by the server on the secondary control connection. 1128.It Ic put Ar local-file Op Ar remote-file 1129Store a local file on the remote machine. 1130If 1131.Ar remote-file 1132is left unspecified, the local file name is used 1133after processing according to any 1134.Ic ntrans 1135or 1136.Ic nmap 1137settings 1138in naming the remote file. 1139File transfer uses the 1140current settings for 1141.Ic type , 1142.Ic format , 1143.Ic mode , 1144and 1145.Ic structure . 1146.It Ic pwd 1147Print the name of the current working directory on the remote 1148machine. 1149.It Ic quit 1150A synonym for 1151.Ic bye . 1152.It Ic quote Ar arg1 arg2 ... 1153The arguments specified are sent, verbatim, to the remote 1154.Tn FTP 1155server. 1156.It Xo 1157.Ic rate Ar direction 1158.Op Ar maximum Op Ar increment 1159.Xc 1160Throttle the maximum transfer rate to 1161.Ar maximum 1162bytes/second. 1163If 1164.Ar maximum 1165is 0, disable the throttle. 1166.Pp 1167.Ar direction 1168may be one of: 1169.Bl -tag -width "all" -offset indent -compact 1170.It Cm all 1171Both directions. 1172.It Cm get 1173Incoming transfers. 1174.It Cm put 1175Outgoing transfers. 1176.El 1177.Pp 1178.Ar maximum 1179can be modified on the fly by 1180.Ar increment 1181bytes (default: 1024) each time a given signal is received: 1182.B 1183.Bl -tag -width "SIGUSR1" -offset indent 1184.It Dv SIGUSR1 1185Increment 1186.Ar maximum 1187by 1188.Ar increment 1189bytes. 1190.It Dv SIGUSR2 1191Decrement 1192.Ar maximum 1193by 1194.Ar increment 1195bytes. 1196The result must be a positive number. 1197.El 1198.Pp 1199If 1200.Ar maximum 1201is not supplied, the current throttle rates are displayed. 1202.Pp 1203Note: 1204.Ic rate 1205is not yet implemented for ascii mode transfers. 1206.It Ic rcvbuf Ar size 1207Set the size of the socket receive buffer to 1208.Ar size . 1209.It Ic recv Ar remote-file Op Ar local-file 1210A synonym for 1211.Ic get . 1212.It Ic reget Ar remote-file Op Ar local-file 1213.Ic reget 1214acts like 1215.Ic get , 1216except that if 1217.Ar local-file 1218exists and is 1219smaller than 1220.Ar remote-file , 1221.Ar local-file 1222is presumed to be 1223a partially transferred copy of 1224.Ar remote-file 1225and the transfer 1226is continued from the apparent point of failure. 1227This command 1228is useful when transferring very large files over networks that 1229are prone to dropping connections. 1230.It Ic remopts Ar command Op Ar command-options 1231Set options on the remote 1232.Tn FTP 1233server for 1234.Ar command 1235to 1236.Ar command-options 1237(whose absence is handled on a command-specific basis). 1238Remote 1239.Tn FTP 1240commands known to support options include: 1241.Sq MLST 1242(used for 1243.Dv MLSD 1244and 1245.Dv MLST ) . 1246.It Ic rename Op Ar from Op Ar to 1247Rename the file 1248.Ar from 1249on the remote machine, to the file 1250.Ar to . 1251.It Ic reset 1252Clear reply queue. 1253This command re-synchronizes command/reply sequencing with the remote 1254.Tn FTP 1255server. 1256Resynchronization may be necessary following a violation of the 1257.Tn FTP 1258protocol by the remote server. 1259.It Ic restart Ar marker 1260Restart the immediately following 1261.Ic get 1262or 1263.Ic put 1264at the 1265indicated 1266.Ar marker . 1267On 1268.Ux 1269systems, marker is usually a byte 1270offset into the file. 1271.It Ic rhelp Op Ar command-name 1272Request help from the remote 1273.Tn FTP 1274server. 1275If a 1276.Ar command-name 1277is specified it is supplied to the server as well. 1278.It Ic rmdir Ar directory-name 1279Delete a directory on the remote machine. 1280.It Ic rstatus Op Ar remote-file 1281With no arguments, show status of remote machine. 1282If 1283.Ar remote-file 1284is specified, show status of 1285.Ar remote-file 1286on remote machine. 1287.It Ic runique 1288Toggle storing of files on the local system with unique filenames. 1289If a file already exists with a name equal to the target 1290local filename for a 1291.Ic get 1292or 1293.Ic mget 1294command, a ".1" is appended to the name. 1295If the resulting name matches another existing file, 1296a ".2" is appended to the original name. 1297If this process continues up to ".99", an error 1298message is printed, and the transfer does not take place. 1299The generated unique filename will be reported. 1300Note that 1301.Ic runique 1302will not affect local files generated from a shell command 1303(see below). 1304The default value is off. 1305.It Ic send Ar local-file Op Ar remote-file 1306A synonym for 1307.Ic put . 1308.It Ic sendport 1309Toggle the use of 1310.Dv PORT 1311commands. 1312By default, 1313.Nm 1314will attempt to use a 1315.Dv PORT 1316command when establishing 1317a connection for each data transfer. 1318The use of 1319.Dv PORT 1320commands can prevent delays 1321when performing multiple file transfers. 1322If the 1323.Dv PORT 1324command fails, 1325.Nm 1326will use the default data port. 1327When the use of 1328.Dv PORT 1329commands is disabled, no attempt will be made to use 1330.Dv PORT 1331commands for each data transfer. 1332This is useful 1333for certain 1334.Tn FTP 1335implementations which do ignore 1336.Dv PORT 1337commands but, incorrectly, indicate they've been accepted. 1338.It Ic set Op Ar option Ar value 1339Set 1340.Ar option 1341to 1342.Ar value . 1343If 1344.Ar option 1345and 1346.Ar value 1347are not given, display all of the options and their values. 1348The currently supported options are: 1349.Bl -tag -width "http_proxy" -offset indent 1350.It Cm anonpass 1351Defaults to 1352.Ev $FTPANONPASS 1353.It Cm ftp_proxy 1354Defaults to 1355.Ev $ftp_proxy . 1356.It Cm http_proxy 1357Defaults to 1358.Ev $http_proxy . 1359.It Cm no_proxy 1360Defaults to 1361.Ev $no_proxy . 1362.It Cm pager 1363Defaults to 1364.Ev $PAGER . 1365.It Cm prompt 1366Defaults to 1367.Ev $FTPPROMPT . 1368.It Cm rprompt 1369Defaults to 1370.Ev $FTPRPROMPT . 1371.El 1372.It Ic site Ar arg1 arg2 ... 1373The arguments specified are sent, verbatim, to the remote 1374.Tn FTP 1375server as a 1376.Dv SITE 1377command. 1378.It Ic size Ar remote-file 1379Return size of 1380.Ar remote-file 1381on remote machine. 1382.It Ic sndbuf Ar size 1383Set the size of the socket send buffer to 1384.Ar size . 1385.It Ic status 1386Show the current status of 1387.Nm ftp . 1388.It Ic struct Ar struct-name 1389Set the file transfer 1390.Ar structure 1391to 1392.Ar struct-name . 1393The default (and only supported) 1394structure is 1395.Dq file . 1396.It Ic sunique 1397Toggle storing of files on remote machine under unique file names. 1398The remote 1399.Tn FTP 1400server must support 1401.Tn FTP 1402protocol 1403.Dv STOU 1404command for 1405successful completion. 1406The remote server will report unique name. 1407Default value is off. 1408.It Ic system 1409Show the type of operating system running on the remote machine. 1410.It Ic tenex 1411Set the file transfer type to that needed to 1412talk to 1413.Tn TENEX 1414machines. 1415.It Ic throttle 1416A synonym for 1417.Ic rate . 1418.It Ic trace 1419Toggle packet tracing. 1420.It Ic type Op Ar type-name 1421Set the file transfer 1422.Ic type 1423to 1424.Ar type-name . 1425If no type is specified, the current type 1426is printed. 1427The default type is network 1428.Tn ASCII . 1429.It Ic umask Op Ar newmask 1430Set the default umask on the remote server to 1431.Ar newmask . 1432If 1433.Ar newmask 1434is omitted, the current umask is printed. 1435.It Ic unset Ar option 1436Unset 1437.Ar option . 1438Refer to 1439.Ic set 1440for more information. 1441.It Ic usage Ar command 1442Print the usage message for 1443.Ar command . 1444.It Xo 1445.Ic user Ar user-name 1446.Op Ar password Op Ar account 1447.Xc 1448Identify yourself to the remote 1449.Tn FTP 1450server. 1451If the 1452.Ar password 1453is not specified and the server requires it, 1454.Nm 1455will prompt the user for it (after disabling local echo). 1456If an 1457.Ar account 1458field is not specified, and the 1459.Tn FTP 1460server 1461requires it, the user will be prompted for it. 1462If an 1463.Ar account 1464field is specified, an account command will 1465be relayed to the remote server after the login sequence 1466is completed if the remote server did not require it 1467for logging in. 1468Unless 1469.Nm 1470is invoked with 1471.Dq auto-login 1472disabled, this process is done automatically on initial connection to the 1473.Tn FTP 1474server. 1475.It Ic verbose 1476Toggle verbose mode. 1477In verbose mode, all responses from 1478the 1479.Tn FTP 1480server are displayed to the user. 1481In addition, 1482if verbose is on, when a file transfer completes, statistics 1483regarding the efficiency of the transfer are reported. 1484By default, 1485verbose is on. 1486.It Ic xferbuf Ar size 1487Set the size of the socket send and receive buffers to 1488.Ar size . 1489.It Ic \&? Op Ar command 1490A synonym for 1491.Ic help . 1492.El 1493.Pp 1494Command arguments which have embedded spaces may be quoted with 1495quote 1496.Sq \&" 1497marks. 1498.Pp 1499Commands which toggle settings can take an explicit 1500.Ic on 1501or 1502.Ic off 1503argument to force the setting appropriately. 1504.Pp 1505Commands which take a byte count as an argument 1506(e.g., 1507.Ic hash , 1508.Ic rate , 1509and 1510.Ic xferbuf ) 1511support an optional suffix on the argument which changes the 1512interpretation of the argument. 1513Supported suffixes are: 1514.Bl -tag -width 3n -offset indent -compact 1515.It Li b 1516Causes no modification. 1517(Optional) 1518.It Li k 1519Kilo; multiply the argument by 1024 1520.It Li m 1521Mega; multiply the argument by 1048576 1522.It Li g 1523Giga; multiply the argument by 1073741824 1524.El 1525.Pp 1526If 1527.Nm 1528receives a 1529.Dv SIGINFO 1530(see the 1531.Dq status 1532argument of 1533.Xr stty 1 ) 1534or 1535.Dv SIGQUIT 1536signal whilst a transfer is in progress, the current transfer rate 1537statistics will be written to the standard error output, in the 1538same format as the standard completion message. 1539.Sh AUTO-FETCHING FILES 1540In addition to standard commands, this version of 1541.Nm 1542supports an auto-fetch feature. 1543To enable auto-fetch, simply pass the list of hostnames/files 1544on the command line. 1545.Pp 1546The following formats are valid syntax for an auto-fetch element: 1547.Bl -tag -width "FOO " 1548.\" [user@]host:[path][/] 1549.It Xo 1550.Sm off 1551.Op Ar user Li \&@ 1552.Ar host Li \&: 1553.Op Ar path 1554.Op Li / 1555.Sm on 1556.Xc 1557.Dq Classic 1558.Tn FTP 1559format. 1560.Pp 1561If 1562.Ar path 1563contains a glob character and globbing is enabled, 1564(see 1565.Ic glob ) , 1566then the equivalent of 1567.Ql mget path 1568is performed. 1569.Pp 1570If the directory component of 1571.Ar path 1572contains no globbing characters, 1573it is stored locally with the name basename (see 1574.Xr basename 1 ) 1575of 1576.Ic path , 1577in the current directory. 1578Otherwise, the full remote name is used as the local name, 1579relative to the local root directory. 1580.\" ftp://[user[:password]@]host[:port]/path[/][;type=X] 1581.It Xo 1582.Sm off 1583.Li ftp:// 1584.Oo Ar user 1585.Op Li \&: Ar password 1586.Li \&@ Oc 1587.Ar host Oo Li \&: Ar port Oc 1588.Li / Ar path 1589.Op Li / 1590.Op Li ;type= Ar X 1591.Sm on 1592.Xc 1593An 1594.Tn FTP 1595URL, retrieved using the 1596.Tn FTP 1597protocol if 1598.Ic "set ftp_proxy" 1599isn't defined. 1600Otherwise, transfer the URL using 1601.Tn HTTP 1602via the proxy defined in 1603.Ic "set ftp_proxy" . 1604If 1605.Ic "set ftp_proxy" 1606isn't defined and 1607.Ar user 1608is given, login as 1609.Ar user . 1610In this case, use 1611.Ar password 1612if supplied, otherwise prompt the user for one. 1613.Pp 1614If a suffix of 1615.Sq ;type=A 1616or 1617.Sq ;type=I 1618is supplied, then the transfer type will take place as 1619ascii or binary (respectively). 1620The default transfer type is binary. 1621.Pp 1622In order to be compliant with 1623.Li RFC3986 , 1624.Nm 1625interprets the 1626.Ar path 1627part of an 1628.Dq ftp:// 1629auto-fetch URL as follows: 1630.Bl -bullet 1631.It 1632The 1633.Sq Li / 1634immediately after the 1635.Ar host Ns Oo Li \&: Ns Ar port Oc 1636is interpreted as a separator before the 1637.Ar path , 1638and not as part of the 1639.Ar path 1640itself. 1641.It 1642The 1643.Ar path 1644is interpreted as a 1645.So Li / Sc Ns -separated 1646list of name components. 1647For all but the last such component, 1648.Nm 1649performs the equivalent of a 1650.Ic cd 1651command. 1652For the last path component, 1653.Nm 1654performs the equivalent of a 1655.Ic get 1656command. 1657.It 1658Empty name components, 1659which result from 1660.Sq Li // 1661within the 1662.Ar path , 1663or from an extra 1664.Sq Li / 1665at the beginning of the 1666.Ar path , 1667will cause the equivalent of a 1668.Ic cd 1669command without a directory name. 1670This is unlikely to be useful. 1671.It 1672Any 1673.Sq Li \&% Ns Ar XX 1674codes 1675(per 1676.Li RFC3986 ) 1677within the path components are decoded, with 1678.Ar XX 1679representing a character code in hexadecimal. 1680This decoding takes place after the 1681.Ar path 1682has been split into components, 1683but before each component is used in the equivalent of a 1684.Ic cd 1685or 1686.Ic get 1687command. 1688Some often-used codes are 1689.Sq Li \&%2F 1690(which represents 1691.Sq Li / ) 1692and 1693.Sq Li \&%7E 1694(which represents 1695.Sq Li ~ ) . 1696.El 1697.Pp 1698The above interpretation has the following consequences: 1699.Bl -bullet 1700.It 1701The path is interpreted relative to the 1702default login directory of the specified user or of the 1703.Sq anonymous 1704user. 1705If the 1706.Pa / 1707directory is required, use a leading path of 1708.Dq %2F . 1709If a user's home directory is required (and the remote server supports 1710the syntax), use a leading path of 1711.Dq %7Euser/ . 1712For example, to retrieve 1713.Pa /etc/motd 1714from 1715.Sq localhost 1716as the user 1717.Sq myname 1718with the password 1719.Sq mypass , 1720use 1721.Dq ftp://myname:mypass@localhost/%2fetc/motd 1722.It 1723The exact 1724.Ic cd 1725and 1726.Ic get 1727commands can be controlled by careful choice of 1728where to use 1729.Sq / 1730and where to use 1731.Sq %2F 1732(or 1733.Sq %2f ) . 1734For example, the following URLs correspond to the 1735equivalents of the indicated commands: 1736.Bl -tag -width "ftp://host/%2Fdir1%2Fdir2%2Ffile" 1737.It ftp://host/dir1/dir2/file 1738.Dq "cd dir1" , 1739.Dq "cd dir2" , 1740.Dq "get file" . 1741.It ftp://host/%2Fdir1/dir2/file 1742.Dq "cd /dir1" , 1743.Dq "cd dir2" , 1744.Dq "get file" . 1745.It ftp://host/dir1%2Fdir2/file 1746.Dq "cd dir1/dir2" , 1747.Dq "get file" . 1748.It ftp://host/%2Fdir1%2Fdir2/file 1749.Dq "cd /dir1/dir2" , 1750.Dq "get file" . 1751.It ftp://host/dir1%2Fdir2%2Ffile 1752.Dq "get dir1/dir2/file" . 1753.It ftp://host/%2Fdir1%2Fdir2%2Ffile 1754.Dq "get /dir1/dir2/file" . 1755.El 1756.It 1757You must have appropriate access permission for each of the 1758intermediate directories that is used in the equivalent of a 1759.Ic cd 1760command. 1761.El 1762.\" http://[user[:password]@]host[:port]/path 1763.It Xo 1764.Sm off 1765.Li http:// 1766.Oo Ar user 1767.Op Li \&: Ar password 1768.Li \&@ Oc 1769.Ar host Oo Li \&: Ar port Oc 1770.Li / Ar path 1771.Sm on 1772.Xc 1773An 1774.Tn HTTP 1775URL, retrieved using the 1776.Tn HTTP 1777protocol. 1778If 1779.Ic "set http_proxy" 1780is defined, it is used as a URL to an 1781.Tn HTTP 1782proxy server. 1783If 1784.Tn HTTP 1785authorization is required to retrieve 1786.Ar path , 1787and 1788.Sq user 1789(and optionally 1790.Sq password ) 1791is in the URL, use them for the first attempt to authenticate. 1792.\" file:///path 1793.It Xo 1794.Sm off 1795.Li file:/// Ar path 1796.Sm on 1797.Xc 1798A local URL, copied from 1799.Pa / Ns Ar path 1800on the local host. 1801.\" about: 1802.It Xo 1803.Sm off 1804.Li about: 1805.Ar topic 1806.Sm on 1807.Xc 1808Display information regarding 1809.Ar topic ; 1810no file is retrieved for this auto-fetched element. 1811Supported values include: 1812.Bl -tag -width "about:version" 1813.It Li about:ftp 1814Information about 1815.Nm ftp . 1816.It Li about:version 1817The version of 1818.Nm ftp . 1819Useful to provide when reporting problems. 1820.El 1821.El 1822.Pp 1823Unless noted otherwise above, and 1824.Fl o Ar output 1825is not given, the file is stored in the current directory as the 1826.Xr basename 1 1827of 1828.Ar path . 1829Note that if a 1830.Tn HTTP 1831redirect is received, the fetch is retried using the new target URL 1832supplied by the server, with a corresponding new 1833.Ar path . 1834Using an explicit 1835.Fl o Ar output 1836is recommended, to avoid writing to unexpected file names. 1837.Pp 1838If a classic format or an 1839.Tn FTP 1840URL format has a trailing 1841.Sq / 1842or an empty 1843.Ar path 1844component, then 1845.Nm 1846will connect to the site and 1847.Ic cd 1848to the directory given as the path, and leave the user in interactive 1849mode ready for further input. 1850This will not work if 1851.Ic "set ftp_proxy" 1852is being used. 1853.Pp 1854Direct 1855.Tn HTTP 1856transfers use HTTP 1.1. 1857Proxied 1858.Tn FTP 1859and 1860.Tn HTTP 1861transfers use HTTP 1.0. 1862.Pp 1863If 1864.Fl R 1865is given, all auto-fetches that don't go via the 1866.Tn FTP 1867or 1868.Tn HTTP 1869proxies will be restarted. 1870For 1871.Tn FTP , 1872this is implemented by using 1873.Nm reget 1874instead of 1875.Nm get . 1876For 1877.Tn HTTP , 1878this is implemented by using the 1879.Sq "Range: bytes=" 1880.Tn "HTTP/1.1" 1881directive. 1882.Pp 1883If WWW or proxy WWW authentication is required, you will be prompted 1884to enter a username and password to authenticate with. 1885.Pp 1886When specifying IPv6 numeric addresses in a URL, you need to 1887surround the address in square brackets. 1888E.g.: 1889.Dq ftp://[::1]:21/ . 1890This is because colons are used in IPv6 numeric address as well as 1891being the separator for the port number. 1892.Sh ABORTING A FILE TRANSFER 1893To abort a file transfer, use the terminal interrupt key 1894(usually Ctrl-C). 1895Sending transfers will be immediately halted. 1896Receiving transfers will be halted by sending an 1897.Tn FTP 1898protocol 1899.Dv ABOR 1900command to the remote server, and discarding any further data received. 1901The speed at which this is accomplished depends upon the remote 1902server's support for 1903.Dv ABOR 1904processing. 1905If the remote server does not support the 1906.Dv ABOR 1907command, the prompt will not appear until the remote server has completed 1908sending the requested file. 1909.Pp 1910If the terminal interrupt key sequence is used whilst 1911.Nm 1912is awaiting a reply from the remote server for the ABOR processing, 1913then the connection will be closed. 1914This is different from the traditional behaviour (which ignores the 1915terminal interrupt during this phase), but is considered more useful. 1916.Sh FILE NAMING CONVENTIONS 1917Files specified as arguments to 1918.Nm 1919commands are processed according to the following rules. 1920.Bl -enum 1921.It 1922If the file name 1923.Sq Fl 1924is specified, the 1925.Ar stdin 1926(for reading) or 1927.Ar stdout 1928(for writing) is used. 1929.It 1930If the first character of the file name is 1931.Sq \&| , 1932the 1933remainder of the argument is interpreted as a shell command. 1934.Nm 1935then forks a shell, using 1936.Xr popen 3 1937with the argument supplied, and reads (writes) from the stdout 1938(stdin). 1939If the shell command includes spaces, the argument 1940must be quoted; e.g. 1941.Dq Qq Li \&| ls\ \-lt . 1942A particularly 1943useful example of this mechanism is: 1944.Dq Li dir \&"\&" \&|more . 1945.It 1946Failing the above checks, if 1947.Dq globbing 1948is enabled, local file names are expanded according to the rules 1949used in the 1950.Xr csh 1 ; 1951see the 1952.Ic glob 1953command. 1954If the 1955.Nm 1956command expects a single local file (e.g. 1957.Ic put ) , 1958only the first filename generated by the "globbing" operation is used. 1959.It 1960For 1961.Ic mget 1962commands and 1963.Ic get 1964commands with unspecified local file names, the local filename is 1965the remote filename, which may be altered by a 1966.Ic case , 1967.Ic ntrans , 1968or 1969.Ic nmap 1970setting. 1971The resulting filename may then be altered if 1972.Ic runique 1973is on. 1974.It 1975For 1976.Ic mput 1977commands and 1978.Ic put 1979commands with unspecified remote file names, the remote filename is 1980the local filename, which may be altered by a 1981.Ic ntrans 1982or 1983.Ic nmap 1984setting. 1985The resulting filename may then be altered by the remote server if 1986.Ic sunique 1987is on. 1988.El 1989.Sh FILE TRANSFER PARAMETERS 1990The 1991.Tn FTP 1992specification specifies many parameters which may affect a file transfer. 1993The 1994.Ic type 1995may be one of 1996.Dq ascii , 1997.Dq image 1998(binary), 1999.Dq ebcdic , 2000and 2001.Dq local byte size 2002(for 2003.Tn PDP Ns -10's 2004and 2005.Tn PDP Ns -20's 2006mostly). 2007.Nm 2008supports the ascii and image types of file transfer, 2009plus local byte size 8 for 2010.Ic tenex 2011mode transfers. 2012.Pp 2013.Nm 2014supports only the default values for the remaining 2015file transfer parameters: 2016.Ic mode , 2017.Ic form , 2018and 2019.Ic struct . 2020.Sh THE .netrc FILE 2021The 2022.Pa .netrc 2023file contains login and initialization information 2024used by the auto-login process. 2025It resides in the user's home directory, 2026unless overridden with the 2027.Fl N Ar netrc 2028option, or specified in the 2029.Ev NETRC 2030environment variable. 2031The following tokens are recognized; they may be separated by spaces, 2032tabs, or new-lines: 2033.Bl -tag -width password 2034.It Ic machine Ar name 2035Identify a remote machine 2036.Ar name . 2037The auto-login process searches the 2038.Pa .netrc 2039file for a 2040.Ic machine 2041token that matches the remote machine specified on the 2042.Nm 2043command line or as an 2044.Ic open 2045command argument. 2046Once a match is made, the subsequent 2047.Pa .netrc 2048tokens are processed, 2049stopping when the end of file is reached or another 2050.Ic machine 2051or a 2052.Ic default 2053token is encountered. 2054.It Ic default 2055This is the same as 2056.Ic machine 2057.Ar name 2058except that 2059.Ic default 2060matches any name. 2061There can be only one 2062.Ic default 2063token, and it must be after all 2064.Ic machine 2065tokens. 2066This is normally used as: 2067.Pp 2068.Dl default login anonymous password user@site 2069.Pp 2070thereby giving the user an automatic anonymous 2071.Tn FTP 2072login to 2073machines not specified in 2074.Pa .netrc . 2075This can be overridden 2076by using the 2077.Fl n 2078flag to disable auto-login. 2079.It Ic login Ar name 2080Identify a user on the remote machine. 2081If this token is present, the auto-login process will initiate 2082a login using the specified 2083.Ar name . 2084.It Ic password Ar string 2085Supply a password. 2086If this token is present, the auto-login process will supply the 2087specified string if the remote server requires a password as part 2088of the login process. 2089Note that if this token is present in the 2090.Pa .netrc 2091file for any user other 2092than 2093.Ar anonymous , 2094.Nm 2095will abort the auto-login process if the 2096.Pa .netrc 2097is readable by 2098anyone besides the user. 2099.It Ic account Ar string 2100Supply an additional account password. 2101If this token is present, the auto-login process will supply the 2102specified string if the remote server requires an additional 2103account password, or the auto-login process will initiate an 2104.Dv ACCT 2105command if it does not. 2106.It Ic macdef Ar name 2107Define a macro. 2108This token functions like the 2109.Nm 2110.Ic macdef 2111command functions. 2112A macro is defined with the specified name; its contents begin with the 2113next 2114.Pa .netrc 2115line and continue until a blank line (consecutive new-line 2116characters) is encountered. 2117Like the other tokens in the 2118.Pa .netrc 2119file, a 2120.Ic macdef 2121is applicable only to the 2122.Ic machine 2123definition preceding it. 2124A 2125.Ic macdef 2126entry cannot be used by multiple 2127.Ic machine 2128definitions; rather, it must be defined following each 2129.Ic machine 2130it is intended to be used with. 2131If a macro named 2132.Ic init 2133is defined, it is automatically executed as the last step in the 2134auto-login process. 2135For example, 2136.Bd -literal -offset indent 2137default 2138macdef init 2139epsv4 off 2140.Ed 2141.Pp 2142followed by a blank line. 2143.El 2144.Sh COMMAND LINE EDITING 2145.Nm 2146supports interactive command line editing, via the 2147.Xr editline 3 2148library. 2149It is enabled with the 2150.Ic edit 2151command, and is enabled by default if input is from a tty. 2152Previous lines can be recalled and edited with the arrow keys, 2153and other GNU Emacs-style editing keys may be used as well. 2154.Pp 2155The 2156.Xr editline 3 2157library is configured with a 2158.Pa .editrc 2159file - refer to 2160.Xr editrc 5 2161for more information. 2162.Pp 2163An extra key binding is available to 2164.Nm 2165to provide context sensitive command and filename completion 2166(including remote file completion). 2167To use this, bind a key to the 2168.Xr editline 3 2169command 2170.Ic ftp-complete . 2171By default, this is bound to the TAB key. 2172.Sh COMMAND LINE PROMPT 2173By default, 2174.Nm 2175displays a command line prompt of 2176.Dq "ftp\*[Gt] " 2177to the user. 2178This can be changed with the 2179.Ic "set prompt" 2180command. 2181.Pp 2182A prompt can be displayed on the right side of the screen (after the 2183command input) with the 2184.Ic "set rprompt" 2185command. 2186.Pp 2187The following formatting sequences are replaced by the given 2188information: 2189.Bl -tag -width "%% " -offset indent 2190.It Li \&%/ 2191The current remote working directory. 2192.\" %c[[0]n], %.[[0]n] 2193.It Xo 2194.Sm off 2195.Li \&%c 2196.Op Oo Li 0 Oc Ar n Ns , 2197.Li \&%. 2198.Op Oo Li 0 Oc Ar n 2199.Sm on 2200.Xc 2201The trailing component of the current remote working directory, or 2202.Em n 2203trailing components if a digit 2204.Em n 2205is given. 2206If 2207.Em n 2208begins with 2209.Sq 0 , 2210the number of skipped components precede the trailing component(s) in 2211the format 2212.\" ``/<number>trailing'' 2213.Do 2214.Sm off 2215.Li / Li \*[Lt] Va number Li \*[Gt] 2216.Va trailing 2217.Sm on 2218.Dc 2219(for 2220.Sq \&%c ) 2221or 2222.\" ``...trailing'' 2223.Dq Li \&... Ns Va trailing 2224(for 2225.Sq \&%. ) . 2226.It Li \&%M 2227The remote host name. 2228.It Li \&%m 2229The remote host name, up to the first 2230.Sq \&. . 2231.It Li \&%n 2232The remote user name. 2233.It Li \&%% 2234A single 2235.Sq % . 2236.El 2237.Sh ENVIRONMENT 2238.Nm 2239uses the following environment variables. 2240.Bl -tag -width "FTPSERVERPORT" 2241.It Ev FTPANONPASS 2242Password to send in an anonymous 2243.Tn FTP 2244transfer. 2245Defaults to 2246.Dq Li `whoami`@ . 2247.It Ev FTPMODE 2248Overrides the default operation mode. 2249Support values are: 2250.Bl -tag -width "passive" 2251.It Cm active 2252active mode 2253.Tn FTP 2254only 2255.It Cm auto 2256automatic determination of passive or active (this is the default) 2257.It Cm gate 2258gate-ftp mode 2259.It Cm passive 2260passive mode 2261.Tn FTP 2262only 2263.El 2264.It Ev FTPPROMPT 2265Command-line prompt to use. 2266Defaults to 2267.Dq "ftp\*[Gt] " . 2268Refer to 2269.Sx COMMAND LINE PROMPT 2270for more information. 2271.It Ev FTPRPROMPT 2272Command-line right side prompt to use. 2273Defaults to 2274.Dq "" . 2275Refer to 2276.Sx COMMAND LINE PROMPT 2277for more information. 2278.It Ev FTPSERVER 2279Host to use as gate-ftp server when 2280.Ic gate 2281is enabled. 2282.It Ev FTPSERVERPORT 2283Port to use when connecting to gate-ftp server when 2284.Ic gate 2285is enabled. 2286Default is port returned by a 2287.Fn getservbyname 2288lookup of 2289.Dq ftpgate/tcp . 2290.It Ev FTPUSERAGENT 2291The value to send for the 2292.Tn HTTP 2293User-Agent 2294header. 2295.It Ev HOME 2296For default location of a 2297.Pa .netrc 2298file, if one exists. 2299.It Ev NETRC 2300An alternate location of the 2301.Pa .netrc 2302file. 2303.It Ev PAGER 2304Used by various commands to display files. 2305Defaults to 2306.Xr more 1 2307if empty or not set. 2308.It Ev SHELL 2309For default shell. 2310.It Ev ftp_proxy 2311URL of 2312.Tn FTP 2313proxy to use when making 2314.Tn FTP 2315URL requests 2316(if not defined, use the standard 2317.Tn FTP 2318protocol). 2319.Pp 2320See 2321.Ev http_proxy 2322for further notes about proxy use. 2323.It Ev http_proxy 2324URL of 2325.Tn HTTP 2326proxy to use when making 2327.Tn HTTP 2328URL requests. 2329If proxy authentication is required and there is a username and 2330password in this URL, they will automatically be used in the first 2331attempt to authenticate to the proxy. 2332.Pp 2333If 2334.Dq unsafe 2335URL characters are required in the username or password 2336(for example 2337.Sq @ 2338or 2339.Sq / ) , 2340encode them with 2341.Li RFC3986 2342.Sq Li \&% Ns Ar XX 2343encoding. 2344.Pp 2345Note that the use of a username and password in 2346.Ev ftp_proxy 2347and 2348.Ev http_proxy 2349may be incompatible with other programs that use it 2350(such as 2351.Xr lynx 1 ) . 2352.Pp 2353.Em NOTE : 2354this is not used for interactive sessions, only for command-line 2355fetches. 2356.It Ev no_proxy 2357A space or comma separated list of hosts (or domains) for which 2358proxying is not to be used. 2359Each entry may have an optional trailing ":port", which restricts 2360the matching to connections to that port. 2361.El 2362.Sh EXTENDED PASSIVE MODE AND FIREWALLS 2363Some firewall configurations do not allow 2364.Nm 2365to use extended passive mode. 2366If you find that even a simple 2367.Ic ls 2368appears to hang after printing a message such as this: 2369.Pp 2370.Dl 229 Entering Extended Passive Mode (|||58551|) 2371.Pp 2372then you will need to disable extended passive mode with 2373.Ic epsv4 off . 2374See the above section 2375.Sx The .netrc File 2376for an example of how to make this automatic. 2377.Sh SEE ALSO 2378.Xr getservbyname 3 , 2379.Xr editrc 5 , 2380.Xr services 5 , 2381.Xr ftpd 8 2382.Sh STANDARDS 2383.Nm 2384attempts to be compliant with: 2385.Bl -tag -offset indent -width 8n 2386.It Li RFC0959 2387.Em File Transfer Protocol 2388.It Li RFC1123 2389.Em Requirements for Internet Hosts - Application and Support 2390.It Li RFC1635 2391.Em How to Use Anonymous FTP 2392.It Li RFC2389 2393.Em Feature negotiation mechanism for the File Transfer Protocol 2394.It Li RFC2428 2395.Em FTP Extensions for IPv6 and NATs 2396.It Li RFC2616 2397.Em Hypertext Transfer Protocol -- HTTP/1.1 2398.It Li RFC2822 2399.Em Internet Message Format 2400.It Li RFC3659 2401.Em Extensions to FTP 2402.It Li RFC3986 2403.Em Uniform Resource Identifier (URI) 2404.El 2405.Sh HISTORY 2406The 2407.Nm 2408command appeared in 2409.Bx 4.2 . 2410.Pp 2411Various features such as command line editing, context sensitive 2412command and file completion, dynamic progress bar, automatic 2413fetching of files and URLs, modification time preservation, 2414transfer rate throttling, configurable command line prompt, 2415and other enhancements over the standard 2416.Bx 2417.Nm 2418were implemented in 2419.Nx 1.3 2420and later releases 2421by 2422.An Luke Mewburn 2423.Aq lukem@NetBSD.org . 2424.Pp 2425IPv6 support was added by the WIDE/KAME project 2426(but may not be present in all non-NetBSD versions of this program, depending 2427if the operating system supports IPv6 in a similar manner to KAME). 2428.Sh BUGS 2429Correct execution of many commands depends upon proper behavior 2430by the remote server. 2431.Pp 2432An error in the treatment of carriage returns 2433in the 2434.Bx 4.2 2435ascii-mode transfer code 2436has been corrected. 2437This correction may result in incorrect transfers of binary files 2438to and from 2439.Bx 4.2 2440servers using the ascii type. 2441Avoid this problem by using the binary image type. 2442.Pp 2443.Nm 2444assumes that all IPv4 mapped addresses 2445.Po 2446IPv6 addresses with a form like 2447.Li ::ffff:10.1.1.1 2448.Pc 2449indicate IPv4 destinations which can be handled by 2450.Dv AF_INET 2451sockets. 2452However, in certain IPv6 network configurations, this assumption is not true. 2453In such an environment, IPv4 mapped addresses must be passed to 2454.Dv AF_INET6 2455sockets directly. 2456For example, if your site uses a SIIT translator for IPv6-to-IPv4 translation, 2457.Nm 2458is unable to support your configuration. 2459