for the real current ncftp documentation see (http://www.ncftp.com
ncftp - Browser program for the File Transfer Protocol
ncftp [host]
ncftp [ftp://host.name/directory/]
ncftp provides 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 pro-
gram, which is transfer files between two interconnected systems.
Some of the cooler features include progress meters, filename completion, command-line editing, back-
ground processing, auto-resume downloads, 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 pro-
gram.
The program allows you to specify a host or directory URL on the command 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 (deprecated).
-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 sym-
bolic 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 spe-
cific 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 for-
mer is terse, preferring more remote files in less screen space, and the latter is more verbose, giv-
ing 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 com-
mand 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 com-
mands 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 settings for later. You can use the
bookmark command 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.
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 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. 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 accordingly. 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 trans-
fers 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 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 diffi-
cult 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 binary.
bookmark
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.
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 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 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.
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 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 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
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 containing 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 ncftp-
batch -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
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 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 username ââmario:ââ
open -u mario bowser.nintendo.co.jp
Here is a list of options available for use with the open command:
-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 program. This is useful for read-
ing 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 sys-
tems, 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 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 [ 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 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
VARIABLE REFERENCE
anon-password
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.
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 auto-
matically 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 bookmarks 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 automatically 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 seconds, for a connection estab-
lishment to complete before considering 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 primitive 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 number of seconds before trying
again. The smallest you can set this is to 10 seconds -- so if you were planning on being
inconsiderate, 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-anonymous 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-configured with them enabled.
xfer-timeout
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.
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 external 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 connections. A passive data connection is established by the
TERM If the program was compiled with support for GNU Readline it will need to know how to manipu-
late 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 sphygmomanometer.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 (http://www.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 filename 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 pro-
viding a solid and affordable development 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.