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