Accepting incoming connections

Introduction
------------

This paper is part of the "Zorp Anatomy" series of articles and as such it
gives some background information about the Dispatch subsystem of Zorp. It
is intended for advanced Zorp users, those interested in what behind the
scene is.

What is 'dispatch'?
-------------------

As Zorp is a proxy based firewall it processes traffic in connections. Each
session is usually one or more pairs of connections (one for the client and
one for the server) and a session starts as soon as a new client side
connection is detected.

In fact each new incoming connection starts a new proxy instance, provided
the incoming connection is destined to an opened port and when the use of
the service bound to that port is permitted.

A dispatch is a general entity encapsulating a TCP or UDP listener, e.g.
initializing a dispatch object yields the opening of a new port. The stock
Zorp objects Listener and Receiver (and their derivates) both use dispatch
objects behind the scenes.

However the dispatch framework allows more than simply opening a new port,
as several dispatch entries might open the same port. Strange? There is an
explanation.

Dispatch priorities
-------------------

As introduced in the previous section, several dispatch objects can be
initialized with the same IP/port combination. When there are more 
dispatches on the same port, registered entries are processed in priority
order. This priority is a simple 32 bit, signed integer (smaller value means
greater priority). Default "Listener" and "Receiver" objects are registered
with priority 100.

The interesting part comes in when new entries are registered with higher
priorities, this way anything in Zorp (this anything is a proxy in most
cases) can conditionally 'steal' connections from the standard proxy startup.

Dispatch uses
-------------

The use of the dispatch framework within Zorp is twofold:

1) it is used to implement related connections

  A related connection is something like the DATA channel for FTP, where
  protocol commands are transferred using a main channel (usually called
  control channel) while larger data transfers (file up- and downloads) are
  transmitted in a separate connection. This separate connection is handled
  by the same proxy as the control channel but as this is a new connection
  per definition, it needs a new listener to start up.
  
  When opening the listener for the data transfer, the FTP proxy registers a
  new dispatch entry with high priority (numerically equal to -100) to make
  sure no other dispatch entries will steal the data connection.

2) it is used to implement secondary sessions

  In traditional proxy based firewalls a single proxy instance handles a
  single session only (e.g. one connection pair). As a proxy instance
  usually requires a separate process or thread (Zorp is thread based) to
  run, this might become a problem in high performance environments as the
  maximum number of processes/threads are limited.
    
  When a proxy supports secondary sessions, it is able to process several
  protocol flows in a single instance (e.g. single process or thread). By
  registering a dispatch entry to the same IP/port which triggered the proxy
  to start at a moderate priority (which is between RELATED and LISTEN
  priorities and equals to 0 numerically) the proxy will be able to steal
  'similar' connections to its original connection.

  When a new connection is accepted, it is offered to the proxy for
  processing. The proxy in turn decides whether the connection is similar
  enough to its master session (this decision is usually made based on the
  administrator's settings).  When the connection is not similar enough
  (e.g. it doesn't match the requirements of the administrator), the
  connection is rejected by the proxy and processing continues as normal,
  the lower priority Listener will accept the connection and start a new,
  separate proxy instance. When the connection is good enough the proxy will
  be able to start a new, internal session, thus without the need to start
  new threads. Currently the RADIUS and PLUG proxies support this feature
  and their behaviour can be controlled by their 'secondary_mask' and
  'secondary_limit' attributes.