| FTP(1) | General Commands Manual | FTP(1) |
ftp — Internet
file transfer program
ftp |
[-46AadEegimnptVv] [-D
title] [-k
seconds] [-P
port] [-r
seconds] [-s
srcaddr] [host
[port]] |
ftp |
[-C] [-o
output] [-s
srcaddr]
ftp://[user:password@]host[:port]/file[/]
... |
ftp |
[-C] [-c
cookie] [-o
output] [-S
ssl_options] [-s
srcaddr] [-U
useragent]
http[s]://[user:password@]host[:port]/file
... |
ftp |
[-C] [-o
output] [-s
srcaddr]
file:file
... |
ftp |
[-C] [-o
output] [-s
srcaddr]
host:/file[/]
... |
ftp 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.
The latter four usage formats will fetch a file using either the FTP, HTTP, or HTTPS protocols into the current directory. This is ideal for scripts. Refer to AUTO-FETCHING FILES below for more information.
The options are as follows:
-4ftp to use IPv4 addresses only.-6ftp to use IPv6 addresses only.-Aftp will try to
use passive mode FTP and fall back to active mode if passive is not
supported by the server. This option causes ftp to
always use an active connection. It is only useful for connecting to very
old servers that do not implement passive mode properly.-aftp to bypass the normal login procedure
and use an anonymous login instead.-Cftp will continue transferring from an offset
equal to the length of file.
Resuming HTTP(S) transfers are only supported if the remote server supports the “Range” header.
-c
cookiehttp_cookies environment
variable has the same effect. If both the
http_cookies environment variable is set and the
-c argument is given, the latter takes
precedence.-D
title-d-E-e-g-i-k
secondsNOOP command that can be used for that purpose.
This assumes the FTP server can deal with extra commands coming over the
control connection during a transfer. Well-behaved servers queue those
commands, and process them after the transfer. By default,
ftp will send a byte every 60 seconds.-mftp to always display the progress meter in
cases where it would not do so by default.-nftp from attempting
“auto-login” upon initial connection. If auto-login is
enabled, ftp will check the
.netrc file (see below) in the user's home
directory for an entry describing an account on the remote machine. If no
entry exists, ftp will prompt for the remote
machine login name (default is the user identity on the local machine),
and, if necessary, prompt for a password and an account with which to log
in.-o
output-P
port-pftp
now tries to use passive mode by default, falling back to active mode if
the server does not support passive connections.-r
seconds-S
ssl_optionscafile=/path/to/cert.pemcapath=/path/to/certs/ciphers=cipher_listftp. See the
openssl(1)
ciphers subcommand.depth=max_depthdodontBy default, server certificate validation is performed, and if
it fails ftp will abort. If no
cafile or capath setting
is provided, /etc/ssl/cert.pem will be used.
-s
srcaddr-t-U
useragent-V-vftp to show all responses from the remote
server, as well as report on data transfer statistics.The host with which ftp is to communicate
may be specified on the command line. If this is done,
ftp will immediately attempt to establish a
connection to an FTP server on that host; otherwise,
ftp will enter its command interpreter and await
instructions from the user. When ftp is awaiting
commands, the prompt “ftp>” is provided to the user. The
following commands are recognized by ftp:
!
[command [arg ...]]$
macro-name [arg ...]macdef command. Arguments are passed to the
macro unglobbed.?
[command]help.account
[password]append
local-file [remote-file]ntrans or nmap setting.
File transfer uses the current settings for type,
format, mode, and
structure.asciitype to network ASCII.bell
[on | off]binarytype to support binary image
transfer. This is the default type.byeftp. An end-of-file will also terminate the
session and exit.case
[on | off]mget commands. When case
is on (default is off), remote computer file names with all letters in
upper case are written in the local directory with the letters mapped to
lower case.cd
remote-directorycdupchmod
mode fileclosecr
[on | off]cr is on (the default), carriage
returns are stripped from this sequence to conform with the
UNIX single linefeed record delimiter. Records on
non-UNIX remote systems may contain single linefeeds; when an ASCII type
transfer is made, these linefeeds may be distinguished from a record
delimiter only when cr is off.debug
[on | off |
debuglevel]ftp prints each command sent to the remote
machine, preceded by the string
‘-->’.delete
remote-filedir
[remote-directory
[local-file]]ls.disconnectclose.edit
[on | off]epsv4
[on | off]exitbye.form
formatform to
format. The default format is
“file”.ftp
host [port]open.gate
[on | off |
host [port]]FTPSERVER environment variable). If
host is given, then gate-ftp mode will be enabled,
and the gate-ftp server will be set to host. If
port is also given, that will be used as the port to
connect to on the gate-ftp server.get
remote-file [local-file]case, ntrans, and
nmap settings. The current settings for
type, form,
mode, and structure are
used while transferring the file.glob
[on | off]mdelete,
mget and mput. If globbing
is turned off with glob, the file name arguments
are taken literally and not expanded. Globbing for
mput is done as in
csh(1). For
mdelete and mget, each
remote file name is expanded separately on the remote machine and the
lists are not merged. Expansion of a directory name is likely to be
different from expansion of the name of an ordinary file: the exact result
depends on the foreign operating system and FTP server, and can be
previewed by doing “mls remote-files -”. Note:
mget and mput are not
meant to transfer entire directory subtrees of files. That can be done by
transferring a tar(1) archive
of the subtree (in binary mode).hash
[on | off |
size]#’) printing for
each data block transferred. The size of a data block defaults to 1024
bytes. This can be changed by specifying size in
bytes.help
[command]ftp prints a list of the known commands.idle
[seconds]lcd
[local-directory]less
filepage.lpwdls
[remote-directory
[local-file]]ls
-l’. If remote-directory is left
unspecified, the current working directory is used. If interactive
prompting is on, ftp will prompt the user to
verify that the last argument is indeed the target local file for
receiving ls output. If no local file is
specified, or if local-file is ‘-’,
the output is sent to the terminal.macdef
macro-nameopen command), and remain defined until a
close command is executed. To invoke a macro, use
the $ command (see above).
The macro processor interprets
‘$’ and
‘\’ as special characters. A
‘$’ followed by a number (or
numbers) is replaced by the corresponding argument on the macro
invocation command line. A ‘$’
followed by an ‘i’ tells the macro processor that the
executing macro is to be looped. On the first pass
‘$i’ is replaced by the first
argument on the macro invocation command line, on the second pass it is
replaced by the second argument, and so on. A
‘\’ followed by any character is
replaced by that character. Use the
‘\’ to prevent special treatment
of the ‘$’.
mdelete
[remote-files]mdir
remote-files local-filemls.mget
[-cnr] [-d
depth] remote-filesget for each file name thus produced. See
glob for details on the filename expansion.
Resulting file names will then be processed according to
case, ntrans, and
nmap settings. Files are transferred into the
local working directory, which can be changed with
‘lcd directory’; new local
directories can be created with ‘! mkdir
directory’.
The options are as follows:
mkdir
directory-namemls
remote-files local-filels, except multiple remote files may be
specified, and the local-file must be specified. If
interactive prompting is on, ftp will prompt the
user to verify that the last argument is indeed the target local file for
receiving mls output.mode
[mode-name]mode to
mode-name. The default mode is
“stream” mode.modtime
filemore
filepage.mput
[-cr] [-d
depth] local-filesput for each file in the resulting list. See
glob for details of filename expansion. Resulting
file names will then be processed according to
ntrans and nmap settings.
If the -c flag is specified then The
options are as follows:
msend
[-c] local-filesmput.newer
remote-file [local-file]newer. Otherwise, this command is identical to
get.nlist
[remote-directory
[local-file]]ftp will prompt the user to verify that the last
argument is indeed the target local file for receiving
nlist output. If no local file is specified, or if
local-file is ‘-’, the output is sent
to the terminal. Note that on some servers, the
nlist command will only return information on
normal files (not directories or special files).nmap
[inpattern outpattern]mput
commands and put commands issued without a
specified remote target filename. If arguments are specified, local
filenames are mapped during mget commands and
get commands issued without a specified local
target filename. This command is useful when connecting to a non-UNIX
remote computer with different file naming conventions or practices.
The mapping follows the pattern set by
inpattern and outpattern.
inpattern is a template for incoming filenames
(which may have already been processed according to the
ntrans and case
settings). Variable templating is accomplished by including the
sequences ‘$1’,
‘$2’, ...,
‘$9’ in
inpattern. Use
‘\’ to prevent this special
treatment of the ‘$’ character.
All other characters are treated literally, and are used to determine
the nmap inpattern
variable values.
For example, given inpattern $1.$2 and
the remote file name "mydata.data", $1 would have the value
"mydata", and $2 would have the value "data". The
outpattern determines the resulting mapped
filename. The sequences ‘$1’,
‘$2’, ...,
‘$9’ are replaced by any value
resulting from the inpattern template. The
sequence ‘$0’ is replaced by the
original filename. Additionally, the sequence
‘[seq1, seq2]’
is replaced by seq1 if seq1
is not a null string; otherwise it is replaced by
seq2. For example:
nmap $1.$2.$3
[$1,$2].[$2,file]This command would yield the output filename myfile.data for input filenames myfile.data and myfile.data.old; myfile.file for the input filename myfile; and myfile.myfile for the input filename .myfile. Spaces may be included in outpattern by quoting them, as in the following example:
nmap $1.$2 "$1 $2"
Use the ‘\’ character to
prevent special treatment of the
‘$’,
‘[’,
‘]’, and
‘,’ characters.
ntrans
[inchars [outchars]]mput commands and
put commands issued without a specified remote
target filename. If arguments are specified, characters in local filenames
are translated during mget commands and
get commands issued without a specified local
target filename. This command is useful when connecting to a non-UNIX
remote computer with different file naming conventions or practices.
Characters in a filename matching a character in
inchars are replaced with the corresponding
character in outchars. If the character's position
in inchars is longer than the length of
outchars, the character is deleted from the file
name.open
host [port]ftp will attempt to contact an FTP server at that
port. If the auto-login option is on (default),
ftp will also attempt to automatically log the
user in to the FTP server (see below).page
filefile and display with the program defined
in PAGER (defaulting to
more(1) if
PAGER is null or not defined).passive
[on | off]ftp will send a EPSV
command for all data connections instead of the usual
PORT command. The PASV
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 PORT 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 ftp through a
gateway router or host that controls the directionality of traffic. (Note
that though FTP servers are required to support the
PASV command by RFC 1123, some do not.)preserve
[on | off]progress
[on | off]prompt
[on | off]mget or mput will transfer
all files, and any mdelete will delete all files.
When prompting is on, the following commands are available at a prompt:
?anpqyproxy
commandproxy
command should be an open, to establish the
secondary control connection. Enter the command proxy
? to see other FTP commands executable on the secondary connection.
The following commands behave differently when prefaced by
proxy: open will not
define new macros during the auto-login process;
close will not erase existing macro definitions;
get and mget transfer
files from the host on the primary control connection to the host on the
secondary control connection; and put,
mput, and append transfer
files from the host on the secondary control connection to the host on the
primary control connection. Third party file transfers depend upon support
of the FTP protocol PASV command by the server on
the secondary control connection.put
local-file [remote-file]ntrans
or nmap settings in naming the remote file. File
transfer uses the current settings for type,
format, mode, and
structure.pwdquitbye.quote
arg ...recv
remote-file [local-file]get.reget
remote-file [local-file]rename
from-name to-namereput
local-file [remote-file]resetrestart
markerget or
put at the indicated marker.
On UNIX systems, marker is
usually a byte offset into the file.rhelp
[command-name]rmdir
directory-namerstatus
[file]runique
[on | off]get or mget command, a
“.1” is appended to the name. If the resulting name matches
another existing file, a “.2” is appended to the original
name. If this process continues up to “.99”, an error
message is printed, and the transfer does not take place. The generated
unique filename will be reported. Note that
runique will not affect local files generated from
a shell command (see below). The default value is off.send
local-file [remote-file]put.sendport
[on | off]PORT commands. By default,
ftp will attempt to use a
PORT command when establishing a connection for
each data transfer. The use of PORT commands can
prevent delays when performing multiple file transfers. If the
PORT command fails, ftp
will use the default data port. When the use of
PORT commands is disabled, no attempt will be made
to use PORT commands for each data transfer. This
is useful for certain FTP implementations which do ignore
PORT commands but, incorrectly, indicate they've
been accepted.site
arg ...SITE command.size
filestatusftp.sunique
[on | off]STOU command for successful completion. The remote
server will report the unique name. Default value is off.systemtenextrace
[on | off]type
[type-name]type to
type-name. If no type is specified, the current type
is printed. The default type is “binary”.umask
[newmask]user
username [password
[account]]ftp will prompt the user for it (after
disabling local echo). If an account field is not
specified, and the FTP server requires it, the user will be prompted for
it. If an account field is specified, an account
command will be relayed to the remote server after the login sequence is
completed if the remote server did not require it for logging in. Unless
ftp is invoked with “auto-login”
disabled, this process is done automatically on initial connection to the
FTP server.verbose
[on | off]Command arguments which have embedded spaces may be quoted with
quote (‘"’) marks.
Commands which toggle settings can take an explicit
on or off argument to force
the setting appropriately.
If ftp receives a
SIGINFO (see the “status” argument of
stty(1)) signal whilst a
transfer is in progress, the current transfer rate statistics will be
written to the standard error output, in the same format as the standard
completion message.
In addition to standard commands, this version of
ftp supports an auto-fetch feature. To enable
auto-fetch, simply pass the list of hostnames/files on the command line.
The following formats are valid syntax for an auto-fetch element:
ftp format.ftp_proxy isn't defined. Otherwise, transfer using
HTTP via the proxy defined in ftp_proxy. If a
user and password are given
and ftp_proxy isn't defined, log in as
user with a password of
password.http_proxy is defined, it is used as a URL to an
HTTP proxy server. If a user and
password are given and
http_proxy isn't defined, log in as
user with a password of
password using Basic authentication.http_proxy is defined, this HTTPS proxy server
will be used to fetch the file using the CONNECT method. If a
user and password are given
and http_proxy isn't defined, log in as
user with a password of
password using Basic authentication.If a classic format or an FTP URL format has a trailing
‘/’, then ftp will connect to the site
and cd to the directory given as the path, and leave
the user in interactive mode ready for further input.
If successive auto-fetch FTP elements refer to the same host, then the connection is maintained between transfers, reducing overhead on connection creation and deletion.
If file contains a glob character and
globbing is enabled (see glob), then the equivalent
of mget file is performed.
If no -o option is specified, and the
directory component of file contains no globbing
characters, then it is stored in the current directory as the
basename(1) of
file. If -o
output is specified, then file
is stored as output. Otherwise, the remote name is
used as the local name.
To abort a file transfer, use the terminal interrupt key (usually
Ctrl-C). Sending transfers will be immediately halted. Receiving transfers
will be halted by sending an FTP protocol ABOR
command to the remote server, and discarding any further data received. The
speed at which this is accomplished depends upon the remote server's support
for ABOR processing. If the remote server does not
support the ABOR command, an
‘ftp>’ prompt will not appear until
the remote server has completed sending the requested file.
The terminal interrupt key sequence will be ignored when
ftp has completed any local processing and is
awaiting a reply from the remote server. A long delay in this mode may
result from the ABOR processing described above, or from unexpected behavior
by the remote server, including violations of the FTP protocol. If the delay
results from unexpected remote server behavior, the local
ftp program must be killed by hand.
Files specified as arguments to ftp
commands are processed according to the following rules.
ftp then forks a shell, using
popen(3) with the argument
supplied, and reads (writes) from the standard output (standard input). If
the shell command includes spaces, the argument must be quoted; e.g.,
"ls -lt". A particularly useful example of this mechanism is:
"dir |more".glob command. If the ftp
command expects a single local file (e.g., put),
only the first filename generated by the “globbing”
operation is used.mget commands and get
commands with unspecified local file names, the local filename is the
remote filename, which may be altered by a case,
ntrans, or nmap setting.
The resulting filename may then be altered if
runique is on.mput commands and put
commands with unspecified remote file names, the remote filename is the
local filename, which may be altered by a ntrans
or nmap setting. The resulting filename may then
be altered by the remote server if sunique is
on.The FTP specification specifies many parameters which may affect a
file transfer. The type may be one of
“ascii”, “binary”, “image”,
“ebcdic” (currently not supported) or “tenex”
(local byte size 8, for PDP-10's and PDP-20's mostly).
ftp supports the ASCII and image types of file
transfer, plus local byte size 8 for tenex mode
transfers.
ftp supports only the default values for
the remaining file transfer parameters: mode,
form, and struct.
The .netrc file contains login and initialization information used by the auto-login process. It resides in the user's home directory. The following tokens are recognized; they may be separated by spaces, tabs, or new-lines:
machine
namemachine token that matches the remote machine
specified on the ftp command line or as an
open command argument. Once a match is made, the
subsequent .netrc tokens are processed, stopping
when the end of file is reached or another machine
or a default token is encountered.defaultmachine
name except that default
matches any name. There can be only one default
token, and it must be after all machine tokens.
This is normally used as:
default login anonymous password
user@sitethereby giving the user automatic
anonymous FTP login to machines not specified in
.netrc. This can be overridden by using the
-n flag to disable auto-login.
login
namepassword
stringftp will abort
the auto-login process if the .netrc is readable
by anyone besides the user.account
stringACCT command if it does not.macdef
nameftp
macdef command functions. A macro is defined with
the specified name; its contents begin with the next
.netrc line and continue until a null line
(consecutive new-line characters) is encountered. Like the other tokens in
the .netrc file, a macdef
is applicable only to the machine definition
preceding it. A macdef entry cannot be utilized by
multiple machine definitions; rather, it must be
defined following each machine it is intended to
be used with. If a macro named init is defined, it
is automatically executed as the last step in the auto-login process.ftp supports interactive command line
editing, via the
editline(3) library. It is
enabled with the edit command, and is enabled by
default if input is from a tty. Previous lines can be recalled and edited
with the arrow keys, and other GNU Emacs-style editing keys may be used as
well.
The editline(3) library is configured with a .editrc file - refer to editrc(5) for more information.
An extra key binding is available to ftp
to provide context sensitive command and filename completion (including
remote file completion). To use this, bind a key to the
editline(3) command
ftp-complete. By default, this is bound to the TAB
key.
ftp utilizes the following environment
variables:
FTPMODEFTPSERVERgate is
enabled.FTPSERVERPORTgate is enabled. Default is port returned by a
getservbyname() lookup of
“ftpgate/tcp”.HOMEPAGERpage to display files.SHELLTMPDIRftp_proxyhttp_proxyFor active mode data connections, ftp will
listen to a random high TCP port. The interval of ports used are
configurable using sysctl(8)
variables net.inet.ip.porthifirst and
net.inet.ip.porthilast.
basename(1), csh(1), more(1), stty(1), tar(1), tftp(1), editline(3), getservbyname(3), popen(3), editrc(5), services(5), ftp-proxy(8), ftpd(8)
J. Postel and J. Reynolds, FILE TRANSFER PROTOCOL (FTP), RFC 959, October 1985.
P. Hethmon, Extensions to FTP, RFC 3659, March 2007.
The ftp command appeared in
4.2BSD.
Correct execution of many commands depends upon proper behavior by the remote server.
In the recursive mode of mget, files and
directories starting with whitespace are ignored because the list cannot be
parsed any other way.
| July 11, 2014 | OpenBSD-5.6 |