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