||FreeBSD General Commands Manual
ncftp - Browser program for the File Transfer Protocol
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
Some of the cooler features include progress meters, filename
completion, command-line editing, background processing, auto-resume
downloads, bookmarking, cached directory listings, host redialing, working
with firewalls and proxies, downloading entire directory trees, 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.
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:
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 ``184.108.40.206.'' To open a
connection to that system, you use the program's 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
- -P XX
- Use port number XX instead of the default FTP service port
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:
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:
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.
- The first command to know is help. If you just type
- 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:
- prints information about the open command.
- 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 immediately,
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 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. 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
- 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.
- 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
- 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.
- 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.
- 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:
- or, more concisely,
- 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:
- to change to the last directory you were in.
- Acts like the ``/bin/chmod'' UNIX command, only for remote files.
However, this is not a standard command, so remote FTP servers may not
- 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.
- This command is mostly for internal testing. You could type
- 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
- 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
- would try to act like
- would on UNIX.
- Downloads into a temporary file for editing on the local host, then
uploads the changed file back to the remote host.
- 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
- 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
- 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
- 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
- Views the list of currently executing NcFTP background tasks. This
actually just runs ncftpbatch -l for you.
- 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
- Runs ``/bin/chmod'' on the local host.
- 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:
lls -lrt p*.txt
- Runs ``/bin/mkdir'' on the local host.
- 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,
lookup cse.unl.edu ftp.cs.unl.edu sphygmomanometer.unl.edu
- There is also a more detailed option, enabled with ``-v,'' i.e.:
lookup -v cse.unl.edu ftp.cs.unl.edu
- You can also give IP addresses, so this would work too:
- Views a local file one page at a time, with your preferred $PAGER
- Prints the current local directory. Use this command when you forget where
you are on your local machine.
- Runs ``/bin/mv'' on the local host.
- Runs ``/bin/rm'' on the local host.
- Runs ``/bin/rmdir'' on the local host.
- 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
- would try to act like
- 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!
- Creates a new directory on the remote host. For many public archives, you
won't have the proper access permissions to do that.
- 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
- -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).
- 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
- 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.
- 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
- 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
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
- 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.
- Prints the current remote working directory. A portion of the pathname is
also displayed in the shell's prompt.
- Of course, when you finish using the program, type quit to end the
program (You could also use bye, exit, or ^D).
- 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.
- 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
- 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:
- One server responded:
Syntax: NLST [ <sp> path-name ]
- 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.
- Similarly, the rmdir command removes a directory. Depending on the
remote server, you may be able to remove a non-empty directory, so be
- 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
set anon-password firstname.lastname@example.org
- See the next section for a list of things you change.
- 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,
- 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
- 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
- The ascii command is equivalent to ``type a'', and the
binary command is equivalent to ``type i'' and
- Sets the process' umask on the remote server, if it has any concept
of a umask, i.e.:
- However, this is not a standard command, so remote FTP servers may not
- This command dumps some information about the particular edition of the
program you are using, and how it was installed on your system.
You may find that your network administrator has placed a firewall between your
machine and the Internet, and that you cannot reach external hosts.
- 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.
- 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 automatically 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.
- If set to a list of pipe-character delimited extensions, files with these
extensions will be sent in ASCII mode even if binary mode is currently in
effect. This option allows you to transfer most files in binary, with the
exception of a few well-known file types that should be sent in ASCII.
This option is enabled by default, and set to a list of common extensions
(e.g., .txt and .html).
- 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
- 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
- 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 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 command over the
control connection to the remote server. If the server hasn't replied in
that many seconds, it considers the session lost.
- 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.
- This is the external program to use to view a text file, and is
more by default.
- 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.
- You can change how the program reports file transfer status. Select from
meter 2, 1, or 0.
- 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
- 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.
- If set to yes and operating from within an xterm window, the
program will change the window's titlebar accordingly.
- 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.
- 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
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 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
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.
- Saves bookmark and host information.
- Firewall access configuration file.
- Program preferences.
- Debugging output for entire program run.
- Used to tell if this version of the program has run before.
- Directory where background jobs are stored in the form of spool
- Information for background data transfer processes.
There are no such sites named bowser.nintendo.co.jp or
- User's search path, used to find the ncftpbatch program, pager, and
some other system utilities.
- Program to use to view text files one page at a time.
- 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.
- By default, the program writes its configuration data in a .ncftp
subdirectory of the HOME directory.
- 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.
- Both the built-in ls command and the external ls command
need this to determine how many screen columns the terminal has.
Auto-resume should check the file timestamps instead of relying
upon just the file sizes, but it is difficult to do this reliably within
Directory caching and recursive downloads depend on
UNIX-like behavior of the remote host.
Mike Gleason, NcFTP Software (http://www.ncftp.com).
ncftpput(1), ncftpget(1), ncftpbatch(1), ftp(1),
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
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
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 (email@example.com).
Thanks to Tim MacKenzie (firstname.lastname@example.org) for the original
filename completion code for version 2.3.0 and 2.4.2.
Thanks to DaviD W. Sanderson (email@example.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
To the users, for not being able to respond personally to most of your
To Phil, for things not being the way they should be.
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.