		  IKSD - The Internet Kermit Service Daemon

		      UNIX SYSTEM ADMINISTRATOR'S GUIDE

			      The Kermit Project
			     Columbia University
		       http://www.columbia.edu/kermit/

			      D R A F T  #  1 5

			  Sun Nov 14 17:55:09 1999


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
contains IKSD functions, but these can be (easily?) added to the VMS, VOS,
AOS/VS, and other versions too.  

This is a draft.  Everything here is subject to change.


CONTENTS

  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


1. Why IKSD?

Why run an Internet Kermit Service Daemon when you are already running
an FTP server?

 . Like FTP, Kermit provides a service that can be accessed from many
   different platforms with a consistent set of commands, but unlike FTP,
   these commands include programming constructions such as variables,
   arrays, looping and selection mechanisms, and local and remote procedure
   calls, thus allowing file transfer and management operations of arbitrary
   complexity to be easily automated.

 . Like FTP, Kermit provides both text- and binary-mode data transfer, as
   well as file management capabilities.  But Kermit also offers numerous
   features lacking from FTP, such as character-set translation, flexible
   file selection mechanisms, preservation of timestamps and permissions,
   automatic per-file text/binary mode switching (important in cross-platform
   transfers), cross-platform directory-tree transfer, and a selection of file
   collision options including "make backup copy of existing file and accept
   incoming file", "reject incoming file", "accept incoming file only if newer
   than existing file", etc.

 . Unlike FTP, Kermit supports atomic file movement, in which the source
   file can be deleted (or renamed, or moved) when and only when it has been
   transferred successfully, as part of the transfer operation itself.

 . Unlike most FTP implementations, Kermit supports recovery of interrupted
   transfers from the point of failure.  You can even use it to recover
   interrupted FTP transfers when FTP itself does not offer this option.

 . Unlike standard FTP, Kermit can transfer data through firewalls or
   proxies or NATs on a single well-known port (unless the TCP port for the
   connection has been explicitly filtered).

 . Unlike FTP, Kermit can transfer data across a combination of transports
   (e.g. dial-up to a terminal server and thence to an Internet host).

 . Authentication and data transfer can take place over secure connections
   (mutually authenticated and encrypted) using established Telnet
   authentication and encryption options.

 . Unlike traditional Kermit use over Telnet, anonymous access is possible,
   and the considerable overhead of the intervening Telnet server and
   pseudoterminal service is eliminated.

 . Unlike the FTP daemon (ftpd), the IKSD can be monitored in real time
   by the system administrator (see Section 7).

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 an
Internet Draft:

  ftp://ftp.ietf.org/internet-drafts/draft-altman-telnet-kermit-server-01.txt

The Internet Kermit Service itself is discussed in a separate Internet Draft:

  ftp://ftp.ietf.org/internet-drafts/draft-columbia-kermit-service-01.txt


2. System Configuration

WARNING: Do NOT attempt to install a pre-7.0 version of C-Kermit as an IKSD.
Earlier versions do not perform the necessary authentication and security
functions, and therefore will leave your system wide open to anonymous root
access.  (Don't worry, the installation procedure described here, if you
follow it, and the interface to IKSD, prevent you from starting an earlier
version of C-Kermit as an IKSD, since it lacks the needed command-line
options and will halt with a usage message if you try to use them.)

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:

 a. The C-Kermit executable should be copied to the directory that is 
    normally used for launching Internet services, and renamed to "iksd".
    Normally the owner and group should be root and the permission 0750.

 b. The following entry should be added to the Internet services file,
    normally /etc/services:

      kermit   1649/tcp

 c. An entry must be made in the inetd configuration file, normally
    /etc/inetd.conf.  See your system-specific documentation for the
    name, location, and format of this file, e.g. "man inetd" and
    "man inetd.conf".  A typical example might be:

      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>

 d. When using TCP wrappers, make the appropriate entries in its
    configuration file(s), such as /etc/hosts.allow and /etc/hosts.deny.
    See the TCP wrappers documentation for further info.

 e. Make any required hard or soft links to the iksd executable.

 f. If desired, create an IKSD configuration file (/etc/iksd.conf by default).

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


