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