3. The Kermit FTP Client

D R A F T

  As of: C-Kermit 7.1.199 Alpha.01
  This file last updated: 14 December 2000

  Copyright © 2000, Frank da Cruz and Christine M. Gianone.
  All rights reserved.

C-Kermit 7.1 includes a new built-in FTP client. This documant, which was extracted from the C-Kermit 7.1 update notes and converted to HTML for easy reading on the Web, contains preliminary FTP client documentation, pending publication of the next edition of Using C-Kermit. Familiarity with C-Kermit usage and commands is assumed. Section numbering is based on the original plain-text document.

   3.1. Making and Managing FTP Connections
      3.1.1. Kermit Command-Line Options for FTP
      3.1.2. The FTP Command-Line Personality
      3.1.3. The FTP URL Interpreter
      3.1.4. Interactive FTP Session Establishment
   3.2. Making Secure FTP Connections
   3.3. Setting FTP Preferences
   3.4. Managing Directories and Files
   3.5. Uploading Files With FTP
      3.5.1. FTP PUT Switches
      3.5.2. Update Mode
      3.5.3. Recovery
   3.6. Downloading Files With FTP
      3.6.1. FTP GET Switches
      3.6.2. Filename Collisions
      3.6.3. Recovery
   3.7. Translating Character Sets
      3.7.1. Character Sets and Uploading
      3.7.2. Character Sets and Downloading
   3.8. FTP Command Shortcuts
   3.9. Dual Sessions
   3.10. Automating FTP Sessions
      3.10.1. FTP-Specific Variables and Functions
      3.10.2. Examples
   3.11. Advanced FTP Protocol Features

[ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.1. Making and Managing FTP Connections

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.

A Kermit FTP session can be established by command-line options, by URL, or by interactive commands.

3.1.1. Kermit Command-Line Options for FTP

The new command-line option '-9' (sorry, we're out of letters) can be used when starting C-Kermit, telling it to make an FTP connection: 

  kermit -9 hostname

or if a non-default FTP port is needed: 

  kermit -9 hostname:port

You can also specify the username on the command line with the -M ("My User ID") option that was already there for other connection types: 

  kermit -9 hostname -M olga

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).

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 -S ("Stay") option on the command line.

Other Kermit command-line options that are not specific to non-FTP connections should affect the FTP session in the expected ways; for example, -i and -T force binary and text mode transfers, respectively.

File transfers can not be initiated on the "kermit -9" command line; for that you need to use Kermit's FTP personality (next section).

3.1.2. The FTP Command-Line Personality

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: 

  ftp [ options ] hostname [ port ]

In this case the options are like those of a regular FTP client: 

  -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.

and the hostname can also be a URL (explained in Section 3.1.3). To specify a non-default TCP port for the FTP server, include the port number or name after the hostname.

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 -n option. These are not available with regular FTP clients, and at least one of these options (-g) conflicts with UNIX ftp (where -g 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: 

  -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]

[1] Same as Kermit, not available in regular FTP clients.
[2] Conflicts with Kermit, not available in regular FTP clients.
[3] Same as Kermit, conflicts with regular FTP clients.

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.

The following security options are also available, explained in Section 3.2: 

  -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]

If you include -A or specify a name of "anonymous" or "ftp", you are logged in anonymously and, in the absence of -P, Kermit automatically supplies a password of "user@host", where "user" is your local user ID, and "host" is the hostname of the computer where Kermit is running. If you do not include -p or -g, Kermit enters command mode so you can type commands or execute them from a script.

If you include -p or -g, Kermit attempts to transfer the specified files and then exits automatically at the end of the transfer unless you also included -S (Stay). It uses the "brief" file transfer display (one line per file) unless you include the -q option to suppress it.

When uploading files with -p, Kermit switches automatically between text and binary mode for each file.

When downloading, you should always specify the desired mode, and there is no per-file mode switching (see Sections 3.5 and 3.6 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).

It should go without saying that the -P 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 ps and w 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.

