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