Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FTP(1)			FreeBSD	General	Commands Manual			FTP(1)

NAME
     ftp -- Internet file transfer program

SYNOPSIS
     ftp [-46AadEegiMmnptVv] [-D title]	[-k seconds] [-P port] [-r seconds]
	 [-s sourceaddr] [host [port]]
     ftp [-C] [-N name]	[-o output] [-s	sourceaddr]
	 ftp://[user:password@]host[:port]/file[/] ...
     ftp [-CTu]	[-c cookie] [-N	name] [-o output] [-S ssl_options]
	 [-s sourceaddr] [-U useragent]	[-w seconds]
	 http[s]://[user:password@]host[:port]/file ...
     ftp [-C] [-N name]	[-o output] [-s	sourceaddr] file:file ...
     ftp [-C] [-N name]	[-o output] [-s	sourceaddr] host:/file[/] ...

DESCRIPTION
     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	     Forces ftp	to use IPv4 addresses only.

     -6	     Forces ftp	to use IPv6 addresses only.

     -A	     Force active mode FTP.  By	default, 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	     Causes ftp	to bypass the normal login procedure and use an	anony-
	     mous login	instead.

     -C	     Continue a	previously interrupted file transfer.  ftp will	con-
	     tinue 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	cookie
	     Load a Netscape-like cookiejar file for HTTP and HTTPS transfers.
	     With this option relevant cookies from the	jar are	sent with each
	     HTTP(S) request.  Setting the http_cookies	environment variable
	     has the same effect.  If both the http_cookies environment	vari-
	     able is set and the -c argument is	given, the latter takes	prece-
	     dence.

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

     -d	     Enables debugging.

     -E	     Disables EPSV/EPRT	command	on IPv4	connections.

     -e	     Disables command line editing.  Useful for	Emacs ange-ftp.

     -g	     Disables file name	globbing.

     -i	     Turns off interactive prompting during multiple file transfers.

     -k	seconds
	     When greater than zero, sends a byte after	each seconds period
	     over the control connection during	long transfers,	so that	incor-
	     rectly configured network equipment won't aggressively drop it.
	     The FTP protocol supports a NOOP 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	     Causes ftp	to never display the progress meter in cases where it
	     would do so by default.

     -m	     Causes ftp	to always display the progress meter in	cases where it
	     would not do so by	default.

     -N	name
	     Use this alternative name instead of ftp in some error reports.

     -n	     Restrains ftp from	attempting "auto-login"	upon initial connec-
	     tion.  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
	     When fetching a single file or URL, save the contents in output.
	     To	make the contents go to	stdout,	use `-'	for output.

     -P	port
	     Sets the port number to port.

     -p	     Enable passive mode operation for use behind connection filtering
	     firewalls.	 This option has been deprecated as ftp	now tries to
	     use passive mode by default, falling back to active mode if the
	     server does not support passive connections.

     -r	seconds
	     Retry to connect if failed, pausing for number of seconds.

     -S	ssl_options
	     SSL/TLS options to	use with HTTPS transfers.  The following set-
	     tings are available:

	     cafile=/path/to/cert.pem
		     PEM encoded file containing CA certificates used for cer-
		     tificate validation.

	     capath=/path/to/certs/
		     Directory containing PEM encoded CA certificates used for
		     certificate validation.  Such a directory can be prepared
		     using the c_rehash	script distributed with	OpenSSL.

	     ciphers=cipher_list
		     Specify the list of ciphers that will be used by ftp.
		     See the openssl(1)	ciphers	subcommand.

	     depth=max_depth
		     Maximum depth of the certificate chain allowed when per-
		     forming validation.

	     do	     Perform server certificate	validation.

	     dont    Don't perform server certificate validation.

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

	     noverifytime
		     Disable validation	of certificate times and OCSP valida-
		     tion.

	     protocols=protocol_list
		     Specify the TLS protocols that will be supported by ftp
		     (see tls_config_parse_protocols(3)	for details).

	     session=/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.

	     By	default, server	certificate validation is performed, and if it
	     fails ftp will abort.  If no cafile or capath setting is pro-
	     vided, /etc/ssl/cert.pem will be used.

     -s	sourceaddr
	     Set the source address for	connections, which is useful on	ma-
	     chines with multiple interfaces.

     -T	     Send an "If-Modified-Since" header	to the remote to determine if
	     the remote	file's timestamp has changed.

     -t	     Enables packet tracing.

     -U	useragent
	     Set useragent as the User-Agent for HTTP(S) URL requests.	If not
	     specified,	the default User-Agent is "OpenBSD ftp".

     -u	     Disable setting the local file's timestamps based on the
	     "Last-Modified" header.  By default the local file's timestamps
	     are set to	match those from the remote.

     -V	     Disable verbose mode, overriding the default of enabled when in-
	     put is from a terminal.

     -v	     Enable verbose mode.  This	is the default if input	is from	a ter-
	     minal.  Forces ftp	to show	all responses from the remote server,
	     as	well as	report on data transfer	statistics.

     -w	seconds
	     For URL format connections	to HTTP/HTTPS servers, abort a slow
	     connection	after seconds.

     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 con-
     nection to	an FTP server on that host; otherwise, ftp will	enter its com-
     mand interpreter and await	instructions from the user.  When ftp is
     awaiting commands,	the prompt "ftp>" is provided to the user.  The	fol-
     lowing commands are recognized by ftp:

     ! [command	[arg ...]]
	     Invoke an interactive shell on the	local machine.	If there are
	     arguments,	the first is taken to be a command to execute di-
	     rectly, with the rest of the arguments as its arguments.

     $ macro-name [arg ...]
	     Execute the macro macro-name that was defined with	the macdef
	     command.  Arguments are passed to the macro unglobbed.

     ? [command]
	     A synonym for help.

     account [password]
	     Supply a supplemental password required by	a remote system	for
	     access to resources once a	login has been successfully completed.
	     If	no argument is included, the user will be prompted for an ac-
	     count password in a non-echoing input mode.

     append local-file [remote-file]
	     Append a local file to a file on the remote machine.  If
	     remote-file is left unspecified, the local	file name is used in
	     naming the	remote file after being	altered	by any ntrans or nmap
	     setting.  File transfer uses the current settings for type,
	     format, mode, and structure.

     ascii   Set the file transfer type	to network ASCII.

     bell [on |	off]
	     Arrange that a bell be sounded after each file transfer command
	     is	completed.

     binary  Set the file transfer type	to support binary image	transfer.
	     This is the default type.

     bye     Terminate the FTP session with the	remote server and exit ftp.
	     An	end-of-file will also terminate	the session and	exit.

     case [on |	off]
	     Toggle remote computer file name case mapping during mget com-
	     mands.  When case is on (default is off), remote computer file
	     names with	all letters in upper case are written in the local di-
	     rectory with the letters mapped to	lower case.

     cd	remote-directory
	     Change the	working	directory on the remote	machine	to
	     remote-directory.

     cdup    Change the	remote machine working directory to the	parent of the
	     current remote machine working directory.

     chmod mode	file
	     Change the	permission modes of file on the	remote system to mode.

     close   Terminate the FTP session with the	remote server and return to
	     the command interpreter.  Any defined macros are erased.

     cr	[on | off]
	     Toggle carriage return stripping during ASCII type	file re-
	     trieval.  Records are denoted by a	carriage return/linefeed se-
	     quence during ASCII type file transfer.  When cr is on (the de-
	     fault), carriage returns are stripped from	this sequence to con-
	     form 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]
	     Toggle debugging mode.  If	an optional debuglevel is specified,
	     it	is used	to set the debugging level.  When debugging is on, ftp
	     prints each command sent to the remote machine, preceded by the
	     string `-->'.

     delete remote-file
	     Delete the	file remote-file on the	remote machine.

     dir [remote-directory [local-file]]
	     A synonym for ls.

     disconnect
	     A synonym for close.

     edit [on |	off]
	     Toggle command line editing, and context sensitive	command	and
	     file completion.  This is automatically enabled if	input is from
	     a terminal, and disabled otherwise.

     epsv4 [on | off]
	     Toggle use	of EPSV/EPRT command on	IPv4 connection.

     exit    A synonym for bye.

     form format
	     Set the file transfer form	to format.  The	default	format is
	     "file".

     ftp host [port]
	     A synonym for open.

     gate [on |	off | host [port]]
	     Toggle gate-ftp mode.  This will not be permitted if the gate-ftp
	     server hasn't been	set (either explicitly by the user, or from
	     the 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]
	     Retrieve the 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, subject to alteration by the	cur-
	     rent case,	ntrans,	and nmap settings.  The	current	settings for
	     type, form, mode, and structure are used while transferring the
	     file.

     glob [on |	off]
	     Toggle filename expansion for mdelete, mget and mput.  If glob-
	     bing 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 ex-
	     pansion of	the name of an ordinary	file: the exact	result depends
	     on	the foreign operating system and FTP server, and can be	pre-
	     viewed 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]
	     Toggle hash mark (`#') 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]
	     Print an informative message about	the meaning of command.	 If no
	     argument is given,	ftp prints a list of the known commands.

     idle [seconds]
	     Set the inactivity	timer on the remote server to seconds seconds.
	     If	seconds	is omitted, the	current	inactivity timer is printed.

     lcd [local-directory]
	     Change the	working	directory on the local machine.	 If no
	     local-directory is	specified, the user's home directory is	used.

     less file
	     A synonym for page.

     lpwd    Print the working directory on the	local machine.

     ls	[remote-directory [local-file]]
	     Print a listing of	the contents of	a directory on the remote ma-
	     chine.  The listing includes any system-dependent information
	     that the server chooses to	include; for example, most UNIX	sys-
	     tems will produce output from the command `ls -l'.	 If
	     remote-directory is left unspecified, the current working direc-
	     tory 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 speci-
	     fied, or if local-file is `-', the	output is sent to the termi-
	     nal.

     macdef macro-name
	     Define a macro.  Subsequent lines are stored as the macro
	     macro-name; a null	line (consecutive newline characters in	a file
	     or	carriage returns from the terminal) terminates macro input
	     mode.  There is a limit of	16 macros and 4096 total characters in
	     all defined macros.  Macro	names can be a maximum of 8 charac-
	     ters.  Macros are only applicable to the current session they are
	     defined in	(or if defined outside a session, to the session in-
	     voked with	the next open 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	corre-
	     sponding 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 sec-
	     ond 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]
	     Delete the	remote-files on	the remote machine.

     mdir remote-files local-file
	     A synonym for mls.

     mget [-cnr] [-d depth] remote-files
	     Expand the	remote-files on	the remote machine and do a get	for
	     each file name thus produced.  See	glob for details on the	file-
	     name expansion.  Resulting	file names will	then be	processed ac-
	     cording to	case, ntrans, and nmap settings.  Files	are trans-
	     ferred 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:

	     -c	     Use reget instead of get.

	     -d	depth
		     Specify the maximum recursion level depth.	 The default
		     is	0, which means unlimited.

	     -n	     Use newer instead of get.

	     -r	     Recursively descend the directory tree, transferring all
		     files and directories.

     mkdir directory-name
	     Make a directory on the remote machine.

     mls remote-files local-file
	     Like ls, 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 in-
	     deed the target local file	for receiving mls output.

     mode [mode-name]
	     Set the file transfer mode	to mode-name.  The default mode	is
	     "stream" mode.

     modtime file
	     Show the last modification	time of	file on	the remote machine.

     more file
	     A synonym for page.

     mput [-cr]	[-d depth] local-files
	     Expand wild cards in the list of local files given	as arguments
	     and do a put 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:

	     -c	     Use reput instead of put.

	     -d	depth
		     Specify the maximum recursion level depth.	 The default
		     is	0, which means unlimited.

	     -r	     Recursively descend the directory tree, transferring all
		     files and directories.

     msend [-c]	local-files
	     A synonym for mput.

     newer remote-file [local-file]
	     Get the file only if the modification time	of the remote file is
	     more recent than the file on the current system.  If the file
	     does not exist on the current system, the remote file is consid-
	     ered newer.  Otherwise, this command is identical to get.

     nlist [remote-directory [local-file]]
	     Print a list of the files in a directory on the remote machine.
	     If	remote-directory is left unspecified, the current working di-
	     rectory 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 nlist output.  If	no local file is spec-
	     ified, or if local-file is	`-', the output	is sent	to the termi-
	     nal.  Note	that on	some servers, the nlist	command	will only re-
	     turn information on normal	files (not directories or special
	     files).

     nmap [inpattern outpattern]
	     Set or unset the filename mapping mechanism.  If no arguments are
	     specified,	the filename mapping mechanism is unset.  If arguments
	     are specified, remote filenames are mapped	during mput commands
	     and put commands issued without a specified remote	target file-
	     name.  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 set-
	     tings).  Variable templating is accomplished by including the se-
	     quences `$1', `$2', ..., `$9' in inpattern.  Use `\' to prevent
	     this special treatment of the `$' character.  All other charac-
	     ters are treated literally, and are used to determine the nmap
	     inpattern variable	values.

	     For example, given	inpattern $1.$2	and the	remote file name "my-
	     data.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 se-
	     quence `[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 in-
	     put filenames myfile.data and myfile.data.old; myfile.file	for
	     the input filename	myfile;	and myfile.myfile for the input	file-
	     name .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]]
	     Set or unset the filename character translation mechanism.	 If no
	     arguments are specified, the filename character translation mech-
	     anism is unset.  If arguments are specified, characters in	remote
	     filenames are translated during mput commands and put commands
	     issued without a specified	remote target filename.	 If arguments
	     are specified, characters in local	filenames are translated dur-
	     ing mget commands and get commands	issued without a specified lo-
	     cal 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]
	     Establish a connection to the specified host FTP server.  An op-
	     tional port number	may be supplied, in which case ftp will	at-
	     tempt 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 file
	     Retrieve file and display with the	program	defined	in PAGER (de-
	     faulting to more(1) if PAGER is null or not defined).

     passive [on | off]
	     Toggle passive mode.  If passive mode is turned on	(default is
	     on), ftp will send	a EPSV command for all data connections	in-
	     stead 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 con-
	     trols 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]
	     Toggle preservation of modification times on retrieved files.

     progress [on | off]
	     Toggle display of transfer	progress bar.  The progress bar	will
	     be	disabled for a transfer	that has local-file as `-' or a	com-
	     mand that starts with `|'.	 Refer to FILE NAMING CONVENTIONS for
	     more information.

     prompt [on	| off]
	     Toggle interactive	prompting.  Interactive	prompting occurs dur-
	     ing multiple file transfers to allow the user to selectively re-
	     trieve or store files.  If	prompting is turned off	(default is
	     on), any 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:

		   ?   Print help message.

		   a   Answer "yes" to the current file	and automatically an-
		       swer "yes" to any remaining files for the current com-
		       mand.

		   n   Do not transfer the file.

		   p   Answer "yes" to the current file	and turn off prompt
		       mode (as	if "prompt off"	had been given).

		   q   Answer "no" to the current file and automatically an-
		       swer "no" to any	remaining files	for the	current	com-
		       mand.

		   y   Transfer	the file.

     proxy command
	     Execute an	FTP command on a secondary control connection.	This
	     command allows simultaneous connection to two remote FTP servers
	     for transferring files between the	two servers.  The first	proxy
	     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 sec-
	     ondary 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 trans-
	     fers depend upon support of the FTP protocol PASV command by the
	     server on the secondary control connection.

     put local-file [remote-file]
	     Store a local file	on the remote machine.	If remote-file is left
	     unspecified, the local file name is used after processing accord-
	     ing to any	ntrans or nmap settings	in naming the remote file.
	     File transfer uses	the current settings for type, format, mode,
	     and structure.

     pwd     Print the name of the current working directory on	the remote ma-
	     chine.

     quit    A synonym for bye.

     quote arg ...
	     The arguments specified are sent, verbatim, to the	remote FTP
	     server.

     recv remote-file [local-file]
	     A synonym for get.

     reget remote-file [local-file]
	     Reget acts	like get, except that if local-file exists and is
	     smaller than remote-file, local-file is presumed to be a par-
	     tially transferred	copy of	remote-file and	the transfer is	con-
	     tinued from the apparent point of failure.	 This command is use-
	     ful when transferring very	large files over networks that are
	     prone to dropping connections.

     rename from-name to-name
	     Rename the	file from-name on the remote machine to	the file
	     to-name.

     reput local-file [remote-file]
	     Reput acts	like put, except that if remote-file exists and	is
	     smaller than local-file, remote-file is presumed to be a par-
	     tially transferred	copy of	local-file and the transfer is contin-
	     ued from the apparent point of failure.  This command is useful
	     when transferring very large files	over networks that are prone
	     to	dropping connections.

     reset   Clear reply queue.	 This command re-synchronizes command/reply
	     sequencing	with the remote	FTP server.  Resynchronization may be
	     necessary following a violation of	the FTP	protocol by the	remote
	     server.

     restart marker
	     Restart the immediately following get or put at the indicated
	     marker.  On UNIX systems, marker is usually a byte	offset into
	     the file.

     rhelp [command-name]
	     Request help from the remote FTP server.  If a command-name is
	     specified,	it is supplied to the server as	well.

     rmdir directory-name
	     Delete a directory	on the remote machine.

     rstatus [file]
	     With no arguments,	show status of remote machine.	If file	is
	     specified,	show status of file on remote machine.

     runique [on | off]
	     Toggle storing of files on	the local system with unique file-
	     names.  If	a file already exists with a name equal	to the target
	     local filename for	a 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]
	     A synonym for put.

     sendport [on | off]
	     Toggle the	use of 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 per-
	     forming 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 ...
	     The arguments specified are sent, verbatim, to the	remote FTP
	     server as a SITE command.

     size file
	     Return size of file on remote machine.

     status  Show the current status of	ftp.

     sunique [on | off]
	     Toggle storing of files on	remote machine under unique file
	     names.  The remote	FTP server must	support	the FTP	protocol STOU
	     command for successful completion.	 The remote server will	report
	     the unique	name.  Default value is	off.

     system  Show the type of operating	system running on the remote machine.

     trace [on | off]
	     Toggle packet tracing.

     type [type-name]
	     Set the file transfer type	to type-name.  If no type is speci-
	     fied, the current type is printed.	 The default type is "binary".

     umask [newmask]
	     Set the default umask on the remote server	to newmask.  If
	     newmask is	omitted, the current umask is printed.

     user username [password [account]]
	     Identify yourself to the remote FTP server.  If the password is
	     not specified and the server requires it, 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 se-
	     quence 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]
	     Toggle verbose mode.  In verbose mode, all	responses from the FTP
	     server are	displayed to the user.	In addition, if	verbose	is on,
	     when a file transfer completes, statistics	regarding the effi-
	     ciency of the transfer are	reported.  By default, verbose is on.

     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.

AUTO-FETCHING FILES
     In	addition to standard commands, this version of ftp supports an auto-
     fetch feature.  To	enable auto-fetch, simply pass the list	of host-
     names/files on the	command	line.

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

     host:/file[/]
	     "Classic" ftp format.

     ftp://[user:password@]host[:port]/file[/]
	     An	FTP URL, retrieved using the FTP protocol if 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://[user:password@]host[:port]/file
	     An	HTTP URL, retrieved using the HTTP protocol.  If 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.

     https://[user:password@]host[:port]/file
	     An	HTTPS URL, retrieved using the HTTPS protocol.	If 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.

     file:file
	     file is retrieved from a mounted file system.

     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	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 con-
     tains 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.

ABORTING A FILE	TRANSFER
     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 send-
     ing the requested file.

     The terminal interrupt key	sequence will be ignored when ftp has com-
     pleted 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,	in-
     cluding violations	of the FTP protocol.  If the delay results from	unex-
     pected remote server behavior, the	local ftp program must be killed by
     hand.

FILE NAMING CONVENTIONS
     Files specified as	arguments to ftp commands are processed	according to
     the following rules.

     1.	  If `-' is specified as a local file name, the	standard input (for
	  reading) or standard output (for writing) is used.

     2.	  If the first character of a local file name is `|', the remainder of
	  the argument is interpreted as a shell command.  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 in-
	  cludes spaces, the argument must be quoted; e.g., "ls	-lt".  A par-
	  ticularly useful example of this mechanism is: "ls . |more".

     3.	  Failing the above checks, if "globbing" is enabled, local file names
	  are expanded according to the	rules used in the csh(1) 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.

     4.	  For mget commands and	get commands with unspecified local file
	  names, the local filename is the remote filename, which may be al-
	  tered	by a case, ntrans, or nmap setting.  The resulting filename
	  may then be altered if runique is on.

     5.	  For mput commands and	put commands with unspecified remote file
	  names, the remote filename is	the local filename, which may be al-
	  tered	by a ntrans or nmap setting.  The resulting filename may then
	  be altered by	the remote server if sunique is	on.

FILE TRANSFER PARAMETERS
     The FTP specification specifies many parameters which may affect a	file
     transfer.	The type may be	one of "ascii",	"binary", or "image".  ftp
     supports the ASCII	and image types	of file	transfer.

     ftp supports only the default values for the remaining file transfer pa-
     rameters: mode, form, and struct.

THE .netrc FILE
     The .netrc	file contains login and	initialization information used	by the
     auto-login	process.  It resides in	the user's home	directory.  The	fol-
     lowing tokens are recognized; they	may be separated by spaces, tabs, or
     new-lines:

     machine name
	       Identify	a remote machine name.	The auto-login process
	       searches	the .netrc file	for a machine 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   This is the same	as 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	ma-
	       chines not specified in .netrc.	This can be overridden by us-
	       ing the -n flag to disable auto-login.

     login name
	       Identify	a user on the remote machine.  If this token is
	       present,	the auto-login process will initiate a login using the
	       specified name.

     password string
	       Supply a	password.  If this token is present, the auto-login
	       process will supply the specified string	if the remote server
	       requires	a password as part of the login	process.  Note that if
	       this token is present in	the .netrc file	for any	user other
	       than anonymous, ftp will	abort the auto-login process if	the
	       .netrc is readable by anyone besides the	user.

     account string
	       Supply an additional account password.  If this token is
	       present,	the auto-login process will supply the specified
	       string if the remote server requires an additional account
	       password, or the	auto-login process will	initiate an ACCT com-
	       mand if it does not.

     macdef name
	       Define a	macro.	This token functions like the ftp macdef com-
	       mand 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 applica-
	       ble only	to the machine definition preceding it.	 A macdef en-
	       try 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 automati-
	       cally executed as the last step in the auto-login process.

COMMAND	LINE EDITING
     ftp supports interactive command line editing, via	the editline(3)	li-
     brary.  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 de-
     fault, this is bound to the TAB key.

ENVIRONMENT
     ftp utilizes the following	environment variables:

     FTPMODE	    Overrides the default operation mode.  Recognized values
		    are:

			  passive    passive mode FTP only
			  active     active mode FTP only
			  auto	     automatic determination of	passive	or ac-
				     tive (this	is the default)
			  gate	     gate-ftp mode

     FTPSERVER	    Host to use	as gate-ftp server when	gate is	enabled.

     FTPSERVERPORT  Port to use	when connecting	to gate-ftp server when	gate
		    is enabled.	 Default is port returned by a getservbyname()
		    lookup of "ftpgate/tcp".

     HOME	    For	default	location of a .netrc file, if one exists.

     PAGER	    Used by page to display files.

     SHELL	    For	default	shell.

     ftp_proxy	    URL	of FTP proxy to	use when making	FTP URL	requests (if
		    not	defined, use the standard FTP protocol).

     http_proxy	    URL	of HTTP	proxy to use when making HTTP or HTTPS URL re-
		    quests.

     http_cookies   Path of a Netscape-like cookiejar file to use when making
		    HTTP or HTTPS URL requests.

PORT ALLOCATION
     For active	mode data connections, ftp will	listen to a random high	TCP
     port.  The	interval of ports used are configurable	using sysctl(8)	vari-
     ables net.inet.ip.porthifirst and net.inet.ip.porthilast.

SEE ALSO
     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)

STANDARDS
     J.	Postel and J. Reynolds,	FILE TRANSFER PROTOCOL (FTP), RFC 959, October
     1985.

     P.	Hethmon, Extensions to FTP, RFC	3659, March 2007.

HISTORY
     The ftp command appeared in 4.2BSD.

BUGS
     Correct execution of many commands	depends	upon proper behavior by	the
     remote server.

     In	the recursive mode of mget, files and directories starting with	white-
     space are ignored because the list	cannot be parsed any other way.

FreeBSD	13.0		       February	2, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | AUTO-FETCHING FILES | ABORTING A FILE TRANSFER | FILE NAMING CONVENTIONS | FILE TRANSFER PARAMETERS | THE .netrc FILE | COMMAND LINE EDITING | ENVIRONMENT | PORT ALLOCATION | SEE ALSO | STANDARDS | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ftp&sektion=1&manpath=OpenBSD+6.9>

home | help