Next: Define servers, Up: Configuring Serveez [Contents][Index]
A port (in Serveez) is a transport endpoint. You might know them
from other TCP or UDP server applications. For example: web servers
(HTTP) usually listen on TCP port 80. However, there is more than TCP
ports: we have UDP, ICMP and named pipes each with different options to
set. Every port has a unique name you assign to it. The name of the port is
later used to bind servers to it.
The following examples show how you setup different types of port
configurations. You start to define such a port using the procedure
define-port!. The first argument specifies the
name of the port configuration. The remaining argument describes the
port in detail.
This table describes each configuration item for a port in Serveez. Note that not each item applies to every kind of port configuration.
proto (string)This is the main configuration item for a port configuration setting up the type of port. Valid values are ‘tcp’, ‘udp’, ‘icmp’, ‘raw’ and ‘pipe’. This configuration item decides which of the remaining configuration items apply and which do not.
port (integer in the range 0..65535)The port item determines the network port number on which TCP and UDP
servers will listen. Thus it does not make sense for ICMP and named pipes.
If you pass ‘0’ Serveez will determine a free port in the range
between 1 and 65535.
recv (string or associative list)This item describes the receiving (listening) end of a named pipe
connection, i.e., the filename of a fifo node to which a client can
connect by opening it for writing. Both the recv and send
item apply to named pipes only. The value can either be an associative
list or a simple filename. Using a simple filename leaves additional
options to use default values. They deal mainly with file permissions
and are described below.
send (string or associative list)This item is the sending end of a named pipe connection. It is used to send data when the receiving (listening) end has detected a connection. The following table enumerates the additional options you can setup if you pass an associative list and not a simple filename.
name (string)The filename of the named pipe. On Windows systems you can also specify the hostname on which the pipe should be created in the format ‘\\hostname\pipe\name’. By default (if you leave the leading ‘\\hostname\pipe\’ part) the pipe will be created on ‘\\.\pipe\name’ which refers to a pipe on the local machine.
permission (octal integer)This specifies the file permissions a named pipe should be created with. The given number is interpreted in a Unix’ish style (e.g., ‘#o0666’ is a permission field for reading and writing for the creating user, all users in the same group and all other users).
user (string)The file owner (username) of the named pipe in textual form.
group (string)The file owner group (groupname) of the named pipe in textual form. If this item is left it defaults to the file owner’s primary group.
uid (integer)The file owner of the named pipe as a user id. You are meant to specify
either the uid item or the user item. Serveez will
complain about conflicting values.
gid (integer)The file owner group of the named pipe as a group id. This item
defaults to the file owner’s primary group id. You are meant to specify
either the gid item or the group item. Serveez will croak
about conflicting values.
ipaddr (string)This configuration item specifies the IP address (either in dotted decimal form e.g., ‘192.168.2.1’ or as a device description which can be obtained via ‘serveez -i’) to which a server is bound to. The ‘*’ keyword for all known IP addresses and the ‘any’ keyword for any IP address are also valid values. The default value is ‘*’. The configuration item applies to network ports (TCP, UDP and ICMP) only.
device (string)The device configuration item also refers to the IP address a server
can be bound to. It overrides the ipaddr item. Valid values are
network device descriptions (probably no aliases and no loopback devices).
It applies to network ports (TCP, UDP and ICMP) only.
A note on device bindings: Device bindings are based on the
SO_BINDTODEVICE socket layer option. This option is not available
on all systems. We only tested it on GNU/Linux (2.2.18 and 2.4.17 as of
this writing). Device bindings are very restrictive: only root can do it
and only physical devices are possible. The loopback device cannot be used
and no interface alias (i.e., ‘eth0:0’). A device binding can only
be reached from the physical outside but it includes all aliases for the
device. So if you bind to device ‘eth0’ even ‘eth0:0’ (and all
other aliases) are used. The connection has to be made from a remote
machine. The advantage of this kind of binding is that it survives
changes of IP addresses. This is tested for ethernet networks (i.e., eth*)
and isdn dialups (i.e., ippp*). It does not work for modem dialups
(i.e., ppp*) (at least for Stefan’s PCMCIA modem). The problem seems to be
the dialup logic actually destroying ppp*. Other opinions are welcome.
Device bindings always win: If you bind to ‘*’ (or an individual IP
address) and to the corresponding device, connections are made with
the device binding. The order of the bind-server! statements
do not matter. This feature is not thoroughly tested.
backlog (integer)The backlog parameter defines the maximum length the queue of
pending connections may grow to. If a connection request arrives with the
queue full the client may receive an error. This parameter applies to
TCP ports only.
type (integer in the range 0..255)This item applies to ICMP ports only. It defines the message type identifier used to send ICMP packets (e.g., ‘8’ is an echo message i.e., PING).
send-buffer-size (integer)The send-buffer-size configuration item defines the maximum number
of bytes the send queue of a client is allowed to grow to. The item
influences the “send buffer overrun error condition”. For packet oriented
protocols (UDP and ICMP) you need to specify at least the maximum number
of bytes a single packets can have. For UDP and ICMP this is 64 KByte.
The value specified here is an initial value. It is used unless the
server bound to this port changes it.
recv-buffer-size (integer)The recv-buffer-size configuration item defines the maximum
number of bytes the receive queue of a client is allowed to grow to.
The item influences the “receive buffer underrun error condition”. The
value specified here is an initial value. It is used unless the server
bound to this port changes it.
connect-frequency (integer)This item determines the maximum number of connections per second the port will accept. It is a kind of “hammer protection”. The item is evaluated for each remote client machine separately. It applies to TCP ports.
allow (list of strings)Both the allow and deny lists are lists of IP addresses in
dotted decimal form (e.g., ‘192.168.2.1’). The allow list defines
the remote machines which are allowed to connect to the port. It applies
to TCP ports.
deny (list of strings)The deny list defines the remote machines which are not allowed to
connect to the port. Each connection from one of these IP addresses will
be refused and shut down immediately. It applies to TCP ports.
Definition of a TCP port configuration with the name foo-tcp-port. The
enhanced settings are all optional including the ipaddr property
which defaults to ‘*’. The ipaddr item can contain any form
of a dotted decimal internet address, a ‘*’, ‘any’ or an
interface description which you can obtain by running ‘serveez -i’.
(define-port! 'foo-tcp-port '(
;; usual settings
(proto . tcp) ;; protocol is tcp
(port . 42421) ;; network port 42421
(ipaddr . *) ;; bind to all known interfaces
(device . eth0) ;; bind to network card
;; enhanced settings
(backlog . 5) ;; enqueue max. 5 connections
(connect-frequency . 1) ;; allow 1 connect per second
(send-buffer-size . 1024) ;; initial send buffer size in bytes
(recv-buffer-size . 1024) ;; initial receive buffer size in bytes
;; allow connections from these ip addresses
(allow . (127.0.0.1 127.0.0.2))
;; refuse connections from this ip address
(deny . (192.168.2.7))
))
Definition of a pipe port configuration with the name foo-pipe-port.
When bound to a server it creates the receiving end and listens on that.
If some client accesses this named pipe the server opens the sending end
which the client has to open for reading previously.
The only mandatory item is the file name of each pipe. If you want to specify a user creating the named pipe (file ownership) use either the user or the uid setting. Same goes for the items group and gid.
(define-port! 'foo-pipe-port `(
(proto . pipe) ;; protocol is named pipe
;; specify the receiving endpoint
(recv . ((name . ".foo-recv") ;; name of the pipe
(permissions . #o0666) ;; create it with these permissions
(user . "calvin") ;; as user "calvin"
(uid . 50) ;; with the user id 50
(group . "heros") ;; which is in the group "heros"
(gid . 100))) ;; with the group id 100
;; specify the sending endpoint
(send . ((name . ".foo-send")
(permissions . #o0666)
(user . "hobbes")
(uid . 51)
(group . "stuffed")
(gid . 101)))
))
Define an ICMP port configuration which will accept connections from the
network interface ‘127.0.0.1’ only and communicates via the message
type 8 as described in the Tunnel Server chapter. The name of
this port configuration is foo-icmp-port. When you are going to bind
some server to this kind of port you have to ensure root (or
Administrator under Windows) privileges.
(define-port! 'foo-icmp-port '((proto . icmp)
(ipaddr . 127.0.0.1)
(type . 8)))
Simple definition of a UDP port configuration with the name foo-udp-port.
(define-port! 'foo-udp-port `((proto . udp)
(port . 27952)))
Next: Define servers, Up: Configuring Serveez [Contents][Index]