3. Compile-Time Configuration Options

You can use any C-Kermit configuration as an IKSD, ranging from a fully
configured version, to a special IKSD-Only version, to any of the various
"stripped-down" versions, as described in the C-Kermit Configuration Guide
(ckccfg.txt) and/or Installation Instructions (ckuins.txt).

The following compile-time options are specific to or of special relevance
to the IKSD:

TNCODE - Required for IKS.
  Include Telnet protocol code, even if networking code is not included.
  Defined by default if TCPSOCKET defined, otherwise must be defined
  explicitly. 

IKS_OPTION - Required for IKS.
  Include code for the new Internet Kermit Service Option.
  Currently defined automatically if TNCODE is defined.

CK_LOGIN - Required for IKS.
  Include user authentication code.  Defined automatically for UNIX unless
  NOLOGIN defined.

CK_PAM 
  The IKS is to be compiled to use PAM (Pluggable Authentication Modules)
  to authenticate the user for interactive logins instead of Unix password
  files.  The default PAM service type for IKSD is "kermit".

PAM_SERVICE_TYPE 
  If CK_PAM is defined and you wish to use a service type other than
  "kermit" you can define PAM_SERVICE_TYPE to equal the string you
  wish to use.

CK_SHADOW
  If your host utilizes the shadow password system for storing user
  passwords the IKS must be compiled with support for shadow passwords.
  This might also require some additional libraries added the LIBS
  clause, such as -lgen, for loading the getspnam() routine.

CKSYSLOG
  Include code for making syslog entries.  This symbol is defined
  automatically if (a) CK_LOGIN is defined; (b) UNIX is defined; and (c)
  NOSYSLOG is not defined.

CKWTMP
  Include code for making wtmp log entries.  This symbol is defined
  automatically if (a) CK_LOGIN is defined; (b) UNIX is defined; and (c)
  NOWTMP is not defined.

WTMPFILE
  String containing pathname of the default wtmp logfile.  If not specified,
  a default is supplied, currently /var/log/wtmp on Linux and /usr/adm/wtmp
  elsewhere.  The wtmp file can also be specified at runtime; see next
  section.

CK_CURSES
  Need not be defined in an IKSD-only build, since curses is used only
  in local mode, and the IKSD is always in remote mode, plus the fact that
  curses initialization can cause spurious error messages in IKSD since it
  might not have a terminal type (TERM variable) in its environment.

NOLOCAL
  This may be defined to exclude all code relating to the making of
  both serial and network connections from the C-Kermit/IKSD executable.
  This code is presently not needed, and is never used, in the IKSD.
  Compiling it out reduces the size of the executable and eliminates any
  possibility that a loophole could be exploited to use the IKSD as a
  relay.

NOPUSH
  This symbol may be defined to exclude all code that is used to access
  local shell or system functions, such as the RUN (!) command, the server
  end of the REMOTE HOST command, file-transfer pipes and filters, etc.
  Note that such code is disabled at runtime in the IKS anyway; compiling
  it out completely reduces the size of the executable and the risk of
  loopholes.

NOICP
  Disables the interactive command parser as well as long-form command-line
  options (Section 4.1).  In this configuration, the IKS runs only in Kermit
  Server mode, and the size of the executable is reduced dramatically.
  WARNING: NOICP also inhibits extended command-line options (the ones that
  start with "--"), since these share the same parsing routines as the
  interactive parser.

NOSPL
  Disables the script programming language (INPUT, OUTPUT, FOR, WHILE,
  IF, SWITCH, macros, variables, etc) without disabling the interactive
  command parser. 

