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