The purpose of the TCP Server is to provide a generic, reuseable TCP based server for handling socket communications. The TCP Server will take on the same basic design as the major HTTP servers (such as NCSA, Roxen, and Apache). The basic operation of these servers is:

• read configuration files
• allocate tcp/ip socket, and listen on known port
• when a client connects, fork a child process to server the client connection, and return to listen for more clients

The child processes often completely encapsulate the communications protocol, and all operations once they have been forked. This design provides a high degree of re-usability for creating new servers, as the parent server process just needs to be linked in with a child function, or object, that provides the proper protocol handeling.

A high level of abstraction will be attempted in the design, and coding of the main server module. Protocol specific information will be kept out of the implementation of this module. In addition to the managing of the client socket connections, the main module should provide some facility for performing logging, and informational access (such as status information).

The protocol handlers are only responsible for performing socket communications with the client, they are free to enforce what ever higher level protocol they wish.

Protocol handling will be performed by external processes. These external processes should follow some specific design features:

• Protocol handlers will be standalone executables.
• All communications will be performed through standard input, and standard output.
• The protocol handler should return error or success information to the server either through a call to exit, or via the return from the main function.

Using standalone executables has several advantages, the first of which is flexibility in the server design and configuration. This allows the addition/modification of the protocol list through a configuration file. This also allows the protocol handlers to be interacted with by executing them from a command line, or scripted though the use of playback files and redirection of standard in/standard out.

The basic operation of the protocol handlers should be to perform any comunications initialization by exchanging configuraiton information across the connection, followed by transactional based communications. The communications session should be considered over whenever either party closes it's socket connection. When the session ends, the protcol handler should return from it's main function.

The underlying communications protocol will be tcp/ip, while a higher level application level protocol will be built up on top of tcp/ip. For most protocol handlers, this should consist entirely of ASCII data. The protocol handler(s) will be free to implement any protocol they feel appropraite, with the exception of the first line of the communicaiton. This first line of the communications will be interpreted by the TCP Server as the client's request for a particular protcol handler.

The advantage of performing the communications exclusivly in ascii, is so that the information is human-readable. This should make it much easier to both develop, and test software that needs to communicate with this sever process. Also, this provides the ability for a programmer to use other tools (including telnet) to communicate with the server for debugging purposes.

To make the server as flexible as possible, all of it's dynamicly configurable settings will be externalized into a configuration file. Also, many of the settings will be modifiable from the command line, and command line arguments will override configuration file settings.

tcp_server can be interacted with at run time. This can be accomplished because tcp_server sets up signal handlers for the following signals:

• SIGINT - Signal produced by a CTRL+C. This causes tcp_server to shutdown gracefuly.
• SIGALRM - This signal handler is used to produce the scoreboard file. You can cause tcp_server to emit a scoreboard file immediately if you send it a SIGALRM.
• SIGHUP - tcp_server uses this signal as notification that it should re-read it's configuration file, as well as the protocol_handlers file. This can be used to update a running copy of tcp_server with new information with out seriously interrupting it's operation.

To send a signal to tcp_server, all you need to do is obtain it's process id, and use the kill command to send it a signal. tcp_server stores it's process id in the file pointed to by pid_file just for this reason.

• NCSA httpd, available from the University of Illinois at Urbana - Champaign.
• The Apache Server project.
• The Roxen Webserver, information is available from either:
  the Roxen Website, or the FSF's Website.
• Unix Network Programming, W. Richard Stevens, Published by Prentice Hall Inc., ISBN 0-13-949876-1
• Unix Systems Programming for SVR4, David A. Curry, Published by O'Reilly & Associates, Inc., ISBN 1-56592-163-1
• The C++ Programming Language, Bjarne Stroustrup, Published by Addison Wesley, ISBN0-201-88954-4

#
# sample configuration file for tcp_server
#
# created Wed Jul  1 13:09:23 EDT 1998 KRB
#
#

# this is the only required setting
protocol_handler_file     ../config/protocol_handlers.conf


# this sets the maximum number of concurrently running
# clients -- i.e. protocol handlers
#    defualt is 25
max_num_concurrent_children 100

# set this to FALSE if you wan't all output to go to stdout,
# or TRUE if you want it to go to the file pointed to by 
# the log_file setting.
# default is FALSE
use_log_file TRUE

# this sets the path to the loging file
#    default is ./tcp_server.log
log_file ../log/tcp_server.log

# this sets the path to the config file -- the reason
# why you can set this from the conf file is so when you
# to a sighup, tcp_serverd will pick up this value, and 
# a second sighup will cause it to init from the second
# file...you'll have to do a double sighup to get this to
# take effect.
#    default is ./tcp_server.conf
config_file ../config/tcp_server.conf

# this instructs tcp_serverd on where it should write
# it's pid file.

pid_file ../log/tcp_server.pid


# this is the frequency which the server will re-write
# the scoreboard file (see the next setting)
#    default is 600
scoreboard_frequency 120

# this is the stats file that will be written
# every scoreboard_frequency secons
#    default is ./tcp_server.stats
scoreboard_file tcp_server.stats

# this is the port that tcp_serverd will listen on
#    default is 4137
port 4137


# this sets the type of buffering that tcp_serverd
# will use via a call to setvbuf(3).  You probably
# don't have to worry about this.  You can choose
# none, line, or full for this setting
#    default is none
buffering_type none

#
# protocol_handlers.conf
#
# description: this is a sample protocol handler 
#    configuration file.  The format is:   
#         protocol_name  handler_app
#    The protocol name may not have whitespace 
#    in it, the handler app is the remainder of 
#    the line after the protocol name.  When a 
#    client connects, it should pass the 
#    protocol_name as it's first line of the 
#    communication, after that, all further 
#    communicaions should be to/from the 
#    handler_app.
#
# created: Mon Jul  6 07:53:23 EDT 1998 KRB
#
# Mod  : Tue Aug 4 09:59:39 EDT 1998 MWZ - Set up 
#       for std dir struct; apollo_tcop
#
#
test_server             /usr/bin/perl ../src/echo.pl
apollo_tcop             ../../apollo_tcop/release/apollo_tcop \
                          ../../apollo_tcop/config/apollocnct.conf