Accepting incoming connections
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
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
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.
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