ncftp
Hurricane Electric Internet Services
NAME
NcFTP -- Internet file transfer program
SYNOPSIS
ncftp [program options] [[open options] hostname[:path-
name]]
DESCRIPTION
NcFTP is a user interface to the Internet standard File
Transfer Protocol. This program allows a user to transfer
files to and from a remote network site, and offers addi-
tional features that are not found in the standard inter-
face, ftp.
FEATURES
Program options will be explained later in this document.
Let's get down to business and go over the features that
make this program worthwhile.
Here is the list of section headers; I have my $MANPAGER
environment variable set to use ``less -i'' so that I can
skip to the section I want (otherwise, /regex commands to
the pager won't match the section headers because of the
formatting codes; the ``-i'' can search through the for-
matting codes)
Establishing the remote connection
Format of the RC file
The Recent-sites file
Redialing a busy remote site
Supplying a sitename from your shell's command line
Using Colon-mode
Using FTP-cat and FTP-more mode
Supplying a port number with the open command
Displaying and changing program variables
Program variables
Listing a remote directory
Viewing a remote directory with your pager
Redisplaying the last directory listing
Fetching files from the remote host
Viewing a remote file with your pager
Creating a message file on the remote host
Looking up site names and addresses
Checking the configuration of the program
Using the command shell
Customizing the prompt
Keeping a log of your file transfers
Program options
A sample RC file
Establishing the remote connection
Just opening a connection to a remote server was inconve-
nient enough in the stock ftp program to justify writing
this program. Here at NCEMRSoft, we want to do our
business as quickly and painlessly as possible. We'd
rather save time and wear and tear on our metacarpals than
bother typing entire site names, usernames, and email
addresses masquerading as passwords, and setting binary
mode.
We made all connections anonymous by default, and we auto-
matically send our email address for the password on those
connections. We allowed for site names to be abbreviated.
For each commonly accessed site, you can put an entry in
your program preferences file (let's call it the ``ncftprc
file'' or ``RC file'' for short). To open the site, from
the command shell all you do is type:
open wuarchive.wustl.edu
or
o wuarchive.wustl.edu
As promised, you can abbreviate that further. Just use
any abbreviation that would match only the site you had in
mind. For the previous example, you could try:
o wuarc
o wustl
o stl
o wu
Any of those abbreviations would open wuarchive.wustl.edu
anonymously, sending your anon-password (usually set to
your email address) as the password. Keep in mind that
the program tries opening the first site that matches the
abbreviation you supplied. So:
o w
might match a site named bowser.nintendo.co.jp if that
site appeared before your entry for wuarchive.wustl.edu.
Most of the time we open remote sites anonymously, but
there are times where you need to specifically open a site
with an actual username and password. Let's say my part-
ner, Phil Dietz, wants to FTP something out of my account.
Perhaps he wants to fetch the latest version of the source
code to NcFTP so he can optimize something or add a new
feature behind my back. Since the program opens remote
sites anonymously by default (actually, you can change
this behavior; more on that later), he would have to spec-
ify a flag to the open command so he can supply my user-
name and password. He would try:
o -u sphygmomanometer.unl.edu
or, more likely:
o -u sph
Then the program would prompt him for a username (login,
whatever) and a password:
Login Name (pdietz): mgleason
Password: ********
If he got it right, he could raid my stuff. If not, he'd
probably drop me an email asking me to quit changing my
password so often.
There are even times where you want to FTP from your own
account, like if you are debugging an FTP client you
wrote. At this prompt:
Login Name (mgleason):
I could just hit return to tell the program that I want
``mgleason'' as my username, then I would enter my pass-
word.
Format of the RC file
This release of the program is somewhat compatible with
the stock ftp program's .netrc file. However, I can
promise you that in the near future the program will use a
new format, so don't invest too much time in it.
The RC file can be named ``ncftprc'', ``netrc'', or
``.ncftprc'', but it is usually named ``.netrc'' so it can
be used with the stock ftp program. NcFTP looks in the
current working directory for any of those files, and then
in your home directory, and after that it gives up (which
is OK, because RC files aren't mandatory).
The file usually starts with #set and #unset commands that
do things to the programs variables. The reason for the
``#'' is so the stock ftp program will think they are com-
ments. You might have this appearing as the first few
lines in your RC file (I'll explain later):
#set debug 1
#set pager "less -EMi"
#unset startup-msg
After those, you put in machine entries for each of your
favorite sites. Let's put in an entry for
wuarchive.wustl.edu. First you would put:
machine wuarchive.wustl.edu
Then you could put in your username, password, and account
if you like:
user anonymous
password -mgleason@cse.unl.edu
account wuarc.does.not.use.accounts
Following that, you would add the startup macro that is
run each time you connect to wuarchive. You must start it
with this line:
macdef init
Then put in the commands you want to do:
cd /graphics/gif
ls -lt
After that, you end the macro with a blank line (impor-
tant!). The finished machine entry would look like the
following. To make the transition to the impending new
format less painful, I recommend you adhere to this for-
mat:
machine wuarchive.wustl.edu
user anonymous
password -mgleason@cse.unl.edu
account wuarc.does.not.use.accounts
macdef init
cd /graphics/gif
ls -lt
(mandatory blank line to end the macro)
Of course, if all you want to do is open wuarchive anony-
mously, you needn't bother with the ``user'', ``pass-
word'', and ``account'' lines. You may want to put them
in if you plan on using the stock ftp program, though.
Try something like this:
machine wuarchive.wustl.edu
macdef init
cd /graphics/gif
ls -lt
(mandatory blank line to end the macro)
You can tell the program to not run the startup macro if
you supply -i to the open command.
Really, you should only bother adding entries for sites
that you want to run startup macros upon connection. The
next section explains why.
The Recent-sites file
Each time you open a site, the program saves the name of
the site and the last directory you were in to the recent-
sites file which is named .ncrecent and placed in your
home directory. The program saves a predetermined number
of these sites in the file, and when it reaches the limit,
it discards the oldest entry so it can add a new one.
You can just go ahead and use the name of the site you
want with the open command if you know it is in the
recent-file (and you can abbreviate the name, just like
those in the RC file). But if you cannot remember what
the name of the site you want, all you do is run the open
command with no site parameter:
open
This will pop up a list of the sites in the recent-file,
and sites in your RC file. At the open prompt, just type
the name (or an abbreviation of that name) or the number
preceding the site name to open that site. After opening
the site you wanted, the program sets the remote working
directory to the same one you left in the last time you
called.
If you don't like the idea of having the sites you called
stored on disk, you can turn this feature off using an
unset command, explained later.
Redialing a busy remote site
Some remote sites limit the number of leeches, er, anony-
mous connections at a time to reduce the load on the host
computer. You can use the open command's redial feature
to keep attempting connections until you get on, although
that is not a very polite thing to do. The simplest way
to do this would be to just supply the -r option:
open -r wuarc
There are also options you can use to tweak redial. The
-d flag sets the delay between dials, and the -g flag sets
a limit on how many dials should be attempting before giv-
ing up. If you don't supply -g the program will dial a
day and forever (which my Number Theory professor, Dr.
Mientka, says is longer than forever and a day) until it
connects successfully, or until you get sick of waiting
and hit the interrupt key (usually ^C).
This example dials wuarchive every ten minutes, giving up
after twenty attempts. Note that the redial delay is
specified in seconds:
open -r -d 600 -g 20 wuarc
Please be considerate when you use redialing, so you won't
tax the network. Site administrators can and do get angry
when they get flooded with connections.
Supplying a sitename from your shell's command line
When you run the program:
ncftp
by itself does nothing and waits for you to type commands
to the program's own shell. Just like the stock ftp pro-
gram, you can supply a site name on the command line:
ncftp wuarchive.wustl.edu
You can also use abbreviations as usual:
ncftp wuarc
This is equivalent to running the program, then issuing an
open command to open wuarchive.
Using Colon-mode
The open command is not a one-trick pony. Another option
is what I call colon-mode. This feature is used (most of
the time) from your shell's command line.
In ancient times, way back during the Disco era, you could
use a program called tftp to fetch a file using the Inter-
net standard Trivial File Transfer Protocol. You could
use that program to do something like this from within its
shell:
get wuarchive.wustl.edu:/graphics/gif/README
and that would call wuarchive and fetch the README file.
You can use this program to do the same thing from your
shell's command line:
csh> ncftp wuarchive.wustl.edu:/graphics/gif/README
csh> head README
This tells your shell, in this case the ``c-shell'' to run
NcFTP, which would open wuarchive, fetch /graph-
ics/gif/README and write the file ./README in the current
working directory, and then exits. This is nice if you
don't want to browse around the remote site, and you know
exactly want you want. It would also come in handy in
shell scripts, where you don't want to enter the command
shell, and might not want the program to spew output.
You can use colon-mode to set the starting remote working
directory also:
csh> ncftp wuarchive.wustl.edu:/graphics/gif
This would run the program, open wuarchive, and cd to the
gif directory, then run the program's command shell so you
can browse.
Colon-mode is also available from within the program's
command shell. At a prompt you can do stuff like this:
ncftp> open wuarchive.wustl.edu:/graphics/gif/README
ncftp> o wuarc:/graphics/gif
Using FTP-cat and FTP-more mode
There are times where you might not want the program to
write a colon-mode file in the current working directory,
or perhaps you want to pipe the output of a remote file
into something else. Colon-mode has options to do this.
It was inspired by the guy who wrote the ftpcat perl
script. The -c option tells the program to write on the
standard output stream. The -m option pipes the file into
your pager (like more) Of course this won't work if the
thing you give colon-mode is a directory! This example
just dumps a remote file to stdout:
csh> ncftp -c wuarc:/graphics/gif/README
...
csh>
This example redirects a remote file into a different
location:
csh> ncftp -c wu:/README > ~pdietz/thesis.tex
This one shows how to use a pipeline:
csh> ncftp -c wuarc:/README | tail | wc -l
10
csh>
This shows how to page a remote file:
csh> ncftp -m wuarc:/graphics/gif/README
...
csh>
Supplying a port number with the open command
This option just didn't fit anywhere else, so to finish
out the open command, -p lets you supply a port number if
you have to ftp to a site using an nonstandard port num-
ber. Personally, I have yet to use this feature, but it
is there for compatibility with the stock ftp program.
Displaying and changing program variables
Now I'll explain the commands unique to NcFTP. The others
should perform the same as they would in the stock ftp
program; consult the man page for it if you want those
explained, or use the help command for a brief blurb.
The show command is used to display program variables and
their values.
show all
or
show
would display all the variables with their values.
show var1 var2 ... varN
would display each specified variable and its value.
The set command changes the value of a program variable.
Its syntax is:
set varname value
For Boolean or Integer variables,
set varname
would set the value of the variable varname to 1 (true).
The unset command can be used to set the variable to its
default value, or for Boolean and Integer variables, set
the value of the variable to 0 (false). For String vari-
ables, you can use this to set the value to an empty
string.
You can use any of those three commands in both the com-
mand shell, or in the RC file with a ``#'' prepended.
Program variables
Each variable can be one of the following types:
Boolean:
Can be ``on'' or ``off'' (you can also use ``1'' or
``0'').
Integer:
Can be any positive or negative number, or 0.
String:
Is a string of characters. If the string needs to
have a space in it, make sure you surround the
whole string with double quotes in a set command.
Variables follow. Some variables are explained later in
the relevant sections.
anon-open (Boolean)
Tells whether the default login mode is anonymous
if on, or if off, will prompt for a username/pass-
word. You can always override this by using either
-a or -u with the open command.
anon-password (String)
Sends this as the password when you login anony-
mously. By default this is your email address.
ansi-escapes (Boolean)
If on, the program can use boldface, underline, and
inverse text.
auto-binary (Boolean)
If on, sets the transfer type to binary mode imme-
diately after connection.
debug (Integer)
Sets the debugging level.
gateway-login (String)
Tells which username to use when logging in to your
firewall gateway host.
gateway-host (String)
The site which is acting as your firewall gateway,
or empty if you aren't using one.
local-dir (String)
The current local working directory. I like to set
this from my RC file, so all my files go into my
download directory.
logfile (String)
The name of your personal transfer log, or empty if
you aren't using a transfer log.
logsize (Integer)
The maximum ceiling of your log file, before the
program removes old entries.
mprompt (Boolean)
If on, prompts for each remote file expanded from a
wildcard globbing expression.
netrc (String, Read-only)
Tells you the name of the RC file in use.
pager (String)
The pathname and flags of the program used to dis-
play output one screenful at a time. The default
is the value of your $PAGER environment variable.
prompt (String)
The prompt specification that expands into the
prompt.
progress-reports (Integer)
Which progress meter to use, or 0 if you don't want
progress reports during file transfers. Set it to
1 for a simple percentage meter; 2 for a fancy bar
graph indicator; 3 to print just the number of
kilobytes transferred; or 4 to print one dot for
each 10% transferred, if you want to avoid the use
of backspaces. Note that the program may use a
different meter depending on how cooperative the
remote host is, and what you have the ansi-escapes
variable set to.
recent-list (Boolean)
If on, uses and updates the recent-file.
remote-is-unix (Boolean)
Set automatically by the program upon connection,
you may need to use this in a startup macro if the
program guessed that a remote site was UNIX when it
really is not.
startup-msg (Boolean)
If on, prints the opening message and tip.
tips (Boolean)
If on, prints a tip on how to use the program bet-
ter each time you run the program.
type (String)
The name of the file transfer mode in use, such as
``binary'' or ``ascii''.
verbose (String/Integer)
Controls the amount of output spewed by the pro-
gram. You can supply either the first character of
the name of the verbosity level, or its number:
Quiet (-1)
Won't print any output at all, even if an
error occurs.
Errors Only (0)
No output, except when errors occur.
Terse (1)
Prints errors, and useful output from the
remote host.
Verbose (2)
Prints everything, even junk output from the
remote end.
Listing a remote directory
The ls and dir commands perform in a similar manner to
those of the stock ftp program.
The ls command sends the FTP command ``NLST'' for you.
This command has been set so that it defaults to always
listing files in columns (this is the -C option given to
the UNIX ls command) and appending metacharacters to each
item name (this is the -F option), so you can see which
items are directories, files, links, etcetera. If you
don't want your items columnized, you can try using the -1
option with ls to print one item per line.
The dir command sends the FTP command ``LIST'' for you,
which instead of printing just item names, it prints item
sizes, owners, dates, and permissions as well. This com-
mand is equivalent to ``ls -l'' on most remote systems.
The usage for both commands is the same. Here is the one
for ls:
ls [-flags] [directory and file names] [redirec-
tion]
Note that in this program, you can supply both flags and
items to list in the same command. The stock version of
ftp doesn't let you do this:
ls -lrt /info-mac/help
Another thing that the program does which the others
should have done is let you supply more than one item:
ls -lrt /info-mac/help /pub /info-mac/README
You can also redirect the output into a file, or pipe it
into something. This example shows how to list the con-
tents of the current remote directory, and save the output
into a file in the current local directory:
ls -t >ls.out
Note that for this to work, there must be no whitespace
between the ``>'' and the filename, unlike your shell com-
mand line which allows for extra whitespace. This will be
(actually, is) fixed in a future version of the program.
These examples show how to use a pipe:
ls -t |tail
dir -t "|less -CM"
ls -t "|tail | wc"
Like the redirection example, there must be no whitespace
between the first pipe character and the rest of the
stuff. The trick is that it has to appear as one argument
to the commands. The second and third examples illustrate
the use of double quotes to squeeze extra parameters in.
The second example can be done without all that typing.
See the descriptions of the pdir and pls commands below.
Viewing a remote directory with your pager
Didn't you hate it when you listed a remote directory,
only to have most of the stuff scrolled off your terminal
before you could read it? The pls and pdir commands take
care of this for you. As you might have guessed, they
perform exactly like their regular counterparts, only you
view them with your pager. The pager to use is controlled
by the pager program variable.
Redisplaying the last directory listing
The program saves the listing into a local buffer, so if
you need to see it again (probably forgot about pdir) you
can use the redir and predir commands for this.
Fetching files from the remote host
The get and mget retrieve remote files for you. The usage
for get is:
get remote-file [local-file or redirection]
To fetch /pub/README and write it as a file named
./junk/readme, try:
get /pub/README ./junk/readme
To fetch /pub/README and write it as ./README, just do:
get /pub/README
This lets you fetch a file using its whole pathname, and
write a copy of it in the current directory, without hav-
ing to bother with typing a local filename. In the
unlikely event that you have write permission to a direc-
tory called /pub on your local machine, it would write
``README'' in that directory.
Most of the time the file you want will be in the current
remote directory, so you can just do these:
get README
get README ./junk/readme
You can also use a redirection for get, just like you can
with the ls, dir, and redir commands. As described ear-
lier, you have to conform to the format below for this
release of the program:
get README >/dev/null
get README |head
get README "|head -8"
get README "|less -EMi"
The last example is facilitated by the page command
described later.
The get command can also use a wildcard expression in an
attempt to match exactly one remote file. I call it
``Poor Man's File Completion.'' If you've done a remote
listing, and you decide you want to download a file by the
name of ``obnoxiouslylongpackagename.tar.Z'', you can use
``PMFC'' to save some keystrokes. Choose an expression
that will only match that one file, then use it with get:
get obn*.Z a.tar.Z
If your pattern was unique, get will fetch that file only.
If the pattern matched more than one file, the program
will bitch and moan.
The mget command is used to fetch many files at a time.
The difference between get and mget is that get lets you
write only one file, but you can put it in a different
directory, while mget fetches many files, always writing
them in the current local directory. This example fetches
several remote files at once:
mget a.file.Z b.file.Z c.tar d.tar.Z
The mget command, and its ugly sisters, mput and mdelete
let you use wildcard expressions. I could have done the
previous example as:
mget *.Z c.tar
instead. The ``m'' commands will verify each file, if you
have the program variable mprompt set.
Viewing a remote file with your pager
If you would like to read a file on the remote host with-
out saving a copy of it on your machine, you can use the
page (or more if you wish) command:
page README
page obn*README
page README.Z
The second example show that you can use ``PMFC'' like you
can for get. The third example will work also, because if
the program knows how to decompress the file, it will do
so before feeding it to your pager. As stated earlier,
you can change the program to use to page by setting the
program variable pager.
Creating a message file on the remote host
Use the create an empty file on the remote site. Some-
times it is necessary to leave a note if you can't get in
touch with the remote site's administrator. For example
if a file is corrupted, you could try:
create Foo.tar_is_corrupt
in hopes that the original uploader will replace it.
Looking up site names and addresses
You can use the program's builtin mini-nslookup facility.
If you wanted to know the site's IP number, but only knew
the name you could do:
lookup cse.unl.edu
This would spit out IP number for that site, in this case
``129.93.1.12''. If you needed to know what a site's name
was, but only knew the IP number, try:
lookup 129.93.1.12
This would spit out the name for that site, in this case
``cse.unl.edu''.
Checking the configuration of the program
Use the version command to print version and compilation
information about the program. This will also tell you
which optional features are compiled into the program,
such as logging to the system log and which command line
editor (if any) has been installed.
The author's email address is listed, and if you need to
report something, send the output of this command along
with your message.
Using the command shell
Just like the stock ftp program, you type commands to it
until you get bored and hit either ^D or type the quit
command.
The program supports links to popular command line editing
libraries. If the person who compiled it went to the
effort, you will be able to edit the command line with
arrow keys and other editing commands, and also scroll up
and down in the command line history, usually with the up
and down arrows. You can check the version command to see
if either ``GETLINE'' or ``READLINE'' are installed.
Customizing the prompt
You can set the shell's prompt string to whatever you
like. You can use several metacharacters that expand into
something each prompt. The ``%'' flags are passed to
strftime(3), so you can put the date or time in the prompt
formatted as you like it:
set prompt "%I:%M ncftp>"
That would insert the current time in the prompt.
The ``@'' flags are expanded by the program itself.
Here's the list of them.
If you have an ANSI-compatible terminal, or you have the
program variable ansi-escapes set, you can use @B, @I, and
@U to turn on boldface, inverse, and underline text
respectively (otherwise they won't insert anything). You
can also use @R to turn on inverse (reverse) text. @P
sets the text back to plain text.
@D Inserts the full path of the current remote directory.
The @J flag is similar except it inserts only the direc-
tory name.
@H Inserts the name of the remote host. @C inserts the
host and current directory path in colon-mode format, such
as ``cse.unl.edu:/pub/mgleason'', or ``(not connected)''.
The @c flag is similar, only it will insert
``cse.unl.edu:/pub/mgleason'' and a newline if connected,
otherwise it prints nothing. The default prompt uses this
flag to print a two line prompt when connected and a one
line prompt when not connected.
@E or @! inserts the event number (how many commands
you've typed).
@M inserts ``(Mail) '' if mail has arrived since running
the program.
@N inserts a newline character.
Keeping a log of your file transfers
You can have the program keep a personal log file. I find
it is useful so I can see where I got a certain file, or
what the name of that site was I called two weeks ago.
To use a log, add:
#set logfile ~/.ftplog
(or whatever you want to name the log) to your RC file. I
don't want my log growing too large and using up all my
disk space, so I also have:
#set logsize 10240
in my RC file. If you set the limit on the maximum log
size, the program will keep the log file at or below that
size, discarding old entries.
Note that this is different from having SYSLOG appear in
the version command's output. When this is on, your
actions are recorded to the system log, so your system
administrator can make sure you aren't doing anything
``bad.''
Program options
Remember that you can treat the command line like an open
command, so all lowercase options are passed to the open
command, and the uppercase options are handled by the main
program. The uppercase options are described below; refer
to the open command for descriptions of its options.
-D x sets the debugging level to x.
-H runs the version command and exits, so you can save
the output of it to use when you need to mail me
something.
-I toggles the mprompt variable; this is provided for
compatibility with ``ftp -i''.
-N disables reading of the RC file; this is provided
for compatibility with ``ftp -n''.
-V x sets verbosity to level x (-1, 0, 1, 2) or (quiet,
errs, terse, verbose). See the description of the
verbose program variable for more information.
Here are some example command lines. Again, see the
description of the open command (especially colon-mode and
FTP-cat mode) and all its functions for more information.
This just enters the NcFTP command shell:
csh> ncftp
This fetches CONTENTS and then quits:
csh> ncftp cse.unl.edu:/pub/mgleason/CONTENTS
Some others examples, with open options and main program
options mixed in:
csh> ncftp -V quiet -u ftp.unl.edu
csh> ncftp -c cse.unl.edu:/pub/mgleason/CONTENTS
csh> ncftp -D 2 -r -d 120 -g 10 -N ftp.unl.edu
A sample RC file
Here is a sample RC file:
#set logfile ~/.ftplog
#set progress-reports 2
#set local-dir /usr/tmp/zz
#set prompt "@B@E @UNcFTP@P @B@M@D@P ->"
machine sumex-aim.stanford.edu
macdef init
cd /info-mac
get ./help/recent-files.txt "|grep -v '.abs' > sumex"
!less sumex
pwd
# This site is in here just so I can use ``apple''
# as an abbreviation.
machine ftp.apple.com
# NcFTP will only ask for your password:
machine cse.unl.edu
login mgleason
# You can supply a login and a password:
machine fake.machine.unl.edu
login mgleason
password mypass
macdef init
cd ./foo/bar
# If an antiquated non-UNIX machine doesn't use
# the "SYST" command, you may need to unset
# remote-is-unix, if the remote host complains
# about ``ls -CF''.
machine some.vms.unl.edu
macdef init
unset remote-is-unix
AUTHORS
NcFTP was written by Mike Gleason, NCEMRSoft (mglea-
son@cse.unl.edu), and based on code by the authors of the
ftp from the BSD 4.3 distribution. NcFTP is copyrighted
1992, 1993 by NCEMRSoft and 1985, 1989 by the Regents of
California.
Ideas and some code contributed by Phil Dietz, NCEMRSoft
(pdietz@cse.unl.edu). Testing and debugging done by Phil
and Kok Hon Yin (hkok@cse.unl.edu).
Extensive man page formatting work by DaviD W. Sanderson
(dws@ssec.wisc.edu).
BUGS
Correct execution of many commands depends upon proper
behavior by the remote server.
The remote server may drop the connection if you take a
long time to page remote files.
Termcap padding is not correctly displayed.
There are no such sites named bowser.nintendo.co.jp or
sphygmomanometer.unl.edu.
SEE ALSO
strftime(3), ftpd(8), ftp(1), nslookup(1), compress(1),
gzip(1), zcat(1), fsp(1), archie(1), tftp(1).
Hurricane Electric Internet Services
Copyright (C) 1998
Hurricane Electric.
All Rights Reserved.