2. Using Serveez

We know, you usually don't read the documentation. Who does. But please, read at the very least this chapter. It contains information on the basic concepts. Larger parts of the manual can be used as a reference manual for the various servers.

2.1 Building and installing

2.1.1 Rebuild the package from the sources

2.1.1.1 Getting the source

2.1.1.2 Requirements

2.1.1.3 Installation

Unpack the distribution tarball:

sleepless ~> gzip -cd serveez-0.1.5.tar.gz | tar xvf -

Change into the source directory:

sleepless ~> cd serveez-0.1.5

Configure the source package for your system:

We recommend to use `--enable-opt' unless you have a good reason not to do so. It follows a complete list of the `configure' script options. The list of known options can the obtained via `./configure --help'.

`--enable-warn'

With this option you enable the detection of various compiler warning switches. Most guessed options come from GCC.

`--enable-opt'

When enabling this feature the configure script tries some of the commonly known compiler optimization switches.

`--with-opt=FLAGS'

You can pass here a comma separated list of additional compiler flags which will be tested. This feature is only active if you specified the above `--enable-opt' switch.

`--enable-ppro'

If you want to compile for the i686 target try this option.

`--enable-486'

Compiler optimizations for the i486 target of GCC. If you passed `--enable-ppro' and this option could be used, then the i486 option will be silently dropped.

`--enable-debug'

All of the debug messages (debug: some annoying crap text) can be suppressed by setting the debug level (-v). If you do not want these messages built in at all then disable this feature.

`--enable-control-proto'

If you enable this feature the control protocol will be supported by Serveez. This protocol is for remote control of the server.

`--enable-irc-proto'

Enabling this feature tells the software package to support the IRC (Internet Relay Chat) protocol.

`--enable-irc-ts'

This feature is only available if you enabled the IRC protocol. If you enabled both of them then Serveez will support the so called TimeStamp protocol, which is an EFNet extension of the original IRC protocol. In order to connect to EFNet you MUST use this option.

`--enable-awcs-proto'

In order to use the Serveez software for the textSure (C) chat system you MUST enable this feature.

`--enable-http-proto'

When using Serveez as part of the textSure (C) chat system you will will have need of an additional web server. This option makes Serveez support a simple HTTP protocol.

`--enable-flood'

If you enable this feature Serveez will support a simple built-in flood protection. It is always useful to protect the software from flood clients.

`--with-guile=DIR'

The DIR argument specifies a Guile installation directory.

`--with-guile-source=DIR'

If the user wants to link Serveez against a static Guile core library you can pass the DIR argument to specify the location of a Guile source distribution which will then be configured and built.

`--with-mingw=DIR'

When compiling under M$-Windows the DIR argument specifies the path to the extra MinGW32 library and header files. If you want the final executable to use the Cygwin project's `cygwin1.dll' instead, you have to disable this option by passing the configure script `--without-mingw' or `--with-mingw=no'.

`--enable-sntp-proto'

This option enables support for a simple network time protocol server.

`--enable-poll'

If the target system supports poll() and this feature is enabled the main file descriptor loop is done via poll(). This helps to work around the (g)libc's file descriptor limit. Otherwise Serveez always falls back to the select() system call.

`--enable-sendfile'

This option enables the use of the sendfile() system call. Disabling it using `--disable-sendfile' provides a work-around for bogus implementations of sendfile().

`--enable-gnutella'

If you do *not* want the Gnutella spider client compiled in you need to *disable* this option.

`--enable-crypt'

This option tells Serveez to process any passwords as crypt()ed.

`--enable-tunnel'

If you enable this feature the port forwarder will be included. This is useful if you plan to use Serveez as a gateway or firewall workaround.

`--enable-fakeident'

By enabling this you will get a fake ident server included in the binary executable.

`--enable-guile-server'

If you enable this feature the user is able to write servers using Guile.

`--enable-passthrough'

This includes the program passthrough server in the Serveez binary. The server provides basic inetd functionality.

`--enable-iflist'

