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