NOGETUSERSHELL
  Add this if the link steps fails because it can't resolve getusershell()
  and/or endusershell().  Normally, IKSD will refuse a login if the user's
  login shell is not one of those returned by getusershell() (normally,
  getusershell() simply lists the shells listed in /etc/shells, but we
  can't depend on this).  Thus if your site "invalidates" user IDs by
  setting their login shell to something that is not really a shell (like
  /etc/nologin), but does not have a getusershell() function, IKSD will
  still let such users log in unless (a) you put them in the forbidden
  users file (see Section 4.1), or (b) add some code to ckufio.c to check
  for whatever invalid or valid shells might apply at your site.

NOIKSD
  This defines the symbols NOLOGIN, NOSYSLOG, NOWTMP, NOPRINTFSUBST, which
  in turn prevent the definition of symbols (CK_LOGIN, CKSYSLOG, etc) that
  cause IKSD-specific code to be included.

CK_SYSINI
CK_DSYSINI
  System-wide initialization file; see Section 4.4.

IKSD
  Is defined automatically if NOIKSD is not defined.

IKSDCONF
  The name of the IKSD configuration file.  In UNIX this is
  "/etc/iksd.conf" by default; elsewhere "iksd.cfg".

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"

-DNOLOCAL: excludes all code that is used to make connections.   
-DNOPUSH:  excludes all code that accesses local system shells and commands.
-DTNCODE:  includes Telnet protocol code even though -DNOLOCAL is included.

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, and/or SRP, or any other authentication / security
mechanism may be also selected at build time if you have the appropriate
libraries and header files installed on your system.  See security.txt
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


4. Runtime Configuration Options

The IKSD can be configured at runtime with command-line options or by an
initialization file or other auxilliary file(s), in any combination.

4.1. Command-Line Options

To start C-Kermit as an Internet Kermit Service Daemon, include the '-A'
command-line option.  This option not only configures C-Kermit as an IKSD, but
it also ensures that you are running a version of C-Kermit that can do this,
i.e. C-Kermit 7.0 or later built with all the necessary compile-time options
(Section 3).  If either of these conditions does not apply, the '-A' option
will be invalid and the Kermit program will halt immediately.

In addition to -A and the command-line options described in "Using C-Kermit"
(2nd Edition), plus any other new ones described in the ckermit2.txt file, a
selection of new long-form options apply specifically to the IKSD.  Long-form
options work as follows:

 a. All long-form options must begin with "--" (two hyphens) or "-+".  If the
    option begins with "--" it is executed before or after the C-Kermit
    initializaton file, according to its internal keyword flags.  If it
    begins with "-+", it is executed before the init file, regardless of the
    keyword flags.  There is no way to force an argument to be executed after
    the init file if it has the CM_PRE bit set (see table below).

 b. No spaces are allowed in the keyword.

 c. If an operand contains spaces, it (or the entire option) must be quoted
    according to the rules of the shell from which Kermit is invoked.

 d. Case doesn't matter in the option keyword (unlike with regular
    single-letter options).

 e. If an operand is required, it must be included.  If no operand is
    required, no operand must be included.

 f. The operand follows the keyword, separated by a colon (:) or equal
    sign (=).  There are no spaces between the separator and the keyword
    or operand.

 g. Long-form option names may be abbreviated according to the same rules as
    interactive keywords.

 h. On/Off operands can be On, Off, Yes, No, True, False, 0, 1, or OK (case
    of letters does not matter).

 i. Long-form options are available only when the interactive command parser
    is built-in (i.e. not NOICP).

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:

--nointerrupts
  Disables keyboard interrupts that are normally ensabled.  In IKSD, when it
  is in interactive prompting state, commands can normally be interrupted
  with Ctrl-C.  Suspending (normally via Ctrl-Z) is always disabled in IKSD.

--help
  Lists the extended command-line options that are available in your version
  of C-Kermit.  If any options seem to be missing, that is because your
  copy of C-Kermit was built with compile-time options to deselect them.