Here's an example in which you download the latest C-Kermit "tarball" from the Columbia University FTP archive: 

  ftp -A kermit.columbia.edu -bg kermit/archives/ckermit.tar.gz

This assumes that "ftp" is a symbolic link to C-Kermit. It logs you in anonymously and gets the ckermit.tar.gz file in binary mode from the kermit/archives directory.

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): 

  ftp -A kermit.columbia.edu -D kermit/f -ag "ck[cuw]*.[cwh]" makefile

In this case we CD to the kermit/f directory so we don't have to include it in each file specification, and we quote the ck[cuw]*.[cwh] 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.

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): 

  ftp -A kermit.columbia.edu -D kermit/incoming -bp debug.log

In this case the -D option is required to tell the server where to put the incoming file.

Unless the -Y option is included, your Kermit initialization file (.kermrc in UNIX, K95.INI in Windows) is executed before the command line options, so you can set any FTP-related preferences there, as described in the subsequent sections.

3.1.3. The FTP URL Interpreter

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:
ftp ftp://user:password@host/path
ftp ftp://user@host/path
ftp ftp://host/path

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:

If no path (and no action options) are included, an interactive FTP session is started, as in this example:
ftp ftp://kermit.columbia.edu/

If a path is included, but a username is not included, "anonymous" is used and an appropriate user@host 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 -S option on the command line).

Here's an example that gets a listing of the top-level directory at the Kermit ftp site:
ftp ftp://kermit.columbia.edu/kermit/

This example gets the top-level READ.ME file from the same directory:
ftp ftp://kermit.columbia.edu/kermit/READ.ME

Here's the same example, but requesting a text-mode transfer:
ftp -T ftp://kermit.columbia.edu/kermit/READ.ME
This illustrates that you can mix command-line options and URLs if you desire.

Here's an example that logs in as a (fictitious) real user to get a file:
ftp ftp://olga@ftp.xyzcorp.com/resume.txt
The password is not included, so Kermit prompts for it.

3.1.4. Interactive FTP Session Establishment

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. CLICK HERE if you would like to learn a bit more about script writing.

An FTP session is established with the FTP OPEN command:

FTP [ OPEN ] hostname [ switches ] [ port ]
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 "ftp ?").

The hostname can be an IP host name, numeric IP address, or if you have a network directory active (SET NETWORK DIRECTORY; see Using C-Kermit), 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.

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.

The optional FTP OPEN switches are:

/ANONYMOUS
Logs you in anonymously, automatically supplying username "anonymous" and user@host as the password, based on your local user and host names.

/USER:name
Uses the given username to log you in, thus avoiding the Name: prompt.

/PASSWORD:text
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.

/ACCOUNT:text
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.

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.

Examples: 

  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

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.

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 Section 3.8 for details).

When your FTP session is complete, you can terminate it as follows:

