[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can skip this section if you are familiar with the GNU'ish way of configuring, compiling and installing a GNU package.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Serveez can be found on http://ftp.gnu.org/gnu/serveez/, on one of the mirrors (http://www.gnu.org/prep/ftp.html) or at its original location http://www.textsure.net/~ela/download/. At this location you will also find the RPM package mentioned in the next section.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Serveez needs GNU Guile (Ubiquitous Intelligent Language for Extensions). The current version of Serveez is known to work with Guile 1.3 and later. Guile can be downloaded at http://ftp.gnu.org/gnu/guile/.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
sleepless ~> gzip -cd serveez-0.1.5.tar.gz | tar xvf - |
sleepless ~> cd serveez-0.1.5 |
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’.
With this option you enable the detection of various compiler warning switches. Most guessed options come from GCC.
When enabling this feature the configure script tries some of the commonly known compiler optimization switches.
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.
If you want to compile for the i686 target try this option.
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.
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.
If you enable this feature the control protocol will be supported by Serveez. This protocol is for remote control of the server.
Enabling this feature tells the software package to support the IRC (Internet Relay Chat) protocol.
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.
In order to use the Serveez software for the textSure (C) chat system you MUST enable this feature.
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.
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.
The DIR argument specifies a Guile installation directory.
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.
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’.
This option enables support for a simple network time protocol server.
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.
This option enables the use of the sendfile()
system call.
Disabling it using ‘--disable-sendfile’ provides a work-around
for bogus implementations of sendfile()
.
If you do *not* want the Gnutella spider client compiled in you need to *disable* this option.
This option tells Serveez to process any passwords as crypt()ed.
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.
By enabling this you will get a fake ident server included in the binary executable.
If you enable this feature the user is able to write servers using Guile.
This includes the program passthrough server in the Serveez binary. The server provides basic inetd functionality.
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.
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.
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 |
sleepless ~/serveez-0.1.5> make |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The binary RPM distribution ‘serveez-0.1.5-1.i386.rpm’ of Serveez has been prebuild on a x86 / GNU/Linux 2.4 machine. It is a relocatable package with its default installation directory in ‘/opt/serveez’. You need to ensure root privileges in order to install or remove rpm packages.
sleepless ~> rpm -qiRl -p serveez-0.1.5-1.i386.rpm |
sleepless ~> rpm -Uvh serveez-0.1.5-1.i386.rpm \ [ --nodeps ] [ --prefix=/opt/serveez ] serveez #################### |
sleepless ~> rpm -ev serveez-0.1.5 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The binary Debian distribution ‘serveez_0.1.5_i386.deb’ of Serveez has been prebuild on a x86 / GNU/Linux 2.4 machine. You need to ensure root privileges in order to install or remove Debian packages.
sleepless ~> dpkg -I serveez_0.1.5_i386.deb sleepless ~> dpkg -c serveez_0.1.5_i386.deb |
sleepless ~> dpkg -i serveez_0.1.5_i386.deb |
sleepless ~> dpkg -r serveez |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
-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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [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 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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)) )) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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))) )) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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))) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Simple definition of a UDP port configuration with the name "foo-udp-port".
(define-port! 'foo-udp-port `((proto . udp) (port . 27952))) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 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 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 Existing servers.).
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on September, 7 2009 using texi2html 1.78.