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:
-4
ftp
to use IPv4 addresses only.-6
ftp
to use IPv6 addresses only.-A
ftp
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.-a
ftp
to bypass the normal login procedure
and use an anonymous login instead.-C
ftp
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.-m
ftp
to always display the progress meter in
cases where it would not do so by default.-n
ftp
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-p
ftp
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_depthdo
dont
By 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
-v
ftp
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
.ascii
type
to network ASCII.bell
[on
| off
]binary
type
to support binary image
transfer. This is the default type.bye
ftp
. 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-directorycdup
chmod
mode fileclose
cr
[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
.disconnect
close
.edit
[on
| off
]epsv4
[on
| off
]exit
bye
.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
.lpwd
ls
[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:
?
a
n
p
q
y
proxy
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
.pwd
quit
bye
.quote
arg ...recv
remote-file [local-file]get
.reget
remote-file [local-file]rename
from-name to-namereput
local-file [remote-file]reset
restart
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
filestatus
ftp
.sunique
[on
| off
]STOU
command for successful completion. The remote
server will report the unique name. Default value is off.system
tenex
trace
[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.default
machine
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@site
thereby 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:
FTPMODE
FTPSERVER
gate
is
enabled.FTPSERVERPORT
gate
is enabled. Default is port returned by a
getservbyname
() lookup of
“ftpgate/tcp”.HOME
PAGER
page
to display files.SHELL
TMPDIR
ftp_proxy
http_proxy
For 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 |