FTP BYE
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 Section 3.8 for details). If a connection log is active, an FTP record is written to it. If Kermit was started with the -9 command-line option or with its FTP command-line personality, and the -S (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.

The following commands can be used to achieve greater control over the connection and login process:

SET FTP AUTOLOGIN { ON, OFF }
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 -n command-line option when using Kermit's FTP command-line personality.

FTP USER name [ password [ account ] ]
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.

FTP ACCOUNT text
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.

Example: 

  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

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.

FTP RESET
Terminates a user session but leaves the connection open, allowing a new login via FTP USER.

FTP IDLE [ number ]
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.

FTP STATUS
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.

FTP SYSTEM
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.

FTP HELP [ keyword [ keyword [ ... ] ]
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".

FTP SITE text
(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.

FTP QUOTE text
(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.

SHOW FTP
Lists client (Kermit) FTP settings and information. Also SHOW CONNECTION, SHOW COMMUNICATIONS.

HELP FTP [ keyword ]
Asks Kermit to list and describe its built-in FTP commands.

HELP SET FTP [ keyword ]
Asks Kermit to list and describe its built-in SET FTP commands.

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.2. Making Secure FTP Connections

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.

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.

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.

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:

SET FTP AUTHTYPE { AUTOMATIC, GSSAPI-KRB5, KERBEROS4, SRP, SSL, TLS }
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.

SET FTP AUTOAUTHENTICATION { ON, OFF }
Tells whether authentication should be negotiated by the FTP OPEN command. Default is ON.

SET FTP AUTOENCRYPTION { ON, OFF }
Tells whether encryption (privacy) should be negotiated by the FTP OPEN command. Default is ON.

SET FTP COMMAND-PROTECTION-LEVEL { CLEAR, CONFIDENTIAL, PRIVATE, SAFE }
Determines the level of protection applied to the command channel: 

  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.

The default is PRIVATE.

SET FTP CREDENTIAL-FORWARDING { ON, OFF }
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.)

SET FTP DATA-PROTECTION-LEVEL { CLEAR, CONFIDENTIAL, PRIVATE, SAFE }
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.

SET FTP SRP CIPHER name
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: 

  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

The default is CAST5_CBC.

SET FTP SRP HASH name
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.

Command-line options:

-k name
Specifies the realm to be used with Kerberos 4 authentication (= SET AUTH K4 REALM name).

-f
Enables forwarding of Kerberos 5 credentials to the host when using GSSAPI authentication (= SET AUTH K5 FORWARDABLE ON).

-x
Enables autoencryption (= SET FTP AUTOENCRYPTION ON).

-c cipher
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.

-H hash
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.

-z debug
Turns on SSL/TLS debugging.

-z secure
Requires secure connection.

-z certsok
Says to accept all certificates without checking validity.

-z verify=n
Sets certificate verification mode to the given number, n: 
  0 = no verification
  1 = verify certificate if presented
  2 = require verification of certificate

-z cert=filename
Specifies a file containing a client certificate to be presented to the FTP server.

-z key=filename
Specifies a file containing a private key matching the client certificate.

-z !krb4
nokrb4 Disables the use of Kerberos 4.

-z !gss
-z nogss
Disables the use of GSSAPI - Kerberos 5.

-z !srp
-z nosrp
Disables use of SRP.

-z !ssl
-z nossl
Disables the use of SSL.

-z !tls
-z notls
Disables the use of TLS.

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.3. Setting FTP Preferences

You can control the amount of feedback received from your FTP session with the following commands:

SET TRANSFER DISPLAY { FULLSCREEN, CRT, SERIAL, BRIEF, NONE }
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 -q).

While a file-transfer is in progress, you can interrupt it in the normal Kermit ways: 

  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).

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.

SET QUIET { ON, OFF }
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.

SET FTP ERROR-ACTION { PROCEED, QUIT }
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).

SET FTP CHARACTER-SET-TRANSLATION { ON, OFF }
Whether to translate character sets when transferring text files with FTP (explained in Section 3.7). OFF by default.

SET FTP SERVER-CHARACTER-SET name
Tells Kermit the character set used by the FTP server (Section 3.7).

SET FTP PERMISSIONS { AUTO, ON, OFF }
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.

SET FTP PROGRESS-MESSAGES { ON, OFF }
Tells whether Kermit should print locally-generated feedback messages for each non-file-transfer command. ON by default.

SET FTP VERBOSE-MODE { ON, OFF }
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.

SET FTP DEBUG { ON, OFF }
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.

Set all of these to OFF (or NONE) when silent running is desired.

SET FTP AUTOLOGIN { ON, OFF }
Described in Section 3.1.

SET FTP FILENAMES { AUTO, CONVERTED, LITERAL }
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.

SET FTP UNIQUE-SERVER-NAMES { ON, OFF }
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 (.) and a number to the name.

SET FTP COLLISION { ... }
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 Section 3.6.2 for details.

SET FTP PASSIVE-MODE { ON, OFF }
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.

SET FTP SEND-PORT-COMMANDS { ON, OFF }
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.

SET FTP TYPE { TEXT, BINARY }
Changes the default transfer mode. When sending (uploading) files, this command has no effect unless you disable automatic text/binary mode switching (Section 4) 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.

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.4. Managing Directories and Files

