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

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

.\"

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

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

.\" are met:

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

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

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

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

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

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

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

.\"    without specific prior written permission.

.\"

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

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

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

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

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

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

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

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

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

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

.\" SUCH DAMAGE.

.\"

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

.\"

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

.\"

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

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

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

.\"

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

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

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

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

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

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

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

.\"

.Dd $Mdocdate: August 13 2015 $

.Dt FTP 1

.Os

.Sh NAME

.Nm ftp

.Nd Internet file transfer program

.Sh SYNOPSIS

.Nm

.Op Fl 46AVv

.Op Fl N Ar name

.Op Fl D Ar title

.Op Ar host Op Ar port

.Nm

.Op Fl 46ACMmVv

.Op Fl N Ar name

.Op Fl D Ar title

.Op Fl o Ar output

.Op Fl S Ar tls_options

.Op Fl U Ar useragent

.Op Fl w Ar seconds

.Ar url ...

.Sh DESCRIPTION

.Nm

is the user interface to the Internet standard File Transfer

Protocol (FTP).

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

remote network site.

.Pp

The latter usage format will fetch a file using either the

FTP, HTTP or HTTPS protocols into the current directory.

This is ideal for scripts.

Refer to

.Sx AUTO-FETCHING FILES

below for more information.

.Pp

The options are as follows:

.Bl -tag -width Ds

.It Fl 4

Forces

.Nm

to use IPv4 addresses only.

.It Fl 6

Forces

.Nm

to use IPv6 addreses only.

.It Fl A

Force active mode FTP.

By default,

.Nm

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

if passive is not supported by the server.

This option causes

.Nm

to always use an active connection.

It is only useful for connecting

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

.It Fl C

Continue a previously interrupted file transfer.

.Nm

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

.Pp

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

.Dq Range

header.

.It Fl D Ar title

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

.It Fl M

Causes

.Nm

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

.It Fl N Ar name

Use this alternative name instead of

.Nm

in some error reports.

.It Fl m

Causes

.Nm

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

.It Fl o Ar output

When fetching a file or URL, save the contents in

.Ar output .

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

.Ar output .

.It Fl S Ar tls_options

TLS options to use with HTTPS transfers.

The following settings are available:

.Bl -tag -width Ds

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

PEM encoded file containing CA certificates used for certificate validation.

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

Directory containing PEM encoded CA certificates used for certificate

validation.

.It Cm ciphers Ns = Ns Ar cipher_list

Specify the list of ciphers that will be used by

.Nm .

See the

.Xr openssl 1

.Cm ciphers

subcommand.

.It Cm depth Ns = Ns Ar max_depth

Maximum depth of the certificate chain allowed when performing validation.

.It Cm dont

Don't perform server certificate validation.

.It Cm protocols Ns = Ns Ar string

Specify the TLS protocols to use.

If not specified the value

.Qq all

is used.

Refer to the

.Xr tls_config_parse_protocols 3

function for other valid protocol string values.

.It Cm muststaple

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

.It Cm noverifytime

Disable validation of certificate times and OCSP validation.

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

Specify a file to use for TLS session data.

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

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

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

new session data, if available.

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

.El

.Pp

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

.Nm

will abort.

If no

.Cm cafile

or

.Cm capath

setting is provided,

.Pa /etc/ssl/cert.pem

will be used.

.It Fl U Ar useragent

Set

.Ar useragent

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

If not specified, the default User-Agent is

.Dq OpenBSD ftp .

.It Fl V

Disable verbose mode.

.It Fl v

Enable verbose mode.

This is the default if input if from a terminal.

Forces

.Nm

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

transfer statistics.

.It Fl w Ar seconds

Abort a slow connection after

.Ar seconds .

.El

.Pp

The host with which

.Nm

is to communicate may be specified on the command line.

If this is done,

.Nm

will immediately attempt to establish a connection to an

FTP server on that host; otherwise,

.Nm

will enter its command interpreter and await instructions

from the user.

When

.Nm

is awaiting commands, the prompt

