ncftp
ncftp(1) ncftp(1)
NAME
ncftp - Browser program for the File Transfer Protocol
SYNOPSIS
ncftp [host]
ncftp [ftp://host.name/directory/]
DESCRIPTION
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 automatically 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, filename comple-
tion, command-line editing, background processing, auto-resume down-
loads, bookmarking, cached directory listings, host redialing, working
with firewalls and proxies, downloading entire directory trees, etc.,
etc.
The ncftp distribution comes with the useful utility programs
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.
OPTIONS
The program allows you to specify a host or directory URL on the com-
mand line. This is a synonym for running ncftp and then using the open
command. A few command-line flags are allowed with this mode:
-u XX Use username XX instead of anonymous.
-p XX Use password XX with the username.
-j XX Use account XX in supplement to the username and password (dep-
recated).
-P XX Use port number XX instead of the default FTP service port
(21).
INTRODUCTION TO THE COMMAND SHELL
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
filesystem. 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 ``typhoon.unl.edu,'' and its IP address could be
``129.93.33.24.'' To open a connection to that system, you use the
program's open command:
open typhoon.unl.edu
open 129.93.33.24
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 permission. 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 ``anonymous'' as
the account name, and when prompted for a password, 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 current 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 verbose, giving detailed
information about each item in the directory.
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 finish, 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 session's set-
tings for later. You can use the bookmark command to save an entry
into your $HOME/.ncftp/bookmarks file. When you use the bookmark com-
mand, 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.
COMMAND REFERENCE
help The first command to know is help. If you just type
help
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 use-
ful 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 charac-
ter and a line feed character. Therefore, 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 commands explained
below, except that they do the job in the background. Normally
when you do a get then the program does the download immedi-
ately, and does not return control to you until the download
completes. The background transfers are nice because you can
continue browsing the remote filesystem and even open other sys-
tems. 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. The daemon will also automatically continue to retry
the transfers until they finish. To tell when background jobs
have finished, you have to examine the $HOME/.ncftp/spool/log
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/q2_100.zip
bgstart
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 pro-
gram. 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 sys-
tem. 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 binary.
bookmark
Saves the current session settings for later use. This is use-
ful 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.
bookmarks
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 command 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 com-
mand 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 directory, 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 directory. 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 command, so remote FTP
servers may not support it.
close Disconnects you from the remote server. The program does this
for you automatically when needed, so you can simply open other
sites or quit the program 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 try:
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 reconnect to the FTP server and do another get on the same
file name and it would get the last 10 kilobytes, 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 ``-f'' 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 down-
load 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
contents.
jobs Views the list of currently executing NcFTP background tasks.
This actually just runs ncftpbatch -l for you.
lcd The lcd command is the first of a few ``l'' commands that work
with the local host. This changes the current working directory
on the local host. If you want to download files into a differ-
ent local directory, you could use lcd to change to that direc-
tory 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 window. You can use the same flags
with lls as you would in your command shell, so you can do
things like:
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:
lookup cse.unl.edu ftp.cs.unl.edu sphygmomanometer.unl.edu
prints:
cse.unl.edu 129.93.33.1
typhoon.unl.edu 129.93.33.24
sphygmomanometer.unl.edu 129.93.33.126
There is also a more detailed option, enabled with ``-v,'' i.e.:
lookup -v cse.unl.edu ftp.cs.unl.edu
prints:
cse.unl.edu:
Name: cse.unl.edu
Address: 129.93.33.1
ftp.cs.unl.edu:
Name: typhoon.unl.edu
Alias: ftp.cs.unl.edu
Address: 129.93.33.24
You can also give IP addresses, so this would work too:
lookup 129.93.33.24
prints:
typhoon.unl.edu 129.93.33.24
lpage Views a local file one page at a time, with your preferred
$PAGER program.
lpwd Prints the current local directory. Use this command when you
forget where you are on your local machine.
lrename
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'' command. 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 information 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 ``bowser.nintendo.co.jp'' using the user-
name ``mario:''
open -u mario bowser.nintendo.co.jp
Here is a list of options available for use with the open com-
mand:
-u XX Use username XX instead of anonymous.
-p XX Use password XX with the username.
-j XX Use account XX in supplement to the username and password
(deprecated).
-P XX Use port number XX instead of the default FTP service port
(21).
page Browses a remote file one page at a time, using your $PAGER pro-
gram. 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 respectively, 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 ``xx.zip'' and ``yy.zip''
in the remote directory, you could try:
put xx.zip yy.zip
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 command 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 Pro-
tocol commands is often printed, and sometimes some other infor-
mation that is actually useful, like how to reach the site
administrator.
Depending on the remote server, you may be able to give a param-
eter 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 permissions. 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 direc-
tory, 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 pass-
word, you might do:
set anon-password ncftp@ncftp.com
See the next section for a list of things you change.
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 specific'' commands. These
``site'' commands vary of course, such as:
site chmod 644 README
Actually, ncftp's chmod command really does the above.
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 con-
cept of a umask, i.e.:
umask 077
However, this is not a standard command, so remote FTP servers
may not support it.
version
This command dumps some information about the particular edition
of the program you are using, and how it was installed on your
system.
VARIABLE REFERENCE
anon-password
Specifies what to use for the password when logging in anony-
mously. 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.
auto-resume
NcFTP 3 now prompts the user by default when you try to download
a file that already exists locally, or upload a file that
already exists remotely. Older versions of the program automat-
ically guessed whether to overwrite the existing file or attempt
to resume where it left off, but sometimes the program would
guess wrong. If you would prefer that the program always guess
which action to take, set this variable to yes, otherwise, leave
it set to no and the program will prompt you for which action to
take.
autosave-bookmark-changes
With the advent of version 3 of NcFTP, the program treats book-
marks more like they would with your web browser, which means
that once you bookmark the site, the remote directory is static.
If you set this variable to yes, then the program will automati-
cally update the bookmark's starting remote directory with the
directory you were in when you closed the site. This behavior
would be more like that of NcFTP version 2.
confirm-close
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.
connect-timeout
Previous versions of the program used a single timeout value for
everything. You can now have different values for different
operations. However, 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 sec-
onds, for a connection establishment to complete before consid-
ering it hopeless. You can choose to not use a timeout at all
by setting this to -1.
control-timeout
This is the timer used when ncftp sends an FTP command over the
control connection to the remote server. If the server hasn't
replied in that many seconds, it considers the session lost.
logsize
This is controls how large the transfer log ($HOME/.ncftp/log)
can grow to, in kilobytes. The default is 200, for 200kB; if
you don't want a log, set this to 0.
pager This is the external program to use to view a text file, and is
more by default.
passive
This controls ncftp's behavior for data connections, 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 primi-
tive PORT which has the server establish data connections to the
client. The default setting for this variable, optional, allows
ncftp to choose whichever method it deems necessary.
progress-meter
You can change how the program reports file transfer status.
Select from meter 2, 1, or 0.
redial-delay
When a host is busy or unavailable, the program waits this num-
ber of seconds before trying again. The smallest you can set
this is to 10 seconds -- so if you were planning on being incon-
siderate, think again.
save-passwords
If you set this variable to yes, the program will save passwords
along with the bookmarks you save. While this makes non-anony-
mous logins more convenient, 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.
so-bufsize
If your operating system supports TCP Large Windows, you can try
setting this variable to the number of bytes to set the TCP/IP
socket buffer to. This option won't be of much use unless the
remote server also supports large window sizes and is pre-con-
figured with them enabled.
xfer-timeout
This timer controls how long to wait for data blocks to com-
plete. Don't set this too low or else your transfers will time-
out without completing.
FIREWALL AND PROXY CONFIGURATION
You may find that your network administrator has placed a firewall
between your machine and the Internet, and that you cannot reach exter-
nal hosts.
The answer may be as simple as setting ncftp to use passive mode only,
which you can do from a ncftp command prompt like this:
set passive on
The reason for this is because many firewalls do not allow incoming
connections to the site, but do allow users to establish outgoing con-
nections. A passive data connection is established by the client to
the server, whereas the default is for the server to establish the con-
nection 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 auto-
matically 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 fire-
wall, 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.
FILES
$HOME/.ncftp/bookmarks
Saves bookmark and host information.
$HOME/.ncftp/firewall
Firewall access configuration file.
$HOME/.ncftp/prefs
Program preferences.
$HOME/.ncftp/trace
Debugging output for entire program run.
$HOME/.ncftp/v3init
Used to tell if this version of the program has run before.
$HOME/.ncftp/spool/
Directory where background jobs are stored in the form of spool
configuration files.
$HOME/.ncftp/spool/log
Information for background data transfer processes.
ENVIRONMENT
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 time.
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 setting.
HOME By default, the program writes its configuration data in a
.ncftp subdirectory of the HOME directory.
NCFTPDIR
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 directory.
COLUMNS
Both the built-in ls command and the external ls command need
this to determine how many screen columns the terminal has.
BUGS
There are no such sites named bowser.nintendo.co.jp or sphygmomanome-
ter.unl.edu.
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.
AUTHOR
Mike Gleason, NcFTP Software (mgleason@ncftp.com).
SEE ALSO
ncftpput(1), ncftpget(1), ncftpbatch(1), ftp(1), rcp(1), tftp(1).
LibNcFTP (http://www.ncftp.com/libncftp).
NcFTPd (http://www.ncftp.com/ncftpd).
THANKS
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, LibNcFTP.
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
(ache@astral.msk.su).
Thanks to Tim MacKenzie (t.mackenzie@trl.oz.au) for the original file-
name completion code for version 2.3.0 and 2.4.2.
Thanks to DaviD W. Sanderson (dws@ora.com), for helping me out with the
man page.
Thanks to those of you at UNL who appreciate my work.
Thanks to Red Hat Software for honoring my licensing agreement, but
more importantly, thanks for providing a solid and affordable develop-
ment platform.
APOLOGIES
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.
Software NcFTP ncftp(1)
