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