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, youll 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 programs shell. Usually you will want to open a
remote filesystem to transfer files to and from your local machines
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
programs 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 Protocols 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 accounts files. However, most remote systems that
have anything you might be interested in dont 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 systems 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
whats in the current remote directory, you can use the programs 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 programs 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 programs 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
programs command shell.
You can use the programs 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 sessions 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 youve 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 doesnt 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
UNIXs /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.
edit Downloads into a temporary file for editing on the local host,
then uploads the changed file back to the remote host.
get Copies files from the current working directory on the remote
host to your machines 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.
When using the -R flag, you can also use the -T flag to
disable automatic on-the-fly TAR mode for downloading whole
directory trees. The program uses TAR whenever possible since
this usually preserves symbolic links and file permissions. TAR
mode can also result in faster transfers for directories con
taining many small files, since a single data connection can be
used rather than an FTP data connection for each small file. The
downside to using TAR is that it forces downloading of the whole
directory, even if you had previously downloaded a portion of it
earlier, so you may want to use this option if you want to
resume downloading of a directory.
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 programs 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 UNIXs /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 wont 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 READMEs 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 machines 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 shells 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 isnt 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 [ path-name ]
rm If you need to delete a remote file you can try the rm command.
Much of the time this wont work because you wont have the
proper access permissions. This command doesnt accept any
flags, so you cant 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
