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