In Kermit, commands for directory and file management can refer to:

(There can also be an HTTP connection, but the commands in this section don't apply to HTTP connections.)

Thus in general, each such command comes in three forms:

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 Section 3.8). In most FTP clients, on the other hand, unprefixed commands are for the server, and local commands require a prefix.

Kermit's FTP file and directory management commands are:

FTP CD [ directory ]
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).

FTP UP
Tells the FTP server to change its default (working) directory to the parent directory of its current one (equivalent to "cd .." in UNIX, or "cd [-]" in VMS).

FTP PWD
Asks the FTP server to report ("print") its current working directory.

FTP MKDIR directory
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.

FTP RMDIR directory
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.

FTP DIRECTORY [ filespec ] [ redirectors ]
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 (Using C-Kermit, Chapter 11). Examples: 

    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"

FTP MODTIME filename
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).

FTP SIZE filename
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.

FTP CHMOD permissions filename
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): 

  ftp chmod 664 oofa.txt

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.

FTP UMASK [ number ]
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.

FTP RENAME filename newname
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).

FTP DELETE [ switches ] filespec [ filespec [ ... ] ]
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: 

 /ERROR-ACTION:  /FILENAMES:     /NOBACKUPFILES  /QUIET
 /EXCEPT:        /LARGER-THAN:   /NODOTFILES     /RECURSIVE
 /SMALLER-THAN:

For details, see the decriptions of these switches in Section 3.6. Synonym: FTP MDELETE (Kermit makes no distinction between DELETE and MDELETE).

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.5. Uploading Files With FTP

Uploading means sending files from the client (Kermit) to the FTP server. The basic command for uploading files with FTP is PUT:

FTP PUT [ switches ] [ filespec [ as-name ] ]
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).

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.

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: 

  http://www.columbia.edu/kermit/ckermit2.html#x4.9

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 Section 3.5.1.

FTP MPUT [ switches ] filespec [ filespec [ ... ] ]
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.

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.

FTP uploads may be interrupted just like Kermit uploads. While the transfer is in progress, type: 

  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.

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: 

  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

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: 

  ftp put oofa.txt budget.txt    ; Send oofa.txt AS budget.txt
  ftp mput oofa.txt budget.txt   ; Send oofa.txt AND budget.txt

If the source file specification includes any path segments, for example: 

  put /tmp/oofa.txt
  put subdir/another/andanother/oofa.txt

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: 

  ftp put /usr/doc/oofa.txt      ; Send as "oofa.txt".
  ftp put oofa.txt /tmp/oofa.txt ; Send as "/tmp/oofa.txt"

The latter example sends the file oofa.txt 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.

3.5.1. FTP PUT Switches

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: 

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

Most of these switches are common to Kermit's SEND and MSEND commands, so are described only briefly here. For greater detail see: 

  http://www.columbia.edu/kermit/ckermit2.html#x1.5 (explanation of switches)
  http://www.columbia.edu/kermit/ckermit2.html#x4.7 (file-transfer switches)

First the file-selection switches:

/AFTER:date-time
/BEFORE:date-time
/NOT-AFTER:date-time
/NOT-BEFORE:date-time
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:
  ftp put /after:{1 jan 2000 0:00:00} *
  ftp put /after:-5days *

/LARGER-THAN:number
/SMALLER-THAN:number
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.

/TYPE:{TEXT,BINARY}
Only send files that are the given type, which is determined for each file just before sending it by file scanning.

