1 .\"	$OpenBSD: ftp.1,v 1.114 2019/05/15 11:53:22 kmos Exp $

     2 .\"	The Regents of the University of California.  All rights reserved.

     3 .\"

     4 .\" Redistribution and use in source and binary forms, with or without

     5 .\" modification, are permitted provided that the following conditions

     6 .\" are met:

     7 .\" 1. Redistributions of source code must retain the above copyright

     8 .\"    notice, this list of conditions and the following disclaimer.

     9 .\" 2. Redistributions in binary form must reproduce the above copyright

    10 .\"    notice, this list of conditions and the following disclaimer in the

    11 .\"    documentation and/or other materials provided with the distribution.

    12 .\" 3. Neither the name of the University nor the names of its contributors

    13 .\"    may be used to endorse or promote products derived from this software

    14 .\"    without specific prior written permission.

    15 .\"

    16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND

    17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

    18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

    19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE

    20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

    21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

    22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

    23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

    24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

    25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

    26 .\" SUCH DAMAGE.

    27 .\"

    28 .\"	@(#)ftp.1	8.3 (Berkeley) 10/9/94

    29 .\"

    30 .\" Copyright (c) 2015 Sunil Nimmagadda <sunil@openbsd.org>

    31 .\"

    32 .\" Permission to use, copy, modify, and distribute this software for any

    33 .\" purpose with or without fee is hereby granted, provided that the above

    34 .\" copyright notice and this permission notice appear in all copies.

    35 .\"

    36 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES

    37 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF

    38 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR

    39 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES

    40 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN

    41 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF

    42 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

    43 .\"

    44 .Dd $Mdocdate: August 13 2015 $

    45 .Dt FTP 1

    46 .Os

    47 .Sh NAME

    48 .Nm ftp

    49 .Nd Internet file transfer program

    50 .Sh SYNOPSIS

    51 .Nm

    52 .Op Fl 46AVv

    53 .Op Fl N Ar name

    54 .Op Fl D Ar title

    55 .Op Ar host Op Ar port

    56 .Nm

    57 .Op Fl 46ACMmVv

    58 .Op Fl N Ar name

    59 .Op Fl D Ar title

    60 .Op Fl o Ar output

    61 .Op Fl S Ar tls_options

    62 .Op Fl U Ar useragent

    63 .Op Fl w Ar seconds

    64 .Ar url ...

    65 .Sh DESCRIPTION

    66 .Nm

    67 is the user interface to the Internet standard File Transfer

    68 Protocol (FTP).

    69 The program allows a user to transfer files to and from a

    70 remote network site.

    71 .Pp

    72 The latter usage format will fetch a file using either the

    73 FTP, HTTP or HTTPS protocols into the current directory.

    74 This is ideal for scripts.

    75 Refer to

    76 .Sx AUTO-FETCHING FILES

    77 below for more information.

    78 .Pp

    79 The options are as follows:

    80 .Bl -tag -width Ds

    81 .It Fl 4

    82 Forces

    83 .Nm

    84 to use IPv4 addresses only.

    85 .It Fl 6

    86 Forces

    87 .Nm

    88 to use IPv6 addreses only.

    89 .It Fl A

    90 Force active mode FTP.

    91 By default,

    92 .Nm

    93 will try to use passive mode FTP and fall back to active mode

    94 if passive is not supported by the server.

    95 This option causes

    96 .Nm

    97 to always use an active connection.

    98 It is only useful for connecting

    99 to very old servers that do not implement passive mode properly.

   100 .It Fl C

   101 Continue a previously interrupted file transfer.

   102 .Nm

   103 will continue transferring from an offset equal to the length of file.

   104 .Pp

   105 Resuming HTTP(S) transfers are only supported if the remote server supports the

   106 .Dq Range

   107 header.

   108 .It Fl D Ar title

   109 Specify a short title for the start of the progress bar.

   110 .It Fl M

   111 Causes

   112 .Nm

   113 to never display the progress meter in cases where it would do so by default.

   114 .It Fl N Ar name

   115 Use this alternative name instead of

   116 .Nm

   117 in some error reports.

   118 .It Fl m

   119 Causes

   120 .Nm

   121 to display the progress meter in cases where it would not do so by default.

   122 .It Fl o Ar output

   123 When fetching a file or URL, save the contents in

   124 .Ar output .

   125 To make the contents go to stdout, use `-' for

   126 .Ar output .

   127 .It Fl S Ar tls_options

   128 TLS options to use with HTTPS transfers.

   129 The following settings are available:

   130 .Bl -tag -width Ds

   131 .It Cm cafile Ns = Ns Ar /path/to/cert.pem

   132 PEM encoded file containing CA certificates used for certificate validation.

   133 .It Cm capath Ns = Ns Ar /path/to/certs/

   134 Directory containing PEM encoded CA certificates used for certificate

   135 validation.

   136 .It Cm ciphers Ns = Ns Ar cipher_list

   137 Specify the list of ciphers that will be used by

   138 .Nm .

   139 See the

   140 .Xr openssl 1

   141 .Cm ciphers

   142 subcommand.

   143 .It Cm depth Ns = Ns Ar max_depth

   144 Maximum depth of the certificate chain allowed when performing validation.

   145 .It Cm dont

   146 Don't perform server certificate validation.

   147 .It Cm protocols Ns = Ns Ar string

   148 Specify the TLS protocols to use.

   149 If not specified the value

   150 .Qq all

   151 is used.

   152 Refer to the

   153 .Xr tls_config_parse_protocols 3

   154 function for other valid protocol string values.

   155 .It Cm muststaple

   156 Require the server to present a valid OCSP stapling in the TLS handshake.

   157 .It Cm noverifytime

   158 Disable validation of certificate times and OCSP validation.

   159 .It Cm session Ns = Ns Ar /path/to/session

   160 Specify a file to use for TLS session data.

   161 If this file has a non-zero length, the session data will be read from this file

   162 and the client will attempt to resume the TLS session with the server.

   163 Upon completion of a successful TLS handshake this file will be updated with

   164 new session data, if available.

   165 This file will be created if it does not already exist.

   166 .El

   167 .Pp

   168 By default, server certificate validation is performed, and if it fails

   169 .Nm

   170 will abort.

   171 If no

   172 .Cm cafile

   173 or

   174 .Cm capath

   175 setting is provided,

   176 .Pa /etc/ssl/cert.pem

   177 will be used.

   178 .It Fl U Ar useragent

   179 Set

   180 .Ar useragent

   181 as the User-Agent for HTTP(S) URL requests.

   182 If not specified, the default User-Agent is

   183 .Dq OpenBSD ftp .

   184 .It Fl V

   185 Disable verbose mode.

   186 .It Fl v

   187 Enable verbose mode.

   188 This is the default if input if from a terminal.

   189 Forces

   190 .Nm

   191 to show all responses from the remote server, as well as report on data

   192 transfer statistics.

   193 .It Fl w Ar seconds

   194 Abort a slow connection after

   195 .Ar seconds .

   196 .El

   197 .Pp

   198 The host with which

   199 .Nm

   200 is to communicate may be specified on the command line.

   201 If this is done,

   202 .Nm

   203 will immediately attempt to establish a connection to an

   204 FTP server on that host; otherwise,

   205 .Nm

   206 will enter its command interpreter and await instructions

   207 from the user.

   208 When

   209 .Nm

   210 is awaiting commands, the prompt

   211 .Dq ftp\*(Gt

   212 is provided to the user.

   213 The following commands are recognized

   214 by

   215 .Nm :

   216 .Bl -tag -width Ds

   217 .It Ic open Ar host Op Ar port

   218 Establish a connection to the specified

   219 .Ar host

   220 FTP server.

   221 An optional port number may be supplied,

   222 in which case

   223 .Nm

   224 will attempt to contact an FTP server at that port.

   225 .It Ic close

   226 Terminate the FTP session with the remote server and

   227 return to the command interpreter.

   228 .It Ic help Op Ar command

   229 Print an informative message about the meaning of

   230 .Ar command .

   231 If no argument is given,

   232 .Nm

   233 prints a list of the known commands.

   234 .It Ic \&? Op Ar command

   235 A synonym for

   236 .Ic help .

   237 .It Ic quit

   238 Terminate the FTP session with the remote server and exit

   239 .Nm .

   240 .It Ic exit

   241 A synonym for

   242 .Ic quit .

   243 .It Ic ls Op Ar remote-directory Op Ar local-file

   244 Print a listing of the contents of a directory on the remote machine.

   245 The listing includes any system-dependent information that the server

   246 chooses to include; for example, most

   247 .Ux

   248 systems will produce output from the command

   249 .Ql ls -l .

   250 If

   251 .Ar remote-directory

   252 is left unspecified, the current working directory is used.

   253 If no local file is specified, or if

   254 .Ar local-file

   255 is

   256 .Sq - ,

   257 the output is sent to the terminal.

   258 .It Ic nlist Op Ar remote-directory Op Ar local-file

   259 Print a list of the files in a

   260 directory on the remote machine.

   261 If

   262 .Ar remote-directory

   263 is left unspecified, the current working directory is used.

   264 If no local file is specified, or if

   265 .Ar local-file

   266 is

   267 .Sq - ,

   268 the output is sent to the terminal.

   269 Note that on some servers, the

   270 .Ic nlist

   271 command will only return information on normal files (not directories

   272 or special files).

   273 .It Ic pwd

   274 Print the name of the current working directory on the remote

   275 machine.

   276 .It Ic cd Ar remote-directory

   277 Change the working directory on the remote machine

   278 to

   279 .Ar remote-directory .

   280 .It Ic get Ar remote-file Op Ar local-file

   281 Retrieve the

   282 .Ar remote-file

   283 and store it on the local machine.

   284 If the local

   285 file name is not specified, it is given the same

   286 name it has on the remote machine.

   287 .It Ic passive Op Ic on | off

   288 Toggle passive mode.

   289 If passive mode is turned on (default is on),

   290 .Nm

   291 will send a

   292 .Dv EPSV

   293 command for all data connections instead of the usual

   294 .Dv EPRT

   295 command.

   296 The

   297 .Dv EPSV

   298 command requests that the remote server open a port for the data connection

   299 and return the address of that port.

   300 The remote server listens on that port and the client connects to it.

   301 When using the more traditional

   302 .Dv EPRT

   303 command, the client listens on a port and sends that address to the remote

   304 server, who connects back to it.

   305 Passive mode is useful when using

   306 .Nm

   307 through a gateway router or host that controls the directionality of

   308 traffic.

   309 .It Ic lcd Op Ar local-directory

   310 Change the working directory on the local machine.

   311 If

   312 no

   313 .Ar local-directory

   314 is specified, the user's home directory is used.

   315 .It Ic lpwd

   316 Print the working directory on the local machine.

   317 .It Ic put Ar local-file Op Ar remote-file

   318 Store a local file on the remote machine.

   319 If

   320 .Ar remote-file

   321 is left unspecified, the local file name is used.

   322 .It Ic mget Ar remote-files

   323 Do a

   324 .Ic get

   325 for each file name specified.

   326 .It Ic mput Ar local-files

   327 Do a

   328 .Ic put

   329 for each file name specified.

   330 .El

   331 .Sh AUTO-FETCHING FILES

   332 In addition to standard commands, this version of

   333 .Nm

   334 supports an auto-fetch feature.

   335 To enable auto-fetch, simply pass the list of hostnames/files

   336 on the command line.

   337 .Pp

   338 The following formats are valid syntax for an auto-fetch element:

   339 .Bl -tag -width Ds

   340 .Sm off

   341 .It Xo ftp://

   342 .Ar host Op : Ar port

   343 .No / Ar file

   344 .Xc

   345 .Sm on

   346 An FTP URL, retrieved using the FTP protocol if

   347 .Ev ftp_proxy

   348 isn't defined.

   349 Otherwise, transfer using HTTP via the proxy defined in

   350 .Ev ftp_proxy .

   351 .Sm off

   352 .It Xo http://

   353 .Ar host Op : Ar port

   354 .No / Ar file

   355 .Xc

   356 .Sm on

   357 An HTTP URL, retrieved using the HTTP protocol.

   358 If

   359 .Ev http_proxy

   360 is defined, it is used as a URL to an HTTP proxy server.

   361 .Sm off

   362 .It Xo https://

   363 .Ar host Op : Ar port

   364 .No / Ar file

   365 .Xc

   366 .Sm on

   367 An HTTPS URL, retrieved using the HTTPS protocol.

   368 If

   369 .Ev http_proxy

   370 is defined, this HTTPS proxy server will be used to fetch the

   371 file using the CONNECT method.

   372 .It Pf file: Ar file

   373 .Ar file

   374 is retrieved from a mounted file system.

   375 .El

   376 .Sh ENVIRONMENT

   377 .Nm

   378 utilizes the following environment variables:

   379 .Bl -tag -width Ds

   380 .It Ev ftp_proxy

   381 URL of FTP proxy to use when making FTP URL requests

   382 (if not defined, use the standard FTP protocol).

   383 .It Ev http_proxy

   384 URL of HTTP proxy to use when making HTTP(S) URL requests.

   385 .El

   386 .Sh PORT ALLOCATION

   387 For active mode data connections,

   388 .Nm

   389 will listen to a random high TCP port.

   390 The interval of ports used are configurable using

   391 .Xr sysctl 8

   392 variables

   393 .Va net.inet.ip.porthifirst

   394 and

   395 .Va net.inet.ip.porthilast .

   396 .Sh HISTORY

   397 The

   398 .Nm

   399 command first appeard in

   400 .Bx 4.2 .

   401 A complete rewrite of the

   402 .Nm

   403 command first appeared in

   404 .Ox x.x .

   405 .Sh AUTHORS

   406 .An Sunil Nimmagadda Aq Mt sunil@openbsd.org

   407 .Sh CAVEATS

   408 While aborting a data transfer, certain FTP servers violate

   409 the protocol by not responding with a 426 reply first, thereby making

   410 .Nm

   411 wait indefinitely for a correct reply.