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