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