Socker 1.4
				   ==========

Building
========

Basically, just run make. This will start config.sh if there is no
file config.h yet and then proceed compiling the sources. After
successful compilation you should find the executable socker in the src
directory.

The shell script config.sh creates the header file config.h and is
automagically executed when running make. Set CC, CPP, CFLAGS, LDFLAGS
(or any other variables you use for your compiler) before running
config.sh so that it uses the same settings as the make afterwards.
Otherwise, config.sh might create a wrong config.h. If you want to use
-Werror with GCC, make sure you don't use it while running config.sh
or this step will fail. If you use TenDRA you should add -Xa to CFLAGS
and you might have to add -I/usr/include as well.

Run ./config.sh --help for a list of available options. The defaults
should be fine however.

The default installation path prefix is "/usr/local". To change this
set the environment variable PREFIX to the desired path before
running config.sh or make.

For more exotic operating systems you might have to correct some of
the directories. For example, on IRIX you probably have to correct the
library directory to /usr/local/lib32:

 $ ./config.sh --library-dir=/usr/local/lib32

The default location of the configuration file is /etc/socker.conf.
You can change this by adding -DSOCKER_PATH_TO_CONFIG=\"/path/to/conf\"
to the CFLAGS or CPPFLAGS environment variable. Note the escaped
double-quotes.

Another option is to use a static configuration. The above mentioned
file will not be used then. To change the configuration it will be
required to recompile socker. See src/main.c. The static configuration
will be used if you add -DSOCKER_USE_STATIC_CONFIG to the CFLAGS or
CPPFLAGS environment variable.

For debug purposes, you can use -DSOCKER_DEBUG. Debug and error message
will then be emitted using syslog(3). These messages are rather verbose,
so you don't want to use this in general.

If config.sh fails or doesn't work properly, see config_test.log. It
contains all test programs followed compiler output i.e., warnings,
errors, other diagnostic messages. If you want to change the compiler
or compiler settings run make clobber remove all object files and
config.h. After that run make again to re-create config.h and to
re-build socker.

If you get any compiler warnings, make sure they are harmless. If you
don't know what they mean or assume they indicate a bug, inform the
author(s), please.


Installation
============

After socker has been built successfully, just run "make install". This
step usually requires privileges to copy the files to the target
directories. For security reasons, the make script does not automagically
set the setuid-bit. Use chown and chmod to configure the approriate
permissions on /usr/local/bin/socker. For example, to limit execution
permission to members of the group "sockers", you would do the following
(as root):

# chown -h root:sockers /usr/local/bin/socker
# chmod -h 4110 /usr/local/bin/socker
$ ls -l /usr/local/bin/socker
---s--x---  1 root  sockers  34791 Feb 20  2006 /usr/local/bin/socker

The library is installed in /usr/local/lib and /usr/local/include:

$ ls -lL /usr/local/include/socker.h /usr/local/lib/libsocker.*
-rw-r--r-- 1 root wheel 1803  Feb 20 2006 /usr/local/include/socker.h
-rw-r--r-- 1 root wheel 27972 Feb 20 2006 /usr/local/lib/libsocker.a
-rwxr-xr-x 1 root wheel 25404 Feb 20 2006 /usr/local/lib/libsocker.so
-rwxr-xr-x 1 root wheel 25404 Feb 20 2006 /usr/local/lib/libsocker.so.1


Configuration
=============

The default path for the configuration file is /etc/socker.conf. It is
important that this file is root-owned and only editable by trusted
staff members. As an alternate it is also possible to compile-in a
static configuration instead of using this configuration file.

The format is similar to the one of /etc/passwd. All items are
separated by a colon and the entries are terminated by a line-break.
The following shows an arbitrary example configuration:

# Format:
#
# <user>:<domain>:<type>:<protocol>:<address>:[<port-range>]
#
# Note that colons, for example, in IPv6 addresses have to be escaped
# with a backlash. However, it's easier to read if you use quotes
# which is another way to escape characters. Quote characters can also
# be escaped by a backslash if necessary. Line breaks cannot be
# escaped though. IPv4 and IPv6 addresses can be specified with an
# additional CIDR netmask.

# The first rules allow everybody to bind TCP and UDP sockets for
# IPv4 and IPv6 on unprivileged ports. This is normally unnecessary
# but it might useful to avoid special cases.
*:inet:dgram:0:*:1024-65535
*:inet:stream:0:*:1024-65535
*:inet6:dgram:0:*:1024-65535
*:inet6:stream:0:*:1024-65535

