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