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