Zero-Knowledge Command Server Configuration

Freedom Services 2.0 Archive Validated

$Id: zkcs-conf.html,v 1.4 2001/07/10 20:37:42 sam Exp $
Revision Comments
1.1 Author(s): Francis L'Écuyer (francisl@zks.net); 
Initial draft. 
1.2 Updated to reflect the design change that now makes the Command Server a pre-forking server.

Contents

  1. Introduction
  2. Configuration
  3. Runtime control

1 - Introduction

Goto : [top]
The Command Server is a library for implementing servers based on the Zero-Knowledge Command Protocol (ZKCP). Its main purpose is to listen on a port for new commands and to send back response (following the ZKCP commands format). The handling of the commands is not done by the server itself but by the library users. So the semantic of the commands and protocol  is left out of the server and is defined and handled by the user. The Command Server can be configured through command line options and file configuration as well as process signals.

Notes on Command Server processes

When the server is started, a new process is started as the deamon process which then pre-fork one child process for each simultaneous connection that the server can handle (configurable). All child processes will listen to the socket port waiting for a new connection. Note that only 1 process will get the connection and the other will be blocked again, waiting for another connection. For robustness purpose, the Command Server can be configure so that pre-forked processes eventually die and get recreated.
See also:
ZK Command Server library manual

ZK Command Protocol Specification

2 - Configuration

Goto : [top]

Overview

The Command Server uses the zkConfig frame-work for configuration. So both command line and config file options are available.

2.1 - Command line options

The following command line options are available for the Command Server:
 
Option name Option Parameter Description
Help NA Show a list of command line options.
Config Configuration file Specify the configuration file.
ListenQueueLength Queue length Maximum number of incoming pending connections.
MaxIdleTime Time (seconds) This is the maximum number of seconds that a server will wait for sending or receiving a command. Note that special value 0 will disable the idle timer.
MaxConnections Number of maximum simultaneous connections This specifies the number of simultaneous connections that the Command Server can handle. Note that the Command Server is a pre-forking server so an child process is forked for each possible connections. Be carefull with the number provided when running multiple Command Server on the same machine.
ProcessLife Number of connections The process life is the number of connections that each pre-forked child process handles before terminating. Note that when a process terminates another one is forked to replace it. A process life of 0 indicates an immortal process.
MaxPacketSize Size (kBytes) This is the maximum size of packets tha can be transmitted.
TcpDelay NA Indicate to use delay when sending data over TCP link. This prevents the server from using the TCP_NODELAY socket option.
AuthKey string Specifies the key to use for packet authentication (in MAC)
AddressPath string Server listening path (e.g. "host:port" or only ":port")
AccessFile Path and file File name and path for the access file containing the IP addresses that are allowed to connect.
LogFile Path and file Path and file name of the log file.
PidFile PID file The PID file contains the process identifier of the running Command Server
Verbose 0 to 4 Specifies the logging verbose level. This is an integer value between 0 to 4, where 0 provides almost no logging (error only) and 4 logs all input.
Debug NA This turns on debugging mode.
DontFork NA Prevents the server from running in background when launched.
NoChildren NA When specified, the server process will not fork processes to handle new connections but will handle them itself.

2.2 - Configuration file

All command line options are also available for the configuration file using the same option names (except for the help option). The Command Server options should be contained in the "CommandServer" section of the configuration file.

Example:
 

[ CommandServer ]
AccessFile = /freedom/etc/zkcs.access
AuthKey = SecretKey
AddressPath = :51111
MaxConnections = 100
MaxIdleTimer = 30

2.3 - Access Control list

To prevent intruder from accessing the Command Server, the Command Server maintains an Access Control list that contains IP addresses of all client allowed to connect. When the server is started, the access control file is loaded and the IP addresses are stored so that they can be compared when a new connection arrives. Note the the access control list can be changed after the server is running and reloaded by sending a signal to the server. This is further discussed in one of the following sections. An Access Control list consists simply of IP addresses like in the following example:
 
61.34.76.231
12.432.32.23
92.4.128.65


It is also possible to specify sub-networks using an IP address and a mask. Two formats are available for sub-net addresses:
 

; Following are examples of sub-network addresses:
32.54.23.12/16                    ; Only use the first 16 bits (max of 32 bits)
54.23.34.21/255.255.0.0   ; The second IP address is a mask to apply to IP addresses


As seen in the above examples, comments can be inserted by preceding byt the ';' character.

3 - Runtime Control

Goto : [top]
Like many Freedom servers, the Command Server provides the user with runtime configuration using signals. When the server is running the user still has some control over it by send the following signals:
 


Note that because the Command Server is a pre-forking server special care must be taken to be sure that all processes are signaled. For that, when the server starts it creates a process group to which all processes belong. The syntax to signal a group is to use the parent process ID and prefix it with a dash.  For example, the following would be used to rotate the log file:
 

kill -HUP -51036