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