## SYNOPSIS

           ftp [-v] [-d] [-i] [-n] [-g] [-k realm] [-f] [-x] [-u] [-t] [host]

## DESCRIPTION

           FTP  is the user interface to the ARPANET standard File Transfer Proto-
           col.  The program allows a user to transfer files to and from a  remote
           network site.

## OPTIONS

           Options  may be specified at the command line, or to the command inter-
           preter.

           -v     Verbose option forces ftp to show all responses from the  remote
                  server, as well as report on data transfer statistics.

           -n     Restrains  ftp  from attempting ``auto-login'' upon initial con-
                  nection.  If auto-login is enabled, ftp will  check  the  .netrc
                  (see  below)  file  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
                  login.

           -u     Restrains ftp from attempting ``auto-authentication'' upon  ini-
                  tial   connection.    If  auto-authentication  is  enabled,  ftp
                  attempts to authenticate to the FTP server by sending  the  AUTH
                  command,  using  whichever authentication types are locally sup-
                  ported.  Once an authentication type is accepted, an authentica-
                  tion  protocol  will  proceed  by  issuing  ADAT commands.  This
                  option also disables auto-login.

           -i     Turns off interactive prompting during multiple file  transfers.

           -d     Enables debugging.

           -g     Disables file name globbing.

           -f     Causes credentials to be forwarded to the remote host.

           -x     Causes  the  client to attempt to negotiate encryption (data and
                  command protection levels ``private'')  immediately  after  suc-
                  cessfully authenticating.

           -t     Enables packet tracing.