.Dq ftp\*(Gt

is provided to the user.

The following commands are recognized

by

.Nm :

.Bl -tag -width Ds

.It Ic open Ar host Op Ar port

Establish a connection to the specified

.Ar host

FTP server.

An optional port number may be supplied,

in which case

.Nm

will attempt to contact an FTP server at that port.

.It Ic close

Terminate the FTP session with the remote server and

return to the command interpreter.

.It Ic help Op Ar command

Print an informative message about the meaning of

.Ar command .

If no argument is given,

.Nm

prints a list of the known commands.

.It Ic \&? Op Ar command

A synonym for

.Ic help .

.It Ic quit

Terminate the FTP session with the remote server and exit

.Nm .

.It Ic exit

A synonym for

.Ic quit .

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

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

The listing includes any system-dependent information that the server

chooses to include; for example, most

.Ux

systems will produce output from the command

.Ql ls -l .

If

.Ar remote-directory

is left unspecified, the current working directory is used.

If no local file is specified, or if

.Ar local-file

is

.Sq - ,

the output is sent to the terminal.

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

Print a list of the files in a

directory on the remote machine.

If

.Ar remote-directory

is left unspecified, the current working directory is used.

If no local file is specified, or if

.Ar local-file

is

.Sq - ,

the output is sent to the terminal.

Note that on some servers, the

.Ic nlist

command will only return information on normal files (not directories

or special files).

.It Ic pwd

Print the name of the current working directory on the remote

machine.

.It Ic cd Ar remote-directory

Change the working directory on the remote machine

to

.Ar remote-directory .

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

Retrieve the

.Ar remote-file

and store it on the local machine.

If the local

file name is not specified, it is given the same

name it has on the remote machine.

.It Ic passive Op Ic on | off

Toggle passive mode.

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

.Nm

will send a

.Dv EPSV

command for all data connections instead of the usual

.Dv EPRT

command.

The

.Dv EPSV

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

and return the address of that port.

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

When using the more traditional

.Dv EPRT

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

server, who connects back to it.

Passive mode is useful when using

.Nm

through a gateway router or host that controls the directionality of

traffic.

.It Ic lcd Op Ar local-directory

Change the working directory on the local machine.

If

no

.Ar local-directory

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

.It Ic lpwd

Print the working directory on the local machine.

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

Store a local file on the remote machine.

If

.Ar remote-file

is left unspecified, the local file name is used.

.It Ic mget Ar remote-files

Do a

.Ic get

for each file name specified.

.It Ic mput Ar local-files

Do a

.Ic put

for each file name specified.

.El

.Sh AUTO-FETCHING FILES

In addition to standard commands, this version of

.Nm

supports an auto-fetch feature.

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

on the command line.

.Pp

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

.Bl -tag -width Ds

.Sm off

.It Xo ftp://

.Ar host Op : Ar port

.No / Ar file

.Xc

.Sm on

An FTP URL, retrieved using the FTP protocol if

.Ev ftp_proxy

isn't defined.

Otherwise, transfer using HTTP via the proxy defined in

.Ev ftp_proxy .

.Sm off

.It Xo http://

.Ar host Op : Ar port

.No / Ar file

.Xc

.Sm on

An HTTP URL, retrieved using the HTTP protocol.

If

.Ev http_proxy

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

.Sm off

.It Xo https://

.Ar host Op : Ar port

.No / Ar file

.Xc

.Sm on

An HTTPS URL, retrieved using the HTTPS protocol.

If

.Ev http_proxy

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

file using the CONNECT method.

.It Pf file: Ar file

.Ar file

is retrieved from a mounted file system.

.El

.Sh ENVIRONMENT

.Nm

utilizes the following environment variables:

.Bl -tag -width Ds

.It Ev ftp_proxy

URL of FTP proxy to use when making FTP URL requests

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

.It Ev http_proxy

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

.El

.Sh PORT ALLOCATION

For active mode data connections,

.Nm

will listen to a random high TCP port.

The interval of ports used are configurable using

.Xr sysctl 8

variables

.Va net.inet.ip.porthifirst

and

.Va net.inet.ip.porthilast .

.Sh HISTORY

The

.Nm

command first appeard in

.Bx 4.2 .

A complete rewrite of the

.Nm

command first appeared in

.Ox x.x .

.Sh AUTHORS

.An Sunil Nimmagadda Aq Mt sunil@openbsd.org

.Sh CAVEATS

While aborting a data transfer, certain FTP servers violate

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

.Nm

wait indefinitely for a correct reply.