1.\" $NetBSD: ftp.1,v 1.11 1995/09/08 01:06:24 tls Exp $ 2.\" 3.\" Copyright (c) 1985, 1989, 1990, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)ftp.1 8.3 (Berkeley) 10/9/94 35.\" 36.Dd March 23, 2006 37.Dt FTP 1 38.Os BSD 4.2 39.Sh NAME 40.Nm ftp 41.Nd 42.Tn ARPANET 43file transfer program 44.Sh SYNOPSIS 45.Nm ftp 46.Op Fl K 47.Op Fl d 48.Op Fl g 49.Op Fl i 50.Op Fl l 51.Op Fl n 52.Op Fl p 53.Op Fl t 54.Op Fl v 55.Op Fl x 56.Op Fl Fl no-gss-bindings 57.Op Fl Fl no-gss-delegate 58.Op Ar host 59.Sh DESCRIPTION 60.Nm 61is the user interface to the 62.Tn ARPANET 63standard File Transfer Protocol. 64The program allows a user to transfer files to and from a 65remote network site. 66.Pp 67Modifications have been made so that it almost follows the FTP 68Security Extensions, RFC 2228. 69.Pp 70Options may be specified at the command line, or to the 71command interpreter. 72.Bl -tag -width flag 73.It Fl K 74Disable Kerberos authentication. 75.It Fl t 76Enables packet tracing. 77.It Fl v 78Verbose option forces 79.Nm ftp 80to show all responses from the remote server, as well 81as report on data transfer statistics. 82.It Fl n 83Restrains 84.Nm ftp 85from attempting \*(Lqauto-login\*(Rq upon initial connection. 86If auto-login is enabled, 87.Nm ftp 88will check the 89.Pa .netrc 90(see below) file in the user's home directory for an entry describing 91an account on the remote machine. 92If no entry exists, 93.Nm ftp 94will prompt for the remote machine login name (default is the user 95identity on the local machine), and, if necessary, prompt for a password 96and an account with which to login. 97.It Fl i 98Turns off interactive prompting during 99multiple file transfers. 100.It Fl p 101Turn on passive mode. 102.It Fl d 103Enables debugging. 104.It Fl g 105Disables file name globbing. 106 .It Fl Fl no-gss-bindings 107Don't use GSS-API bindings when talking to peer. IP addresses will not 108be checked to ensure they match. 109.It Fl Fl no-gss-delegate 110Disable delegation of GSSAPI credentials. 111.It Fl l 112Disables command line editing. 113.It Fl x 114Encrypt command and data channel. 115.El 116.Pp 117The client host with which 118.Nm ftp 119is to communicate may be specified on the command line. 120If this is done, 121.Nm ftp 122will immediately attempt to establish a connection to an 123.Tn FTP 124server on that host; otherwise, 125.Nm ftp 126will enter its command interpreter and await instructions 127from the user. 128When 129.Nm ftp 130is awaiting commands from the user the prompt 131.Ql ftp\*[Gt] 132is provided to the user. 133The following commands are recognized 134by 135.Nm ftp : 136.Bl -tag -width Fl 137.It Ic \&! Op Ar command Op Ar args 138Invoke an interactive shell on the local machine. 139If there are arguments, the first is taken to be a command to execute 140directly, with the rest of the arguments as its arguments. 141.It Ic \&$ Ar macro-name Op Ar args 142Execute the macro 143.Ar macro-name 144that was defined with the 145.Ic macdef 146command. 147Arguments are passed to the macro unglobbed. 148.It Ic account Op Ar passwd 149Supply a supplemental password required by a remote system for access 150to resources once a login has been successfully completed. 151If no argument is included, the user will be prompted for an account 152password in a non-echoing input mode. 153.It Ic append Ar local-file Op Ar remote-file 154Append a local file to a file on the remote machine. 155If 156.Ar remote-file 157is left unspecified, the local file name is used in naming the 158remote file after being altered by any 159.Ic ntrans 160or 161.Ic nmap 162setting. 163File transfer uses the current settings for 164.Ic type , 165.Ic format , 166.Ic mode , 167and 168.Ic structure . 169.It Ic ascii 170Set the file transfer 171.Ic type 172to network 173.Tn ASCII . 174This is the default type. 175.It Ic bell 176Arrange that a bell be sounded after each file transfer 177command is completed. 178.It Ic binary 179Set the file transfer 180.Ic type 181to support binary image transfer. 182.It Ic bye 183Terminate the 184.Tn FTP 185session with the remote server 186and exit 187.Nm ftp . 188An end of file will also terminate the session and exit. 189.It Ic case 190Toggle remote computer file name case mapping during 191.Ic mget 192commands. 193When 194.Ic case 195is on (default is off), remote computer file names with all letters in 196upper case are written in the local directory with the letters mapped 197to lower case. 198.It Ic \&cd Ar remote-directory 199Change the working directory on the remote machine 200to 201.Ar remote-directory . 202.It Ic cdup 203Change the remote machine working directory to the parent of the 204current remote machine working directory. 205.It Ic chmod Ar mode file-name 206Change the permission modes of the file 207.Ar file-name 208on the remote 209sytem to 210.Ar mode . 211.It Ic close 212Terminate the 213.Tn FTP 214session with the remote server, and 215return to the command interpreter. 216Any defined macros are erased. 217.It Ic \&cr 218Toggle carriage return stripping during 219ascii type file retrieval. 220Records are denoted by a carriage return/linefeed sequence 221during ascii type file transfer. 222When 223.Ic \&cr 224is on (the default), carriage returns are stripped from this 225sequence to conform with the 226.Ux 227single linefeed record 228delimiter. 229Records on 230.Pf non\- Ns Ux 231remote systems may contain single linefeeds; 232when an ascii type transfer is made, these linefeeds may be 233distinguished from a record delimiter only when 234.Ic \&cr 235is off. 236.It Ic delete Ar remote-file 237Delete the file 238.Ar remote-file 239on the remote machine. 240.It Ic debug Op Ar debug-value 241Toggle debugging mode. 242If an optional 243.Ar debug-value 244is specified it is used to set the debugging level. 245When debugging is on, 246.Nm ftp 247prints each command sent to the remote machine, preceded 248by the string 249.Ql \-\-\*[Gt] 250.It Xo 251.Ic dir 252.Op Ar remote-directory 253.Op Ar local-file 254.Xc 255Print a listing of the directory contents in the 256directory, 257.Ar remote-directory , 258and, optionally, placing the output in 259.Ar local-file . 260If interactive prompting is on, 261.Nm ftp 262will prompt the user to verify that the last argument is indeed the 263target local file for receiving 264.Ic dir 265output. 266If no directory is specified, the current working 267directory on the remote machine is used. 268If no local 269file is specified, or 270.Ar local-file 271is 272.Fl , 273output comes to the terminal. 274.It Ic disconnect 275A synonym for 276.Ar close . 277.It Ic form Ar format 278Set the file transfer 279.Ic form 280to 281.Ar format . 282The default format is \*(Lqfile\*(Rq. 283.It Ic get Ar remote-file Op Ar local-file 284Retrieve the 285.Ar remote-file 286and store it on the local machine. 287If the local 288file name is not specified, it is given the same 289name it has on the remote machine, subject to 290alteration by the current 291.Ic case , 292.Ic ntrans , 293and 294.Ic nmap 295settings. 296The current settings for 297.Ic type , 298.Ic form , 299.Ic mode , 300and 301.Ic structure 302are used while transferring the file. 303.It Ic glob 304Toggle filename expansion for 305.Ic mdelete , 306.Ic mget 307and 308.Ic mput . 309If globbing is turned off with 310.Ic glob , 311the file name arguments 312are taken literally and not expanded. 313Globbing for 314.Ic mput 315is done as in 316.Xr csh 1 . 317For 318.Ic mdelete 319and 320.Ic mget , 321each remote file name is expanded 322separately on the remote machine and the lists are not merged. 323Expansion of a directory name is likely to be 324different from expansion of the name of an ordinary file: 325the exact result depends on the foreign operating system and ftp server, 326and can be previewed by doing 327.Ql mls remote-files \- . 328As a security measure, remotely globbed files that starts with 329.Sq / 330or contains 331.Sq ../ , 332will not be automatically received. If you have interactive prompting 333turned off, these filenames will be ignored. Note: 334.Ic mget 335and 336.Ic mput 337are not meant to transfer 338entire directory subtrees of files. 339That can be done by 340transferring a 341.Xr tar 1 342archive of the subtree (in binary mode). 343.It Ic hash 344Toggle hash-sign (``#'') printing for each data block 345transferred. 346The size of a data block is 1024 bytes. 347.It Ic help Op Ar command 348Print an informative message about the meaning of 349.Ar command . 350If no argument is given, 351.Nm ftp 352prints a list of the known commands. 353.It Ic idle Op Ar seconds 354Set the inactivity timer on the remote server to 355.Ar seconds 356seconds. 357If 358.Ar seconds 359is omitted, the current inactivity timer is printed. 360.It Ic lcd Op Ar directory 361Change the working directory on the local machine. 362If 363no 364.Ar directory 365is specified, the user's home directory is used. 366.It Xo 367.Ic \&ls 368.Op Ar remote-directory 369.Op Ar local-file 370.Xc 371Print a listing of the contents of a 372directory on the remote machine. 373The listing includes any system-dependent information that the server 374chooses to include; for example, most 375.Ux 376systems will produce 377output from the command 378.Ql ls \-l . 379(See also 380.Ic nlist . ) 381If 382.Ar remote-directory 383is left unspecified, the current working directory is used. 384If interactive prompting is on, 385.Nm ftp 386will prompt the user to verify that the last argument is indeed the 387target local file for receiving 388.Ic \&ls 389output. 390If no local file is specified, or if 391.Ar local-file 392is 393.Sq Fl , 394the output is sent to the terminal. 395.It Ic macdef Ar macro-name 396Define a macro. 397Subsequent lines are stored as the macro 398.Ar macro-name ; 399a null line (consecutive newline characters 400in a file or 401carriage returns from the terminal) terminates macro input mode. 402There is a limit of 16 macros and 4096 total characters in all 403defined macros. 404Macros remain defined until a 405.Ic close 406command is executed. 407The macro processor interprets `$' and `\e' as special characters. 408A `$' followed by a number (or numbers) is replaced by the 409corresponding argument on the macro invocation command line. 410A `$' followed by an `i' signals that macro processor that the 411executing macro is to be looped. 412On the first pass `$i' is 413replaced by the first argument on the macro invocation command line, 414on the second pass it is replaced by the second argument, and so on. 415A `\e' followed by any character is replaced by that character. 416Use the `\e' to prevent special treatment of the `$'. 417.It Ic mdelete Op Ar remote-files 418Delete the 419.Ar remote-files 420on the remote machine. 421.It Ic mdir Ar remote-files local-file 422Like 423.Ic dir , 424except multiple remote files may be specified. 425If interactive prompting is on, 426.Nm ftp 427will prompt the user to verify that the last argument is indeed the 428target local file for receiving 429.Ic mdir 430output. 431.It Ic mget Ar remote-files 432Expand the 433.Ar remote-files 434on the remote machine 435and do a 436.Ic get 437for each file name thus produced. 438See 439.Ic glob 440for details on the filename expansion. 441Resulting file names will then be processed according to 442.Ic case , 443.Ic ntrans , 444and 445.Ic nmap 446settings. 447Files are transferred into the local working directory, 448which can be changed with 449.Ql lcd directory ; 450new local directories can be created with 451.Ql "\&! mkdir directory" . 452.It Ic mkdir Ar directory-name 453Make a directory on the remote machine. 454.It Ic mls Ar remote-files local-file 455Like 456.Ic nlist , 457except multiple remote files may be specified, 458and the 459.Ar local-file 460must be specified. 461If interactive prompting is on, 462.Nm ftp 463will prompt the user to verify that the last argument is indeed the 464target local file for receiving 465.Ic mls 466output. 467.It Ic mode Op Ar mode-name 468Set the file transfer 469.Ic mode 470to 471.Ar mode-name . 472The default mode is \*(Lqstream\*(Rq mode. 473.It Ic modtime Ar file-name 474Show the last modification time of the file on the remote machine. 475.It Ic mput Ar local-files 476Expand wild cards in the list of local files given as arguments 477and do a 478.Ic put 479for each file in the resulting list. 480See 481.Ic glob 482for details of filename expansion. 483Resulting file names will then be processed according to 484.Ic ntrans 485and 486.Ic nmap 487settings. 488.It Ic newer Ar file-name 489Get the file only if the modification time of the remote file is more 490recent that the file on the current system. 491If the file does not 492exist on the current system, the remote file is considered 493.Ic newer . 494Otherwise, this command is identical to 495.Ar get . 496.It Xo 497.Ic nlist 498.Op Ar remote-directory 499.Op Ar local-file 500.Xc 501Print a list of the files in a 502directory on the remote machine. 503If 504.Ar remote-directory 505is left unspecified, the current working directory is used. 506If interactive prompting is on, 507.Nm ftp 508will prompt the user to verify that the last argument is indeed the 509target local file for receiving 510.Ic nlist 511output. 512If no local file is specified, or if 513.Ar local-file 514is 515.Fl , 516the output is sent to the terminal. 517.It Ic nmap Op Ar inpattern outpattern 518Set or unset the filename mapping mechanism. 519If no arguments are specified, the filename mapping mechanism is unset. 520If arguments are specified, remote filenames are mapped during 521.Ic mput 522commands and 523.Ic put 524commands issued without a specified remote target filename. 525If arguments are specified, local filenames are mapped during 526.Ic mget 527commands and 528.Ic get 529commands issued without a specified local target filename. 530This command is useful when connecting to a 531.No non\- Ns Ux 532remote computer 533with different file naming conventions or practices. 534The mapping follows the pattern set by 535.Ar inpattern 536and 537.Ar outpattern . 538.Op Ar Inpattern 539is a template for incoming filenames (which may have already been 540processed according to the 541.Ic ntrans 542and 543.Ic case 544settings). 545Variable templating is accomplished by including the 546sequences `$1', `$2', ..., `$9' in 547.Ar inpattern . 548Use `\\' to prevent this special treatment of the `$' character. 549All other characters are treated literally, and are used to determine the 550.Ic nmap 551.Op Ar inpattern 552variable values. 553For example, given 554.Ar inpattern 555$1.$2 and the remote file name "mydata.data", $1 would have the value 556"mydata", and $2 would have the value "data". 557The 558.Ar outpattern 559determines the resulting mapped filename. 560The sequences `$1', `$2', ...., `$9' are replaced by any value resulting 561from the 562.Ar inpattern 563template. 564The sequence `$0' is replace by the original filename. 565Additionally, the sequence 566.Ql Op Ar seq1 , Ar seq2 567is replaced by 568.Op Ar seq1 569if 570.Ar seq1 571is not a null string; otherwise it is replaced by 572.Ar seq2 . 573For example, the command 574.Pp 575.Bd -literal -offset indent -compact 576nmap $1.$2.$3 [$1,$2].[$2,file] 577.Ed 578.Pp 579would yield 580the output filename "myfile.data" for input filenames "myfile.data" and 581"myfile.data.old", "myfile.file" for the input filename "myfile", and 582"myfile.myfile" for the input filename ".myfile". 583Spaces may be included in 584.Ar outpattern , 585as in the example: `nmap $1 sed "s/ *$//" \*[Gt] $1' . 586Use the `\e' character to prevent special treatment 587of the `$','[','[', and `,' characters. 588.It Ic ntrans Op Ar inchars Op Ar outchars 589Set or unset the filename character translation mechanism. 590If no arguments are specified, the filename character 591translation mechanism is unset. 592If arguments are specified, characters in 593remote filenames are translated during 594.Ic mput 595commands and 596.Ic put 597commands issued without a specified remote target filename. 598If arguments are specified, characters in 599local filenames are translated during 600.Ic mget 601commands and 602.Ic get 603commands issued without a specified local target filename. 604This command is useful when connecting to a 605.No non\- Ns Ux 606remote computer 607with different file naming conventions or practices. 608Characters in a filename matching a character in 609.Ar inchars 610are replaced with the corresponding character in 611.Ar outchars . 612If the character's position in 613.Ar inchars 614is longer than the length of 615.Ar outchars , 616the character is deleted from the file name. 617.It Ic open Ar host Op Ar port 618Establish a connection to the specified 619.Ar host 620.Tn FTP 621server. 622An optional port number may be supplied, 623in which case, 624.Nm ftp 625will attempt to contact an 626.Tn FTP 627server at that port. 628If the 629.Ic auto-login 630option is on (default), 631.Nm ftp 632will also attempt to automatically log the user in to 633the 634.Tn FTP 635server (see below). 636.It Ic passive 637Toggle passive mode. If passive mode is turned on 638(default is off), the ftp client will 639send a 640.Dv PASV 641command for all data connections instead of the usual 642.Dv PORT 643command. The 644.Dv PASV 645command requests that the remote server open a port for the data connection 646and return the address of that port. The remote server listens on that 647port and the client connects to it. When using the more traditional 648.Dv PORT 649command, the client listens on a port and sends that address to the remote 650server, who connects back to it. Passive mode is useful when using 651.Nm ftp 652through a gateway router or host that controls the directionality of 653traffic. 654(Note that though ftp servers are required to support the 655.Dv PASV 656command by RFC 1123, some do not.) 657.It Ic prompt 658Toggle interactive prompting. 659Interactive prompting 660occurs during multiple file transfers to allow the 661user to selectively retrieve or store files. 662If prompting is turned off (default is on), any 663.Ic mget 664or 665.Ic mput 666will transfer all files, and any 667.Ic mdelete 668will delete all files. 669.It Ic proxy Ar ftp-command 670Execute an ftp command on a secondary control connection. 671This command allows simultaneous connection to two remote ftp 672servers for transferring files between the two servers. 673The first 674.Ic proxy 675command should be an 676.Ic open , 677to establish the secondary control connection. 678Enter the command "proxy ?" to see other ftp commands executable on the 679secondary connection. 680The following commands behave differently when prefaced by 681.Ic proxy : 682.Ic open 683will not define new macros during the auto-login process, 684.Ic close 685will not erase existing macro definitions, 686.Ic get 687and 688.Ic mget 689transfer files from the host on the primary control connection 690to the host on the secondary control connection, and 691.Ic put , 692.Ic mput , 693and 694.Ic append 695transfer files from the host on the secondary control connection 696to the host on the primary control connection. 697Third party file transfers depend upon support of the ftp protocol 698.Dv PASV 699command by the server on the secondary control connection. 700.It Ic put Ar local-file Op Ar remote-file 701Store a local file on the remote machine. 702If 703.Ar remote-file 704is left unspecified, the local file name is used 705after processing according to any 706.Ic ntrans 707or 708.Ic nmap 709settings 710in naming the remote file. 711File transfer uses the 712current settings for 713.Ic type , 714.Ic format , 715.Ic mode , 716and 717.Ic structure . 718.It Ic pwd 719Print the name of the current working directory on the remote 720machine. 721.It Ic quit 722A synonym for 723.Ic bye . 724.It Ic quote Ar arg1 arg2 ... 725The arguments specified are sent, verbatim, to the remote 726.Tn FTP 727server. 728.It Ic recv Ar remote-file Op Ar local-file 729A synonym for get. 730.It Ic reget Ar remote-file Op Ar local-file 731Reget acts like get, except that if 732.Ar local-file 733exists and is 734smaller than 735.Ar remote-file , 736.Ar local-file 737is presumed to be 738a partially transferred copy of 739.Ar remote-file 740and the transfer 741is continued from the apparent point of failure. 742This command 743is useful when transferring very large files over networks that 744are prone to dropping connections. 745.It Ic remotehelp Op Ar command-name 746Request help from the remote 747.Tn FTP 748server. 749If a 750.Ar command-name 751is specified it is supplied to the server as well. 752.It Ic remotestatus Op Ar file-name 753With no arguments, show status of remote machine. 754If 755.Ar file-name 756is specified, show status of 757.Ar file-name 758on remote machine. 759.It Xo 760.Ic rename 761.Op Ar from 762.Op Ar to 763.Xc 764Rename the file 765.Ar from 766on the remote machine, to the file 767.Ar to . 768.It Ic reset 769Clear reply queue. 770This command re-synchronizes command/reply sequencing with the remote 771ftp server. 772Resynchronization may be necessary following a violation of the ftp protocol 773by the remote server. 774.It Ic restart Ar marker 775Restart the immediately following 776.Ic get 777or 778.Ic put 779at the 780indicated 781.Ar marker . 782On 783.Ux 784systems, marker is usually a byte 785offset into the file. 786.It Ic rmdir Ar directory-name 787Delete a directory on the remote machine. 788.It Ic runique 789Toggle storing of files on the local system with unique filenames. 790If a file already exists with a name equal to the target 791local filename for a 792.Ic get 793or 794.Ic mget 795command, a ".1" is appended to the name. 796If the resulting name matches another existing file, 797a ".2" is appended to the original name. 798If this process continues up to ".99", an error 799message is printed, and the transfer does not take place. 800The generated unique filename will be reported. 801Note that 802.Ic runique 803will not affect local files generated from a shell command 804(see below). 805The default value is off. 806.It Ic send Ar local-file Op Ar remote-file 807A synonym for put. 808.It Ic sendport 809Toggle the use of 810.Dv PORT 811commands. 812By default, 813.Nm ftp 814will attempt to use a 815.Dv PORT 816command when establishing 817a connection for each data transfer. 818The use of 819.Dv PORT 820commands can prevent delays 821when performing multiple file transfers. 822If the 823.Dv PORT 824command fails, 825.Nm ftp 826will use the default data port. 827When the use of 828.Dv PORT 829commands is disabled, no attempt will be made to use 830.Dv PORT 831commands for each data transfer. 832This is useful 833for certain 834.Tn FTP 835implementations which do ignore 836.Dv PORT 837commands but, incorrectly, indicate they've been accepted. 838.It Ic site Ar arg1 arg2 ... 839The arguments specified are sent, verbatim, to the remote 840.Tn FTP 841server as a 842.Dv SITE 843command. 844.It Ic size Ar file-name 845Return size of 846.Ar file-name 847on remote machine. 848.It Ic status 849Show the current status of 850.Nm ftp . 851.It Ic struct Op Ar struct-name 852Set the file transfer 853.Ar structure 854to 855.Ar struct-name . 856By default \*(Lqstream\*(Rq structure is used. 857.It Ic sunique 858Toggle storing of files on remote machine under unique file names. 859Remote ftp server must support ftp protocol 860.Dv STOU 861command for 862successful completion. 863The remote server will report unique name. 864Default value is off. 865.It Ic system 866Show the type of operating system running on the remote machine. 867.It Ic tenex 868Set the file transfer type to that needed to 869talk to 870.Tn TENEX 871machines. 872.It Ic trace 873Toggle packet tracing. 874.It Ic type Op Ar type-name 875Set the file transfer 876.Ic type 877to 878.Ar type-name . 879If no type is specified, the current type 880is printed. 881The default type is network 882.Tn ASCII . 883.It Ic umask Op Ar newmask 884Set the default umask on the remote server to 885.Ar newmask . 886If 887.Ar newmask 888is omitted, the current umask is printed. 889.It Xo 890.Ic user Ar user-name 891.Op Ar password 892.Op Ar account 893.Xc 894Identify yourself to the remote 895.Tn FTP 896server. 897If the 898.Ar password 899is not specified and the server requires it, 900.Nm ftp 901will prompt the user for it (after disabling local echo). 902If an 903.Ar account 904field is not specified, and the 905.Tn FTP 906server 907requires it, the user will be prompted for it. 908If an 909.Ar account 910field is specified, an account command will 911be relayed to the remote server after the login sequence 912is completed if the remote server did not require it 913for logging in. 914Unless 915.Nm ftp 916is invoked with \*(Lqauto-login\*(Rq disabled, this 917process is done automatically on initial connection to 918the 919.Tn FTP 920server. 921.It Ic verbose 922Toggle verbose mode. 923In verbose mode, all responses from 924the 925.Tn FTP 926server are displayed to the user. 927In addition, 928if verbose is on, when a file transfer completes, statistics 929regarding the efficiency of the transfer are reported. 930By default, 931verbose is on. 932.It Ic \&? Op Ar command 933A synonym for help. 934.El 935.Pp 936The following command can be used with ftpsec-aware servers. 937.Bl -tag -width Fl 938.It Xo 939.Ic prot 940.Ar clear | 941.Ar safe | 942.Ar confidential | 943.Ar private 944.Xc 945Set the data protection level to the requested level. 946.El 947.Pp 948The following command can be used with ftp servers that has 949implemented the KAUTH site command. 950.Bl -tag -width Fl 951.It Ic kauth Op Ar principal 952Obtain remote tickets. 953.El 954.Pp 955Command arguments which have embedded spaces may be quoted with 956quote `"' marks. 957.Sh ABORTING A FILE TRANSFER 958To abort a file transfer, use the terminal interrupt key 959(usually Ctrl-C). 960Sending transfers will be immediately halted. 961Receiving transfers will be halted by sending a ftp protocol 962.Dv ABOR 963command to the remote server, and discarding any further data received. 964The speed at which this is accomplished depends upon the remote 965server's support for 966.Dv ABOR 967processing. 968If the remote server does not support the 969.Dv ABOR 970command, an 971.Ql ftp\*[Gt] 972prompt will not appear until the remote server has completed 973sending the requested file. 974.Pp 975The terminal interrupt key sequence will be ignored when 976.Nm ftp 977has completed any local processing and is awaiting a reply 978from the remote server. 979A long delay in this mode may result from the ABOR processing described 980above, or from unexpected behavior by the remote server, including 981violations of the ftp protocol. 982If the delay results from unexpected remote server behavior, the local 983.Nm ftp 984program must be killed by hand. 985.Sh FILE NAMING CONVENTIONS 986Files specified as arguments to 987.Nm ftp 988commands are processed according to the following rules. 989.Bl -enum 990.It 991If the file name 992.Sq Fl 993is specified, the 994.Ar stdin 995(for reading) or 996.Ar stdout 997(for writing) is used. 998.It 999If the first character of the file name is 1000.Sq \&| , 1001the 1002remainder of the argument is interpreted as a shell command. 1003.Nm Ftp 1004then forks a shell, using 1005.Xr popen 3 1006with the argument supplied, and reads (writes) from the stdout 1007(stdin). 1008If the shell command includes spaces, the argument 1009must be quoted; e.g. 1010\*(Lq" ls -lt"\*(Rq. 1011A particularly 1012useful example of this mechanism is: \*(Lqdir more\*(Rq. 1013.It 1014Failing the above checks, if ``globbing'' is enabled, 1015local file names are expanded 1016according to the rules used in the 1017.Xr csh 1 ; 1018c.f. the 1019.Ic glob 1020command. 1021If the 1022.Nm ftp 1023command expects a single local file (.e.g. 1024.Ic put ) , 1025only the first filename generated by the "globbing" operation is used. 1026.It 1027For 1028.Ic mget 1029commands and 1030.Ic get 1031commands with unspecified local file names, the local filename is 1032the remote filename, which may be altered by a 1033.Ic case , 1034.Ic ntrans , 1035or 1036.Ic nmap 1037setting. 1038The resulting filename may then be altered if 1039.Ic runique 1040is on. 1041.It 1042For 1043.Ic mput 1044commands and 1045.Ic put 1046commands with unspecified remote file names, the remote filename is 1047the local filename, which may be altered by a 1048.Ic ntrans 1049or 1050.Ic nmap 1051setting. 1052The resulting filename may then be altered by the remote server if 1053.Ic sunique 1054is on. 1055.El 1056.Sh FILE TRANSFER PARAMETERS 1057The FTP specification specifies many parameters which may 1058affect a file transfer. 1059The 1060.Ic type 1061may be one of \*(Lqascii\*(Rq, \*(Lqimage\*(Rq (binary), 1062\*(Lqebcdic\*(Rq, and \*(Lqlocal byte size\*(Rq (for 1063.Tn PDP Ns -10's 1064and 1065.Tn PDP Ns -20's 1066mostly). 1067.Nm Ftp 1068supports the ascii and image types of file transfer, 1069plus local byte size 8 for 1070.Ic tenex 1071mode transfers. 1072.Pp 1073.Nm Ftp 1074supports only the default values for the remaining 1075file transfer parameters: 1076.Ic mode , 1077.Ic form , 1078and 1079.Ic struct . 1080.Sh THE .netrc FILE 1081The 1082.Pa .netrc 1083file contains login and initialization information 1084used by the auto-login process. 1085It resides in the user's home directory. 1086The following tokens are recognized; they may be separated by spaces, 1087tabs, or new-lines: 1088.Bl -tag -width password 1089.It Ic machine Ar name 1090Identify a remote machine 1091.Ar name . 1092The auto-login process searches the 1093.Pa .netrc 1094file for a 1095.Ic machine 1096token that matches the remote machine specified on the 1097.Nm ftp 1098command line or as an 1099.Ic open 1100command argument. 1101Once a match is made, the subsequent 1102.Pa .netrc 1103tokens are processed, 1104stopping when the end of file is reached or another 1105.Ic machine 1106or a 1107.Ic default 1108token is encountered. 1109.It Ic default 1110This is the same as 1111.Ic machine 1112.Ar name 1113except that 1114.Ic default 1115matches any name. 1116There can be only one 1117.Ic default 1118token, and it must be after all 1119.Ic machine 1120tokens. 1121This is normally used as: 1122.Pp 1123.Dl default login anonymous password user@site 1124.Pp 1125thereby giving the user 1126.Ar automatic 1127anonymous ftp login to 1128machines not specified in 1129.Pa .netrc . 1130This can be overridden 1131by using the 1132.Fl n 1133flag to disable auto-login. 1134.It Ic login Ar name 1135Identify a user on the remote machine. 1136If this token is present, the auto-login process will initiate 1137a login using the specified 1138.Ar name . 1139.It Ic password Ar string 1140Supply a password. 1141If this token is present, the auto-login process will supply the 1142specified string if the remote server requires a password as part 1143of the login process. 1144Note that if this token is present in the 1145.Pa .netrc 1146file for any user other 1147than 1148.Ar anonymous , 1149.Nm ftp 1150will abort the auto-login process if the 1151.Pa .netrc 1152is readable by 1153anyone besides the user. 1154.It Ic account Ar string 1155Supply an additional account password. 1156If this token is present, the auto-login process will supply the 1157specified string if the remote server requires an additional 1158account password, or the auto-login process will initiate an 1159.Dv ACCT 1160command if it does not. 1161.It Ic macdef Ar name 1162Define a macro. 1163This token functions like the 1164.Nm ftp 1165.Ic macdef 1166command functions. 1167A macro is defined with the specified name; its contents begin with the 1168next 1169.Pa .netrc 1170line and continue until a null line (consecutive new-line 1171characters) is encountered. 1172If a macro named 1173.Ic init 1174is defined, it is automatically executed as the last step in the 1175auto-login process. 1176.El 1177.Sh ENVIRONMENT 1178.Nm Ftp 1179uses the following environment variables. 1180.Bl -tag -width Fl 1181.It Ev HOME 1182For default location of a 1183.Pa .netrc 1184file, if one exists. 1185.It Ev SHELL 1186For default shell. 1187.El 1188.Sh SEE ALSO 1189.Xr ftpd 8 1190.Rs 1191.%T RFC2228 1192.Re 1193.Sh HISTORY 1194The 1195.Nm ftp 1196command appeared in 1197.Bx 4.2 . 1198.Sh BUGS 1199Correct execution of many commands depends upon proper behavior 1200by the remote server. 1201.Pp 1202An error in the treatment of carriage returns 1203in the 1204.Bx 4.2 1205ascii-mode transfer code 1206has been corrected. 1207This correction may result in incorrect transfers of binary files 1208to and from 1209.Bx 4.2 1210servers using the ascii type. 1211Avoid this problem by using the binary image type. 1212