The Kermit Project
Columbia University
http://www.columbia.edu/kermit/
As of: C-Kermit 8.0, 12 Dec 2001
This page last updated: 23 March 2003
The Internet Kermit Service Deamon (IKSD) is C-Kermit 7.0 or later, started in a special way. At this writing, only the UNIX version of C-Kermit can act as IKSD, but IKSD will also be available soon in the Windows version, and can be added to the VMS, VOS, and other versions if there is sufficient demand. The Internet Kermit Service is specified in RFC2839 and RFC2840.
1. Why IKSD? 2. System Configuration 3. Compile-Time Configuration Options 4. Runtime Configuration Options 4.1. Command-Line Options 4.2. System Logging 4.3. The IKSD Log File 4.4. IKSD Configuration File 4.5. Initialization File 5. Access to Services 5.1. Automatic Settings 5.2. Authentication 5.3. The DISABLE Command 5.4. Shell Access 5.5. Anonymous Users 5.6. Management Information 6. Open Issues 6.1. Connection Establishment 6.2. Shell Access 6.3. External and/or non-Kermit Protocols 6.4. Additional Administrative Controls 6.5. Known Bugs 7. Monitoring 7.1. Database Record Format 7.2. The Display Module 7.3. Database Management 8. Testing
A prototype IKSD is available for public access at:
kermit.columbia.edu port 1649
This service is based in part on a new Telnet Kermit Option described in
RFC2839 RFC2840
Directory organization, file system, naming conventions, and other administrative details vary from system to system and site to site, so specific instructions can not be given here. In general, however, the steps are:
kermit 1649/tcp
kermit stream tcp nowait root iksd -A other-iksd-options
Or, with TCP wrappers:
kermit stream tcp nowait root tcpd iksd -A other-iksd-options
Include full pathnames for tcpd and iksd if required. See Section 4 for iksd-options. NOTE: Different platforms might require different syntax, e.g.:
kermit stream tcp nowait root /usr/sbin/iksd iksd -A other-iksd-options
This setup allows multiple simultaneous IKSD sessions. A fresh IKSD process is started for each session, and disappears when IKSD exits, automatically closing the session and the connection.
To kill a particular instance of IKSD, find its pid with "ps ax | grep iksd" (or the equivalent command to list all processes) and then "kill -9 pid" (as root).
To update the IKSD program, simply replace the executable in the "launch" directory ((a) above).
To discontinue IKSD service quickly, delete the iksd executable, or (to avoid unwanted console logging) replace it with (say) /bin/false.
The following compile-time options are specific to or of special relevance to the IKSD:
In an IKSD-only build, you should omit the termcap/termlib and (n)curses libraries, and set up the link step to make sure the IKSD is linked with the same user authorization libraries used by your local login program. Here is a sample for SunOS 4.1.3 at a particular site:
sunos41giks: @echo Making C-Kermit $(CKVER) for SunOS 4.1 with gcc for IKS... $(MAKE) wermit "CC= gcc" "CC2= gcc" \ "CFLAGS= -O -DSUNOS41 -DNDGPWNAM \ -DTNCODE -DNOLOCAL -DNOPUSH $(KFLAGS)" \ "LIBS= -L/usr/local/lib -lpwent -lcrypt"
in which:
At sites that use shadow passwords, you'll need to add -DCK_SHADOW to CFLAGS and perhaps -lgen to LIBS.
Also note that the crypt() function, which is used for verifying passwords, is normally found in libc, but on some platforms it has been broken out into a separate library, such as -lcrypt, and in that case must be included in the LIBS clause.
For PAM installations, here's an example /etc/pam.d/kermit file that uses EPS password files for user authentication and the standard unix modules for account and session management:
auth required /lib/security/pam_eps_auth.so password required /lib/security/pam_eps_passwd.so account required /lib/security/pam_unix_acct.so session required /lib/security/pam_unix_session.so
Kerberos IV, Kerberos V, SRP, and TLS can also be selected at build time if you have the appropriate libraries and header files installed on your system. See the Kermit Security Reference for further details.
For a build that excludes all IKSD functions, it is normally sufficient to add NOIKSD to the CFLAGS, e.g.:
make aix41 KFLAGS=-DNOIKSD
In addition to -A and the command-line options described in Using C-Kermit (2nd Edition), plus any other new ones described in the C-Kermit 7.0 Update Notes and C-Kermit 8.0 Update Notes, a selection of new long-form options apply specifically to the IKSD. Long-form options work as follows:
The new long-form options are:
Option Values Default CM_PRE Effect
--anonymous on/off on yes anonymous login allowed
--bannerfile filename (none) no greeting message
-+cdfile filelist (see below) no CD message filename
-+cdmessage on/off on no CD messages on/off
-+cdmsg on/off on no synonym for cdmessage
--help (none) (n/a/) no list available --options
--helpfile filename (none) no custom text for HELP command
--initfile filename /.kermrc yes Init file for anonymous users
--nointerrupt (none) (see below) yes Disables SIGINT and SIGTSTP
--permissions octalnum 0040 yes anonymous upload permissions
--perms octalnum 0040 yes synonym for permissions
--root directory /pub/ftp yes root for anonymous users
--syslog number 3 yes level of syslogging
--timeout number 300 yes time limit for login
--userfile filename /etc/ftpusers yes forbidden local users list
--wtmplog on/off on yes wtmp logging on/off
--wtmpfile filename (see below) yes pathname of wtmp logfile
--xferlog on/off off yes use an ftpd-logfile
--xferfile filename (see below) yes pathname of ftpd-like logfile
Note: in all options that take a filename, except --cdfile, relative filenames or filenames that start with ~ are expanded to full pathnames.
In more detail:
--cdfile:READ.ME
You can also give a list of up to 8 filenames by (a) enclosing each filename in braces, and (b) enclosing the entire list in braces. Example: --cdfile:{{./.readme}{READ.ME}{aaareadme.txt}{README}{read-this-first}} When a list is given, it is searched from left to right and the first file found is displayed. The default list for UNIX is:
{{./.readme}{README.TXT}{READ.ME}}
Some of the traditional options have special significance in the IKS, e.g.:
Examples:
Bad syntax in an extended command-line option causes immediate termination with the message "Extended option error", and an exit status code of 1.
Brief help about command line options may be obtained at the C-Kermit prompt with "help options", and for extended options with "help extended-options".
You can prototype the IKSD command line by including any desired extended options, but omitting the -A option, and then when you get the C-Kermit> prompt, use "show extended-options" to check the parsing of the options you have included. Example:
$ kermit --anonymous:ok --root:/tmp --userfile:/etc/badusers (/users/olga/) C-Kermit>show extended-options --bannerfile=(null) --cdfile:./.readme --cdmessage:0 --syslog:3 --wtmplog:1 --wtmpfile=(null) --anonymous:1 --permission:0040 --initfile:(null) --userfile:/etc/badusers --root:/tmp --xferlog=0 --xferfile=(null) --timeout:300 (/users/olga) C-Kermit>
Note that this only shows the values that were given as arguments to the extended options, or their default values, if they have any, but it does not show values that will be computed dynamically at runtime in the absence of a command-line value. For example, --wtmplog:1 and --wtmpfile:(null) mean that an appropriate default will be supplied for the wtmp logfile name at runtime.
Also note that SHOW EXTENDED-OPTIONS does not show the IKSD-specific options when this command given at the IKSD prompt by the user. Thus this command is useful only as a prototyping tool. (And as noted elsewhere, the IKSD command-line argument vector is also inaccessible to the IKSD user via other methods such as the \&@[] array.)
All IKSD entries (except debugging, see below) appear in the daemon log, as defined in the syslog.conf file with a tag of "iksd" and the process ID (pid) of the IKSD process, and therefore can be extracted by grepping for "iksd".
The system logging levels are:
0 = no logging 1 = Login/out, failed login attempts, failed Kerberos (etc) authentication 2 = Dialing out (does not apply to IKSD) 3 = Making any kinds of connections (does not apply to IKSD) 4 = Creating / receiving / deleting / renaming / copying files 5 = Sending / typing / reading / transmitting files 6 = All top-level commands and all server commands sent to iksd 7 = Commands executed from macros and command files 8 = Debug
Each level includes all the levels beneath it (except 0 is not included if the logging level is greater than 0).
The default logging level is 5, and is used if the --syslog: option is not included on the command line, or if is given with an affirmative keyword (yes, true, on, ok) rather than a number. If you specify a number higher than the the maximum, it is the same as specifying the maximum.
Syslog entries are at LOG_INFO priority, except for refused logins, which are at LOG_NOTICE priority, and failed Telnet-level authentication (such as Kerberos), which are at LOG_ERR priority.
Note that if C-Kermit is built with -DSYSLOGLEVEL=n (where n is a number) on the cc command line, this turns on syslogging and hardwires it to the given level for all users. See ftp://kermit.columbia.edu/kermit/f/ckuins.txt for further info.
The transfer log has the same format as the wu-ftpd log, and so all the same scripts can be used to process it, collect statistics, etc. In fact, you can even have ftpd and iksd share the same log, in which case records will be intermixed.
The Transfer log can also be used in regular user-mode C-Kermit sessions.
The first field is fixed-length and contains spaces; subsequent fields are variable length, contain no spaces, and are separated by one or more spaces. The fields are:
When C-Kermit is started as IKSD, it always begins by reading the IKSD configuration file, if any. By default this is /etc/iksd.conf (you may change the definition at compile time by adding -DIKSDCONF=\"filename\" to CFLAGS). This file contains ordinary C-Kermit commands. Normally these would be SET or DISABLE commands. In case any commands in this file write to standard output, remember that IKSD's standard output is the connection to the client. For more ideas about what can go in the iksd.conf file, read the next section -- the difference is that when you put commands in the iksd.conf file, they apply not only to anonymous users, but to real users too. So, for example, if you want to disable uploads for all users, you could put DISABLE SEND in the iksd.conf file, whereas if you wanted to disable them only for anonymous users, you would put this command in the anonymous-user initialization file.
The IKSD configuration file is executed before the user logs in (or is otherwise authenticated), before the C-Kermit initialization file, and before any extended-format command line options that start with "--", but after any that are marked CM_PRE in the table in Section 4.1, or that start with "-+". Since execution occurs before login, the \v(user) variable is meaningless here.
For anonymous users, the default initialization file, if any, is .kermrc in the chroot'd file system. This default may be overridden with the --initfile:xxx command-line option. The system administrator may include commands in this file to disable selected services for anonymous users, e.g.:
disable delete ; Don't let anonymous users delete files disable send ; Don't let anonymous users send files
Of course, any Kermit commands at all may be included: settings, macro definitions, etc. (Also see Section 5.5.)
When the sysadmin specifies the initialization file, this allows a high degree of fine-grained control over who is allowed access to what commands and resources, using standard C-Kermit commands, functions, and variables. The following are particularly useful:
So, for example, if the sysadmin wishes to prevent user "olga" from using the IKS on Mondays, the initialization file could contain a command like:
if equal \v(user) olga -
if equal \v(nday) 1 -
exit 1 Sorry Olga - please come back another day
Or suppose it is desirable to block access from all xyzcorp.com hosts between 9:00am and noon:
if match \v(line) *.xyzcorp.com -
if lgt \v(time) 09:00:00 -
if llt \v(time) 12:00:00 -
exit 1 Sorry - Please come back after noon
Or suppose a certain user is to be allowed to GET files from the server, but not SEND, PRINT, or MAIL them:
xif equal \v(user) ivan {
disable send
disable print
disable mail
disable enable
}
Kermit 95 2.1 is shipped with support for all of the security options. The availability of various options is determined by the options selected at install time.
Instructions for building C-Kermit 8.0 with arbitrary combinations of security options are available in the C-Kermit Security documentation.
http://www.columbia.edu/kermit/security.htmlMost installations of IKSD utilize the TELNET START_TLS option to provide encrypted and integrity protected connections in conjunction with X.509 certificate based server-side authentication. START_TLS is often combined with Kerberos, Secure Remote Password, or X.509 client certificates to provide secure client side authentication. Username and Password prompts are issued over the TLS connection when secure authentication of the client is unavailable.
4.6.2. Configuring IKSD for use with TELNET START-TLS
- Retrieve or generate Server Side Certificate and Private Key
- In your IKSD configuration file, \v(common)IKSD.KSC (on Windows) or /etc/iksd.conf (on Unix), specify these options:
- To request or require the use of TLS, add:
SET TELOPT START-TLS {REQUESTED, REQUIRED}4.6.3. Configuring IKSD TELNET START-TLS utilizing X.509 Certificates
- Kermit supports the installation of both RSA and DSS certificates. If you have an RSA-based server certificate then you must specify the file containing the certificate as well as the file containing the private key. The private key file must not be encrypted; otherwise, it will not be able to be loaded by IKSD.
SET AUTH TLS RSA-CERT-FIL C:/OPENSSL/TELNETD-RSA.PEM SET AUTH TLS RSA-KEY-FIL C:/OPENSSL/TELNETD-RSA-KEY.PEM
- If your certificate is not directly signed by the Root CA, you will need to include the intermediary CA certificates in a Certificate Chain file:
SET AUTH TLS RSA-CERT-CHAIN-FILE C:/OPENSSL/TELNETD-RSA-CHAIN.PEM
- If you have an DSS-based server certificate then you must specify the file containing the certificate as well as the file containing the private key. The private key file must not be encrypted; otherwise, it will not be able to be loaded by IKSD.
SET AUTH TLS DSA-CERT-FIL C:/OPENSSL/TELNETD-DSA.PEM SET AUTH TLS DSA-KEY-FIL C:/OPENSSL/TELNETD-DSA-KEY.PEM
- If your certificate is not directly signed by the Root CA, you will need to include the intermediary CA certificates in a Certificate Chain file:
SET AUTH TLS DSA-CERT-CHAIN-FILE C:/OPENSSL/TELNETD-DSA-CHAIN.PEM
- If you wish to restrict the ciphers used to secure the connection you may do so with the SET AUTH TLS CIPHERS command. If you do not have any certificates at all to use, specify the use of Anonymous-Diffie-Hellman ciphers:
SET AUTH TLS CIPHERS ADH4.6.4. Configuring IKSD to accept Client Side Certificates
Read about these commands in http://www.columbia.edu/kermit/security.html for information on the details of how Certificates and CRLs are stored in files and directories for use with OpenSSL.
- If you wish to accept client certificates you must specify:
SET AUTH TLS VERIFY PEER-CERT
- If you wish to require the use of client certificates specify:
SET AUTH TLS VERIFY FAIL-IF-NO-PEER-CERTIn addition, you must configure where the validation information for the client side certificates is located. First, the location of the CA certificates for the validation chain must be specified. This is done with:
SET AUTH TLS VERIFY-FILE C:/OPENSSL/CA_CERTS.PEM SET AUTH TLS VERIFY-DIR C:/OPENSSL/CERTSThe location of Certificate Revocation Files must also be specified:
SET AUTH TLS CRL-FILE C:/OPENSSL/CRLS.PEM SET AUTH TLS CRL-DIR C:/OPENSSL/CRLSAlso, read the section on how to build C-Kermit for different methods of extracting the userid from the client certificate.
4.6.5. Configuring IKSD TELNET START-TLS Utilizing Kerberos 5 Tickets
When utilizing Kerberos 5 to authenticate the IKSD to the client you must specify the location of the Kerberos Keytab File:
SET AUTH KRB5 KEYTAB C:/ROOT/KEYTABand specify the use of KRB5 ciphers:
SET AUTH TLS CIPHERS KRB5NOTE: OpenSSL must have been built with support for MIT Kerberos 5.
Configuring IKSD to utilize TELNET AUTHENTICATION options:
- The TELNET AUTH options (KRB4, KRB5, SRP, NTLM) may be used either with or without the START-TLS option. If you wish to request or require the use of the AUTH option:
SET TELOPT AUTH {REQUEST, REQUIRED}
- To specify an authentication type(s) use:
SET TELNET AUTH TYPE type(s)where type(s) is one or more of KRB4, KRB5, SRP, NTLM.
5. Access to Services
The IKSD behaves at runtime just like the regular C-Kermit program, with any restrictions resulting from compile-time options, and with the differences noted in this section and in Section 4.5.1. Automatic Settings
When C-Kermit is started as an Internet Kermit Service, the following settings occur automatically:
- Login (authentication) is required.
- Shell access is disabled.
- Server-side Telnet negotiation is enabled.
- SET RELIABLE ON (see the C-Kermit 7.0 Supplement).
- FAST file-transfer settings, including "cautious" unprefixing.
- No flow control, no parity.
Items d-f can be overridden with command-line options and/or in the initialization file.
5.2. Authentication
The IKSD command prompt will not appear, and no commands may be given, before the user is authenticated.When the IKSD has been started without the '-x' command-line option, it issues a Username: prompt. The user may type a username at the prompt, in which case a Password: prompt is issued, and the user must enter a password. Three login attempts are allowed, with a pause enforced between each one. If all three fail, the connection is closed.
The user may also authenticate from the client by sending a [ REMOTE ] LOGIN command (again, only 3 tries are allowed), or by Telnet Authentication negotiations. Prior to authentication, the IKSD responds to only the following client commands:
[ REMOTE ] LOGIN [ REMOTE ] LOGOUT REMOTE HELP (or RHELP) REMOTE EXIT (or REXIT) BYEOnce authenticated, the user may not re-authenticate or change identities.
The connection persists until it is broken in any of the following ways:
- Client sends BYE or REMOTE EXIT (REXIT) or [ REMOTE ] LOGOUT to IKSD.
- Client sends FINISH to IKSD that has been started with "-x".
- User gives HANGUP or CLOSE command to the client.
- User gives EXIT, QUIT, or LOGOUT command at IKSD prompt.
The connection is also closed if the user exits from the client, but only if it was an end-to-end Telnet connection. There can be no guarantee that exiting from a serial communication program will close and hang up the serial connection.
5.3. The DISABLE Command
In the IKSD, the DISABLE command applies not only to client/server functions, but also to the corresponding commands when given at the prompt. For example, DISABLE DELETE disables not only REMOTE DELETE commands given from the client, but also DELETE commands given at the IKSD's command prompt, as well as implicit forms of file deletion, such as when the target of a COPY command is an existing file.The DISABLE ENABLE command is irreversible; once this command is given, the ENABLE command can not be re-enabled, and therefore no other disabled commands can be enabled either. ENABLE is DISABLEd automatically for anonymous users, so any DISABLE commands in the anonymous-user initialization file (Section 4.4) are also irreversible.
5.4. Shell Access
All forms of system and shell access are disabled in the IKS. Thus the user can not execute REMOTE HOST commands from the client, nor access the shell from the IKS command prompt via shell escapes (!), the RUN or PUSH command, or by specifying pipes or filters in file-transfer commands, or by pipe specifications in REMOTE commands, or in any other way. This is true even if the executable was built without the NOPUSH compile-time option.5.5. Anonymous Users
Anonymous users are allowed by default, but can be denied with --anonymous:no on the command line (Section 4.1).Anonymous users are handled in about the same way as they are by ftpd. Their effective user ID is set to "ftp" and their file-system access is restricted to the tree rooted at the home directory of the "ftp" user, normally /pub/ftp, via chroot. If /pub/ftp does not exist, login fails. In that case (or for any other desired reason), the anonymous root directory can be changed with the --root: option, e.g. --root:/tmp. Note that, unlike ftpd, iksd does not necessarily require any particular binaries (such as ls) to be in the chroot'd tree. DLLs might be another story, but so far these have not been needed, even with dynamically linked Kermit binaries (at least in Linux and Solaris). Should DLLs be a problem, use a statically linked Kermit binary (if possible), or install the needed DLLs in the anonymous root.
File access is according to user "ftp" and the directory and file permissions of the /pub/ftp tree. If anonymous uploads are to be allowed, then usually only specific directories (often with a name like "incoming") are given write permission, and any files that are created in such a directory have owner "ftp", with the group set to the group of the directory. As noted in Section 4.1, the permission for all files created by anonymous users is 0040 (group-read only), or whatever else the sysadmin has specified in the --permissions: command-line option.
Thus, if you already have a public ftp server, most likely everything is set up appropriately already">up appropriately already. If anonymous ftp is allowed (by the presence of a valid user "ftp" in your system's password file), it will be allowed also for IKSD unless explicitly disallowed on the IKSD command-line (or if /pub/ftp doesn't exist and you did not supply a --root: option on the command line).
In addition to the FTP-like restrictions, certain Kermit services are always denied to anonymous users. These include:
- PRINT (at IKSD prompt) and REMOTE PRINT (from client)
- MAIL (or SEND /MAIL) at IKSD prompt and from client.
- Creation of any logs (transaction, debug, packet, etc).
- No file may be deleted, including implicitly, e.g. by the COPY command.
- FILE COLLISION is set to RENAME and may not be changed.
The latter three provisions mean that anonymous users can not delete, overwrite, rename, or alter any existing files in any way, whether by file transfer or with the DELETE or RENAME command.
Note that IKSD, like FTPD, does not allow directory creation by anonymous users, even when file/directory permissions would otherwise allow it. To change this, add:
enable mkdir ; Enable directory creationto /pub/ftp/.kermrc (or whatever other initialization file you have designated for anonymous users with --initfile). Similarly for directory removal:
enable rmdir ; Enable directory removalOf course directories can be removed only if (a) they are empty, and (b) their permissions allow it.
5.6. Management Information
The command-line argument vector, normally accessible in the \&@[] array, the top-level \%0..9 variables, or by other means, is inaccessible to IKSD users. Thus IKSD clients can not discover the IKSD startup path or options, the logfile pathnames or directories, logging level, etc.
6. Open Issues
Several services that are normally provided by C-Kermit are not available when it is an Internet Kermit Service Daemon.6.1. Connection Establishment
If the user has access to the IKSD command prompt, why not allow her to "set host" or "set line" from there to another place? Obviously this would be a security risk if allowed for anonymous users. For authenticated users, it should be OK, but is not currently possible for Telnet connections since the IKSD is already a Telnet server on the incoming connection, and is not designed to conduct two separate Telnet sessions simultaneously. It might be possible to allow the user to make a dialout connection, but some coding and testing would be needed should this prove desirable.6.2. Shell Access
Shell access is forbidden to anonymous users for obvious reasons. From a security standpoint, it could be allowed for authenticated users, but there remains a technical obstacle: the absence of a terminal driver for the connection.6.3. External and/or non-Kermit Protocols
External protocols such as Zmodem can not be expected to perform any of the logging or security functions that are done by C-Kermit itself within its protocol and file modules. Thus external protocols are disabled in the IKSD. Plus the fact that such protocols are likely to be incompatible with Telnet connections in the first place. In more detail:
- When the user is 'anonymous' the file system is chroot'd, which means that any external executables must exist in the chroot'd file system. This leaves open the possibility that executables might be replaced by a different file of the same name that has been uploaded either on top of the existing file or just into the same directory. If "." is in the PATH for the process anything the user uploads with the name 'rz' or 'sz' might be executed in its place. Therefore, the IKSD does not use any external commands of any kind. Not 'ls', not 'cp', not 'df', not anything. To allow the execution of external programs is a major security hole in this setting.
- Most implementations of 'sz' and 'rz' are designed for remote use over a terminal connection. They expect to be run underneath a pseudoterminal (PTY). When IKSD is running there is no PTY. In fact, when IKSD is running there is only a raw socket; the IKSD handles all necessary Telnet protocol translations including Telnet Network Virtual Terminal (NVT) rules regarding quoting of Carriage Return and 0xFF depending upon the state of the BINARY Telnet option in each direction. 'sz' and 'rz' are completely incapable of performing these translations in either direction and any attempt to transfer a file with them will result in a transfer failure and the corruption of the data stream.
- IKSD supports encrypted sessions, in which case it handles the encryption and decryption itself; an external protocol module would not do this, and so could not be used on encrypted channels in any case.
6.4. Additional Administrative Controls
Certain options available in wu-ftpd are not implemented in iksd:
- Ability to select IKSD logging for real vs anonymous users.
- Ability to select IKSD logging for inbound vs outbound files.
- Currently all transfers are logged or not logged.
- Ability to allow/restrict chmod/delete/overwrite for anonymous users.
- Currently there is no command for changing file permissions.
- Guests may not delete files, period.
- FILE COLLISION is set to RENAME for guests and may not be changed since all the other options allow existing files to be altered.
- There is no way to grant these capabilities to guests.
- Ability to allow directory creation by anonymous users.
- Anonymous users may not create or remove directories.
- Ability to allow/specify CD messages on a per-directory basis.
- RFC931 authentication of remote (client) user (but wu-ftpd doesn't either).
These or other controls can be added if there is sufficient reason or demand.
6.5. Known Bugs
- When commands are logged in syslog, the EXIT command appears twice.
- wtmp entries show pids in hex due to length restrictions, so you'll need to convert them to decimal before using them with ps, kill, etc.
7. Monitoring
Unless you disable it, all IKSDs keep current session information in a shared database. The IKSD instances can be within one computer or running on any number of different computers that share the same file system on the same network. The database can be monitored by the sysadmin with a simple "systat"-like display program, which shows who is logged in, from where, and what they're doing. (The idea is easily adapted to other servers, such as FTP.) For maximum portability and reliability, the database is an ordinary file on disk.The IKSD database file should reside in its own directory (to avoid conflicts with other servers that might use the same filename conventions), and this directory and its files should be visible to the sysadmin without privileges (e.g. by group access) but hidden from the public for privacy reasons if other such logs (e.g. the ftpd log, syslog, etc) also are.
The database is a random-access file indexed by "slot number", which is self-assigned during a quick search at startup. Once a slot is claimed, there is no more searching; each IKSD updates its own slot in place and does not touch the others. Slots never move.
When an IKSD instance starts, it must obtain a "slot allocation lock" before it can claim its slot. Otherwise there could be a race condition when another IKSD instance starts at the same time, in which the two could wind up with the same slot.
Since exclusive access is a nonportable concept, we obtain the lock in a crude but portable manner, without recourse to kernel locks, interprocess communication, semaphores, memory-mapped files, or other platform-specific mechanisms:
- Create a temp file in the database directory called ip.pid,, where ip is the local IP address as 8 hex digits and pid is my own process ID (PID) in hex (no leading zeros). This is guaranteed to be a unique name (and if by chance a file of this name already exists, it can't possibly be valid, so it it's ok to overwrite it).
- Write my own ID string into the file. The ID string is ip:pid, where ip is (again) my IP address as 8 hex digits, and pid is my PID in decimal (not hex). (The reason for decimal here is readability, so sysadmins can easily enter it into other tools or commands; it has to be hex in the temp filename for compactness in case of 14-character filename limitations.)
- Try to open iksd.lck, which is the real lockfile. If this succeeds, read its contents (an ip:pid string). If the ip not the same as mine, consider the file locked. If it is the same, extract the PID and check its validity. If it is not valid, delete the lockfile. (Currently this step is skipped by K95 since it can't check PIDs.)
- At this point the iksd.lck file might or might not exist. Try to rename the temp file to iksd.lck. This will fail if the lockfile exists, in which case we sleep, loop, and try again, up to a certain number of times -- say 16 tries spaced 1 second apart. If we fail to get a lock, we let the user on anyway, in the spirit of service over management. If the rename succeeds, on the other hand, we have a lock.
When and if we have obtained a lock, we open the database file itself and search the whole database (sequentially) for:
(*) In-Use flag is 1 and IP address is ours, but PID is invalid.
- Free slots (In-Use flag is 0), or:
- Stale slots(*), or:
- Any slot with our own IP and PID (a special kind of stale slot).
In C-Kermit only (not K-95) we also perform some housekeeping duties while searching (the Windows APIs include no provisions for this):
- Whenever a stale slot is found, we free it (set its In-Use flag to 0).
- We remove all free slots after the last in-use slot by truncating the database file (this keeps the database file from constantly growing as new highwater marks are reached).
Then we claim the first one of these that was found. If no slot was claimed, we add a new slot at the end and claim it. If the database file did not exist, we create it and claim the first slot. (In Windows, the IKSD listener simply deletes the existing database, if any, on initial startup.)
To claim a slot:
- We set the In-Use flag to 1, fill in the Server PID and IP address fields with our own PID and IP address, fill in the session-start and update time fields, and clear the other fields.
- Then we release the lock.
From this point, we can write freely into our slot regardless of locks.
Notes:
- Since all IKSDs follow the same procedure, only one can have a lock a at a time.
- The lockfile is readable text; it can be typed (cat'd). The contents are the same format on every platform, regardless of byte order or word size.
- This scheme allows (but does not require) multiple computers that share a common file system to have a single IKSD database, which in turn allows the site manager to monitor all IKSDs on all computers at once. This works if each computer has a unique IP address (which it must if they are on the same network sharing a common file system; nevertheless, care must be taken regarding IP address pools, etc). It also depends on the file- sharing mechanism (such as NFS) to propogate updates promptly and in sequence.
- While one IKSD is allocating its slot, nothing prevents other IKSD instances that already have their own slots from updating them, since that does not interfere with slot allocation.
- The tempfile name format is UNIXish and will need modification for file systems with restrictive names, such as FAT, 14-char UNIXes, etc. In such cases we could (a) omit the IP address if we're not concerned about multiple computers sharing a single database, or (b) encode the IP address in Base 64 to make it shorter. But probably none of this will ever come up.
- The design accommodates 64-bit IPv6 addresses, but for now the software uses only 32 bits.
7.1. Database Record Format
A slot is 4K (4096 octets), divided into 4 1K chunks. The first chunk is further subdivided into shorter fields. Numeric fields are coded in hexadecimal, right-adjusted, and left-padded with 0's. Text fields are left-adjusted and right-padded with blanks. Date-time fields are right-adjusted within a field of 18 with the leading blank reserved for Y10K. Date-time format is:yyyymmdd hh:mm:sswhere yyyymmdd are the numeric year, month, and day, and hh:mm:ss are the hour (24-hour clock), minute, and second. Months and days are 1-based, leading 0's are supplied where needed.
The layout of each slot is as follows (fields and byte positions are numbered from 0):
0. FLAGS (Slot/Session Flags) Start: 0 Length: 4 Type: Bit Mask Format: Hex digits. Bit Values: 1: 1 = Slot in use, 0 = Slot is free. 2: 1 = Real user, 0 = Anonymous user. 4: 1 = Logged in, 0 = Not logged in. 1. AUTHTYPE (Authorization Type) Start: 4 Length: 4 Type: Number Format: Hex digits. Values: 0: None 8: (reserved) 1: Kerberos IV 9: (reserved) 2: Kerberos V 10: LOKI 3: SPX 11: SSA 4: MINK 12: KEA_SJ 5: SRP 13: KEA_INTEG 6: RSA 14: DSS 7: SSL 15: NTLM 2. AUTHMODE (Authorization Type) Start: 8 Length: 4 Type: Number Format: Hex digits. Values: 0: Rejected 1: Unknown 2: Other 3: User 4: Valid 3. STATE (IKSD State) Start: 12 Length: 4 Type: Bit Mask Format: Hex digits. Bit Values: 1: Initializing 2: Sending a file 4: Receiving a file 8: Executing a REMOTE command 32: At command prompt 4. PID (IKSD's Process ID) Start: 16 Length: 16 Type: Number Format: Hex digits. 5. SERVER IP (IKSD's IP Address) Start: 32 Length: 16 Type: IP address as a series of numeric octets in network byte order Format: Hex digits 6. CLIENT IP (Client's IP Address) Start: 48 Length: 16 Type: IP address as a series of numeric octets in network byte order Format: Hex digits 7. SESSION START (Date and Time session started) Start: 64 Length: 18 Type: Date-time Format: Date-time string 8. LAST UPDATE (Date and Time this record was last updated) Start: 82 Length: 18 Type: Date-time Format: Date-time string 9. ULENGTH (Username length) Start: 100 Length: 4 Type: Number Format: Hex digits, right adjusted 10. DLENGTH (Length of current directory) Start: 104 Length: 4 Type: Number Format: Hex digits, right adjusted 11. ILENGTH (Length of state-specific information) Start: 108 Length: 4 Type: Number Format: Hex digits, right adjusted 12. RESERVED Start: 112 Length: 912 Type: None Format: Filled with blanks 13. USERNAME (Username; if anonymous "anonymous:password") Start: 1024 Length: 1024 Type: None Format: Text, ULENGTH sigificant chars, right-filled with blanks 14. DIRECTORY (Current directory) Start: 2048 Length: 1024 Type: None Format: Text, DLENGTH sigificant chars, right-filled with blanks 15. INFO (State-specific information) Start: 3072 Length: 1024 Type: None Format: Text, ILENGTH sigificant chars, right-filled with blanks
The state-specific information tells you whether IKSD is at its command prompt or in server command wait, if it is sending or receiving a file (in which case the filename is shown), it is executing a REMOTE command (in which case the command is shown), or how it was terminated (BYE, REMOTE EXIT, disconnect, etc)
Notes:
- There are no control characters (CR, LF, NUL, etc) or 8-bit characters; only ASCII graphic characters are used in the database. Fields are left- or right-padded with Space or '0' as indicated.
- Since the USERNAME, DIRECTORY, and INFO fields are right-padded with spaces, it would be laborious to isolate their actual values by trimming spaces from the right (since we must allow for internal spaces); hence the ULENGTH, DLENGTH, and ILENGTH fields.
- The USERNAME, DIRECTORY, and INFO fields are 1K each since 1K is the maximum pathname length found on common UNIX platforms (even though many platforms have smaller maximums). Thus, for example, the current directory string might be exactly 1K long. This is why its length is kept outside the block. Also the division of the record into four 1K blocks tends to make for more efficient i/o.
- The IKSD database does not provide a permanent record or give complete information. That's what the syslog entries and the IKSD log are for.
7.2 The Display Module
The straightforward data definitions and formats allow a display module to be written easily in the language of your choice, including scripting languages such as Kermit's own. A sample display module, iksdpy, is provided as a "Kerbang" script, providing a running display of the active IKSD sessions from the database. In its startup mode, it lists each session in the database, refreshing every 4 seconds. Various keystroke commands are available for help, quitting, etc, and to enter the detail screen for a specific session. The detail screen, too, refreshes itself every 4 seconds. Here you have keys to return to the main screen, to pick another session, to cycle through sessions, and so on.When a slot is freed, its information is left intact so you can still see who was using it, when, and from where, and the last thing they did before logging out. The old info persists until the slot is removed or reclaimed, which will happen when the next new IKSD session starts.
The iksdpy script is short, simple, and easily extensible. For example, while watching a detail screen and you see somebody doing something bad, you might like to have a "K" key to kill the session (the script already knows the pid, so it need simply form a "!kill -9" command, including the pid).
7.3. Database Management
The following command-line options let you disable/enable the database and specify its location:
- --database:{on,off}
- Whether an active-sessions database should be kept. On by default. If "on", but --dbfile is not specified, /var/log/iksd.db is used.
- --dbfile:filename
- Use this option to specify an iksd database file name. If you include this option, it implies --database:on.
In UNIX, the system startup procedure can delete the database file before starting inetd, since nothing in it is valid; however, this is not necessary since normal cleanup procedures will do the job too. In Windows, the IKSD listener takes care of it.
To capture a snapshot of IKSD usage, simply copy the database file.
8. TESTING
In case you want to test IKSD on a port other than 1649, be aware that IKS-aware Kermit clients (such as C-Kermit 7.0 and K95 1.1.18 and later) will not initiate Telnet negotiations with it, since it is not on a Telnet port (i.e. 23 or 1649). To get correct operation you'll need to force the client to negotiate, e.g.:telnet hostname 3000 set host hostname 3000 /telnet
[Top] [C-Kermit Home] [7.0 Update Notes] [8.0 Update Notes] [Kermit Home]
C-Kermit IKSD Aministration / Columbia University / kermit@columbia.edu / 12 Dec 2001