Next: , Up: Configuring Serveez   [Contents][Index]


1.5.1 Define ports

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.

1.5.1.1 Port configuration items

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.

1.5.1.2 TCP port definition

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))
  ))

1.5.1.3 Pipe port definition

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)))
   ))

1.5.1.4 ICMP port definition

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)))

1.5.1.5 UDP port definition

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]