home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Columbia Kermit
/
kermit.zip
/
pub
/
public_html
/
ftpdoc.old
< prev
next >
Wrap
Text File
|
2020-01-01
|
107KB
|
2,219 lines
<html><head>
<title>The Kermit FTP Client</title>
</head><body>
<h1><a name="top"><tt>3. The Kermit FTP Client</tt></a></h1>
<p>
<big><tt><b>D R A F T</b></tt></big>
<p>
<tt> </tt><i>As of:</i> <b>C-Kermit 7.1.199 Alpha.01</b><br>
<tt> </tt><i>This file last updated:</i> <b>14 December 2000</b>
<p>
<tt> </tt>Copyright © 2000, Frank da Cruz and Christine M. Gianone.<br>
<tt> </tt>All rights reserved.
<p>
<b>C-Kermit 7.1 includes a new built-in FTP client.</b>
This documant, which was extracted from the
<a href="ftp://kermit.columbia.edu/kermit/test/text/ckc71.txt">
C-Kermit 7.1 update notes</a> and converted to HTML for easy reading on
the Web, contains preliminary FTP client documentation, pending
publication of the next edition of <a href="ck60manual.html"><cite>Using
C-Kermit</cite></a>. Familiarity with C-Kermit usage and commands is assumed.
Section numbering is based on the original plain-text document.
<p>
<tt> </tt> <a href="#x3.1"><b>3.1. Making and Managing FTP Connections</b></a><br>
<tt> </tt> <tt> </tt> <a href="#x3.1.1">3.1.1. Kermit Command-Line Options for FTP</a><br>
<tt> </tt> <tt> </tt> <a href="#x3.1.2">3.1.2. The FTP Command-Line Personality</a><br>
<tt> </tt> <tt> </tt> <a href="#x3.1.3">3.1.3. The FTP URL Interpreter</a><br>
<tt> </tt> <tt> </tt> <a href="#x3.1.4">3.1.4. Interactive FTP Session Establishment</a><br>
<tt> </tt> <a href="#x3.2"><b>3.2. Making Secure FTP Connections</b></a><br>
<tt> </tt> <a href="#x3.3"><b>3.3. Setting FTP Preferences</b></a><br>
<tt> </tt> <a href="#x3.4"><b>3.4. Managing Directories and Files</b></a><br>
<tt> </tt> <a href="#x3.5"><b>3.5. Uploading Files With FTP</b></a><br>
<tt> </tt> <tt> </tt> <a href="#x3.5.1">3.5.1. FTP PUT Switches</a><br>
<tt> </tt> <tt> </tt> <a href="#x3.5.2">3.5.2. Update Mode</a><br>
<tt> </tt> <tt> </tt> <a href="#x3.5.3">3.5.3. Recovery</a><br>
<tt> </tt> <a href="#x3.6"><b>3.6. Downloading Files With FTP</b></a><br>
<tt> </tt> <tt> </tt> <a href="#x3.6.1">3.6.1. FTP GET Switches</a><br>
<tt> </tt> <tt> </tt> <a href="#x3.6.2">3.6.2. Filename Collisions</a><br>
<tt> </tt> <tt> </tt> <a href="#x3.6.3">3.6.3. Recovery</a><br>
<tt> </tt> <a href="#x3.7"><b>3.7. Translating Character Sets</b></a><br>
<tt> </tt> <tt> </tt> <a href="#x3.7.1">3.7.1. Character Sets and Uploading</a><br>
<tt> </tt> <tt> </tt> <a href="#x3.7.2">3.7.2. Character Sets and Downloading</a><br>
<tt> </tt> <a href="#x3.8"><b>3.8. FTP Command Shortcuts</b></a><br>
<tt> </tt> <a href="#x3.9"><b>3.9. Dual Sessions</b></a><br>
<tt> </tt> <a href="#x3.10"><b>3.10. Automating FTP Sessions</b></a><br>
<tt> </tt> <tt> </tt> <a href="#x3.10.1">3.10.1. FTP-Specific Variables and Functions</a><br>
<tt> </tt> <tt> </tt> <a href="#x3.10.2">3.10.2. Examples</a><br>
<tt> </tt> <a href="#x3.11"><b>3.11. Advanced FTP Protocol Features</b></a><br>
<p>
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.1">3.1. Making and Managing FTP Connections</a></h3>
Each copy of Kermit can have one FTP connection open at a time. FTP
connections are independent of regular Kermit connections; a Kermit connection
(serial or network via SET LINE, DIAL, SET HOST, TELNET, etc) may be, but need
not be, open at the same time as an FTP connection, and Kermit connections can
also be closed, and new connections opened, without interfering with the FTP
connection (and vice versa). Thus, for example, Kermit can have an FTP
connection and a TELNET connection open to the same host simultaneously, using
the TELNET connection (e.g.) to send mail or take other desired actions as
various FTP actions complete. Of course, each copy of Kermit can do only one
thing at a time, so it can't (for example) transfer a file with FTP and
another file with Kermit protocol simultaneously.
<p>
A Kermit FTP session can be established by
<a href="#x3.1.1">command-line options</a>, by
<a href="#x3.1.3">URL</a>, or by
<a href="#x3.1.4">interactive commands</a>.
<h3><a name="x3.1.1">3.1.1. Kermit Command-Line Options for FTP</a></h3>
The new command-line option '<tt>-9</tt>' (sorry, we're out of letters) can be
used when starting C-Kermit, telling it to make an FTP connection:
<p><pre>
kermit -9 hostname
</pre><p>
or if a non-default FTP port is needed:
<p><pre>
kermit -9 hostname:port
</pre><p>
You can also specify the username on the command line with the <tt>-M</tt>
("My User ID") option that was already there for other connection types:
<p><pre>
kermit -9 hostname -M olga
</pre><p>
If you specify the username on the command line, Kermit uses it when making
the connection and does not prompt you for it (but it does prompt you for
the password if one is required).
<p>
Once the connection is made, you get the regular Kermit prompt, and can give
interactive commands such as the ones described below. When you give a BYE
command, Kermit closes the session and exits, just as a regular FTP client
would do. If you don't want Kermit to exit when you give a BYE command,
include the <tt>-S</tt> ("Stay") option on the command line.
<p>
Other Kermit command-line options that are not specific to non-FTP connections
should affect the FTP session in the expected ways; for example, <tt>-i</tt>
and <tt>-T</tt> force binary and text mode transfers, respectively.
<p>
File transfers can not be initiated on the "<tt>kermit</tt> <tt>-9</tt>"
command line; for that you need to use Kermit's FTP personality (next section).
<p>
<h3><a name="x3.1.2">3.1.2. The FTP Command-Line Personality</a></h3>
<p>
If you want to replace your regular FTP client with C-Kermit, you can make
a link called "ftp" to the C-Kermit binary (or you can store a copy of the
C-Kermit binary under the name "ftp"). When C-Kermit is invoked with a
program name of "ftp" (or "FTP", case doesn't matter), it assumes the
command-line personality of the regular FTP client:
<p><pre>
ftp <i>[ options ] hostname [ port ]</i>
</pre>
<p>
In this case the options are like those of a regular FTP client:
<p><pre>
-d Debug: enables debug messages and creates a debug.log file.
-n No autologin: Kermit should not send your user ID automatically.
-t Packet trace: accepted but is treated the same as -d.
-v Verbose: accepted but ignored (operation is verbose by default).
-i Not interactive: accepted but ignored.
</pre><p>
and the hostname can also be a URL (explained in
<a href="#x3.1.3">Section 3.1.3</a>). To specify a
non-default TCP port for the FTP server, include the port number or name after
the hostname.
<p>
There are also some bonus options that allow you to execute an entire FTP
session from the shell command line, as long as you don't include the
<tt>-n</tt> option. These are not available with regular FTP clients, and at
least one of these options (<tt>-g</tt>) conflicts with UNIX ftp (where
<tt>-g</tt> means "no globbing", which does not apply to Kermit), and some of
them (like the options above) also conflict with regular Kermit command-line
options:
<p>
<pre>
-Y Don't execute the Kermit initialization file [1]
-q Quiet, suppresses all but error messages [1]
-S Stay, don't exit automatically [1]
-A Autologin anonymously [2]
-u name Username for autologin [2] (synonym: -M [1])
-P password Password for autologin (see cautions below) [2]
-D directory cd after autologin [2]
-b Binary mode [2]
-a Text ("ascii") mode [2] (synonym: -T [1])
-p files Files to put (upload) after autologin [2] (synonym: -s [1])
-g files Files to get (download) after autologin [3]
</pre><p>
<tt>[1] </tt>Same as Kermit, not available in regular FTP clients.<br>
<tt>[2] </tt>Conflicts with Kermit, not available in regular FTP clients.<br>
<tt>[3] </tt>Same as Kermit, conflicts with regular FTP clients.<br>
<p>
Fancier options such as restart, character-set translation, filename collision
selection, automatic move/rename/delete, etc, are not available from the
command line; for these you can use the commands described in the following
sections.
<p>
The following security options are also available, explained in
<a href="#x3.2">Section 3.2</a>:
<p><pre>
-k realm Kerberos 4 realm [2]
-f Kerberos 5 credentials forwarding [2]
-x autoencryption mode [2]
-c cipher SRP cipher type [2]
-H hash SRP encryption hash [2]
-z option Security options [2]
</pre>
<p>
If you include <tt>-A</tt> or specify a name of "anonymous" or "ftp", you are
logged in anonymously and, in the absence of <tt>-P</tt>, Kermit automatically
supplies a password of "<i>user</i><tt>@</tt><i>host</i>", where "user" is
your local user ID, and "host" is the hostname of the computer where Kermit is
running. If you do not include <tt>-p</tt> or <tt>-g</tt>, Kermit enters
command mode so you can type commands or execute them from a script.
<p>
If you include <tt>-p</tt> or <tt>-g</tt>, Kermit attempts to transfer the
specified files and then exits automatically at the end of the transfer unless
you also included <tt>-S</tt> (Stay). It uses the "brief" file transfer
display (one line per file) unless you include the <tt>-q</tt> option to
suppress it.
<p>
When uploading files with <tt>-p</tt>, Kermit switches automatically between
text and binary mode for each file.
<p>
When downloading, you should always specify the desired mode, and there is no
per-file mode switching (see <a href="#x3.5">Sections 3.5</a> and
<a href="#x3.6">3.6</a> for greater detail). In
UNIX be sure to quote any wildcard characters to prevent the shell from
expanding them. Filename collisions are handled according Kermit's FILE
COLLISION setting (if specified in your Kermit customization file; otherwise
the default, which is BACKUP).
<p>
It should go without saying that the <tt>-P</tt> option should be used with
caution. In addition to the well-known risks of transmitting plaintext
passwords over the Internet, in this case the password also echos to the
screen if you type it, and can be seen in <tt>ps</tt> and <tt>w</tt> listings
that show the user's currently active command and command-line arguments.
Thus command-line FTP sessions are most appropriate for secure or anonymous
connections.
<p>
Here's an example in which you download the latest C-Kermit "tarball" from
the Columbia University FTP archive:
<p><pre>
ftp -A kermit.columbia.edu -bg kermit/archives/ckermit.tar.gz
</pre><p>
This assumes that "ftp" is a symbolic link to C-Kermit. It logs you in
anonymously and gets the <tt>ckermit.tar.gz</tt> file in binary mode from the
<tt>kermit/archives</tt> directory.
<p>
Here's a slightly more ambitious example that illustrates CD'ing to the
desired server directory to get a group of files in text mode (in this case
the C-Kermit source files):
<p><pre>
ftp -A kermit.columbia.edu -D kermit/f -ag "ck[cuw]*.[cwh]" makefile
</pre>
<p>
In this case we CD to the <tt>kermit/f</tt> directory so we don't have to
include it in each file specification, and we quote the
<tt>ck[cuw]*.[cwh]</tt> specification so the shell doesn't expand it, since we
have to pass it as-is to the server. Note also that the quotes don't go
around the entire file list; only around each file specification that needs to
be quoted.
<p>
Here's one more example, that uploads a debug log file in binary mode to the
Kermit incoming directory (as we might ask you to do when following up on a
problem report):
<p>
<pre>
ftp -A kermit.columbia.edu -D kermit/incoming -bp debug.log
</pre><p>
In this case the <tt>-D</tt> option is required to tell the server where to
put the incoming file.
<p>
Unless the <tt>-Y</tt> option is included, your Kermit initialization file
(<tt>.kermrc</tt> in UNIX, <tt>K95.INI</tt> in Windows) is executed before the
command line options, so you can set any FTP-related preferences there, as
described in the subsequent sections.
<h3><a name="x3.1.3">3.1.3. The FTP URL Interpreter</a></h3>
<dl>
<dt>If Kermit is invoked with its FTP personality, you can also give a URL
(Universal Resource Locator) instead of a hostname and options, with or
without a username and password:</dt>
<dd><tt>ftp ftp://<i>user</i>:<i>password</i>@<i>host</i>/<i>path</i></tt><br>
<tt>ftp ftp://<i>user</i>@<i>host</i>/<i>path</i></tt><br>
<tt>ftp ftp://<i>host</i>/<i>path</i></tt>
</dl>
<p>
The service must be "ftp" and a hostname or address must be included. If a
user is included but no password, you are prompted for the password. If a
path (filename) is included:
<p><ul>
<li>If no user is included, "anonymous" is used.
<li> GET is assumed.
</ul>
<p>
<dl>
<dt>If no path (and no action options) are included, an interactive FTP
session is started, as in this example:</dt>
<dd><tt>ftp ftp://kermit.columbia.edu/</tt>
</dl>
<p>
If a path is included, but a username is not included, "anonymous" is used and
an appropriate <i>user</i><tt>@</tt><i>host</i> password is supplied
automatically. If authentication is successful, Kermit attempts to GET the
file indicated by the path or, if the path is the name of a directory, it asks
the server for a directory listing. In both cases, Kermit disconnects from
the server and exits after the operation is complete (unless you have included
the <tt>-S</tt> option on the command line).
<p>
<dl>
<dt>Here's an example that gets a listing of the top-level directory at the
Kermit ftp site:</dt>
<dd><tt>ftp ftp://kermit.columbia.edu/kermit/</tt>
<p>
<dt>This example gets the top-level <tt>READ.ME</tt> file from the same directory:</dt>
<dd><tt>ftp ftp://kermit.columbia.edu/kermit/READ.ME</tt>
<p>
<dt>Here's the same example, but requesting a text-mode transfer:</dt>
<dd><tt>ftp -T ftp://kermit.columbia.edu/kermit/READ.ME</tt><br>
This illustrates that you can mix command-line options and URLs if you desire.
<p>
<dt>Here's an example that logs in as a (fictitious) real user to get a file:</dt>
<dd><tt>ftp ftp://olga@ftp.xyzcorp.com/resume.txt</tt><br>
The password is not included, so Kermit prompts for it.
</dl>
<h3><a name="x3.1.4">3.1.4. Interactive FTP Session Establishment</a></h3>
As you read this and the following sections, bear in mind that any command
that can be given at the prompt can also be used in a script program.
Kermit's script programming language is the same as its interactive command
language. <a href="ftpscript.html">CLICK HERE</a> if you would like to learn
a bit more about script writing.
<p>
An FTP session is established with the FTP OPEN command:
<p><dl>
<dt><tt><b>FTP</b> <i>[</i> <b>OPEN</b> <i>] hostname [ switches ] [ port ]</i></b></tt></dt>
<dd>Opens an FTP connection to the given host on the given port and, if FTP
AUTOLOGIN is ON, also logs you in to the server, prompting for username and
password if necessary. If no port is specified, the regular FTP protocol
port (21) is used. The OPEN keyword is optional (unless the hostname
conflicts with one of the FTP command keywords, which you can list
by typing "<tt>ftp</tt> <tt>?</tt>").
</dl>
<p>
The hostname can be an IP host name, numeric IP address, or if you have a
network directory active (SET NETWORK DIRECTORY; see
<a href="ck60manual,html"><cite>Using C-Kermit</cite></a>), an
entry name in the directory. In the latter case, if the given hostname
matches exactly one entry, the associated name or address is used; if it
matches more than one, Kermit cycles through them until one is found that can
be opened; if it matches none, then the hostname is used as-is. If a
directory is active but you want to bypass directory lookup, include an "="
sign at the beginning of the hostname, and/or use a numeric IP address.
<p>
When an FTP connection is opened, the default file-transfer mode is set to
binary if the client and server platforms are alike (e.g. both of them are
some kind of UNIX), and to text ("ascii") if they are not alike. This has
no particular effect for uploading since Kermit automatically switches between
text and binary mode for each file, but is important for downloading.
The connection is also set to Stream mode and File structure. Record- or
page-oriented file transfers are not supported by C-Kermit's FTP client.
<p>
The optional FTP OPEN switches are:
<p><dl>
<dt><tt><b>/ANONYMOUS</b></tt></dt>
<dd>Logs you in anonymously, automatically supplying username "anonymous"
and <i>user</i>@<i>host</i> as the password, based on your local user and
host names.
<p>
<dt><tt><b>/USER:</b><i>name</i></tt></dt>
<dd>Uses the given username to log you in, thus avoiding the Name: prompt.
<p>
<dt><tt><b>/PASSWORD:</b><i>text</i></tt></dt>
<dd>Uses the given text as your password, thus avoiding the Password: prompt.
This switch is not recommended for use in script files, which would be a
security risk.
<p>
<dt><tt><b>/ACCOUNT:</b>text</i></tt></dt>
<dd>Uses the given text as your account (or secondary password, depending on
the requirements of the server; most servers do not require or accept an
account name). If an account is not supplied, you are not prompted for
one.
</dl><p>
When a username or password is missing, a prompt is issued at the controlling
terminal and you must type the response; the response can not be scripted.
Use the switches to avoid prompts, or one of the secure authentication methods
described in the next section, or see SET FTP AUTOLOGIN and the FTP USER and
similar commands described later in this section.
<p>
Examples:
<p><pre>
ftp open kermit.columbia.edu /anonymous ; Open and log in anonymously
ftp kermit.columbia.edu /anonymous ; The OPEN keyword can be omitted
ftp xyzcorp.com ; Open and maybe prompt for username
ftp xyzcorp.com /user:olga ; Open and log in as olga
ftp testing.abccorp.com 449 ; Specify a special TCP port number
ftp testing.abccorp.com /user:olaf /password:secret 449
</pre><p>
If you don't give a username, Kermit prompts you for one if FTP AUTOLOGIN is
ON; otherise it opens the connection without trying to log in.
<p>
The FTP OPEN command succeeds if a connection was opened to the server (even
if the given username and password were not valid) and fails otherwise (see
<a href="#x3.8">Section 3.8</a> for details).
<p>
When your FTP session is complete, you can terminate it as follows:
<p><dl>
<dt><tt><b>FTP BYE</b></tt></dt>
<dd>Closes the FTP connection if one was open. Synonym: FTP CLOSE. The FTP
prefix can be omitted if no other connection is open at the same time (see <a
href="#x3.8">Section 3.8</a> for details). If a connection log is active, an
FTP record is written to it. If Kermit was started with the <tt>-9</tt>
command-line option or with its FTP command-line personality, and the
<tt>-S</tt> (Stay) option was
not given, AND there is no other active connection, the FTP BYE command also
exits, just as it does on a regular FTP client.
</dl><p>
The following commands can be used to achieve greater control over the
connection and login process:
<p><dl>
<dt><tt><b>SET FTP AUTOLOGIN</b> <i>{</i> ON, OFF</b> <i>}</i></tt></dt>
<dd>If you give this command prior to opening an FTP connection, it controls
whether Kermit tries to log you in automatically as part of the connection
process. Normally ON, which means the username and password are sent
automatically (and prompted for if they are not yet known). When OFF, FTP
OPEN connects to the server without logging in. OFF is equivalent to the
<tt>-n</tt> command-line option when using Kermit's FTP command-line
personality.
<p>
<dt><tt><b>FTP USER</b> <i>name [ password [ account ] ]</i></tt></dt>
<dd>Used to log in to an FTP server to which a connection has been made without
autologin, or when autologin failed. If the password is furnished on the
command line, it is used; otherwise you are prompted for a password. An
account may also be furnished if required by the server; it is not required
by Kermit and is not prompted for if omitted. Synonym: FTP LOGIN.
<p>
<dt><tt><b>FTP ACCOUNT</b> <i>text</i></tt></dt>
<dd>Sends an account name to a server that supports accounts. If the server
does not support accounts, an error response occurs. If the server does
support accounts, the account is accepted if it is valid and rejected if
it is not. The account might be used for charging purposes or it might
be a secondary password, or it might be used for any other purpose, such
as an access password for a particular disk. Servers that support
accounts might or might not allow or require the account to be sent
prior to login; usually it is sent after login, if at all.
</dl>
<p>
Example:
<p><pre>
set ftp autogin off ; One thing at a time please
ftp xyzcorp.com ; Try to make the connection
if fail exit 1 FTP connection failed ; Check that it was made
user olga secret ; Now log in to the server
if fail exit 1 FTP login failed ; Check that it worked
account 103896854 ; Login OK - send account
if fail echo WARNING - FTP ACCT failed ; Warn if problem
... ; (have session here)
bye ; Log out and disconnect
</pre><p>
The following commands are used to control or get information about the FTP
connection. A particular FTP server does not necessarily support all of them.
<p><dl>
<dt><tt><b>FTP RESET</b></tt></dt>
<dd>Terminates a user session but leaves the connection open, allowing a new
login via FTP USER.
<p>
<dt><tt><b>FTP IDLE</b> <i>[ number ]</i></tt></dt>
<dd>Most FTP servers automatically log you out and and disconnect your session
if there has been no activity for a certain amount of time. Use this
command to ask the server to set its idle limit to the given number of
seconds. Omit the number to ask the server to inform you of its current
idle limit.
<p>
<dt><tt><b>FTP STATUS</b></tt></dt>
<dd>Asks the FTP server to send information about the current session.
The result is a free-format report that might include server
identification, username and login time, FTP protocol settings, and
file-transfer statistics.
<p>
<dt><tt><b>FTP SYSTEM</b></tt></dt>
<dd>Asks the FTP server to identify its operating system (Listed in Internet
Assigned Numbers, Operating System Names). Examples: UNIX, VMS, VM/CMS,
WINDOWS-NT. Unfortunately many variations are allowed (e.g. LINUX-2.0,
LINUX-2.2, FREEBSD, ULTRIX, etc, instead of UNIX; WINDOWS-NT-3,
WINDOWS-NT-3.5, WINDOWS-NT-3.51, WINDOWS-NT-4, etc). The report might
also include other information like "Type L8", "Type I", or "Type A",
indicating the file-transfer mode.
<p>
<dt><tt><b>FTP HELP</b> [ keyword [ keyword [ ... ] ]</i></tt></dt>
<dd>Asks the server to list the commands it supports. The response is usually
cryptic, listing FTP command mnemonics, not the commands used by the client
(since the server has no way of knowing anything about the client's user
interface). For example, the PUT command is STOR in FTP protocol. If a
keyword is given, which should be an FTP protocol command, slightly-more-
detailed help is given about the corresponding command (if the FTP server
supports this feature). Examples: "ftp help", "ftp help stor".
<p>
<dt><tt><b>FTP SITE</b> <i>text</i></tt></dt>
<dd>(Advanced) Sends an FTP SITE (site-specific) command. Usually this means
that the FTP server is asked to run an external command with the given
arguments. You might be able to find out what SITE commands are available
by sending "ftp help site" to the server, but in general the availability
of and response to SITE commands is (not surprisingly) site specific.
<p>
<dt><tt><b>FTP QUOTE</b> <i>text</i></tt></dt>
<dd>(Advanced) Sends an FTP command in FTP protocol format. Use this command
to send commands to the server that the FTP client might not know about.
<p>
<dt><tt><b>SHOW FTP</b></tt></dt>
<dd>Lists client (Kermit) FTP settings and information.
Also SHOW CONNECTION, SHOW COMMUNICATIONS.
<p>
<dt><tt><b>HELP FTP</b> <i>[ keyword ]</i></tt></dt>
<dd>Asks Kermit to list and describe its built-in FTP commands.
<p>
<dt><tt><b>HELP SET FTP</b> <i>[ keyword ]</i></tt></dt>
<dd>Asks Kermit to list and describe its built-in SET FTP commands.
</dl>
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.2">3.2. Making Secure FTP Connections</a></h3>
In the previous section, you can see several examples of traditional insecure
authentication: username and password sent across the network in clear text.
Of course this is bad practice on at least two counts: (1) storing passwords
in files (such as script files) gives access to the target systems to anybody
who can obtain read access to your scripts; and (2) sending this information
over the network leaves it open to interception by network sniffers or
compromised hosts.
<p>
Because of the increasing need for security on the Internet, FTP servers are
beginning to appear that offer secure forms of authentication, in which no
information is sent over the network that would allow anyone who intercepts
it to usurp your identity and gain your access rights.
<p>
Kermit provides an equivalent form of FTP security for each type of security
implemented in Telnet. These include GSSAPI-KERBEROS5, KERBEROS4, Secure
Remote Password (SRP), and Transport Layer Security (SSL and TLS). When
Kermit is built with the necessary libraries, secure FTP connections are
attempted by default, in which all connections are authenticated and the
command and data channels are private.
<p>
The use of authentication and encryption for FTP connections can be
adjusted with the commands listed below, which are available only if your
version of Kermit was built with the corresponding security options and
libraries:
<p><dl>
<dt><tt><b>SET FTP AUTHTYPE</b>
<i>{</i> <b>AUTOMATIC, GSSAPI-KRB5, KERBEROS4, SRP, SSL, TLS</b> <i>}</i>
</tt></dt>
<dd>Specifies an ordered list of authentication methods to be attempted when
AUTOAUTHENTICATION is ON. The default list is: GSSAPI-KRB5, SRP,
KERBEROS_V4, TLS, SSL. If none of the selected methods are supported by
the server, an insecure login is used as a fallback.
<p>
<dt><tt><b>SET FTP AUTOAUTHENTICATION</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>Tells whether authentication should be negotiated by the FTP OPEN command.
Default is ON.
<p>
<dt><tt><b>SET FTP AUTOENCRYPTION</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>Tells whether encryption (privacy) should be negotiated by the FTP OPEN
command. Default is ON.
<p>
<dt><tt><b>SET FTP COMMAND-PROTECTION-LEVEL</b> <i>{</i> <b>CLEAR, CONFIDENTIAL, PRIVATE, SAFE</b> <i>}</i></tt></dt>
<dd>Determines the level of protection applied to the command channel:
<p><pre>
CLEAR Data is sent in plaintext and not protected against tampering.
CONFIDENTIAL Data is encrypted but not protected against tampering.
PRIVATE Data is encrypted and is protected against tampering.
SAFE Data is sent in plaintext but protected against tampering.
</pre><p>
The default is PRIVATE.
<p>
<dt><tt><b>SET FTP CREDENTIAL-FORWARDING</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>Tells whether end-user credentials are to be forwarded to the server if
supported by the authentication method (GSSAPI-KRB5 only). This is often
required to allow access to distributed file systems (e.g. AFS.)
<p>
<dt><tt><b>SET FTP DATA-PROTECTION-LEVEL</b> <i>{</i> <b>CLEAR, CONFIDENTIAL, PRIVATE, SAFE</b> }</i></tt></dt>
<dd>Tells what level of protection is applied to subsequent data channels.
The meanings of the protection-level keywords are the same as for
SET FTP COMMAND-PROTECTION-LEVEL. The default is PRIVATE.
<p>
<dt><tt><b>SET FTP SRP CIPHER</b> <i>name</i></tt></dt>
<dd>Specifies the cipher to be used for encryption when SRP authentication
is in use. The list of possible choices is computed based on the
capabilities of the local SRP library and includes NONE plus zero or
more of the following:
<p><pre>
BLOWFISH_ECB CAST5_ECB DES_ECB DES3_ECB
BLOWFISH_CBC CAST5_CBC DES_CBC DES3_CBC
BLOWFISH_CFB64 CAST5_CFB64 DES_CFB64 DES3_CFB64
BLOWFISH_OFB64 CAST5_OFB64 DES_OFB64 DES3_OFB64
</pre><p>
The default is CAST5_CBC.
<p>
<dt><tt><b>SET FTP SRP HASH name</b></tt></dt>
<dd>Specifies the hash to be used for data protection when SRP authentication
is in use. The choices are MD5 and SHA. The default is SHA.
</dl><p>
Command-line options:
<p><dl>
<dt><tt><b>-k</b> <i>name</i></tt></dt>
<dd>Specifies the realm to be used with Kerberos 4 authentication
(= SET AUTH K4 REALM name).
<p>
<dt><tt><b>-f</b></tt></dt>
<dd>Enables forwarding of Kerberos 5 credentials to the host when using
GSSAPI authentication (= SET AUTH K5 FORWARDABLE ON).
<p>
<dt><tt><b>-x</b></tt></dt>
<dd>Enables autoencryption (= SET FTP AUTOENCRYPTION ON).
<p>
<dt><tt><b>-c</b> <i>cipher</i></tt></dt>
<dd>Specifies the kind of cipher to be used for encryption with SRP
authentication. Equivalent to SET FTP SRP CIPHER, with the same
choices. If this option is not given, CAST5_CBC is used.
<p>
<dt><tt><b>-H</b> <i>hash</i></tt></dt>
<dd>Specifies the hash to be used for encryption with SRP authentication.
Equivalent to SET FTP SRP HASH, with the same choices. If this option
is not given, SHA is used.
<p>
<dt><tt><b>-z debug</b></tt></dt>
<dd>Turns on SSL/TLS debugging.
<p>
<dt><tt><b>-z secure</b></tt></dt>
<dd>Requires secure connection.
<p>
<dt><tt><b>-z certsok</b></tt></dt>
<dd>Says to accept all certificates without checking validity.
<p>
<dt><tt><b>-z verify=</b><i>n</i></tt></dt>
<dd>Sets certificate verification mode to the given number, <i>n</i>:
<pre>
0 = no verification
1 = verify certificate if presented
2 = require verification of certificate
</pre>
<p>
<dt><tt><b>-z cert=</b><i>filename</i></tt></dt>
<dd>Specifies a file containing a client certificate to be presented to the
FTP server.
<p>
<dt><tt><b>-z key=</b><i>filename</i></tt></dt>
<dd>Specifies a file containing a private key matching the client certificate.
<p>
<dt><tt><b>-z !krb4</b></tt></dt>
<dd> nokrb4
Disables the use of Kerberos 4.
<p>
<dt><tt><b>-z !gss</b></tt></dt>
<dt><tt><b>-z nogss</b></tt></dt>
<dd>Disables the use of GSSAPI - Kerberos 5.
<p>
<dt><tt><b>-z !srp</b></tt></dt>
<dt><tt><b>-z nosrp</b></tt></dt>
<dd>Disables use of SRP.
<p>
<dt><tt><b>-z !ssl</b></tt></dt>
<dt><tt><b>-z nossl</b></tt></dt>
<dd>Disables the use of SSL.
<p>
<dt><tt><b>-z !tls</b></tt></dt>
<dt><tt><b>-z notls</b></tt></dt>
<dd>Disables the use of TLS.
</dl>
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.3">3.3. Setting FTP Preferences</a></h3>
You can control the amount of feedback received from your FTP session with
the following commands:
<p><dl>
<dt><tt><b>SET TRANSFER DISPLAY</b> <i>{</i> <b>FULLSCREEN, CRT, SERIAL,
BRIEF, NONE</b> <i>}</i></tt></dt>
<dd>FTP transfers use Kermit's normal file-transfer display styles. Use this
command to choose the desired format; the default on most platforms is
FULLSCREEN. The display is automatically disabled if Kermit is running in
the background or in batch. BRIEF is always used for command-line initiated
transfers (unless suppressed by <tt>-q</tt>).
</dl><p>
While a file-transfer is in progress, you can interrupt it in the normal
Kermit ways:
<p><pre>
X - Cancel current file but go on to the next one (if any).
Z - Cancel the entire transfer.
Ctrl-L or Ctrl-W - Refresh the file-transfer display (if any).
</pre><p>
Other FTP preferences can be set globally and persistently with the following
commands; most of these can also be overridden on a per-command basis with
switches that have the same name.
<p><dl>
<dt><tt><b>SET QUIET</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>This command applies to Kermit in general, not just FTP. OFF by default;
when ON, it surpresses most messages from most commands as well as the
file-transfer display.
<p>
<dt><tt><b>SET FTP ERROR-ACTION</b> <i>{</i> <b>PROCEED, QUIT</b> <i>}</i></tt></dt>
<dd>When transferring a group of files with FTP, and an error occurs with one
of the files, Kermit normally goes on the next file. Use SET FTP
ERROR-ACTION to QUIT to make Kermit stop the transfer immediately and
fail if an error occurs with any single file in the group. Example:
you have given Kermit a list of files to send, and one of the files can
not be found, or read permission is denied. Note that cancelling a
file by typing 'X' during transfer is not considered an error (if you want
to cancel the entire transfer, type 'Z' or Ctrl-C).
<p>
<dt><tt><b>SET FTP CHARACTER-SET-TRANSLATION</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>Whether to translate character sets when transferring text files with FTP
(explained in <a href="#x3.7">Section 3.7</a>). OFF by default.
<p>
<dt><tt><b>SET FTP SERVER-CHARACTER-SET</b> <i>name</i></tt></dt>
<dd>Tells Kermit the character set used by the FTP server
(<a href="#x3.7">Section 3.7</a>).
<p>
<dt><tt><b>SET FTP PERMISSIONS</b> <i>{</i> <b>AUTO, ON, OFF</b> <i>}</i></tt></dt>
<dd>When uploading files with PUT or MPUT, this tells whether Kermit should
send each file's permissions. The default is OFF, which means not to send
permissions, in which case the uploaded file's permissions are set by the
FTP server according to its own criteria. ON means to send them, AUTO
means to send them only if the client (Kermit) and server are on like
platforms (e.g. both UNIX). Also see FTP PUT /PERMISSIONS. Note that
setting permissions after uploading is likely to work (correctly or at
all) only when the client and server platforms are alike (e.g. both of
them are some form of UNIX). Also note that Windows files don't have
permissions. Also see FTP CHMOD.
<p>
<dt><tt><b>SET FTP PROGRESS-MESSAGES</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>Tells whether Kermit should print locally-generated feedback messages for
each non-file-transfer command. ON by default.
<p>
<dt><tt><b>SET FTP VERBOSE-MODE</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>Tells whether to display all responses from the FTP server. ON by default.
This shows all responses to all commands. When OFF, responses are shown
only for commands such as FTP PWD whose purpose is to display information.
<p>
<dt><tt><b>SET FTP DEBUG</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>Tells whether local client debugging information should be displayed.
OFF by default. When ON, the commands that are sent to the server are
shown, as well as its responses (even if VERBOSE-MODE is OFF), plus
additional informational messages are printed regarding the progress of
secure operations.
</dl>
<p>
Set all of these to OFF (or NONE) when silent running is desired.
<p><dl>
<dt><tt><b>SET FTP AUTOLOGIN</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>Described in <a href="#x3.1">Section 3.1</a>.
<p>
<dt><tt><b>SET FTP FILENAMES</b> <i>{</i> <b>AUTO, CONVERTED, LITERAL</b> <i>}</i></tt></dt>
<dd>When uploading (sending) files, this tells whether to convert outbound
filenames to "common form". This means allowing only one period in a name,
uppercasing any lowercase letters, replacing spaces by underscores, etc.
AUTOMATIC is the default, meaning LITERAL when client and server are the
same type of system (e.g. UNIX) and CONVERTED otherwise. Special case: if
the setting is AUTOMATIC and the client is not UNIX and the server
identifies itself as UNIX, Kermit uses a less-strict form of conversion, in
which lowercase letters are not uppercased and the filename can contain any
number of periods, but spaces are still converted to underscore. When
receiving, conversion generally means to change all-uppercase names to
lowercase and spaces to underscore.
<p>
<dt><tt><b>SET FTP UNIQUE-SERVER-NAMES</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>Applies only to uploads. Tells the server to create new, unique names for
incoming files that have the same names as existing files. OFF by default,
in which case the server overwrites existing files with new files of the
same name. When ON, the server uses its own built-in method for creating
new names for incoming files; for example, appending a period (<tt>.</tt>)
and a number to the name.
<p>
<dt><tt><b>SET FTP COLLISION</b> <i>{</i> <b>...</b> <i>}</i></tt></dt>
<dd>When downloading, what to do if an incoming file has the same name as an
existing file. Options are the same as for SET FILE COLLISION. If this
command is not given, Kermit's regular FILE COLLISION setting is used. If
this command is given, it overrides the FILE COLLISION setting for FTP
transfers only. See <a href="#x3.6.2">Section 3.6.2</a> for details.
<p>
<dt><tt><b>SET FTP PASSIVE-MODE</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>ON by default, to avoid random TCP port assignment for data connections,
which can prevent FTP protocol from working through firewalls. Set to
OFF in case the FTP server does not support passive mode.
<p>
<dt><tt><b>SET FTP SEND-PORT-COMMANDS</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>This command determines whether the FTP client sends a new PORT command
to the server when accepting incoming data connections (as when not using
passive mode.) When PASSIVE-MODE is OFF and SET SEND-PORT is OFF, the port
that was originally specified is reused. This is the default behavior for
normal FTP clients but it is not compatible with many firewalls.
<p>
<dt><tt><b>SET FTP TYPE</b> <i>{</i> <b>TEXT, BINARY</b> <i>}</i></tt></dt>
<dd>Changes the default transfer mode. When sending (uploading) files, this
command has no effect unless you disable automatic text/binary mode
switching (<a href="#x4">Section 4</a>)
with SET FILE SCAN OFF. When getting (downloading)
files, this command determines the mode in which Kermit will request the
server to send the files you request. In all cases, the FTP TYPE can be
overridden in any GET or PUT command by including a /TEXT (/ASCII) or
/BINARY switch. The FTP TYPE is independent of the Kermit FILE TYPE
setting. Synonym: ASCII = TEXT.
</dl>
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.4">3.4. Managing Directories and Files</a></h3>
In Kermit, commands for directory and file management can refer to:
<p><ul>
<li>The local computer
<li>A remote computer when you have a connection to a Kermit server or IKSD.
<li>A remote computer when you have a connection to an FTP server.
</ul><p>
(There can also be an HTTP connection, but the commands in this section don't
apply to HTTP connections.)
<p>
Thus in general, each such command comes in three forms:
<p><ul>
<li>With no prefix, it refers to the local computer (CD, DIR, etc).
<li>With the REMOTE prefix, it is for a Kermit server (REMOTE CD, REMOTE DIR).
<li>With the FTP prefix, it's for an FTP server (FTP CD, FTP DIR).
</ul><p>
Note the difference in command format between the Kermit FTP client and most
other FTP clients: in Kermit, unprefixed file management commands apply
locally; the FTP prefix is required to send them to the server (but see
<a href="x3.8">Section 3.8</a>). In most FTP clients, on the other hand,
unprefixed commands are for the server, and local commands require a prefix.
<p>
Kermit's FTP file and directory management commands are:
<p><dl>
<dt><tt><b>FTP CD</b> <i>[ directory ]</i></tt></dt>
<dd>Tells the FTP server to change its default (working) directory to the
one given, which usually must be expressed in the syntax of the server
platform (UNIX, VMS, etc). If the directory is not specified, the result
depends on the FTP server -- it might complain that the command is illegal,
or it might change to your original login directory. Synonym: FTP CWD
(Change Wording Directory).
<p>
<dt><tt><b>FTP UP</b></tt></dt>
<dd>Tells the FTP server to change its default (working) directory to the
parent directory of its current one (equivalent to "<tt>cd</tt> <tt>..</tt>"
in UNIX, or "<tt>cd</tt> <tt>[-]</tt>" in VMS).
<p>
<dt><tt><b>FTP PWD</b></tt></dt>
<dd>Asks the FTP server to report ("print") its current working directory.
<p>
<dt><tt><b>FTP MKDIR</b> <i>directory</i></b></tt></dt>
<dd>Asks the FTP server to create the directory whose name is given. In
general, the name must be in the syntax of the server's file system, and
it must be either absolute (a full pathname) or relative to the server's
current (working) directory. This command fails if the directory can't
be created for any reason, including that it exists already.
<p>
<dt><tt><b>FTP RMDIR</b> <i>directory</i></tt></dt>
<dd>Asks the FTP server to remove the directory whose name is given. The rules
are the same as for MKDIR, plus in most cases, the server will not remove
any directory unless it is empty.
<p>
<dt><tt><b>FTP DIRECTORY</b> <i>[ filespec ] [ redirectors ]</i></tt></dt>
<dd>Tells the FTP server to send a directory listing of the specified files.
If no filespec is given, the server lists all files in its current working
directory. The results are in whatever format the server chooses to send
them. You can use UNIX-line redirectors to send the listing to a file or
a pipeline, exactly as with the regular Kermit client/server REMOTE
DIRECTORY command (<a href="ck60manual.html"><cite>Using C-Kermit</cite></a>, Chapter 11). Examples:
<p><pre>
ftp dir ; Show listing of all files on screen
ftp dir *.txt ; List *.txt files on screen
ftp dir *.txt > somefile ; Put listing in somefile
ftp dir *.txt >> somefile ; Append listing to somefile
ftp dir *.txt | sort > somefile ; Put sorted listing in somefile
ftp dir | more ; Runs list through "more"
ftp dir | sort | more ; Runs list through "sort" and "more"
</pre><p>
<dt><tt><b>FTP MODTIME</b> <i>filename</i></tt></dt>
<dd>Asks the FTP server to send the modification date and time of the given
file. The response should be a numeric string in the format:
yyyymmddhhmmssxxxxx... where yyyy is the year, mm is the month, dd is the
day, hh is the hour (0-23), mm is the minute, ss is the second, and xxx...
is the optional fraction of the second (0 or more digits). The date and time
is expressed in UTC (GMT, Zulu, Zero-Meridian).
<p>
<dt><tt><b>FTP SIZE</b> <i>filename</i></tt></dt>
<dd>Asks the FTP server to send the size (in bytes) of the given file.
The result might vary depending on whether the current FTP TYPE is binary
or text ("ascii"). For a reliable byte count, do FTP TYPE BINARY first.
<p>
<dt><tt><b>FTP CHMOD</b> <i>permissions filename</i></tt></dt>
<dd>Tells the FTP server to set the permissions (protection) of the given
file to the ones given. The permissions and filename must be given in
whatever syntax is required by the server. Example (for a UNIX-based FTP
server):
<p><pre>
ftp chmod 664 oofa.txt
</pre>
<p>
Not all servers support this
command. For non-UNIX-based servers, you might need to use FTP QUOTE
or FTP SITE and the appropriate platform-specific FTP server command.
<p>
<dt><tt><b>FTP UMASK</b> <i>[ number ]</i></tt></dt>
<dd>This command is probably specific to UNIX-based servers; it sets the UNIX
"umask", which is the default permissions mask for new (in this case,
incoming) files. Crudely put, the UNIX umask is an octal representation of
a binary number in in which a 1 bit stands for a permission bit that must be
0, and a 0 bit stands for a permission bit that can be 0 or 1 depending on
other factors, such as the permissions of the parent directory. Example:
"umask 007" requires that new files are created without read/write/execute
world permission. If the number is not specified, the server's current
umask is reported.
<p>
<dt><tt><b>FTP RENAME</b> <i>filename newname</i></tt></dt>
<dd>Asks the FTP server to rename the file whose name is "filename" to
"newname". Works only for one file; can not be used with wildcards. The
server's interpretation of "newname" can vary (in some cases it must be a
filename, in others perhaps it can also be a directory name, in which case if
the filename denote a regular file, the file might be moved to the given
directory).
<p>
<dt><tt><b>FTP DELETE</b> <i>[ switches ] filespec [ filespec [ ... ] ]</i></tt></dt>
<dd>Tells the FTP server to delete the file or files listed. Each file
specification may, but need not, contain wildcard characters to match
multiple files. File specifications and wildcard syntax must be those
of the server. Any file specifications that contain spaces must be
enclosed in braces or doublequotes. FTP MDELETE switches are:
<p><pre>
/ERROR-ACTION: /FILENAMES: /NOBACKUPFILES /QUIET
/EXCEPT: /LARGER-THAN: /NODOTFILES /RECURSIVE
/SMALLER-THAN:
</pre><p>
For details, see the decriptions of these switches in
<a href="#x3.6">Section 3.6</a>.
Synonym: FTP MDELETE (Kermit makes no distinction between DELETE and
MDELETE).
</dl>
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.5">3.5. Uploading Files With FTP</a></h3>
Uploading means sending files from the client (Kermit) to the FTP server.
The basic command for uploading files with FTP is PUT:
<p><dl>
<dt><tt><b>FTP PUT</b> <i>[ switches ] [ filespec [ as-name ] ]</i></tt></dt>
<dd>Uploads (sends) the file or files that match the file specification, which
may include wildcards, to the server. If no filespec is given, the names
of files to send are taken from the /LISTFILE: file, if any, otherwise
from the SEND-LIST, if any. Unless you go out of your way to prevent it,
Kermit determines the transfer mode (text or binary) for each file
automatically, and switches automatically on a per-file basis. If an
as-name is given, the file is sent under that name instead of its own (if
an as-name is given with a wildcard filespec, the result is a bit more
complicated, and is explained later in this section).
</dl>
<p>
Unlike normal FTP clients, Kermit does not prompt you by default (or at all)
for each file; it just sends them, just as it does with Kermit protocol.
<p>
The filespec can be a literal filename or a Kermit pattern, described in
Section 4.9 of the ckermit2.txt file and on the web in:
<p><pre>
<a href="http://www.columbia.edu/kermit/ckermit2.html#x4.9">http://www.columbia.edu/kermit/ckermit2.html#x4.9</a>
</pre><p>
Kermit patterns are equivalent to C-Shell patterns and provide a fair amount
of flexibility in selecting which files to send, which is augmented by the
file-selection switches presented below in
<a href="#x3.5.1">Section 3.5.1</a>.
<p>
<dl>
<dt><tt><b>FTP MPUT</b> <i>[ switches ] filespec [ filespec [ ... ] ]</i></tt></dt>
<dd>FTP MPUT is just like FTP PUT except it allows you to give more than one
file specification, and it does not allow an as-name in the file list.
However, as-names can be given to either PUT or MPUT with the /AS-NAME:
switch.
</dl>
<p>
If a PUT or MPUT command results in one file being uploaded, it succeeds if
the file is uploaded completely and fails otherwise. If more than one file
is selected for upload, success or failure depends on the FTP ERROR-ACTION
setting; if it is PROCEED (the default setting), then the [M]PUT command
succeeds if at least one of the files was completely uploaded, and fails
otherwise, If FTP ERROR-ACTION is QUIT, the [M]PUT command succeeds if all
selected files were uploaded successfully, and fails if any file failed.
<p>
FTP uploads may be interrupted just like Kermit uploads. While the transfer
is in progress, type:
<p><pre>
X to interrupt the current file and go on to the next file.
Z to cancel the current file and all remaining files.
^C (Control-C): Like Z, but might act more quickly.
</pre><p>
MPUT may be used as in regular FTP clients, but it is not required to send
multiple files; in Kermit it is required only if you want to give multiple
file specifications. Examples:
<p><pre>
ftp put oofa.txt ; Send a single file oofa.txt
ftp put oofa.txt budget.txt ; Send single file oofa.txt as budget.txt
ftp put *.txt ; Send all *.txt files
ftp mput *.txt ; Send all *.txt files (same as "put *.txt")
ftp mput *.txt foo.bar ; Send all *.txt files plus foo.bar
</pre><p>
The distinction between PUT and MPUT is important only when more than one
filespec is given, just like the distinction between Kermit SEND and MSEND:
<p><pre>
ftp put oofa.txt budget.txt ; Send oofa.txt AS budget.txt
ftp mput oofa.txt budget.txt ; Send oofa.txt AND budget.txt
</pre><p>
If the source file specification includes any path segments, for example:
<p><pre>
put /tmp/oofa.txt
put subdir/another/andanother/oofa.txt
</pre>
<p>
the path portion is stripped from the filename that is sent to the server.
However, if an as-name contains a path, it is retained. Examples:
<p><pre>
ftp put /usr/doc/oofa.txt ; Send as "oofa.txt".
ftp put oofa.txt /tmp/oofa.txt ; Send as "/tmp/oofa.txt"
</pre>
<p>
The latter example sends the file <tt>oofa.txt</tt> from your current local
directory to the server's /tmp directory. This works only if the server uses
the same directory notation that you used in the as-name AND the given
directory already exists on the server AND if you have write access to it.
<h3><a name="x3.5.1">3.5.1. FTP PUT Switches</a></h3>
FTP PUT and MPUT are similar in format and behavior to the regular Kermit
SEND and MSEND commands, and they allow most of the same optional switches:
<p><pre>
C-Kermit>ftp put ? Filename, or switch, one of the following:
/after: /filenames: /recover
/array: /larger-than: /recursive
/as-name: /listfile: /rename-to:
/before: /local-character-set: /server-character-set:
/binary /move-to: /smaller-than:
/command /nobackupfiles /text
/delete /nodotfiles /transparent
/dotfiles /not-after: /type:
/error-action: /not-before: /update
/except: /permissions: /unique-server-names
/filter: /quiet
</pre><p>
Most of these switches are common to Kermit's SEND and MSEND commands, so are
described only briefly here. For greater detail see:
<p><pre>
<a href="http://www.columbia.edu/kermit/ckermit2.html#x1.5">http://www.columbia.edu/kermit/ckermit2.html#x1.5</a> (explanation of switches)
<a href="http://www.columbia.edu/kermit/ckermit2.html#x4.7">http://www.columbia.edu/kermit/ckermit2.html#x4.7</a> (file-transfer switches)
</pre><p>
First the file-selection switches:
<p>
<dl>
<dt><tt><b>/AFTER:</b><i>date-time</i></tt></dt>
<dt><tt><b>/BEFORE:</b><i>date-time</i></tt></dt>
<dt><tt><b>/NOT-AFTER:</b><i>date-time</i></tt></dt>
<dt><tt><b>/NOT-BEFORE:</b><i>date-time</i></tt></dt>
<dd>Only send those files modified on or after or before the given date and
time. These switches can be combined to select files modified between
two date/times. Various date-time formats are accepted; if the date-time
contains spaces, it must be enclosed in braces or doublequotes.
Examples:<br><pre> ftp put /after:{1 jan 2000 0:00:00} *
ftp put /after:-5days *
</pre><p>
<dt><tt><b>/LARGER-THAN:</b><i>number</i></tt></dt>
<dt><tt><b>/SMALLER-THAN:</b><i>number</i></tt></dt>
<dd>Only send files larger (smaller) than the given number of bytes
(characters, octets). These switches can be combined to select files in a
certain size range.
<p>
<dt><tt><b>/TYPE:</b><i>{</i><b>TEXT,BINARY</b><i>}</i></tt></dt>
<dd>Only send files that are the given type, which is determined for each
file just before sending it by file scanning.
<p>
<dt><tt><b>/[NO]DOTFILES</b></tt></dt>
<dd>[Don't] include files whose names begin with dot (<tt>.</tt>). By default,
such files are not included unless your filespec explicitly mentions
them.
<p>
<dt><tt><b>/NOBACKUPFILES</b></tt></dt>
<dd>Don't include files whose names end with <tt>.~<i>nnn</i>~</tt>, where
<i>nnn</i> is a number. These are backup files created by Kermit, EMACS, and
other applications. By default, backup files are included.
<p>
<dt><tt><b>/EXCEPT:</b><i>pattern</i></tt></dt>
<dd>Exception list -- don't send files whose names match the given pattern.
See <a href="http://www.columbia.edu/kermit/ckermit.html#x1.5.4">http://www.columbia.edu/kermit/ckermit.html#x1.5.4</a>
for details.
<p>
<dt><tt><b>/RECURSIVE</b></tt></dt>
<dd>Sends the desired files from the current (or given) directory, plus all
directories beneath it, replicating the directory structure on the server.
No special capabilities are required in the server, but of course your
login ID on the server must have the appropriate access and permission to
create directories. Recursive PUTs work not only between like platforms
(e.g. UNIX to UNIX) but also between unlike ones (e.g. UNIX to VMS or
Windows), in which case text-file format differences are handled by Kermit's
automatic text/binary mode switching
(<a href="#x4">Section 4</a>) and character-set
translation (<a href="#x3.7">Section 3.7</a>). Synonym: /SUBDIRECTORIES.
<p>
<dt><tt><b>/UPDATE</b></tt></dt>
<dd>Send only files that have changed since last time
(<a href="#x3.5.2">Section 3.5.2</a>).
<p>
<dt><tt><b>/ARRAY:</b><i>arrayname</i></b></tt></dt>
<dd>The "file" to be sent is an array, or a segment of one, rather than a
real file. In this case the other selection switches don't apply.
The array contents are sent in text mode, and each array element is
treated as a line. Example:
<pre>
ftp put /as-name:array.txt /array:&a
</pre>
(or, to send a segment of the array, <tt>/array:&a[100:199]</tt>). If you
don't include an /AS-NAME, a name of "<tt>_array_x_</tt>" is used (where x is
the array letter). If you include this switch, most other switches are
meaningless and ignored.
<p>
<dt><tt><b>/COMMAND</b></tt></dt>
<dd>The "file" to be sent is the standard output of a command, rather than
a real file. It is sent in text or binary mode according to the prevailing
FTP TYPE, which can be overridden with a /TEXT or /BINARY switch. Example:
Example:
<pre>
ftp put /command /as-name:{userlist} {finger | sort -r}
</pre>
<p>
<dt><tt><b>/LISTFILE:</b><i>filename</i></tt></dt>
<dd>Tells Kermit to obtain the list of files to be sent from the file whose
name is given. This file must contain one file specification (which may
be wild) per line.
</dl>
<p>
Now the other switches:
<p>
<dl>
<dt><tt><b>/AS-NAME:</b><i>text</i></tt></dt>
<dd>If a single file is being sent, send it with the given <i>text</i> as
its name.
If multiple files are being sent, the <i>text</i> must be a template that
includes variables such as <tt>\v(filename)</tt>, <tt>\v(filenumber)</tt>,
<tt>\v(ntime)</tt>, to allow dynamic creation of each name. The same applies
to the as-name field of the FTP PUT command. If this switch is not included
(and an as-name is not included as the second filename to PUT), each file is
sent with its own name.
<p>
<dt><tt><b>/BINARY</b></tt></dt>
<dt><tt><b>/TEXT</b></tt></dt>
<dd>Forces this upload to take place in the given mode, regardless of the
current FTP TYPE setting, and without automatic text/binary switching.
/ASCII is a synonym for /TEXT.
<p>
<dt><tt><b>/FILTER:</b><i>command</i></tt></dt>
<dd>Specifies that the file(s) is/are to be passed through the given
command or pipeline on their way to the server. Example:
<p><pre>
ftp put /binary /filter:{gzip -c \v(filename)} /as-name:\v(filename).gz *
</pre><p>
<dt><tt><b>/TRANSPARENT</b></tt></dt>
<dt><tt><b>/LOCAL-CHARACTER-SET:</b><i>name</i></tt></dt>
<dt><tt><b>/SERVER-CHARACTER-SET:</b><i>name</i></tt></dt>
<dd>Character-set translation for text files, explained in
<a href="#x3.7">Section 3.7</a>.
<p>
<dt><tt><b>/ERROR-ACTION:</b><i>{</i><b>PROCEED,QUIT</b><i>}</i></tt></dt>
<dd>Overrides the prevailing FTP ERROR-ACTION for the duration of this
PUT or MPUT command only.
<p>
<dt><tt><b>/RECOVER</b></tt></dt>
<dd>Resume an interrupted transfer where from the point of interruption
(explained in <a href="#x3.5.2">Section 3.5.2</a>). Synonym: /RESTART.
<p>
<dt><tt><b>/DELETE</b></tt></dt>
<dd>Tells Kermit to delete each source file immediately after, and only if,
it has been uploaded completely and successfully. This, in effect, moves
the file from the client to the server.
<p>
<dt><tt><b>/MOVE-TO:</b><i>directory</i></tt></dt>
<dd>Tells Kermit to move each source file to the named local directory after,
and only if, it has been uploaded completely and successfully.
<p>
<dt><tt><b>/RENAME-TO:</b><i>template</i></tt></dt>
<dd>Tells Kermit to rename each source file according to the given template
after, and only if, it has been uploaded completely and successfully. The
template works as in /AS-NAME.
<p>
<dt><tt><b>/FILENAMES:</b><i>{</i><b>AUTOMATIC,CONVERTED,LITERAL</b><i>}</i></tt></dt>
<dd>Overrides the FTP FILENAMES setting for this upload only.
<p>
<dt><tt><b>/PERMISSIONS:</b><i>{</i><b>ON,OFF</b><i>}</i></tt></dt>
<dd>Overrides the FTP PERMISSIONS setting for this upload only.
<p>
<dt><tt><b>/UNIQUE</b></tt></dt>
<dd>Tells Kermit to tell the server to give unique names to incoming files that
would otherwise overwrite existing files that have the same name. This
switch conflicts with /UPDATE, /RECOVER, and /PERMISSIONS, since the client
has no way of knowing the name assigned by the server.
<p>
<dt><tt><b>/QUIET</b></tt></dt>
<dd>Don't display file-transfer progress or statistics.
</dl>
<h3><a name="x3.5.2">3.5.2. Update Mode</a></h3>
When you include the /UPDATE switch, this means to skip sending any file that
already exists on the server if the local file's modification date/time is not
later than that of the corresponding file on the server. Here is a typical
application for update mode: Suppose that on Computer A, you maintain a large
set of files (say, a collection of Web pages and graphics images, or the
source files for a software application), and you need to keep a parallel copy
on another Computer, B. Of course you could upload the entire collection
every day:
<p><pre>
cd <i>source-directory</i>
ftp computerb.xyzcorp.com
<i>( authentication details... )</i>
ftp cd <i>target-directory</i>
ftp put <i>[ switches ]</i> *
</pre><p>
But if the total size is large or the network slow, this would be
unnecessarily time-consuming. By including the /UPDATE switch:
<p><pre>
ftp put /update [ other-switches ] *
</pre><p>
only those files that changed since last time are uploaded. Here's how it
works. For each local file that is selected for uploading:
<p><ul>
<li>The remote filename is determined in the normal way, according to
the FTP FILENAMES setting, /FILENAMES switch, or the as-name, if any.
<p>
<li>Kermit sends an MDTM (modification time) command for the corresponding
remote filename to the server.
<p>
<li>If the server does not understand the MDTM command, the file is sent.
<p>
<li>If the server can't find a file with the given name, the file is sent.
<p>
<li>If the local file's modification time is later than that of the remote
file, the file is sent.
<li>Otherwise -- the remote file exists but its modification time is equal
to or earlier than that of the local file -- the file is skipped.
</ul><p>
All time comparisons take place in Coordinated Universal Time
(UTC)(<a href="#note_utc">1</a>), also
known as GMT or Zulu time: Timezone 0; standard time, without daylight savings.
<p>
Update mode is useful only when always used in the same direction. When you
transfer a file with FTP, the destination file receives the current timestamp
on the receiving computer, not the original file's timestamp. If you try to
FTP PUT /UPDATE the same file again, it will be skipped (as expected) since
the remote copy is newer. However, if you try to FTP GET /UPDATE the same
file (<a href="#x3.6">Section 3.6</a>), it will be transferred for the same
reason.
<p>
To check the availability of PUT /UPDATE on a particular connection, issue an
FTP MODTIME command for a file that is known to exist on the server. If it
succeeds, PUT /UPDATE should work and in that case, you can run a procedure
like the one above every day: the first time, it sends all the files; after
that, it sends only the ones that changed.
<p>
If a transaction log is active, a notation is included for any files that
are skipped.
<p><blockquote><a name="note_utc">(1)</a>
Why is Coordinated Universal Time abbreviated UTC? From the
<a href="http://www.boulder.nist.gov/timefreq/faq/faq.htm#10:">
National Institute of Standards and Technology FAQ</a>:
"In 1970 the Coordinated Universal Time system was devised by an
international advisory group of technical experts within the
International Telecommunication Union (ITU). The ITU felt it was
best to designate a single abbreviation for use in all languages in
order to minimize confusion. Since unanimous agreement could not be
achieved on using either the English word order, CUT, or the French
word order, TUC, the acronym UTC was chosen as a compromise."
</blockquote>
<h3><a name="x3.5.3">3.5.3 Recovery</a></h3>
Suppose that while you are uploading a large file over a slow connection, the
connection is lost before the entire file is transferred. With most FTP
clients, you would have to start over, thus resending the portion of the file
that was sent already, and that is already on the server. But Kermit's
/RECOVER switch (synonym: /RESTART) lets you continue an interrupted transfer
from the point of failure, thus transferring only the part that wasn't sent
already. The prerequisites for recovery are:
<p><ul>
<li>The transfer must be in BINARY mode, or else the client and server must
reside on like systems (e.g. both on some form of UNIX).
<p>
<li>The FTP server must support the SIZE command.
</ul><p>
Here's how it works. When you include the /RECOVER switch:
<p><ul>
<li>Kermit checks for conflicting switches, such as /UPDATE and /UNIQUE;
if /RECOVER is given with these switches an error occurs. If /RECOVER
is given in other circumstances where it could serve no useful purpose
(e.g. with arrays, pipes, or filters), it is ignored.
</ul><p>
If the switch is accepted, then for each selected file:
<p><ul>
<li>If it is not binary (determined by scanning) and the client and server
are not on like platforms, recovery is canceled (the entire file is sent).
Otherwise:
<p>
<li>A SIZE command is sent for the file (using its remote name). If the
reply indicates the file was not found, or the SIZE command was not
understood, or any other kind of error, recovery is canceled. Otherwise:
<p>
<li>A MDTM (modification time) command is sent for the file. If a valid
reply is received, and the modification time of the local file is later
than that of the remote file, recovery is canceled. Otherwise:
<p>
<li>If the sizes of the two files are identical, the file is not sent.
Otherwise:
<p>
<li>Kermit seeks to the recovery spot in the local file, tells the server
to APPEND the data which is about to arrive to the remote file, and then
sends the data starting at the recovery point.
</ul><p>
To safeguard file integrity, recovery is not attempted unless all the
preconditions are met. For the widest possible usefulness, APPEND is used
rather than RESTART. For stream transfers (the only kind that Kermit
supports) the results are the same.
<p>
By design, the /RECOVER switch can be included with any FTP PUT or MPUT
command, even if it specifies a group of files. This allows you to resume
an interrupted batch transfer from where it left off. The files that were
already completely sent are skipped, the file that was interrupted is
recovered, and the remaining files are uploaded.
<p>
By the way, it doesn't matter how the original partial file was uploaded --
FTP, Kermit, Zmodem, etc: as long as the preconditions are met, it can be
recovered with FTP PUT /RECOVER, or for that matter also using Kermit
protocol and SEND /RECOVER.
<p>
A word of caution, however, when the original upload was in text mode with
character-set translation (<a href="#x3.7">Section 3.7</a>):
<p><ul>
<li>If the original upload involved a translation from one single-byte
character set to another (e.g. Code Page 850 to Latin-1), recovery is
safe if you specify the same translations for the recovery. If you don't,
the resulting file will contain a mixture of character sets.
<p>
<li>If the original upload involved a translation that changed the size
of the file (e.g. from an alphabetic Code Page or Latin Alphabet to
Unicode, or vice versa), recovery is NOT safe, even if you specify
the same translations.
</ul><p>
Kermit has no way of knowing anything about the previous upload. As a
safefuard, an error occurs if you include /RECOVER and also specify a
character-set of UCS2 or UTF8, since recovery can't possibly work in that
situation. Otherwise, it's up to you to avoid unsafe recovery operations.
<p>
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.6">3.6. Downloading Files With FTP</a></h3>
Although uploading files with Kermit's FTP client is just as easy and flexible
as sending files with Kermit protocol, the same is not always true for
downloading because FTP servers lack some of the capabilities of a Kermit
server:
<p><ul>
<li>The FTP server does not switch between text and binary mode automatically
on a per-file basis and even if it could, it would not have a way to let
the client know the transfer mode of each file. Therefore: (a) you have
to give an FTP TEXT or BINARY command prior to downloading to put the
server into the desired mode, and (b) you can't download a mixture of text
and binary files in the same operation, at least not when client and
server are on unlike platforms.
<p>
<li>If you want to get more than one file, you have to use MGET, not GET,
since the underlying FTP protocol is different in the two cases. Kermit
can't "autodetect" which one you mean, as it can with PUT and MPUT,
since it can't be expected to know the wildcard syntax of the remote
platform and/or FTP server (the same is true for all other FTP clients).
<p>
<li>Some options that are available with FTP PUT can not be used with FTP
[M]GET or don't work the same way:
/PERMISSIONS (FTP protocol has no mechanism for this).
/[NOT-]BEFORE, /[NOT-]AFTER (because of the timezone problem).
/RECOVER works only in binary mode.
/RECURSIVE has limited utility.
</ul><p>
The commands for downloading are:
<p>
<dl>
<dt><tt><b>SET FILE DOWNLOAD-DIRECTORY</b> <i>[ directory ]</i></tt></dt>
<dd>As with Kermit transfers, this command, if given, tells C-Kermit where to
store incoming files in the absence of a specific as-name. If not given,
incoming files are stored as indicated by the as-name, if any, otherwise
in the current directory, just as with Kermit transfers.
<p>
<dt><tt><b>FTP GET</b> <i>[ switches ] filename [ as-name ]</i></tt></dt>
<dd>Asks the server to send the given file, and if it comes, stores it locally
under the given as-name, if any, otherwise under its original name (modified
according to the selected filename conversion option), in your download
directory, if you have specified one, otherwise in the directory indicated
in the as-name, if any, otherwise in your current directory. If you
accidentally use a wildcard in the filename ("get *.txt") the server will
reply with a message like "File not found" (unless there is a file whose
name actually is "*.txt").
<p>
<dt><tt><b>FTP MGET</b> <i>[ switches ] filespec [ filespec [ filespec [ ... ] ] ]</i></tt></dt>
<dd>Like GET, but for multiple files. One or more file specifications can be
given, and any or all (or none) of them can contain wildcards.
</dl>
<p>
In both the FTP GET and MGET commands, any filenames that contain spaces
must be enclosed in braces or doublequotes (see
<a href="ftp://kermit.columbia.edu/kermit/test/text/ckc71.txt">Section 5</a>
for details).
<p>
FTP downloads may be interrupted just like Kermit uploads. While the
transfer is in progress, type:
<p><pre>
X to interrupt the current file and go on to the next file.
Z (or Control-C) to cancel the current file and all remaining files.
</pre>
<h3><a name="x3.6.1">3.6.1. FTP GET Switches</a></h3>
The following switches are available with FTP GET and MGET:
<p>
<dl>
<dt><tt><b>/TEXT</b></tt></dt>
<dd>Specifies a text-mode transfer. Overrides the global FTP TYPE setting
for the duration of the current command only. All files are downloaded
in text mode. Synonym: /ASCII.
<p>
<dt><tt><b>/BINARY</b></tt></dt>
<dd>Specifies a binary-mode transfer. Overrides the global FTP TYPE setting
for the duration of the current command only. All files are downloaded
in binary mode.
<p>
<dt><tt><b>/RECOVER</b></tt></dt>
<dd>This instructs Kermit to try to recover an incomplete download from the
point of failure. Works only in binary mode, and only if the server
supports the (not-yet-standard) FTP "REST" command. See
<a href="#x3.6.3">Section 3.6.3</a>
for details. Synonym: /RESTART.
<p>
<dt><tt><b>/FILENAMES:</b><i>{</i><b>CONVERTED,LITERAL</b><i>}</i></tt></dt>
<dd>Overrides the <tt>FTP</tt> <tt>FILENAMES</tt> (filename conversion)
setting for this download only.
<p>
<dt><tt><b>/AS-NAME:</b><i>text</i></tt></dt>
<dd>For GET, this is equivalent to giving an as-name after the filename.
For MGET, this is the only way to specify alternative names for the incoming
files. With MGET, the /AS-NAME text should (must) contain a Kermit variable,
usually <tt>\v(filename)</tt> or <tt>\v(filenumber)</tt>. Example:
<p><pre>
mget /text /as-name:\v(filename).new *.c
</pre><p>
This gets all "<tt>.c</tt>" files and stores them with "</tt>.new</tt>"
appended to their names.
See
<a href="http://www.columbia.edu/kermit/#x4.1">http://www.columbia.edu/kermit/#x4.1</a>
for details.
<p>
<dt><tt><b>/COMMAND</b></tt></dt>
<dd>This specifies that the incoming file is to be written to the standard
input of a command, rather than to a file. The command name is the as-name
from the GET command or the /AS-NAME argument. If you need to refer to the
incoming file's name in the command, use <tt>\v(filename)</tt>. See the
description of the regular Kermit GET /COMMAND command for details and
examples.
<p>
<dt><tt><b>/QUIET</b></tt></dt>
<dd>Transfer the files quietly; don't put up a file-transfer display.
<p>
<dt><tt><b>/ERROR-ACTION:</b><i>{</i><b>QUIT,PROCEED</b><i>}</i></tt></dt>
<dd>This switch affects only MGET. If an error occurs with a particular file,
this tells whether to go on to the next file (PROCEED) or to stop right
away and fail (QUIT). The default is PROCEED.
</dl>
<p>
The file selection switches are:
<p>
<dl>
<dt><tt><b>/EXCEPT:{</b><i>pattern</i><b>}</b> <i>or</i>
<b>/EXCEPT:{{</b><i>pattern</i><b>}{</b><i>pattern</i><b>}{...}}</b></tt></dt>
<dd>Exception list for MGET; skip downloading any file whose name matches
any of the given patterns (when using the second format, up to 8 patterns
may be specified).
<p>
<dt><tt><b>/SMALLER-THAN:</b><i>number</i></tt></dt>
<dd>Download only files whose size is smaller than the given number of bytes.
Requires that the FTP server support the SIZE command.
<p>
<dt><tt><b>/LARGER-THAN:</b><i>number</i></tt></dt>
<dd>Download only files whose size is greater than the given number of bytes.
Requires that the FTP server support the SIZE command.
<p>
<dt><tt><b>/NOBACKUPFILES</b></tt></dt>
<dd>During MGET, don't download any files whose names end with backup suffixes
(<tt>.~<i>n</i>~</tt> where <i>n</i> is a number).
<p>
<dt><tt><b>/NODOTFILES</b></tt></dt>
<dd>During MGET, don't download any files whose names begin with period
(<tt>.</tt>). Equivalent to <tt>/EXCEPT:{.*}</tt>.
<p>
<dt><tt><b>/LISTFILE:</b><i>filename</i></tt></dt>
<dd>The given file contains a list of files to GET, one per line. Filenames
in the listfile can contain wildcard characters in the syntax of the
server. There is no limit on the number of lines in the listfile.
<p>
<dt><tt><b>/UPDATE, /COLLISION:</b><i>keyword</i></tt></dt>
<dd>Explained in <a href="#x3.6.2">Section 3.6.2</a>.
<p>
<dt><tt><b>/RECURSIVE</b></tt></dt>
<dd>This means to try to download an entire directory tree, rather than just
files from a particular directory. In fact, FTP protocol does not provide
a method to request a recursive download, so this works only if the FTP
server does it anyway, without being asked. In this case, Kermit detects
that names in the returned file list contain directory separators, and
therefore attempts to create the needed directories as the files arrive.
But this can work only if the server is on the same kind of platform as the
client, so the pathname syntax can be recognized, and also because the
server does not switch between text and binary mode, which would be vital
for cross-platform transfers. Use with caution. Synonym: /SUBDIRECTORIES.
</dl>
<p>
The FTP protocol does not include explicit mechanisms for recursion, so Kermit
builds upon what is available. Although an Internet draft describes a mechanism
("MLST") that would allow protocol-driven recursion, similar to Kermit's File
Attribute packets (circa 1984), it has not yet attained RFC or standard
status, and servers are not yet widely available that offer this feature. In
the meantime, the effectiveness of MGET /RECURSIVE depends on the FTP server
implementation. For example, WU-FTPD always returns a recursive file list,
but only of those files that match the given wildcard; thus "<tt>mget</tt>
<tt>/recursive</tt> <tt>*.txt</tt>" descends only into those subdirectories
whose names end with "<tt>.txt</tt>", which is probably not what you wanted,
whereas "<tt>mget</tt> <tt>/recursive</tt> <tt>*</tt>" does the whole tree.
<p>
When used with FTP DELETE, the /RECURSIVE switch deletes files but not
directories.
<p>
The /BEFORE:, /AFTER:, /NOT-BEFORE:, and /NOT-AFTER: switches are not
available for downloading because of the confusion with timezones. Would the
given times be in the local timezone, the server's timezone, or GMT? The FTP
server's directory listings show its own local times but since we don't know
what timezone the server is in, there's no way to reconcile our local times
with the server's.
<p>
Source-file disposition switches:
<p>
<dl>
<dt><tt><b>/DELETE</b></tt></dt>
<dd>Each file that is downloaded successfully is to be deleted from the server.
Requires the appropriate file access rights on the server.
</dl>
<p>
Destination-file disposition switches:
<p>
<dl>
<dt><tt><b>/TO-SCREEN</b></tt></dt>
<dd>Displays the incoming file on the screen rather than storing it on disk.
If this switch is given, the /RENAME-TO and /MOVE-TO switches are ignored,
the file-transfer display is suppressed, and the given file(s) is/are
shown on the screen. Can be used with /FILTER, e.g.
<p><pre>
get /text /to-screen /filter:more oofa.txt
</pre><p>
In fact, you should always use /TO-SCREEN with /FILTER or /COMMAND when
the command would result in displaying the incoming file on the screen;
otherwise C-Kermit would have no way of knowing to suppress its file
transfer display (since it can't be expected to know what the command
or filter does).
<p>
<dt><tt><b>/RENAME-TO:</b><i>text</i></tt></dt>
<dd>Each file that is downloaded is to be renamed as indicated if and only if
it was received completely and without error. The text can be literal text
or can contain variables that are evaluated for each file. For MGET, the
text must contain variables; for GET it can be a literal string. The
<tt>\v(filename)</tt> variable contains the name of the current file, so:
<p><pre>
ftp mget /rename-to:\v(filename).ok *
</pre>
<p>
causes each file that is successfully downloaded to have "<tt>.ok</tt>"
appended to its name. For details see
<a href="http://www.columbia.edu/kermit/ckermit2.html#x4.1">http://www.columbia.edu/kermit/ckermit2.html#x4.1</a>.
<p>
<dt><tt><b>/MOVE-TO:</b><i>text</i></tt></dt>
<dd>Just like /RENAME-TO:, except the text denotes the name of a directory to
which successfully downloaded files are to be moved. If the directory does
not exist, it is created.
</dl>
<p>
The file transfer display does not show the /MOVE-TO or /RENAME-TO value,
since the incoming file has not yet been moved or renamed.
<h3><a name="x3.6.2">3.6.2. Filename Collisions</a></h3>
What should happen if an incoming file has the same name as an existing file
in the same directory? By default, Kermit's FILE COLLISION setting applies:
BACKUP, RENAME, UPDATE, DISCARD, etc, as described in <a href="ck60manual.html"><cite>Using C-Kermit</cite></a>.
Kermit's default FILE COLLISION setting is BACKUP (rename the existing file
and store the incoming file under its own name) and therefore this is also the
default FTP collision action.
<p>
The name under which an incoming file is to be stored is determined as
follows:
<p><ul>
<li>If an as-name was given, the as-name is used. Otherwise:
<p>
<li>If the client and server platforms are alike or FTP FILENAMES is set to
LITERAL (or the /FILENAMES:LITERAL switch was given for this download),
the incoming filename is used literally. Otherwise:
<p>
<li>The incoming filename is converted to a form that is friendly to the
local platform. For UNIX, for example, incoming filenames that are all
uppercase (as they might be from, say, VMS or an IBM mainframe) are
converted to lowercase.
</ul><p>
If the resulting name coincides with the name of a local file that already
exists, we have a filename collision. Collisions are handled according to
the currently selected collision action:
<p>
<dl>
<dt><tt><b>SET FTP COLLISION</b> <i>{</i> <b>BACKUP, RENAME, UPDATE, DISCARD, APPEND, OVERWRITE</b> <i>}</i></tt></dt>
<dd>This establishes a filename collision for FTP, separate from the Kermit
one. The initial FTP collision setting is inherited from Kermit's FILE
COLLISION setting when the first FTP command is given, but subsequent changes
to Kermit's FILE COLLISION setting do not affect the FTP COLLISION setting.
SHOW FTP tells the current FTP COLLISION setting.
<p>
<dt><tt><b>FTP GET /COLLISION:</b><i>{</i><b>BACKUP,RENAME,UPDATE,DISCARD,APPEND,OVERWRITE</b><i>}</i></tt></dt>
<dd>Overrides the current FTP COLLISION action for this download only.
<p>
<dt><tt><b>FTP GET /UPDATE</b></tt></dt>
<dd>This is equivalent to GET /COLLISION:UPDATE, and is included for symmetry
with PUT /UPDATE
</dl>
<p>
FTP GET /UPDATE and /COLLISION:UPDATE mean to download only those files whose
modification dates on the server are later than those on the client.
Date-time comparisons are done in Coordinated Universal Time (UTC, GMT, ZULU).
<p>
As when uploading, update mode is effective only when used consistently in one
direction. When you download a file with FTP, the local file receives the
current timestamp, not the original file's timestamp. If you try to FTP GET
/UPDATE the same file again, it is skipped (as expected) since the local copy
is newer. However, if you try to FTP PUT /UPDATE the same file, it is sent
for the same reason.
<p>
(It might be possible to set the downloaded file's date from the server file's
date but (a) UNIX does not offer the necessary time conversion APIs, and (b)
FTP protocol offers no mechanism for doing the same thing in the opposite
direction.)
<h3><a name="x3.6.3">3.6.3. Recovery</a></h3>
Recovery is available for downloads too, but there are some differences from
the uploading case described in <a href="#x3.5.3">Section 3.5.3</a>:
<p><ul>
<li>The transfer must be in BINARY mode. It can not be in text mode, even
if the FTP server is on the same kind of platform as Kermit, and even
if there is no character-set translation. The original download must also
have been in binary mode.
<p>
<li>The FTP server must support the REST ("restart") command. Unfortunately,
this is not a standard command; at this writing, it is described only in
an Internet Draft, not an RFC or Internet Standard, but nevertheless it is
found in several popular FTP servers, including WU-FTP.
</ul><p>
Here's how download recovery works:
<p><ul>
<li>Kermit checks for conflicting switches, such as /UPDATE, /COMMAND, or
/FILTER. If /RECOVER is given with these switches an error occurs.
<p>
<li>The prevailing transfer mode (SET FTP TYPE) must be BINARY. If it is not,
the /BINARY switch must have been included with the FTP [M]GET command.
<p>
If the /RECOVER switch is accepted, then for each selected file:
<p>
<li>A SIZE command is sent for the file (using its remote name). If the
reply indicates the file was not found, or the SIZE command was not
understood, or any other kind of error, recovery is canceled (i.e. the
entire file is downloaded). Otherwise:
<p>
<li>A MDTM (modification time) command is sent for the file. If a valid
reply is received, and the modification time of the remote file is later
than that of the local file, recovery is canceled. Otherwise:
<p>
<li>If the sizes of the two files are identical, the file is not sent.
Otherwise:
<p>
<li>Kermit sends the REST command to the server, indicating the size of the
local file. If the server responds affirmatively, Kermit opens the local
file in append mode and appends the incoming data to it. Otherwise,
recovery is canceled and the entire file is downloaded.
</ul><p>
The /RECOVER switch can be included with any FTP GET or MGET command, even if
it specifies a group of files. This lets you resume an interrupted batch
transfer from where it left off. The files that were already completely sent
are skipped, the file that was interrupted is recovered, and the remaining
files are uploaded. BUT... unlike with uploading, where this can be done with
any mixture of text and binary files, when downloading, it can only be done if
all the files are binary.
<p>
It doesn't matter how the original partial file was downloaded -- FTP, Kermit,
Zmodem, etc: as long as the preconditions are met, it can be recovered with
FTP [M]GET /RECOVER, or for that matter also with GET /RECOVER (using Kermit
protocol).
<p>
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.7">3.7. Translating Character Sets</a></h3>
A possibly unique feature of Kermit's FTP client is its ability to convert
character sets when transferring files in text mode, independent of the
capabilites of the FTP server. For compatibility with existing FTP clients,
and because there is a certain performance penalty, Kermit won't do this
unless you ask for it. If you enable this feature, you need to inform Kermit
of the character set (to be) used on the server and in some cases (explained
below) also the local file character set. Here are the commands:
<p>
<dl>
<dt><tt><b>SET FTP CHARACTER-SET-TRANSLATION</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
<dd>Whether to translate character sets when transferring text files with FTP.
OFF by default. Set this to ON to enable character-set translation
for subsequent FTP uploads and downloads.
<p>
<dt><tt><b>SET FTP SERVER-CHARACTER-SET</b> <i>name</i></tt></dt>
<dd>Text character set (to be) used by the server. Most FTP servers are
ignorant of character sets, so all translations are done unilaterally by
Kermit's FTP client. This means that when downloading files, you must
know in advance the character-set used in the files you are downloading.
When uploading, you must specify the character-set to which local text
files are to be translated for transmission to the server. If you SET FTP
CHARACTER-SET-TRANSLATION ON but do not specify an FTP SERVER-CHARACTER-SET,
UTF8 is used, since this is the new Internet standard international
character set; it is upwards compatible with ASCII and it encompasses most
most written languages and therefore does not favor any particular group
of people, as any other default would do.
<p>
<dt><tt><b>SET FILE CHARACTER-SET</b> <i>name</i></tt></dt>
<dd>This is the regular Kermit (non-FTP-specific) command for identifying the
character set (to be) used in local text files.
</dl>
<p>
To reiterate: If you SET FTP CHARACTER-SET TRANSLATION ON but do not specify
an FTP SERVER-CHARACTER-SET, outbound text files are converted to UTF-8 and
inbound text files are assumed to be UTF-8. If this is not appropriate,
be sure to also specify the desired FTP SERVER-CHARACTER-SET.
<h3><a name="x3.7.1">3.7.1. Character Sets and Uploading</a></h3>
Kermit's PUT and MPUT commands include full file-scanning capabilities, as
described in
<a href="#x4">Section 4</a>.
Thus if FTP CHARACTER-SET-TRANSLATION is ON and your
character-set associations are set up appropriately, Kermit automatically
switches on a per-file basis between text and binary mode, and for each text
file between your chosen 7-bit text character set (e.g. ASCII or ISO 646
German), 8-bit text (e.g. Latin-1 or Japanese EUC), UCS-2, and UTF-8, and
converts each of these automatically to the server character-set, and
furthermore automatically differentiates between the Little and Big Endian
forms of UCS-2, always sending in Big Endian form.
<p>
FTP character-set translations differ from the regular Kermit ones by not
restricting translations to a file-character-set / transfer-character-set pair.
You can have Kermit's FTP client translate between any pair of character sets
it knows about. You can see the list of supported character sets by typing
either of the following:
<p><pre>
set ftp server-character-set ?
set file character-set ?
</pre><p>
A typical list looks like this:
<p><pre>
C-Kermit>set file char ? One of the following:
ascii cp869-greek hebrew-7 mazovia-pc
british cyrillic-iso hebrew-iso next-multinational
bulgaria-pc danish hp-roman8 norwegian
canadian-french dec-kanji hungarian portuguese
cp1250 dec-multinational iso2022jp-kanji shift-jis-kanji
cp1251-cyrillic dg-international italian short-koi
cp1252 dutch jis7-kanji spanish
cp437 elot927-greek koi8 swedish
cp850 elot928-greek koi8r swiss
cp852 euc-jp koi8u ucs2
cp855-cyrillic finnish latin1-iso utf8
cp858 french latin2-iso
cp862-hebrew german latin9-iso
cp866-cyrillic greek-iso macintosh-latin
C-Kermit>
</pre><p>
Thus you can translate not only between private sets (like PC code pages) and
standard ones (like Latin-1) as in regular Kermit, but also between any given
pair of private sets (e.g. CP852 and Mazovia). All conversions go through
Unicode as the intermediate character set, resulting in a minimum of character
loss, since Unicode is a superset of all other character sets known to Kermit.
<p>
In addition to the SET commands listed above, the FTP PUT and MPUT commands
include switches that apply only to the current command:
<p>
<dl>
<dt><tt><b>/LOCAL-CHARACTER-SET:</b><i>name</i></tt></dt>
<dt><tt><b>/SERVER-CHARACTER-SET:</b><i>name</i></tt></dt>
<dd>Use these switches to force a particular translation. These switches
override the global FTP CHARACTER-SET-TRANSLATION and SERVER-CHARACTER-SET
settings and also character-set differentiation by file scanning for the
duration of the PUT or MPUT command. The file scan is still performed,
however, to determine whether the file is text or binary; thus these
switches do not affect binary files unless you also include the /TEXT
switch to force all files to be treated as text.
</dl>
<p>
In other words, if you include one or both of these switches with a PUT or
MPUT command, they are used. Similarly, the /TRANSPARENT switch disables
character-set translation for the PUT or MPUT command despite the prevailing
FTP CHARACTER-SET-TRANSLATION and SERVER-CHARACTER-SET settings.
<p>
When uploading, the FILE CHARACTER-SET setting is ignored unless you have
forced Kermit not to scan local files (see <a href="#x4">Section 4</a>).
Examples:
<p>
Suppose you have a CP852 (East European) text file that you want to upload
and store in ISO Latin Alphabet 2 encoding:
<p><pre>
ftp put /local-char:cp852 /server-char:latin2 magyar.txt
</pre><p>
Suppose you always want your text files converted to Latin-2 when uploading
with FTP. Then put:
<p><pre>
set ftp server-character-set latin2
</pre><p>
in your Kermit customization file, and then you can omit the
/SERVER-CHARACTER-SET: switch from your FTP PUT commands:
<p><pre>
ftp put /local-char:cp852 magyar.txt
</pre><p>
Now suppose that all the text files on your PC are written in Hungarian, but
they have a variety of encodings, and you don't want to have to include the
/LOCAL-CHARACTER-SET: switch on every FTP PUT command, or (more to the point)
you want to be able to send a mixture of these files all at once. Put these
commands in your Kermit customization file:
<p><pre>
set ftp server-character-set latin2 ; ISO 8859-2
set file default 7-bit-character-set hungarian ; ISO 646 Hungarian
set file default 8-bit-character-set cp852 ; PC East European Code Page
</pre><p>
and now PUT and MPUT will automatically detect and switch among ISO 646
Hungarian, Code Page 852, UTF-8, and UCS-2 encodings, translating each one
to Latin-2 for uploading:
<p><pre>
ftp put *.txt
</pre><p>
And since binary files are also detected automatically, this can be
simplified to:
<p><pre>
ftp put *
</pre><p>
even when "*" matches a diverse collection of binary and text files, because
translations are skipped automatically for binary files.
<h3><a name="x3.7.2">3.7.2. Character Sets and Downloading</a></h3>
The commands and switches are the same as for uploading, but remember there
is no automatic text/binary switching during downloading, and there is also
no automatic character-set switching. Whatever selections you make for a
particular GET or MGET command apply to all the files that are downloaded by
that command. Example:
<p><pre>
mget /text /server:latin1 /local:utf8 *.txt
</pre><p>
This command:
<p><ul>
<li>Tells C-Kermit that the server's files are encoded in ISO 8859-1
Latin Alphabet 1.
<li>Tells C-Kermit to translate the incoming files into Unicode UTF-8 for
storage.
<li>Asks the server to send all "<tt>.txt</tt>" files in text mode.
</ul>
<h3><a name="x3.7.3">3.7.3. RFC2640</a></h3>
<a href="ftp://ftp.isi.edu/in-notes/rfc2640.txt"> RFC2640</a>, July 1999,
specifies a method by which the FTP client and server can negotiate the use of
UTF8. However, RFC2640-capable servers are rare to nonexistent at this
writing, and in any case you don't need them to be able to transfer text in
UTF8. C-Kermit lets you upload and download text files in any character set
it knows about, converting to or from any other character set it knows about,
without the knowledge, permission, or cooperation of the server, and
regardless of its capabilities.
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.8">3.8. FTP Command Shortcuts</a></h3>
C-Kermit's FTP client coexists with other C-Kermit functions by requiring the
"ftp" prefix for each FTP-related command: FTP OPEN, FTP GET, FTP BYE, and so
on. For interactive use, however, this can be rather awkward and sometimes
surprising, for example when a GET command starts a Kermit GET rather than an
FTP GET. In fact, many Kermit commands might just as easily apply to an FTP
connection: GET, PUT (SEND), BYE, and CLOSE. The following command lets you
choose how these commands are interpreted:
<p>
<dl>
<dt><tt><b>SET GET-PUT-REMOTE</b> <i>{</i> <b>AUTO, KERMIT, FTP</b> <i>}</i></tt></dt>
<dd>Controls the orientation of GET, PUT, REMOTE and other file-transfer and
client/server commands that might apply to either Kermit or FTP. The
default setting is AUTO, meaning that these commands apply to FTP if an
FTP connection is open, and to Kermit otherwise. KERMIT means they always
apply to Kermit, FTP means they always apply to FTP.
</dl>
<p>
Here is a complete list of affected commands:
<p><pre>
<u>Kermit Command</u> <u>FTP Equivalent</u>
(none) FTP <i>[</i> OPEN <i>]</i>
LOGIN FTP USER
LOGOUT FTP RESET
BYE FTP BYE
FINISH FTP BYE
CLOSE FTP BYE
HANGUP FTP BYE
BINARY FTP TYPE BINARY
TEXT (or ASCII) FTP TYPE ASCII
SEND (or PUT) FTP PUT
MSEND (or MPUT) FTP MPUT
RESEND FTP PUT /RECOVER
CSEND FTP PUT /COMMAND
GET FTP GET
MGET FTP MGET
REGET FTP GET /RECOVER
REMOTE HELP (RHELP) FTP HELP
REMOTE CD (RCD) FTP CD (CWD)
REMOTE PWD (RPWD) FTP PWD
REMOTE DIRECTORY (RDIR) FTP DIRECTORY
REMOTE DELETE (RDEL) FTP DELETE
REMOTE MKDIR (RMKDIR) FTP MKDIR
REMOTE RMDIR (RRMDIR) FTP RMDIR
REMOTE RENAME (RRENAME) FTP RENAME
REMOTE TYPE (RTYPE) FTP TYPE
REMOTE EXIT (REXIT) FTP BYE
</pre>
<p>
The commands in the right-hand column always access FTP. The commands in
the left column can access either Kermit protocol or FTP:
<p><ul>
<li>When GET-PUT-REMOTE is set to KERMIT, or to AUTO when there is no FTP
connection, the commands in the left-hand column access Kermit protocol,
and those right-hand column are required for FTP.
<p>
<li>When GET-PUT-REMOTE is set to FTP, or to AUTO when there is an active FTP
connection, the commands in the left-hand column access the FTP connection
and can not be used to access Kermit protocol. In this case, if you want
to be able to use both Kermit protocol and the FTP connection, you must SET
GET-PUT-REMOTE KERMIT, and then use the FTP commands in the right-hand
column to access the FTP connection.
</ul><p>
Note that file-management commands such as DIRECTORY, DELETE, CD, PWD, MKDIR,
RMDIR, HELP, RENAME, COPY, TYPE, and so on, always apply locally, no matter
what kind of connection you have. This is the opposite of most FTP clients,
where these commands are intended for the server, and require an "L" prefix
for local execution (e.g. "dir" gets a directory listing from the server,
"ldir" gets a local directory listing). To illustrate with the CD command
and a typical UNIX FTP client:
<p><pre>
<u>Client</u> <u>Server</u> <u>Change Local Directory</u> <u>Change Remote Directory</u>
FTP FTP lcd cd (cwd)
Kermit Kermit cd rcd, remote cd
Kermit FTP cd ftp cd, rcd, remote cd
</pre><p>
Also note that not all REMOTE commands are useful with FTP, since FTP servers
do not offer the corresponding functions. These include:
<p><pre>
REMOTE ASSIGN - FTP servers don't have variables
REMOTE COPY - FTP servers don't copy files
REMOTE HOST - FTP servers don't execute host (shell) commands
REMOTE KERMIT - FTP servers don't execute Kermit commands
REMOTE PRINT - FTP servers don't print files
REMOTE QUERY - FTP servers don't have variables
REMOTE SET - FTP servers don't have Kermit settings
REMOTE WHO - FTP servers don't send user lists
</pre><p>
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.9">3.9. Dual Sessions</a></h3>
You can have an FTP session open at the same time as a regular Kermit SET
LINE or SET HOST session. In this case, the default SET GET-PUT-REMOTE AUTO
setting should ensure that all "two-faced" commands like GET, PUT, REMOTE,
HANGUP, BYE, etc, apply to the Kermit session, and all commands for the FTP
session must include the FTP prefix. To be absolutely certain, you can use
SET GET-PUT-REMOTE KERMIT.
<p><pre>
ftp foo.bar.baz.com
if fail ...
(log in)
set host foo.bar.baz.com
if fail ...
(log in)
</pre><p>
Now you have both an FTP and Telnet connection to the same host (of course
they could also be to different hosts, and you could also have a direct or
dialed serial connection instead of a Telnet connection). Now assuming you
have a Kermit server on the far end of the Kermit connection:
<p><pre>
rcd incoming ; Changes Kermit server's directory (= REMOTE CD)
ftp cd incoming ; Changes FTP server's directory
put oofa.txt ; Sends a file on the Kermit connection
ftp put oofa.txt ; Sends a file on the FTP connection
bye ; Shuts down the Kermit connection
ftp bye ; Shuts down the FTP connection
</pre><p>
Note that PUT and SEND are synonyms for both FTP and Kermit connections.
<p>
You can also establish dual sessions on the Kermit command line:
<p><pre>
kermit -j host1 -9 host2
</pre><p>
This makes a Telnet connection to host1 and an FTP connection to host2.
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.10">3.10. Automating FTP Sessions</a></h3>
Most of Kermit's scripting features can be used to make and control FTP
sessions: FOR and WHILE loops, IF-ELSE and SWITCH constructions, variables,
arrays, built-in functions, and all the rest. You can't use INPUT, MINPUT,
OUTPUT, CLEAR, or SCRIPT on an FTP session, but these are not needed since
the FTP protocol is well defined.
<h3><a name="x3.10.1">3.10.1. FTP-Specific Variables and Functions</a></h3>
The following variable tells whether an FTP connection is open:
<p><dl>
<dt><tt><b>\v(ftp_connected)</b></tt></dt>
<dd>1 if there is an active FTP connection, 0 if there isn't.
</dl>
<p>
The FTP OPEN command sets:
<p><dl>
<dt><tt><b>\v(ftp_host)</b></tt></tt>
<dd>The host to which the most recent FTP connection was made.
<p>
<dt><tt><b>\v(ftp_server)</b></tt></tt>
<dd>The OS type (UNIX, VMS, etc) of the FTP server host.
<p>
The FTP USER command (or FTP OPEN /USER:, or FTP with automatic login) sets:
<p>
<dt><tt><b>\v(ftp_loggedin)</b></tt></tt>
<dd>1 if you are logged in to an FTP server, 0 if you are not.
</dl>
<p>
plus the following, which apply to Kermit's secure authentication methods:
<p><pre>
\v(authtype) Name of secure authentication method used, if any.
\v(authname) Username for which secure authentication was obtained.
\v(authstate) User, Valid, Rejected, Other, or Unknown.
</pre>
<p>
The FTP GET-PUT-REMOTE setting is reflected in:
<p><pre>
\v(ftp_getputremote)
</pre><p>
Every FTP command sets the \v(success) variable, as well as the following
two FTP-specific variables:
<p><dl>
<dt><tt><b>\v(ftp_code)</b></tt></tt>
<dd>The standardized numeric FTP protocol code from the server's response
to the last client command, a 3-digit decimal number defined in
<a href="ftp://ftp.isi.edu/in-notes/rfc959.txt"> RFC959</a>.
Briefly:
<p><pre>
1xx = Positive Preliminary Reply
2xx = Positive Completion Reply
3xx = Positive Intermediate Reply
4xx = Transient Negative Completion Reply
5xx = Permanent Negative Completion Reply
</pre>
<p>
<dt><tt><b>\v(ftp_msg)</b></tt></tt>
<dd>The text message, if any, from the server's response to the last
client command. If the most recent response had multiple lines,
this variable has only the final line. These messages are not
standardized and vary in format and content from server to server.
</dl>
FTP file transfers set the regular Kermit transfer status variables:
<p><pre>
\v(cps) Characters per second of most recent transfer.
\v(filespec) File specification used in most recent transfer.
\v(fsize) Size of file most recently transferred.
\v(tfsize) Total size of file group most recently transferred.
\v(xferstatus) Status of most recent transfer (0 = success, 1 = failure).
\v(tftime) Elapsed time of most recent transfer, in seconds.
</pre><p>
During an FTP transfer, the per-file variables are:
<p><pre>
\v(filename) Name of current file.
\v(filenumber) Ordinal file number in group (1, 2, 3, ...)
</pre><p>
*** Macros to bundle settings for different servers ***
<h3><a name="x3.10.2">3.10.2. Examples</a></h3>
Let's begin with a simple example showing how to log in, send some files,
and log out:
<p><pre>
define error if fail { ftp bye, stop 1 Error: \%1 }
set transact brief
log t
ftp ftp.xyzcorp.com /anonymous
if fail stop 1 Connection failed
if not \v(ftp_loggedin) stop 1 Login failed
ftp cd incoming
error {ftp cd}
cd upload
error {local cd}
ftp put /delete *
error {put}
ftp bye
</pre><p>
First we define an error handling macro to be used after the connection is
made. Then we set up a brief-format transaction log to keep a record of our
file transfers. Then we make a connection to the host and log in anonymously.
The "if fail" command checks whether the connection was made. The "if not"
command checks whether login was successful. Obviously the script should not
continue unless both tests succeed.
<p>
Next we change to the server's 'incoming' directory and to our own 'upload'
directory, and send all the files that are in it (they can be any mixture of
text and binary files), deleting each source file automatically after it is
successfully uploaded. Each of these operations is checked with the ERROR
macro, which prevents the script from continuing past a failure.
<p>
Finally we close the FTP session with the "bye" command.
<p>
Just like any other Kermit script, this one can be used in many ways:
<p><ul>
<li>It can be stored in a file, and Kermit can be told to TAKE the file.
<li>In UNIX, it can be a "kerbang" script and therefore run directly from
the shell prompt or as a cron job.
</ul><p>
We could have used command shortcuts like "rcd", "put", and "bye", but since
they can be ambiguous under certain circumstances, it is better to avoid them
in scripts; they are intended mainly for convenience during interactive use.
However, if you wish to use the shortcuts in a script, you can do it this way
(error handling omitted for brevity):
<p><pre>
local \%t ; Declare a local temporary veriable
assign \%t \v(ftp_getputremote) ; Save current FTP GET-PUT-REMOTE setting
set ftp get-put-remote ftp ; Choose FTP orientation
ftp xyzcorp.com /anonymous ; Open an FTP connection
get oofa.txt ; GET a file
put foo.bar ; PUT a file
rdel yesterday.log ; Delete a file on the server
bye ; Log out and disconnect from server.
set ftp get-put-remote \%t ; Restore previous GET-PUT-REMOTE setting
</pre><p>
Of course, FTP scripts can also be written as macros. This lets you pass
parameters such as hostnames, usernames, and filenames to them:
<p><pre>
define doftpget {
if < \v(argc) 4 end 1 Usage: \%0 host user remotefile [ localfile ]
ftp \%1 /user:\%2
if fail end 1 FTP OPEN \%1 failed
if not \v(ftp_loggedin) end 1 FTP LOGIN failed
ftp get {\%3} {\%4}
if fail end 1 FTP GET \%3 failed
ftp bye
}
</pre><p>
Add this definition to your Kermit customization file, and it will always
be available when you start Kermit (unless you start it in a way that bypasses
the normal initialization file). This macro lets you download a file with FTP
by giving a single command, e.g.:
<p><pre>
doftpget xyzcorp.com anonymous oofa.txt
</pre>
<p>
<a href="ftpscript.html">CLICK HERE</a> to visit the Kermit FTP script-writing
tutorial.
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<h3><a name="x3.11">3.11. Advanced FTP Protocol Features</a></h3>
FEAT and NLST are not supported by C-Kermit since they are not yet
standardized, nor can they be found in most FTP servers at this writing.
Similarly for the various mail-sending options.
<p>
[ <a href="#top"><b>Contents</b></a> ]
[ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
[ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
[ <a href="index.html"><b>Kermit Home</b></a> ]
<hr>
<address>
The Kermit Project / Columbia University / <a href="mailto:kermit@columbia.edu">kermit@columbia.edu</a> / 14 December 2000
</address>
</body>
</html>