ncftp(1)                                                 ncftp(1)

       ncftp - Browser program for the File Transfer Protocol

       ncftp [host]

       ncftp []

       The purpose of ncftp is to provide a powerful and flexible
       interface to the Internet standard File Transfer Protocol.
       It is intended to replace the stock ftp program that comes
       with the system.

       Although the program appears to be rather spartan,  you'll
       find  that  ncftp has a wealth of valuable performance and
       usage features.  The program was designed with an emphasis
       on  usability, and it does as much as it can for you auto-
       matically so you can do what you expect to do with a  file
       transfer  program,  which  is  transfer  files between two
       interconnected systems.

       Some of the cooler features include progress meters, file-
       name completion, command-line editing, background process-
       ing, auto-resume downloads, bookmarking, cached  directory
       listings, host redialing, working with firewalls and prox-
       ies, downloading entire directory trees, etc., etc.

       The ncftp distribution comes with the useful utility  pro-
       grams  ncftpget(1)  and ncftpput(1) which were designed to
       do command-line FTP.  In particular, they are  very  handy
       for  shell  scripts.  This version of ncftp no longer does
       command-line FTP, since the main ncftp program is more  of
       a browser-type program.

       Upon  running  the  program  you  are  presented a command
       prompt where you type commands  to  the  program's  shell.
       Usually  you  will  want  to  open  a remote filesystem to
       transfer files to and from your local  machine's  filesys-
       tem.   To  do  that, you need to know the symbolic name of
       the remote system, or its Internet Protocol (IP)  address.
       For example, a symbolic name might be ``,''
       and its IP address could be ``''  To  open  a
       connection to that system, you use the program's open com-


       Both of these try to open the machine  called  typhoon  at
       the  University  of  Nebraska.  Using the symbolic name is
       the preferred way, because IP addresses may change without
       notice, while the symbolic names usually stay the same.

       When  you  open a remote filesystem, you need to have per-
       mission.  The FTP Protocol's authentication system is very
       similar  to  that of logging in to your account.  You have
       to give an account name, and its password  for  access  to
       that  account's  files.  However, most remote systems that
       have anything you might be interested in don't require  an
       account  name for use.  You can often get anonymous access
       to a remote filesystem and exchange files that  have  been
       made  publicly  accessible.   The  program attempts to get
       anonymous permission to a remote system by default.   What
       actually happens is that the program tries to use ``anony-
       mous'' as the account name, and when prompted for a  pass-
       word, uses your E-mail address as a courtesy to the remote
       system's maintainer.  You can have the program try to  use
       a specific account also.  That will be explained later.

       After  the  open  command  completes successfully, you are
       connected to the remote system and logged in.  You  should
       now  see  the command prompt change to reflect the name of
       the current remote directory.  To see what's in  the  cur-
       rent  remote  directory,  you can use the program's ls and
       dir commands.  The former is terse, preferring more remote
       files  in  less  screen space, and the latter is more ver-
       bose, giving detailed information about each item  in  the

       You  can  use  the  program's  cd command to move to other
       directories on the remote system.  The cd command  behaves
       very  much like the command of the same name in the Bourne
       and Korn shell.

       The purpose of the program is to exchange data with  other
       systems.   You can use the program's get command to copy a
       file from the remote system to your local system:

            get README.txt

       The program will display the progress of the  transfer  on
       the  screen,  so  you  can  tell how much needs to be done
       before the transfer finishes.  When the transfer does fin-
       ish,  then  you  can  enter more commands to the program's
       command shell.

       You can use the program's put command to copy a file  from
       your system to the remote system:

            put something.tar

       When  you  are  finished  using the remote system, you can
       open another one or use the quit

       Before quitting, you may want to save the current FTP ses-
       sion's  settings for later.  You can use the bookmark com-
       mand to save an  entry  into  your  $HOME/.ncftp/bookmarks
       file.  When you use the bookmark command, you also specify
       a bookmark name, so the next time instead of  opening  the
       full  hostname  you  can  use the name of the bookmark.  A
       bookmark acts just like one for your web  browser,  so  it
       saves  the  remote directory you were in, the account name
       you used, etc., and other information it learned  so  that
       the  next  time  you use the bookmark it should require as
       little effort from you as possible.

       help   The first command to know is  help.   If  you  just


              from  the  command  shell,  the  program prints the
              names of  all  of  the  supported  commands.   From
              there,  you  can get specific help for a command by
              typing the command after, for example:

                   help open

              prints information about the open command.

       ascii  This command sets the transfer type to ASCII  text.
              This  is useful for text-only transfers because the
              concept of text  files  differs  between  operating
              systems.   For example on UNIX, a text file denotes
              line breaks with the linefeed character,  while  on
              MS-DOS  a  line break is denoted by both a carriage
              return character and a line feed character.  There-
              fore, for data transfers that you consider the data
              as text you can use ascii to ensure that  both  the
              remote  system  and  local system translate accord-
              ingly.  The default transfer type that  ncftp  uses
              is not ASCII, but straight binary.

       bgget and bgput
              These  commands  correspond to the get and put com-
              mands explained below, except that they do the  job
              in the background.  Normally when you do a get then
              the program does the download immediately, and does
              not  return  control to you until the download com-
              pletes.  The background transfers are nice  because
              you can continue browsing the remote filesystem and
              even open other systems.  In fact, they are done by
              a  daemon process, so even if you log off your UNIX
              host the daemon should  still  do  your  transfers.
              And,  it  will  automatically the continue to retry
              the transfers until  they  finish.   To  tell  when
              background  jobs have finished, you have to examine
              the $HOME/.ncftp/batchlog file,  or  run  the  jobs
              command from within NcFTP.

              Both  the  bgget  and  bgput  commands allow you to
              schedule when to do the  transfers.   They  take  a
              ``-@''  parameter,  whose argument is a date of the
              form YYYYMMDDhhmmss (four digit year,  month,  day,
              hour,  minute, second).  For example, to schedule a
              download at 3 AM on November 6, you could try:

                   bgget -@ 19971106030000 /pub/idstuff/quake/

              This command tells ncftp to immediately  start  the
              background transfers you've requested, which simply
              runs a copy of  the  ncftpbatch  program  which  is
              responsible  for the background jobs.  Normally the
              program will start the background job  as  soon  as
              you  close  the  current  site, open a new site, or
              quit the program.  The reason for this  is  because
              since  so  many  users  still use slow dialup links
              that starting the transfers would slow things to  a
              crawl,  making  it  difficult  to browse the remote
              system.  An added bonus of starting the  background
              job  when you close the site is that ncftp can pass
              off that open connection to the ncftpbatch program.
              That  is nice when the site is always busy, so that
              the background job doesn't have to wait and get re-
              logged on to do its job.

       binary Sets  the  transfer  type to raw binary, so that no
              translation is done on the data transferred.   This
              is  the  default  anyway,  since  most files are in

              Saves the current session settings for  later  use.
              This is useful to save the remote system and remote
              working directory so you can quickly  resume  where
              you left off some other time.  The bookmark data is
              stored in your $HOME/.ncftp/bookmarks file.

              Lists the contents of  your  $HOME/.ncftp/bookmarks
              file  in a human-readable format.  You can use this
              command to recall the bookmark name of a previously
              saved  bookmark,  so that you can use the open com-
              mand with it.

       cat    Acts like the ``/bin/cat'' UNIX command,  only  for
              remote  files.  This downloads the file you specify
              and dumps it directly  to  the  screen.   You  will
              probably  find  the page command more useful, since
              that lets you view the file one screen  at  a  time
              instead of printing the entire file at once.

       cd     Changes  the  working directory on the remote host.
              Use this command to move to different areas on  the
              remote  server.  If you just opened a new site, you
              might be in the root directory.  Perhaps there  was
              a   directory  called  ``/pub/news/comp.sources.d''
              that someone told you about.  From the root  direc-
              tory, you could:

                   cd pub
                   cd news
                   cd comp.sources.d

              or, more concisely,

                   cd /pub/news/comp.sources.d

              Then,  commands  such  as get, put, and ls could be
              used to refer to items in that directory.

              Some shells in the UNIX environment have a  feature
              I  like,  which is switching to the previous direc-
              tory.  Like those shells, you can do:

                   cd -

              to change to the last directory you were in.

       chmod  Acts like the ``/bin/chmod'' UNIX command, only for
              remote files.  However, this is not a standard com-
              mand, so remote FTP servers may not support it.

       close  Disconnects you from the remote server.   The  pro-
              gram  does  this for you automatically when needed,
              so you can simply open other sites or quit the pro-
              gram  without worrying about closing the connection
              by hand.

       debug  This command is mostly for internal  testing.   You
              could type

                   debug 1

              to  turn debugging mode on.  Then you could see all
              messages between the program and the remote server,
              and things that are only printed in debugging mode.
              However, this information is also available in  the
              $HOME/.ncftp/trace file, which is created each time
              you run ncftp.  If you need to report a bug, send a
              trace file if you can.

       dir    Prints  a  detailed directory listing.  It tries to
              behave like UNIX's ``/bin/ls -l'' command.  If  the
              remote server seems to be a UNIX host, you can also
              use the same flags you would with ls, for instance

                   dir -rt

              would try to act like

                   /bin/ls -lrt

              would on UNIX.

       get    Copies files from the current working directory  on
              the  remote  host to your machine's current working
              directory.  To  place  a  copy  of  ``README''  and
              ``README.too''  in  your local directory, you could

                   get README README.too

              You could also accomplish that by using a  wildcard
              expression, such as:

                   get README*

              This  command  is  similar to the behavior of other
              FTP programs' mget command.  To retrieve  a  remote
              file but give it a different name on your host, you
              can use the ``-z'' flag.  This example shows how to
              download  a  file  called  ReadMe.txt  but  name it
              locally as README:

                   get -z ReadMe.txt README

              The  program  tries  to  ``resume''  downloads   by
              default.   This means that if the remote FTP server
              lost the connection and was only able to  send  490
              kilobytes  of a 500 kilobyte file, you could recon-
              nect to the FTP server and do another  get  on  the
              same  file  name and it would get the last 10 kilo-
              bytes, instead of retrieving the entire file again.
              There  are  some  occasions  where you may not want
              that behavior.  To turn it  off  you  can  use  the
              ``-Z'' flag.

              There are also times where you want to append to an
              existing file.  You can do this by using the ``-A''
              flag, for example

                   get -A log.11

              would  append  to  a  file  named  ``log.11'' if it
              existed locally.

              Another thing you can do is delete  a  remote  file
              after  you  download it.  This can be useful when a
              remote host expects a file to be  removed  when  it
              has been retrieved.  Use the double-D flag, such as
              ``get -DD'' to do this.

              The get command lets you retrieve entire  directory
              trees,  too.   Although  it  may not work with some
              remote systems,  you  can  try  ``get -R''  with  a
              directory  to  download  the directory and its con-

       jobs   Views the list of currently executing  NcFTP  back-
              ground  tasks.   This actually just runs ncftpbatch
              -l for you.

       lcd    The lcd command is the first of a  few  ``l''  com-
              mands  that work with the local host.  This changes
              the current working directory on  the  local  host.
              If  you  want  to  download  files into a different
              local directory, you could use  lcd  to  change  to
              that directory and then do your downloads.

       lchmod Runs ``/bin/chmod'' on the local host.

       lls    Another  local  command  that comes in handy is the
              lls command, which runs ``/bin/ls''  on  the  local
              host and displays the results in the program's win-
              dow.  You can use the same flags with  lls  as  you
              would  in  your command shell, so you can do things

                   lcd ~/doc
                   lls -lrt p*.txt

       lmkdir Runs ``/bin/mkdir'' on the local host.

       lookup The program also has a built-in  interface  to  the
              name  service  via  the lookup command.  This means
              you can lookup entries for remote hosts, like:




              There is also a more detailed option, enabled  with
              ``-v,'' i.e.:

                   lookup -v




              You  can also give IP addresses, so this would work




       lpage  Views a local file one page at a  time,  with  your
              preferred $PAGER program.

       lpwd   Prints  the current local directory.  Use this com-
              mand when you forget where you are  on  your  local

              Runs ``/bin/mv'' on the local host.

       lrm    Runs ``/bin/rm'' on the local host.

       lrmdir Runs ``/bin/rmdir'' on the local host.

       ls     Prints  a directory listing from the remote system.
              It tries to behave like UNIX's ``/bin/ls -CF'' com-
              mand.   If  the  remote  server  seems to be a UNIX
              host, you can also use the  same  flags  you  would
              with ls, for instance

                   ls -rt

              would try to act like

                   /bin/ls -CFrt

              would on UNIX.

              ncftp  has  a  powerful built-in system for dealing
              with directory listings.  It tries  to  cache  each
              one, so if you list the same directory, odds are it
              will display instantly.  Behind the  scenes,  ncftp
              always  tries a long listing, and then reformats it
              as it needs to.  So even if your first listing of a
              directory  was a regular ``ls'' which displayed the
              files  in  columns,  your  next  listing  could  be
              ``ls -lrt''  and  ncftp  would still use the cached
              directory listing to quickly display  the  informa-
              tion for you!

       mkdir  Creates  a  new  directory on the remote host.  For
              many public archives, you  won't  have  the  proper
              access permissions to do that.

       open   Establishes  an  FTP control connection to a remote
              host.  By default, ncftp logs in anonymously to the
              remote  host.   You may want to use a specific user
              account when you log in, so you can use the  ``-u''
              flag to specify which user.  This example shows how
              to open the  host  ``''  using
              the username ``mario:''

                   open -u mario

       page   Browses  a  remote  file  one page at a time, using
              your $PAGER program.  This is  useful  for  reading
              README's  on  the  remote  host without downloading
              them first.

       pdir and pls
              These commands are equivalent to dir and ls respec-
              tively,  only they feed their output to your pager.
              These commands are useful if the directory  listing
              scrolls off your screen.

       put    Copies  files  from  the  local  host to the remote
              machine's current working directory.   To  place  a
              copy  of  ``''  and  ``'' in the remote
              directory, you could try:


              You could also accomplish that by using a  wildcard
              expression, such as:

                   put *.zip

              This  command  is  similar to the behavior of other
              FTP programs' mput command.  To send a remote  file
              but  give it a different name on your host, you can
              use the ``-z'' flag.  This  example  shows  how  to
              upload  a  file  called ``ncftpd-2.0.6.tar.gz'' but
              name it remotely as ``NFTPD206.TGZ:''

                   put -z ncftpd-2.0.6.tar.gz NFTPD206.TGZ

              The program does not try to ``resume''  uploads  by
              default.   If  you do want to resume an upload, use
              the ``-z'' flag.

              There are also times where you want to append to an
              existing remote file.  You can do this by using the
              ``-A'' flag, for example

                   put -A log11.txt

              would append to a file named  ``log11.txt''  if  it
              existed on the remote server.

              Another  thing  you  can  do is delete a local file
              after you upload it.  Use the double-D  flag,  such
              as ``put -DD'' to do this.

              The  put  command  lets  you  send entire directory
              trees, too.  It should work on all remote  systems,
              so  you  can  try  ``put -R''  with  a directory to
              upload the directory and its contents.

       pwd    Prints the current  remote  working  directory.   A
              portion  of  the  pathname is also displayed in the
              shell's prompt.

       quit   Of course, when you finish using the program,  type
              quit  to  end  the program (You could also use bye,
              exit, or ^D).

       quote  This can be used to send a direct FTP Protocol com-
              mand  to  the  remote server.  Generally this isn't
              too useful to the average user.

       rename If you need to change the name of  a  remote  file,
              you can use the rename command, like:

                   rename SPHYGMTR.TAR sphygmomanometer-2.3.1.tar

       rhelp  Sends  a  help  request  to the remote server.  The
              list of FTP Protocol commands is often printed, and
              sometimes  some  other information that is actually
              useful, like how to reach the site administrator.

              Depending on the remote server, you may be able  to
              give a parameter to the server also, like:

                   rhelp NLST

              One server responded:

                   Syntax: NLST [ <sp> path-name ]

       rm     If you need to delete a remote file you can try the
              rm command.  Much  of  the  time  this  won't  work
              because  you  won't  have the proper access permis-
              sions.  This command doesn't accept any  flags,  so
              you  can't nuke a whole tree by using ``-rf'' flags
              like you can on UNIX.

       rmdir  Similarly, the rmdir command removes  a  directory.
              Depending  on the remote server, you may be able to
              remove a non-empty directory, so be careful.

       set    This lets you  configure  some  program  variables,
              which    are    saved    between    runs   in   the
              $HOME/.ncftp/prefs file.  The basic syntax is:

                   set <option> <value>

              For example, to change the value you  use  for  the
              anonymous password, you might do:

                   set anon-password

              See  the  next  section  for  a  list of things you

       show   This lets you display program variables.   You  can
              do  ``show all''  to display all of them, or give a
              variable name to just display that one, such as:

                   show anon-password

       site   One obscure command you may have to use someday  is
              site.   The  FTP  Protocol  allows  for ``site spe-
              cific'' commands.  These ``site'' commands vary  of
              course, such as:

                   site chmod 644 README

              Actually,  ncftp's  chmod  command  really does the

              Try doing one of  these  to  see  what  the  remote
              server supports, if any:

                   rhelp SITE
                   site help

       type   You  may  need  to change transfer types during the
              course of a session with a server.  You can use the
              type command to do this.  Try one of these:

                   type ascii
                   type binary
                   type image

              The  ascii command is equivalent to ``type a'', and
              the binary command is equivalent to ``type i''  and
              ``type b''.

       umask  Sets the process' umask on the remote server, if it
              has any concept of a umask, i.e.:

                   umask 077

              However, this is not a standard command, so  remote
              FTP servers may not support it.

              This  command dumps some information about the par-
              ticular edition of the program you are  using,  and
              how it was installed on your system.

              Specifies what to use for the password when logging
              in anonymously.  Internet convention  has  been  to
              use  your  E-mail address as a courtesy to the site
              administrator.  If you change this, be  aware  that
              some  sites  require (i.e. they check for) valid E-
              mail addresses.

              By default the program will ask you when a site you
              haven't  bookmarked is about to be closed.  To turn
              this prompt off, you can set this variable to no.

              Previous versions of  the  program  used  a  single
              timeout  value  for  everything.   You can now have
              different values for  different  operations.   How-
              ever, you probably do not need to change these from
              the defaults unless you have special  requirements.

              The  connect-timeout  variable controls how long to
              wait, in seconds, for a connection establishment to
              complete  before  considering it hopeless.  You can
              choose to not use a timeout at all by setting  this
              to -1.

              This is the timer used when ncftp sends an FTP com-
              mand over the  control  connection  to  the  remote
              server.   If the server hasn't replied in that many
              seconds, it considers the session lost.

       pager  This is the external program to use to view a  text
              file, and is more by default.

              This  controls  ncftp's  behavior  for data connec-
              tions, and can be set to one of  on,  off,  or  the
              default,  optional.  When passive mode is on, ncftp
              uses the FTP command primitive  PASV  to  have  the
              client  establish  data  connections to the server.
              The default FTP protocol behavior is to use the FTP
              command  primitive PORT which has the server estab-
              lish data connections to the client.   The  default
              setting  for  this variable, optional, allows ncftp
              to choose whichever method it deems necessary.

              You can change how the program reports file  trans-
              fer status.  Select from meter 2, 1, or 0.

              If  you  set this variable to yes, the program will
              save passwords along with the bookmarks  you  save.
              While  this  makes non-anonymous logins more conve-
              nient,  this  can  be  very  dangerous  since  your
              account   information   is   now   sitting  in  the
              $HOME/.ncftp/bookmarks file.  The passwords  aren't
              in  clear  text,  but it is still trivial to decode
              them if someone wants to make a modest effort.

              This timer controls  how  long  to  wait  for  data
              blocks to complete.  Don't set this too low or else
              your transfers will timeout without completing.

       You may find that your network administrator has placed  a
       firewall  between  your machine and the Internet, and that
       you cannot reach external hosts.

       The answer may be as simple as setting ncftp to  use  pas-
       sive  mode  only,  which  you  can do from a ncftp command
       prompt like this:

            set passive yes

       The reason for this is because many firewalls do not allow
       incoming  connections  to  the site, but do allow users to
       establish outgoing connections.  A passive data connection
       is  established  by  the client to the server, whereas the
       default is for the server to establish the  connection  to
       the client, which firewalls may object to.  Of course, you
       now may have  problems  with  sites  whose  primitive  FTP
       servers do not support passive mode.

       Otherwise,  if you know you need to have ncftp communicate
       directly with a firewall or proxy, you can try editing the
       separate  $HOME/.ncftp/firewall  configuration file.  This
       file is created automatically the first time you  run  the
       program,  and contains all the information you need to get
       the program to work in this setup.

       The basics of this  process  are  configuring  a  firewall
       (proxy)  host  to  go through, a user account and password
       for authentication on the  firewall,  and  which  type  of
       firewall  method  to use.  You can also setup an exclusion
       list, so that ncftp does not use the firewall for hosts on
       the local network.

              Information for background data transfer processes.

              Saves bookmark and host information.

              Firewall access configuration file.

              Program preferences.

              Directory where background jobs are stored  in  the
              form of spool configuration files.

              Debugging output for entire program run.

              Used to tell if this version of the program has run

       PATH   User's search path, used  to  find  the  ncftpbatch
              program, pager, and some other system utilities.

       PAGER  Program  to  use  to  view text files one page at a

       TERM   If the program was compiled with  support  for  GNU
              Readline it will need to know how to manipulate the
              terminal  correctly  for  line-editing,  etc.   The
              pager program will also take advantage of this set-

       HOME   By default, the program  writes  its  configuration
              data  in  a  .ncftp subdirectory of the HOME direc-

              If set, the program will use this directory instead
              of  $HOME/.ncftp.  This variable is optional except
              for those users whose home directory  is  the  root

              Both  the  built-in  ls command and the external ls
              command need this  to  determine  how  many  screen
              columns the terminal has.

       There  are  no  such  sites named or

       Auto-resume should check the file  timestamps  instead  of
       relying  upon  just the file sizes, but it is difficult to
       do this reliably within FTP.

       Directory  caching  and  recursive  downloads  depend   on
       UNIX-like behavior of the remote host.

       Mike Gleason, NCEMRSoft (

       ncftpput(1),  ncftpget(1),  ncftpbatch(1), ftp(1), rcp(1),

       LibNcFTP (

       NcFTPd (

       Thanks to everyone who uses the program.  Your support  is
       what drives me to improve the program!

       I  thank  Dale  Botkin  and  Tim Russell at my former ISP,
       Probe Technology.

       Ideas and some code contributed by my partner, Phil Dietz.

       Thanks to Brad Mittelstedt and Chris Tjon, for driving and
       refining the development of the backbone of this  project,

       I'd  like  to  thank my former system administrators, most
       notably Charles Daniel, for making testing on a variety of
       platforms possible, letting me have some extra disk space,
       and for maintaining the UNL FTP site.

       For testing versions 1 and 2 above and beyond the call  of
       duty,   I   am   especially   grateful   to:  Phil  Dietz,
       Kok Hon Yin, and Andrey A. Chernov (

       Thanks to Tim MacKenzie  (  for  the
       original  filename  completion  code for version 2.3.0 and

       Thanks to DaviD W. Sanderson (,  for  helping
       me out with the man page.

       Thanks to those of you at UNL who appreciate my work.

       Thanks to RedHat Software for honoring my licensing agree-
       ment, but more importantly, thanks for providing  a  solid
       and affordable development platform.

       To  the users, for not being able to respond personally to
       most of your inquiries.

       To Phil, for things not being the way they should be.

                            NCEMRSoft                           1