# The next rules would be useful for a DNS server
bind:inet:dgram:0:0.0.0.0:53
bind:inet:stream:0:0.0.0.0:53
bind:inet6:stream:0:"::":53
bind:inet6:stream:0:"::":53

# These two are useful for web servers
apache:inet:stream:0:*:80
apache:inet6:stream:0:*:80

# This would be useful for local-only FTP servers
ftp:pf_inet:sock_stream:0:127.0.0.0/8:21
ftp:pf_inet:sock_stream:0:"::1":21

The items domain, type and protocol refer to the same parameters as in
the socket(2) system call. At the moment Socker supports only the
domains PF_INET (IPv4) or PF_INET6 (IPv6). The socket type may be
SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, SOCK_SEQPACKET, SOCK_RDM. The
protocol can be either a number or the associated identifier according
to /etc/protocols which is used by getprotobyname(3). The socket
domains and types are compared case-insensitively. The "PF_"
respectively "SOCK_" prefixes are also optional.


Using Socker
============

This example C program shows how Socker is used. It acquires an IPv4
TCP on port 80 just like a web server would. It then waits for an
incoming connection and terminates:

#include <sys/socket.h>
#include <stdlib.h>
#include <stdio.h>
#include <socker.h>

int
main(void)
{
  int fd;

  fd = socker_get(PF_INET, SOCK_STREAM, 0, "0.0.0.0", 80);
  if (-1 == fd) {
    fprintf(stderr, "socker() failed\n");
    exit(EXIT_FAILURE);
  }
  if (listen(fd, 10)) {
    perror("listen()");
    exit(EXIT_FAILURE);
  }
  fprintf(stderr, "Listening on port 80\n");

  if (-1 != accept(fd, NULL, NULL)) {
    fprintf(stderr, "Got incoming connection\n");
    exit(EXIT_SUCCESS);
  }

  return EXIT_FAILURE;
}

To compile the program successfully you have to link it against the
socker library. It's usually as simple as this:

$ cc $(socker-config --cflags --libs) example.c -o example

socker-config is a script which is installed to $bin_dir i.e.,
/usr/local/bin by default along with socker and can be used to query
the necessary compiler flags.

Modifying existing programs to use Socker instead of requiring a
setuid-bit or being started by root should be straight forward. You
only have to replace the calls to socket(2) and bind(2) with
socker_get(). The address must be given in its textual representation
as a NUL-terminated string. For IPv4 and IPv6 addresses you would
usually use inet_ntop(3) to convert addresses into strings.


Using Socker as wrapper
=======================

It is not strictly necessary that applications support socker and use
the socker_get() function. Instead socker can be used as function call
wrapper for socket() and bind(). This usually requires that the
application is dynamically linked and the executable must not have the
setuid- or setgid-bit set. The wrapper is typically used as follows:

 $ LD_PRELOAD=/path/to/libsocker_wrap.so application

See your systems man pages for more information about this mechanism,
for example ld.elf_so(1) or loader(1).

IRIX does not support LD_PRELOAD but provides a similar feature. On
IRIX use this instead:

 $ _RLD_LIST=/path/to/libsocker_wrap.so:DEFAULT application

A minor draw-back of the wrapper is that you have to provide rules with
the "protocol" item being a wildcard or empty. The reason is that it's
not possible to determine this value from an established socket.

For example, the necessary rules for a web server may look as this:

apache:inet:stream::*:80
apache:inet6:stream::*:80

or

apache:inet:stream:*:*:80
apache:inet6:stream:*:*:80

The latter is less strict as it could also be used to create a socket
with an abitrary protocol value as far as possible on your system. The
former version does not allow creating a socket and works only for bind
requests as the protocol is unspecified.

Sometimes applications do not even attempt to create a privileged socket
when they're not started by root. Others might insist on using
privileged features like chroot(). In this case the wrapper won't work
and the applications must be fixed.


Dependencies
============

There are not supposed to be any dependencies except a more or less
POSIX-compliant operating system with installed system C header files,
a C compiler and the make tool. config.sh requires a Bourne Shell but
the contents of config.h can be configured by hand if absolutely
necessary. config.sh utilizes a few standard Unix tools e.g., sed.


Author: Christian Biere <christianbiere at gmx dot de>
Last-Edited: 2009-04-20