--helpfile:<filename>
  Specifies the name of a file to be displayed if the user types HELP
  (not followed by a specific command or topic), in place of the built-in
  top-level help text.  The file need not fit on one screen; more-prompting
  is used if the file is more than one screen long if COMMAND MORE-PROMPTING
  is ON, as it is by default.

--anonymous:{on,off}
  Whether anonymous logins are allowed.  By default they are allowed, so
  this option need be included only to disallow them (or for clarity, to
  emphasize that they are allowed).  Anonymous login occurs when the username
  "anonymous" or "ftp" is given, with any password (as with ftpd).

--timeout:<number>
  This sets a limit (in seconds) on the amount of time the client has to log
  in once the connection is made.  If successful login does not occur within
  the given number of seconds, the connection is closed.  The default timeout
  is 300 seconds (5 minutes).  A value of 0 or less indicates there is to be
  no limit.

--bannerfile:<filename>
  The name of a file containing a message to be printed after the user logs
  in, in place of the normal message (Copyright notice, "Type HELP or ? for
  help", "Default transfer mode is...", etc).

--permissions:<octalnum>
  The permissions given to any file that is uploaded by an anonymous user.
  0040 is the default and recommended value.  The default permits only
  group-read access, and therefore prevents anonymous users from uploading
  files (e.g. pirated sofware) to be downloaded by other anonymous users.
  Synonym: --perms.

--initfile:<filename>
  The initialization file to be executed for anonymous logins.  By default
  it is /.kermrc, where "/" is the root of the chroot'd file system.  Any
  <filename> that you specify here must be specified in the notation of the
  the chroot'd file system.  This option is independent of the '-y' option
  (alternative init file), which applies only to real users.

--cdmessage:{on,off,0,1,2}
  For use in the Server-Side Server configuration; whenever the client 
  tells the server to change directory, the server sends the contents of a
  "read me" file to the client's screen.  This feature is On by default,
  and operates only in client/server mode when ON or 1.  If set to 2 or
  higher, it also operates when the CD command is given at the IKSD> prompt.
  Synonym: --cdmsg.

--cdfile:<filename> (or list)
  When cdmessage is on, this is the name of the "read me" file to be sent.
  Normally you would specify a relative (not absolute) name, since the file
  is opened using the literal name you specified, after changing to the new
  directory.  Example:
  
    --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}}

--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.
  *** NOTE: During the test phase, the directory is /tmp/ ***

--dbfile:<filename>
  Use this option to specify an iksd database file name.  If you include 
  this option, it implies --database:on.

--syslog:<number> or {on,off}
  Whether and what level of syslog entries should be made.  A level of 0
  (or "off" or "false" or "no") means no syslogging.  A level of "on" (or
  "yes" or "true") invokes the default syslogging level.  To choose a
  non-default level of syslogging, specify a number (see Section 4.2).

--wtmplog:{on,off}
  Whether wtmp log entries should be made.  On by default.  An entry is made
  when the user logs in and when the session is closed.  The "tty name" field
  is given as "iks_xxxx", where xxxx is the process ID (pid) of the IKSD.
  Thus IKSD session history can be monitored via "last | grep iks_".
  Anonymous logins are shown with a user ID of "ftp".

--wtmpfile:<filename>
  The default wtmp log file is /var/log/wtmp in Linux, and /usr/adm/wtmp
  elsewhere.  In case your system's wtmp log file does not match the default,
  use this option to specify the appropriate filename.

--userfile:<filename>
  This file contains a list of local usernames that are to be denied access
  to Internet Kermit Service.  The default is /etc/ftpusers.  This can be the
  same file that is used by wuftpd, and the syntax is the same: one username
  per line; lines starting with "#" are ignored.  Use this option to specify
  the name of a different forbidden-user file, or use --userfile:/dev/null
  to disable this feature in case there is a /etc/ftpusers file but you
  don't want to use it.

--xferlog:{on,off}
  Whether a wu-ftpd-like log should be kept.  Off by default.  If "on", but
  --xferfile is not specified, /var/log/iksd.log is used.  This log is
  explained in Section 4.3.

