udp-proxy, test-udp — generic UDP proxy
udp-proxy [-hv] [-d ] dbglev-f cfgfile
test-udp [-hv] [-d ] dbglev-f [cfgfile-r] [-t ]test_expr
The udp-proxy is a generic proxy for protocols based on the UDP.
The udp-proxy assumes that a server or servers listen on a fixed UDP port number and clients communicate from arbitrary source ports. The udp-proxy is able to mediate either transparent communication to any number of servers according to the original destination address or to a fixed address given in the configuration (the original destination address is one of the proxy addresses).
The test-udp program checks the syntax and partially the semantics of the configuration; for test expression syntax, see test-expr(5).
Format of the proxy configuration file is described in udp-proxy.cfg(5).
The udp-proxy uses common Kernun mechanism
for policy decisions about received and sent datagrams.
It is described in
access-control(7) and host-matching(7).
The proxy uses single-phase ACLs (session-acl)
which are checked at the moment of a session establishment.
The proxy uses an abstraction of session. The session is a distinctive period of communication between a single client (i.e. IP address and port) and a server (or server set), e.g. TFTP transfer of a file. The session is just a logical concept as there is nothing similar to the TCP connection in the UDP. There is no means of unambiguous detection of session termination (which TCP provides by closing a connection). Thus a number of conditions can be defined in the configuration to limit the session duration.
There are several types of sessions:
one-wayOnly datagrams in the direction from the client to the server are allowed. If a datagram from the server is received, it is not passed to the client and the session is immediately terminated. An example of one-way protocols is SYSLOG.
normalSessions of this type are used for ordinary UDP protocols with bidirectional flow of datagrams between a client and a server, e.g. NFS. The datagrams from the client are forwarded to a fixed server IP address and port and replies from the server must come from the same IP and port. From the client's point of view, all replies come from the same IP address and port as were the original ones used by the client.
any-portThis session type is prepared for situations when the server listens on a port, but it replies form another one. Thus, the first datagram from the server must have a proper source IP address but it can have an arbitrary source port number. The port is then fixed and used for all remaining datagrams of the session (in both directions) on the server side. On the client side, the original address and port remain in use. For example, TFTP servers can be configured to work this way.
any-sockThis is similar to the any-port session
type, extending it to the possibility of fixing not only
the port of the server, but even the IP address.
The first reply can come from any IP address and port.
From the client's point of view, there is an important
difference because in the transparent case,
proxy keeps the actual server address (not the port) in replies.
Be careful and check whether the actual servers are reachable
from the client's network.
broadcastThis is another communication model.
A client sends all datagrams to an IP broadcast address
and any number of servers
in the target network can reply to the client.
There is no address fixing like in the any-*
cases and all replies are forwarded downstream with their
actual addresses (keeping the original ports).
Again, you have to check whether the actual servers
are reachable from the client's network
(in both transparent and non-transparent cases).
This mode enforces nonstandard session handling and must
not be mixed with normal unicast traffic.
Similar mode uses e.g. DHCP, but the DHCP itself cannot be
processed by the udp-proxy (due to lack
of information about the original client when forwarding
the reply).
When a datagram arrives, the proxy checks its source and destination addresses and tries to assign the datagram to an existing session. If a match is found, the datagram is passed to a peer belonging to the session. If no session matches, the configuration ACL set is searched for, whether particular peers are allowed to communicate through the proxy. If this search fails, the datagram is dropped. Otherwise, a new session is established, the target server is selected and the outgoing socket to it is created or assigned.
When a non-transparent session is created
(i.e., a session initiated by a datagram destined
directly for one of the sockets
udp-proxy is listening on),
the proxy must be configured to communicate to a specific remote server
with the plug-to configuration directive.
Otherwise, the session initiation fails.
When a transparent session is created
(i.e., a session initiated by a datagram destined
to a real server “behind” the udp-proxy,
see transparency(7) for details), the proxy either communicates with the
original destination server or with the one defined by
the plug-to directive.
If the plug-to configuration directive is used
in the ACL selected for a transparent session,
it has precedence over the original destination.
This means that the udp-proxy will ignore
the original destination
and communicate with the plug-to server.
When creating the communication channel to the server(s),
the proxy uses a generic IP address and port.
It is possible to force the source address of outgoing datagrams,
either to a specific IP address, or to the address of the client
(by the source-address configuration directive).
UDP based protocols sometimes require to use a specific
source port, not a generic one.
Like the IP address, also the source port number of outgoing datagrams
can be forced in the configuration
(by the source-port configuration directive).
Of course, this setting can be done only if the client source address
is forced, too. Otherwise the proxy should not distinguish among
different server replies.
Moreover, the proxy must be in this case configured for listening
on the particular outgoing interface and forced source port,
because it cannot create a separate server-side socket for every session
(server-side sockets of different session from the same client
would have the same source socket address in this case).
Firewall administrator can choose the out-of-band method described in auth(7) for authenticating users on the proxy.
There are some limitations when using the udp-proxy for protocols with IP broadcast used as destination address.
If the proxy should process datagrams destined non-transparently to it using its client-side network broadcast address (or “limited” broadcast address 255.255.255.255), the proxy must listen on the address 0.0.0.0. The reason is that the proxy must be able to modify the source address of replies outgoing back to the client (for which, the socket bound to 0.0.0.0 is required).
If the proxy should process datagrams destined transparently to some network “behind” the proxy, it must listen on the address 0.0.0.0, or on the interface address transparently. Note that the proxy processes transparently even broadcast datagrams destined to a network directly connected to the proxy, if it is not the client-side network. Example: if the proxy operates on two interfaces with addresses 10.1.1.1 and 192.168.1.1, then a datagram sent from the address 10.1.1.2 to the address 192.168.1.255 will establish a transparent session.
The transparent broadcast mode is not allowed in the case when the incoming and outgoing interface is the same (e.g. in the case of two networks aliased to the same interface) and source-port forcing is on. The proxy has implemented a check against re-processing datagrams sent to the target network by itself (the datagrams will appear on the proxy's listening interface again). However, in this case, the proxy cannot recognize and distinguish a new datagram from the client and a datagram sent by itself. All attributes (interface name, source address, source port, target address and target port) of both of them match.
In the session-acl,
several data limitations can be defined for the session;
if any of them becomes true, the session is terminated.
max-dgrams-inThe maximum number of datagrams passed in the direction from the server(s) to the client per session. If more datagrams are sent from the server, the session will be terminated.
max-dgrams-outThe maximum number of datagrams passed in the direction from the client to the server(s) per session. If more datagrams are sent from the client, the session will be terminated.
max-bytes-inThe maximum number of bytes transferred from the server(s) to the client during a session. When exceeded, the session will be terminated.
max-bytes-outThe maximum number of bytes transferred from the client to the server(s) during a session. When exceeded, the session will be terminated.
Note that if both
the max-dgrams-in and
the max-dgrams-out limits are reached
(not exceeded), the session is terminated immediately.
This feature can significantly decrease number of “dead”
sessions having exchanged sufficient number of datagrams and waiting
for a timeout only. However, if some of the datagrams have lost
(due to the unreliability of the UDP), such a session fails because
a datagram resent by any peer will exceed the limitations.
In the session-acl,
several time limitations can be defined for the session;
if any of them becomes true, the session is terminated.
session element
of the timeout item)The maximum time for a session duration.
The session will be terminated
if session seconds elapse
since the session establishment time.
in element
of the timeout item)Timeout for datagrams from the server(s).
If in seconds elapse without
receiving a datagram from the server(s),
the session will be terminated.
out element
of the timeout item)Timeout for datagrams from the client.
If out seconds elapse without
receiving a datagram from the client,
the session will be terminated.
both element
of the timeout item)Timeout for datagrams regardless their direction.
If no datagram belonging to
a session is received for both seconds,
the session will be terminated.
Note that unidirectional idle timeouts can be affected
by the opposite peer latency. If, for instance, the client consumes
almost all the time of the in timeout,
the server may respond very quickly and in spite of that
the timeout will be reached.
The udp-proxy uses common Kernun mechanisms for several sofisticated features.
The udp-proxy reads its configuration file
and starts receiving
datagrams on UDP sockets (address/port couples) specified by the
listen-on configuration directive.
It also maintains a list of active sessions
(client/server or client/server-set couples),
the maximum number of concurrently active sessions must be set
by the configuration directive
udpserver.max-sessions.
The proxy usually runs as one parent and several child processes, see udpserver(7) for details.
The udp-proxy uses common Kernun mechanism for listening on its sockets, optionally changing root directory and running with alternative user privileges. For more detailed information, see application(5).
For the details of the udp-proxy logging possibilities and configuration, see logging(7).
For the details of the udp-proxy traffic shaping, see traffic-shaping(7).
-hPrint usage information.
-vDisplay version information and exit.
-d
dbglevSet debuging level to a specific number. Permitted values are 3 through to 9, 3 being the least and 9 the most verbose. See logging(7) for details. This setting is relevant only till configuration reading is finished.
-f cfgfileRead cfgfile
for configuration information.
-rResolve names in configuration prior to testing.
-t test_exprTest configuration according to given expression.
Format of the
test_expr is described in test-expr(5).
application(5), test-expr(5), udp-proxy.cfg(5), udpserver(5), access-control(7), host-matching(7), logging(7), traffic-shaping(7), transparency(7), udpserver(7)