/[NO]DOTFILES
[Don't] include files whose names begin with dot (.). By default, such files are not included unless your filespec explicitly mentions them.

/NOBACKUPFILES
Don't include files whose names end with .~nnn~, where nnn is a number. These are backup files created by Kermit, EMACS, and other applications. By default, backup files are included.

/EXCEPT:pattern
Exception list -- don't send files whose names match the given pattern. See http://www.columbia.edu/kermit/ckermit.html#x1.5.4 for details.

/RECURSIVE
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 (Section 4) and character-set translation (Section 3.7). Synonym: /SUBDIRECTORIES.

/UPDATE
Send only files that have changed since last time (Section 3.5.2).

/ARRAY:arrayname
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: 
  ftp put /as-name:array.txt /array:&a
(or, to send a segment of the array, /array:&a[100:199]). If you don't include an /AS-NAME, a name of "_array_x_" is used (where x is the array letter). If you include this switch, most other switches are meaningless and ignored.

/COMMAND
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: 
  ftp put /command /as-name:{userlist} {finger | sort -r}

/LISTFILE:filename
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.

Now the other switches:

/AS-NAME:text
If a single file is being sent, send it with the given text as its name. If multiple files are being sent, the text must be a template that includes variables such as \v(filename), \v(filenumber), \v(ntime), 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.

/BINARY
/TEXT
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.

/FILTER:command
Specifies that the file(s) is/are to be passed through the given command or pipeline on their way to the server. Example: 

  ftp put /binary /filter:{gzip -c \v(filename)} /as-name:\v(filename).gz *

/TRANSPARENT
/LOCAL-CHARACTER-SET:name
/SERVER-CHARACTER-SET:name
Character-set translation for text files, explained in Section 3.7.

/ERROR-ACTION:{PROCEED,QUIT}
Overrides the prevailing FTP ERROR-ACTION for the duration of this PUT or MPUT command only.

/RECOVER
Resume an interrupted transfer where from the point of interruption (explained in Section 3.5.2). Synonym: /RESTART.

/DELETE
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.

/MOVE-TO:directory
Tells Kermit to move each source file to the named local directory after, and only if, it has been uploaded completely and successfully.

/RENAME-TO:template
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.

/FILENAMES:{AUTOMATIC,CONVERTED,LITERAL}
Overrides the FTP FILENAMES setting for this upload only.

/PERMISSIONS:{ON,OFF}
Overrides the FTP PERMISSIONS setting for this upload only.

/UNIQUE
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.

/QUIET
Don't display file-transfer progress or statistics.

3.5.2. Update Mode

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: 

  cd source-directory
  ftp computerb.xyzcorp.com
  ( authentication details... )
  ftp cd target-directory
  ftp put [ switches ] *

But if the total size is large or the network slow, this would be unnecessarily time-consuming. By including the /UPDATE switch: 

  ftp put /update [ other-switches ] *

only those files that changed since last time are uploaded. Here's how it works. For each local file that is selected for uploading:

All time comparisons take place in Coordinated Universal Time (UTC)(1), also known as GMT or Zulu time: Timezone 0; standard time, without daylight savings.

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 (Section 3.6), it will be transferred for the same reason.

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.

If a transaction log is active, a notation is included for any files that are skipped.

(1) Why is Coordinated Universal Time abbreviated UTC? From the National Institute of Standards and Technology FAQ: "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."

3.5.3 Recovery

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:

Here's how it works. When you include the /RECOVER switch:

If the switch is accepted, then for each selected file:

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.

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.

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.

A word of caution, however, when the original upload was in text mode with character-set translation (Section 3.7):

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.

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.6. Downloading Files With FTP

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:

The commands for downloading are:

SET FILE DOWNLOAD-DIRECTORY [ directory ]
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.

FTP GET [ switches ] filename [ as-name ]
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").

FTP MGET [ switches ] filespec [ filespec [ filespec [ ... ] ] ]
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.

In both the FTP GET and MGET commands, any filenames that contain spaces must be enclosed in braces or doublequotes (see Section 5 for details).

FTP downloads may be interrupted just like Kermit uploads. While the transfer is in progress, type: 

  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.

3.6.1. FTP GET Switches

The following switches are available with FTP GET and MGET:

/TEXT
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.

/BINARY
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.

/RECOVER
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 Section 3.6.3 for details. Synonym: /RESTART.

/FILENAMES:{CONVERTED,LITERAL}
Overrides the FTP FILENAMES (filename conversion) setting for this download only.

/AS-NAME:text
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 \v(filename) or \v(filenumber). Example: 

  mget /text /as-name:\v(filename).new *.c

This gets all ".c" files and stores them with ".new" appended to their names. See http://www.columbia.edu/kermit/#x4.1 for details.

/COMMAND
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 \v(filename). See the description of the regular Kermit GET /COMMAND command for details and examples.

/QUIET
Transfer the files quietly; don't put up a file-transfer display.

/ERROR-ACTION:{QUIT,PROCEED}
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.

The file selection switches are:

/EXCEPT:{pattern} or /EXCEPT:{{pattern}{pattern}{...}}
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).