--xferfile:<filename>
  Use this option to specify an iksd log file name.  If you include this
  option, it implies --xferlog:on.

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

Some of the traditional options have special significance in the IKS, e.g.:

-x (server mode).
  If this option is included on the IKSD command line, the Client Side Server
  configuration is disabled, and the user will not get a Username: or
  Password: prompt, and will not be able to access the IKSD command prompt.
  A FINISH command sent to the IKSD will log it out and close the
  connection, rather than returning it to its prompt.

-y filename
  Execute "filename" rather than the normal initialization file for real
  users; this option does not apply to anonymous users.

-Y (no init file)
  Do not execute an initialization file, even if a real user is logging in.

Examples:  

iksd -A
  Starts the Internet Kermit Server with all defaults in effect.  

iksd -A --syslog:5
  As above, but with the highest level of syslogging (section 4.2).

iksd -A --anonymous:off --cdfile:READ.ME
  Starts the IKSD with anonymous access forbidden and changes the name of
  CD message file from the default list to READ.ME.

iksd -A -x --anonym:no --cdf:READ.ME
  As above, but forces the IKSD to operate only in Kermit server mode,
  thus preventing user access to the IKSD command prompt.  Also illustrates
  abbreviation of long-form option keywords and use of "no" as a synonym
  for "off".

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

4.2. System Logging

System logging in UNIX is via the standard syslog() facility ("man syslog"
and/or "man syslogd" for further info).

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 ckuins.txt for further info.

WARNING: Debug level produces VOLUMINOUS amounts of information -- it is
equivalent to (in fact, it *is*) C-Kermit's debug log.  Furthermore, there is
a good possibility it will contain sensitive information such as clear-text
passwords.  Debug records are written to the syslog DEBUG facility, as defined
(or not defined) in syslog.conf.  If you use this level of logging, make sure
that the logfile defined for "daemon.debug" is secured from the public, and
that there is plenty of space for it.

ANOTHER WARNING: In some UNIX systems, syslogging does not work once a
chroot() has occurred, which is done by iksd just as it is by ftpd for
anonymous users, to restrict them to the /pub/ftp (or other desired) directory
tree.  At present, SunOS and Linux are known to have this deficiency and there
probably are many others.  THERE IS NO SYSLOGGING FOR ANONYMOUS USERS on these
systems.  The only way to log the activities of anonymous users on such
systems is to specify a transfer iksd log on the command line (Sections 4.1
and 4.3).

4.3. The Transfer Log File

The transfer log is disabled by default; it must be enabled on the command
line (Section 4.1).

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:

Timestamp
  This is an asctime-style timestamp, example: "Wed Sep 16 20:19:05 1998"
  It is always exactly 24 characters long, and the subfields are always in
  fixed positions.

Elapsed time
  The whole number of seconds required to transfer the file, as a string
  of decimal digits, e.g. "24".

Connection
  In IKSD, the IP hostname or address of the client.  For user-mode C-Kermit
  transfers, The name of the network host to which C-Kermit is connected, or
  the name of the serial device through which it has dialed (or has a direct
  connection), or "/dev/tty" for transfers in remote mode.

Bytes transferred
  The number of bytes transferred, decimal digits, e.g. "1537904".

Filename
  The full pathname of the file that was transferred, e.g.
  "/pub/ftp/kermit/a/README.TXT".  If the filename contains any spaces or
  control characters, each such character is replaced by an underscore ('_')
  character.

Mode
  The letter 'b' if the file was transferred in binary mode, or 'a'
  if it was transferred in text (ASCII) mode.

Options
  For compatibility with the wuftpd log.  This field always contains an
  underscore ('_') character.

Direction
  The letter 'o' if the file was transferred Out, and 'i' if the file was
  transferred In.

User class
  The letter 'r' for real users, or 'a' for anonymous users.

User identification
  The user ID of a real user, or the password given by an anonymous user.