## COMMANDS

           The  client  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 from the user the prompt ``ftp>''
                  pleted.  If no argument is included, the user will  be  prompted
                  for an account 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 set-
                  ting.  File transfer uses the current settings for type, format,
                  mode, and structure.

           ascii  Set  the  file  transfer  type  to  network ASCII .  This is the
                  default type.

           bell   Arrange that a bell be sounded after each file transfer  command
                  is completed.

           binary Set the file transfer type to support binary file transfer.

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

           case   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
                  directory with the letters mapped to lower case.

           ccc    Turn off integrity protection on the command channel.  This com-
                  mand must be sent integrity protected, and must be proceeded  by
                  a  successful ADAT command.  Since turning off integrity protec-
                  tion potentially allows an attacker to insert commands onto  the
                  command  channel, some FTP servers may refuse to honor this com-
                  mand.

           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-name
                  Change the permission modes of the file file-name on the  remote
                  system to mode.

           clear  Set  the protection level on data transfers to ``clear''.  If no
                  ADAT command succeeded, then  this  is  the  default  protection
                  level.

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

           cprotect [protection-level]
                  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  distin-
                  guished from a record delimiter only when cr is off.

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

           debug [debug-value]
                  Toggle  debugging mode.  If an optional debug-value 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 `-->'

           dir [remote-directory] [local-file]
                  Print a listing of the  directory  contents  in  the  directory,
                  remote-directory,  and, optionally, placing the output in local-
                  file.  If interactive prompting is on, ftp will prompt the  user
                  to verify that the last argument is indeed the target local file
                  for receiving dir output.  If no  directory  is  specified,  the
                  current  working directory on the remote machine is used.  If no
                  local file is specified, or local-file is `-', output  comes  to
                  the terminal.

           disconnect
                  A synonym for close.

           form format
                  Set  the  file  transfer  form to format.  The default format is
                  ``file''.

           get remote-file [local-file]
                  Retrieve the file 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
                  current  case,  ntrans, and nmap settings.  The current settings
                  for type, form, mode, and structure are used while  transferring
                  the file.

           glob   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
                  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).

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

           ls [remote-directory] [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 UNIX sys-
                  tems will produce output from the command `ls  -l'.   (See  also
                  nlist.)   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.

           macdefmacro-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.  Macros remain defined until a close command  is
                  executed.  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'  signals  that  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]
                  Delete remote-files on the remote machine.

           mdir remote-files local-file
                  Like dir, except multiple remote files  may  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 mdir output.

           mget 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
                  according 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'.

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

           mput 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.

           newer file-name
                  Get the file only if the modification time of the remote file is
                  more recent that 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
                  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 nlist output.  If no local  file
                  is specified, or if local-file is `-', the output is sent to the
                  terminal.

           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 tar-
                  get 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 non-UNIX remote computer with different file nam-
                  ing 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 replace by the original filename.  Addi-
                  tionally, the sequence `[seq1, seq2]' is replaced by  [seq1]  if
                  seq1  is  not  a  null string; otherwise it is replaced by seq2.
                  For example, the command

                       nmap $1.$2.$3 [$1,$2].[$2,file]

                  would yield the output filename "myfile.data"  for  input  file-
                  names "myfile.data" and "myfile.data.old", "myfile.file" for the
                  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  corre-
                  sponding  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] [-forward]
                  Establish  a  connection  to  the specified host FTP server.  An
                  optional port number may be supplied, in which  case,  ftp  will
                  attempt  to  contact  an  FTP server at that port.  If the auto-
                  authenticate option is on (default), ftp will attempt to authen-
                  ticate  to  the  FTP  server  by sending the AUTH command, using
                  whichever authentication  types  which  are  locally  supported.
                  Once  an authentication type is accepted, an authentication pro-
                  tocol will proceed by issuing ADAT commands.  If the  auto-login
                  option  is  on (default), ftp will also attempt to automatically
                  log the user in to the FTP server (see below).  If the  -forward
                  option  is specified, ftp will forward a copy of the user's Ker-
                  beros tickets to the remote host.

           passive
                  Toggle passive data transfer mode.  In passive mode, the  client
                  initiates  the  data  connection  by listening on the data port.
                  Passive mode may be necessary for operation  from  behind  fire-
                  walls which do not permit incoming connections.

           private
                  Set the protection level on data transfers to ``private''.  Data
                  transmissions are confidentiality  and  integrity  protected  by
                  encryption.   If no ADAT command succeeded, then the only possi-
                  ble level is ``clear''.

           prompt Toggle interactive prompting.  Interactive prompting occurs dur-
                  ing  multiple  file  transfers  to allow the user to selectively
                  retrieve 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.

           protect [protection-level]
                  Set the protection level on data transfers to  protection-level.
                  The  valid  protection levels are ``clear'' for unprotected data
                  transmissions, ``safe'' for data  transmissions  integrity  pro-
                  tected  by  cryptographic  checksum,  and  ``private''  for data
                  transmissions confidentiality and integrity protected by encryp-
                  tion.   If  no  ADAT  command  succeeded, then the only possible
                  level is ``clear''.  If no level is specified, the current level
                  is printed.  The default protection level is ``clear''.

           proxy ftp-command
                  Execute  an ftp command on a secondary control connection.  This

           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
                  according 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
                  machine.

           quit   A synonym for bye.

           quote arg1 [arg2] [...]
                  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.

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

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

           rename [from] [to]
                  Rename the file from on the remote machine, to the file to.

           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.

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

                  If  no  ADAT  command succeeded, then the only possible level is
                  ``clear''.

           send local-file [remote-file]
                  A synonym for put.

           sendport
                  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
                  performing  multiple file transfers.  If the PORT command fails,
                  ftp will use the default data port.  When the use of  PORT  com-
                  mands  is disabled, no attempt will be made to use PORT commands
                  for each data transfer.  This is useful for certain  FTP  imple-
                  mentations which do ignore PORT commands but, incorrectly, indi-
                  cate they've been accepted.

           site arg1 [arg2] [...]
                  The arguments specified are sent, verbatim, to  the  remote  FTP
                  server as a SITE command.

           size file-name
                  Return size of file-name on remote machine.

           status Show the current status of ftp.

           struct struct-name
                  Set  the  file  transfer  structure  to struct-name.  By default
                  ``stream'' structure is used.

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

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

           tenex  Set the file transfer type to  that  needed  to  talk  to  TENEX
                  machines.

           trace  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  network
                  ASCII.

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

                  FTP server are displayed to the user.  In addition,  if  verbose
                  is  on, when a file transfer completes, statistics regarding the
                  efficiency of the transfer are reported.  By default, verbose is
                  on.

            ? [command]
                  A synonym for help.

           Command  arguments  which have embedded spaces may be quoted with quote
           `"' marks.

## 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 a 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 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,
           including  violations  of  the ftp protocol.  If the delay results from
           unexpected 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 the file name `-' is specified, stdin (for reading) or stdout
                  (for writing) is used.

           2.     If the first character of the 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
                  from (writes to) stdout (stdin).  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''.

           3.     Failing the above checks, if ``globbing'' is enabled, local file
                  names are expanded according to the rules used in  csh(1);  c.f.
                  the  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
                  altered by a case, ntrans, or nmap setting.  The resulting file-

           Ftp  supports  only  the default values for the remaining file transfer
           parameters: 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
           following 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
                  machines  not  specified  in  .netrc.  This can be overridden by
                  using 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 command 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

           Lunt, S. J., FTP Security Extensions, Internet Draft, November 1993.

## HISTORY

           The ftp command appeared in 4.2BSD.

## BUGS

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

           An  error in the treatment of carriage returns in the 4.2BSD ascii-mode
           transfer code has been corrected.  This correction may result in incor-
           rect  transfers  of  binary  files to and from 4.2BSD servers using the
           ascii type.  Avoid this problem by using the binary image type.

                                                                            FTP(1)