If Serveez is unable to detect the correct list of local network interfaces (`serveez -i') you can disable this option and setup them manually in the configuration file.

`--enable-heap-count'

This option depends on `--enable-debug'. With the debugging option disabled there is also no support for heap counters. The heap counters are used to detect memory leaks in Serveez.

`--with-thread-safety'

If this option is enabled (disabled by default) Serveez provides some thread safety functionality which can be used by applications based on the Serveez core API and by Serveez itself.

sleepless ~/serveez-0.1.5> sh configure --enable-opt

Now compile the package:

sleepless ~/serveez-0.1.5> make

Install serveez:

You must have root privileges if you want to install the package in the standard location `/usr/local' or in any location that is only writable by root.

sleepless ~/serveez-0.1.5> make install

If you have problems building the package out of the box this is due to GNU libtool's inability to handle dynamic linking in most cases. That is why we recommend to try to configure the package with `--disable-shared' and/or the native compiler (if any). When the build process is not able to link against an existing Guile installation you can try to use the `--with-guile-source=DIR' configure option.

2.1.2 Installing the RPM package

Query information:

sleepless ~> rpm -qiRl -p serveez-0.1.5-1.i386.rpm

Install the package:

sleepless ~> rpm -Uvh serveez-0.1.5-1.i386.rpm \ [ --nodeps ] [ --prefix=/opt/serveez ] serveez ####################

Uninstall the package:

sleepless ~> rpm -ev serveez-0.1.5

2.1.3 Installing the Debian package

Query information:

sleepless ~> dpkg -I serveez_0.1.5_i386.deb sleepless ~> dpkg -c serveez_0.1.5_i386.deb

Install the package:

sleepless ~> dpkg -i serveez_0.1.5_i386.deb

Uninstall the package:

sleepless ~> dpkg -r serveez

2.2 Environment variables

When using the serveezopt package or playing around with the dynamic server module loader of Serveez you can tell the core API of Serveez (which is the `libserveez.[so|dll]' library) to use an additional load path to find these server modules. The environment variable `SERVEEZ_LOAD_PATH' holds this information. You can set it up via:

on Unices sleepless ~> export SERVEEZ_LOAD_PATH=/home/lib:/usr/local/lib or on Windows C:\HOME> set SERVEEZ_LOAD_PATH=C:\HOME\LIB;C:\USR\LOCAL\LIB

2.3 Starting Serveez

When Serveez is started it reads its configuration from a file called `serveez.cfg' in the current directory and runs the server loop afterwards. Press ^C to abort the execution of this program. Serveez is not interactive and does not automatically detach from the terminal.

2.4 Command line options

-h, --help

Display this help and exit.

-V, --version

Display version information and exit.

-i, --iflist

List local network interfaces and exit.

-f, --cfg-file=FILENAME

File to use as configuration file (serveez.cfg).

-v, --verbose=LEVEL

Set level of logging verbosity.

-l, --log-file=FILENAME

Use FILENAME for logging (default is stderr).

-P, --password=STRING

Set the password for control connections.

-m, --max-sockets=COUNT

Set the maximum number of socket descriptors.

-d, --daemon

Start as daemon in background.

-c, --stdin

Use standard input as configuration file.

2.5 Configuring Serveez

As noted above Serveez is configured via a configuration file which is by default `serveez.cfg' and can be set by passing the `-f' command line argument. When you pipe a file into Serveez or pass the `-c' argument on the command line the input stream will be used as configuration file no matter whether you passed a `-f' command line switch or not.

To make configuring more fun we did not invent yet another configuration file format. Instead we use a dialect of the Scheme programming language called GNU Guile (http://www.gnu.org/software/guile/). There is no need to be worried if you are not a programmer. What you have to do is really simple and this document shows you everything you need to know. We also provide many examples. However there are some simple concepts you have to understand. The following paragraphs will explain them.

The idea of the configuration file is this: Serveez starts, runs the configuration file (other applications usually just read them and remember the settings) and finally enters its main loop doing the things you wanted it to.

There are three things you have to do in the configuration file.

2.5.1 Define ports		Port configuration definition
2.5.2 Define servers		Server definition
2.5.3 Bind servers to ports		How to bind servers to port configurations

2.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 Guile function (define-port!). The first argument to this functions specifies the name of the port configuration. The remaining argument describes the port in detail.

2.5.1.1 Port configuration items

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.

2.5.1.2 TCP port definition

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

2.5.1.3 Pipe port definition

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

2.5.1.4 ICMP port definition

(define-port! 'foo-icmp-port '((proto . icmp) (ipaddr . 127.0.0.1) (type . 8)))

2.5.1.5 UDP port definition

(define-port! 'foo-udp-port `((proto . udp) (port . 27952)))

2.5.2 Define servers

A server (in Serveez) is a snippet of code that implements some protocol. There are many servers built into Serveez but you can implement your own, too. For example we provide a webserver implementing the Hypertext Transfer Protocol (HTTP). Each server has a different set of options you can change. You can have many instances of every server, each with a different set of options. For example: You can create a webserver on TCP port 42420 publishing the Serveez documentation and also have another webserver on a different port publishing something else. Every server has a unique name you assign to it. The name of the server is later used to bind it to a port.

The following example instantiates a server with the short name "foo". Each server in Serveez has got a short name. See section 4.4 Existing servers, for the details. This example demonstrates everything which is possible in server configurations. You start a definition of a server with the guile function (define-server!). The following argument specifies the name of the server instance (in this case "foo-server") which starts with the short name. The second argument describes the server in detail. Each configuration item is setup with a (key . value) pair where "key" is the name of the configuration item and "value" is the value which depends on the type of the item. See section 4.3 Some words about server configuration, for a detailed description of each type of value.

(define-server! 'foo-server '( (bar . 100) ;; number (reply . "Booo") ;; character string (messages . ;; list of strings ("Welcome to the foo test server." "This one echos your lines.")) (ports . (5 6 7 8 9)) ;; list of numbers (port . foo-tcp-port) ;; a port configuration (assoc . (( "GNU" . "great" ) ;; associative list ( "Tree" . "tall" ))) (truth . #f) ;; boolean value ))

Serveez provides a number of server types. Each of them has a short name. The name of the server instance has to begin with this short name followed by a dash (-). You can append any suffix then. In the example above "foo" is the short name and "foo-server" the name of the server instance.

2.5.3 Bind servers to ports

Finally you can bind servers to ports. When you do so the server you created listens on the port, accepts connections and serves clients. It does so as soon as Serveez enters its main loop right after running the configuration file. Serveez won't stop until you interrupt it (e.g. by pressing ^C in the terminal you started it in).

This example binds the server "foo-server" (s.a.) to the port "foo-tcp-port" which was described above. Therefore you need to call the guile function (bind-server!) which takes two arguments specifying the name of a port configuration and a server instance. Both need to be defined before you can write this statement.

(bind-server! 'foo-tcp-port 'foo-server)

One of the main features of Serveez is that you can bind multiple servers to the same port. This for example is useful to pass braindead firewall configurations or proxy servers. It is also possible to bind servers to ports they are actually not designed for. This might be used for debugging servers or other funny things (again, think about the firewall). This is the point we have to warn you: Some protocols cannot share the same port (e.g. the tunnel server) and some protocols simply won't work on 'wrong' ports. Additionally, you will not get error messages when that happens. The server just will not work then.

2.5.4 Additional configuration possibilities

The three functions (define-port!), (define-server!) and (bind-server!) return #t on success and #f on failure. For your convenience we provide some more Guile functions. Some of these are based upon the above. You will find the additional functions in the file `serveez.scm'. In order to include this convenience functionality you can (primitive-load "serveez.scm") at the top of the configuration file.

(interface-add! . interface)

Add one more network interface to the list of known interfaces. You can get the list of known interfaces by running `serveez -i'. The interface argument must be in dotted decimal form (e.g. 127.0.0.1). Serveez provides this function for systems where it is unable to detect the list of network interface automatically.

(loadpath-add! . path)

Extends the load path for server modules by the path name path.

(bind-servers! . args)

This function is based upon (bind-server!). It takes a list of port configurations and servers and binds each to another.

(bind-tcp-port-range! from to . servers)

Bind the list of servers to simple TCP port configurations whose network ports range between from and to both inclusive.

(bind-udp-port-range! from to . servers)

Bind the list of servers to simple UDP port configurations whose network ports range between from and to both inclusive.

(serveez-verbosity verbosity)

Set the core library's logging verbosity to the verbosity level. Lesser values mean fewer logging messages. This settings gets overridden by command line.

(serveez-maxsockets max)

Set the number of maximum socket descriptors (number of concurrent connections). When passing Serveez the -m command line argument this setting gets overridden, too.

(serveez-passwd password)

Set the password for the control protocol.

We now have a closer look at the internals of Serveez. If you are not interested in that have a look at the existing servers (See section 4.4 Existing servers.).