Server identification
  The string "iks" (Internet Kermit Server), or if C-Kermit is running
  in user mode, "kermit".  This distinguishes a Kermit transfer log
  record from a WU-FTPD record, which contains "ftp" in this field.

Authentication class
  The digit '1' if we know the user's ID on the client system, 
  otherwise '0'.  Currently, always '0'.

Authenticated user
  If the authentication class is '1', this is the user's ID on the client
  system.  Otherwise it is an asterisk ('*').  Currently it is always an
  asterisk.

4.4. The IKSD Configuration File

The IKSD configuration file is a place to put commands that should always
be executed for every client, real or anonymous.

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.

4.5. The Initialization File

When a real user logs in to the IKSD, the C-Kermit initialization file is
executed in the normal manner, depending on the compile-time configuration of
the IKSD.  Normally, the user's own .kermrc file is executed, and this, in
turn, executes the user's customization file, .mykermrc.  If the IKSD was
built with the CK_SYSINI or CK_DSYSINI compile-time options (described in
ckccfg.txt), a single, shared system-wide initialization file is executed
instead; this may, in turn, execute a customization file out of the user's
home directory.  You may override C-Kermit's automatic selection of
initialization with the regular C-Kermit -y or -Y options on the IKSD command
line, described in the C-Kermit manual.

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:

\v(date), \v(ndate)
  The current date, in case you want to restrict access by date.
  (Also read about the new date-related functions in Section 1.6 of
  ckermit2.txt.)

\v(day), \v(nday)
  The day of the week, in case you want to restrict access to certain days
  of the week.

\v(home)
  The user's home directory.

\v(host)
  The hostname of the IKS.

\v(ipaddress)
  The IP address of the IKS.  This and/or \v(host) may be used when you are
  running an IKS on multiple hosts and want to have different setups on each,
  but still have a common initialization file.

\v(line)
  The IP host name or address of the client's host.

\v(time), \v(ntime)
  The current time of day, in case you wish to restrict access to certain
  times of day.

\v(userid)
  The ID with which the user logged in to the IKS.  For anonymous logins,
  this is "ftp".

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

 a. Login (authentication) is required.
 b. Shell access is disabled.
 c. Server-side Telnet negotiation is enabled.
 d. SET RELIABLE ON (see ckermit2.txt).
 e. FAST file-transfer settings, including "cautious" unprefixing.
 f. 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 will respond to only the
following client commands:

  [ REMOTE ] LOGIN
  [ REMOTE ] LOGOUT
  REMOTE HELP (or RHELP)
  REMOTE EXIT (or REXIT)
  BYE

Once authenticated, the user may not re-authenticate or change identities.

The connection persists until it is broken in any of the following ways:

 a. Client sends BYE or REMOTE EXIT (REXIT) or [ REMOTE ] LOGOUT to IKSD.
 b. Client sends FINISH to IKSD that has been started with '-x'.
 c. User gives HANGUP or CLOSE command to the client.
 d. 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 will fail.  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.  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 creation

to /pub/ftp/.kermrc (or whatever other initialization file you have designated
for anonymous users with --initfile).  Similarly for directory removal:

  enable rmdir    ; Enable directory removal

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

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

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

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

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

 a. Free slots (In-Use flag is 0), or:

 b. Stale slots(*), or:

 c. Any slot with our own IP and PID (a special kind of stale slot).

(*) In-Use flag is 1 and IP address is ours, but PID is invalid.

In C-Kermit only (not K-95) we also perform some housekeeping duties while
searching (the Windows APIs include no provisions for this):

 a. Whenever a stale slot is found, we free it (set its In-Use flag to 0).

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

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

 b. Then we release the lock.

From this point, we can write freely into our slot regardless of locks.

Notes:

 a. Since all IKSDs follow the same procedure, only one can have a lock a
    at a time.

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

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

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

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

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

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

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

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

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

(End of IKSD.TXT)