/SMALLER-THAN:number
Download only files whose size is smaller than the given number of bytes. Requires that the FTP server support the SIZE command.

/LARGER-THAN:number
Download only files whose size is greater than the given number of bytes. Requires that the FTP server support the SIZE command.

/NOBACKUPFILES
During MGET, don't download any files whose names end with backup suffixes (.~n~ where n is a number).

/NODOTFILES
During MGET, don't download any files whose names begin with period (.). Equivalent to /EXCEPT:{.*}.

/LISTFILE:filename
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.

/UPDATE, /COLLISION:keyword
Explained in Section 3.6.2.

/RECURSIVE
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.

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 "mget /recursive *.txt" descends only into those subdirectories whose names end with ".txt", which is probably not what you wanted, whereas "mget /recursive *" does the whole tree.

When used with FTP DELETE, the /RECURSIVE switch deletes files but not directories.

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.

Source-file disposition switches:

/DELETE
Each file that is downloaded successfully is to be deleted from the server. Requires the appropriate file access rights on the server.

Destination-file disposition switches:

/TO-SCREEN
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. 

    get /text /to-screen /filter:more oofa.txt

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).

/RENAME-TO:text
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 \v(filename) variable contains the name of the current file, so: 

  ftp mget /rename-to:\v(filename).ok *

causes each file that is successfully downloaded to have ".ok" appended to its name. For details see http://www.columbia.edu/kermit/ckermit2.html#x4.1.

/MOVE-TO:text
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.

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.

3.6.2. Filename Collisions

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 Using C-Kermit. 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.

The name under which an incoming file is to be stored is determined as follows:

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:

SET FTP COLLISION { BACKUP, RENAME, UPDATE, DISCARD, APPEND, OVERWRITE }
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.

FTP GET /COLLISION:{BACKUP,RENAME,UPDATE,DISCARD,APPEND,OVERWRITE}
Overrides the current FTP COLLISION action for this download only.

FTP GET /UPDATE
This is equivalent to GET /COLLISION:UPDATE, and is included for symmetry with PUT /UPDATE

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).

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.

(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.)

3.6.3. Recovery

Recovery is available for downloads too, but there are some differences from the uploading case described in Section 3.5.3:

Here's how download recovery works:

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.

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).

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.7. Translating Character Sets

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:

SET FTP CHARACTER-SET-TRANSLATION { ON, OFF }
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.

SET FTP SERVER-CHARACTER-SET name
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.

SET FILE CHARACTER-SET name
This is the regular Kermit (non-FTP-specific) command for identifying the character set (to be) used in local text files.

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.

3.7.1. Character Sets and Uploading

Kermit's PUT and MPUT commands include full file-scanning capabilities, as described in Section 4. 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.

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: 

  set ftp server-character-set ?
  set file character-set ?

A typical list looks like this: 

  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>

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.

In addition to the SET commands listed above, the FTP PUT and MPUT commands include switches that apply only to the current command:

/LOCAL-CHARACTER-SET:name
/SERVER-CHARACTER-SET:name
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.

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.

When uploading, the FILE CHARACTER-SET setting is ignored unless you have forced Kermit not to scan local files (see Section 4). Examples:

Suppose you have a CP852 (East European) text file that you want to upload and store in ISO Latin Alphabet 2 encoding: 

  ftp put /local-char:cp852 /server-char:latin2 magyar.txt

Suppose you always want your text files converted to Latin-2 when uploading with FTP. Then put: 

  set ftp server-character-set latin2

in your Kermit customization file, and then you can omit the /SERVER-CHARACTER-SET: switch from your FTP PUT commands: 

  ftp put /local-char:cp852 magyar.txt

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: 

  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

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: 

  ftp put *.txt

And since binary files are also detected automatically, this can be simplified to: 

  ftp put *

even when "*" matches a diverse collection of binary and text files, because translations are skipped automatically for binary files.

3.7.2. Character Sets and Downloading

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: 

  mget /text /server:latin1 /local:utf8 *.txt

This command:

3.7.3. RFC2640

RFC2640, 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.

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.8. FTP Command Shortcuts

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:

SET GET-PUT-REMOTE { AUTO, KERMIT, FTP }
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.

Here is a complete list of affected commands: 

 Kermit Command               FTP Equivalent
  (none)                       FTP [ OPEN ]
  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

The commands in the right-hand column always access FTP. The commands in the left column can access either Kermit protocol or FTP:

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: 

 Client   Server      Change Local Directory     Change Remote Directory
  FTP      FTP         lcd                        cd (cwd)
  Kermit   Kermit      cd                         rcd, remote cd
  Kermit   FTP         cd                         ftp cd, rcd, remote cd

Also note that not all REMOTE commands are useful with FTP, since FTP servers do not offer the corresponding functions. These include: 

  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

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.9. Dual Sessions

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. 

  ftp foo.bar.baz.com
  if fail ...
  (log in)
  set host foo.bar.baz.com
  if fail ...
  (log in)

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: 

  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

Note that PUT and SEND are synonyms for both FTP and Kermit connections.

You can also establish dual sessions on the Kermit command line: 

  kermit -j host1 -9 host2

This makes a Telnet connection to host1 and an FTP connection to host2.

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.10. Automating FTP Sessions

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.

3.10.1. FTP-Specific Variables and Functions

The following variable tells whether an FTP connection is open:

\v(ftp_connected)
1 if there is an active FTP connection, 0 if there isn't.

The FTP OPEN command sets:

\v(ftp_host)
The host to which the most recent FTP connection was made.

\v(ftp_server)
The OS type (UNIX, VMS, etc) of the FTP server host.

The FTP USER command (or FTP OPEN /USER:, or FTP with automatic login) sets:

\v(ftp_loggedin)
1 if you are logged in to an FTP server, 0 if you are not.

plus the following, which apply to Kermit's secure authentication methods: 

 \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.

The FTP GET-PUT-REMOTE setting is reflected in: 

 \v(ftp_getputremote)

Every FTP command sets the \v(success) variable, as well as the following two FTP-specific variables:

\v(ftp_code)
The standardized numeric FTP protocol code from the server's response to the last client command, a 3-digit decimal number defined in RFC959. Briefly: 

1xx = Positive Preliminary Reply
2xx = Positive Completion Reply
3xx = Positive Intermediate Reply
4xx = Transient Negative Completion Reply
5xx = Permanent Negative Completion Reply

\v(ftp_msg)
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.
FTP file transfers set the regular Kermit transfer status variables: 

  \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.

During an FTP transfer, the per-file variables are: 

  \v(filename)    Name of current file.
  \v(filenumber)  Ordinal file number in group (1, 2, 3, ...)

*** Macros to bundle settings for different servers ***

3.10.2. Examples

Let's begin with a simple example showing how to log in, send some files, and log out: 

  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

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.

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.

Finally we close the FTP session with the "bye" command.

Just like any other Kermit script, this one can be used in many ways:

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): 

  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

Of course, FTP scripts can also be written as macros. This lets you pass parameters such as hostnames, usernames, and filenames to them: 

  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
  }

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.: 

  doftpget xyzcorp.com anonymous oofa.txt

CLICK HERE to visit the Kermit FTP script-writing tutorial.

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

3.11. Advanced FTP Protocol Features

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.

[ Contents ] [ C-Kermit 7.1 ] [ C-Kermit Home ] [ Kermit Home ]

The Kermit Project / Columbia University / kermit@columbia.edu / 14 December 2000