libserver(8) BSD System Manager's Manual libserver(8)NAMElibserver — Generic Server Library
SYNOPSIS
#include <libserver.h>
(-pthread) -I/usr/local/include -L/usr/local/lib -lserver(threads)DESCRIPTION
The Libserver package supplies 3 libraries that implement generic
servers. The libraries perform network and concurrency tasks. You sup‐
ply code to service connections. All 3 libraries service TCP or UNIX-
domain connections. Separate libraries implement multi-process, multi-
threaded, and event-driven servers. This manual documents the multi-
process and multi-threaded libraries. The event-driven library is
described in the "libserverevents" manual.
To create a multi-process server, link with -lserver. To create a multi-
threaded server, link with -lserverthreads.
Example echo servers are included in the libserver source distribution.
USAGE
The libraries provide your server's "main" function. You define 3 func‐
tions to match the following prototypes.
void serv_init_func();
void serv_worker_init_func();
void serv_service_connection( FILE * );
Do not define any other global symbol beginning with the five characters
´serv_' because the library reserves that namespace.
SERV_SERVICE_CONNECTION()
One master process/thread grows and shrinks a pool of workers to service
connections. Workers call serv_service_connection() once to service each
connection that they accept. Workers close connections when serv_ser‐
vice_connection() returns.
serv_service_connection() is invoked with the FILE pointer of a buffered
stream that is connected to the client. You use the standard buffered IO
functions to communicate with the client. If you want to use non-
buffered IO, use the fileno() function to determine the descriptor that
is associated with the FILE pointer. Do not close the FILE pointer or
its underlying descriptor, or you will crash your server.
SERV_INIT_FUNC()
In serv_init_func() perform the initialization tasks your server needs to
do once at server start-up before any workers are created.
The library calls serv_init_func():
· after changing to the directory specified by the -r command line
option.
· before attempting to change the server's user and group to the values
specified by the command line options. If the server starts as root
serv_init_func(), executes as root.
· before the server becomes a daemon and starts listening for connec‐
tions. The standard streams are connected to the terminal from which
the server was started. Error and informative messages should be
sent to the terminal.
SERV_SET_NAME()
Call serv_set_name() inside serv_init_func() to set the server's name.
void serv_set_name( char * );
If not set the server's name defaults to "server". The server's name is
used in two ways:
· When the server is running, stderr is connected to /dev/null. Errors
must are reported with syslog(3). The library calls openlog() with
the server's name as argument to ensure that log entries are identi‐
fied by the server's name.
· The server's pidfile is written to /var/run/ if the server is started
as root. The filename is the server's name with ".pid" appended to
it. This file is used by rc.d scripts to stop the server. A sample
script is included in the libserver distribution.
SERV_SET_PERIODIC()
In serv_init_func(), you can install a function for the master to invoke
periodically with:
void serv_set_periodic( void (*)(), int );
The function pointed to by first argument is called when the number of
seconds specified by the second argument have elapsed and then again
repeatedly when that number of seconds has elapsed since the last call.
SERV_WORKER_INIT_FUNC()
In serv_worker_init_func() perform the initialization tasks each worker
needs to perform independently of the master. For example, open unique
database connections for each worker in serv_worker_init_func().
serv_worker_init_func() is called after:
· the user and group of the process have been changed to the values
specified by the -u and -g command line options.
· the standard streams are connected to /dev/null. Errors must be
reported with syslog(3).
SIGNALS
Both libraries need to catch SIGTERM, so do not change the disposition of
that signal.
The multi-threaded library additionally needs to catch SIGUSR1, so do not
change the disposition of that signal in multi-threaded servers.
Upon receipt of SIGBUS or SIGSEGV, libserver restarts servers with a call
to execv(3). If you want to do something else, install your own handler.
If your server starts as root and changes user and group, the library
will be unable to restart if your server is not executable by the user or
group.
The library will be unable to perform the operations that require root
privileges after restart unless you turn on the setuid bit of the server
(chmod u=+s).
ACCESS TO CONFIGURATION VARIABLES
You can examine the following configuration variables from your code, but
you must not modify them. See the CONFIGURATION section for more infor‐
mation.
char *serv_config_file;
char *serv_root_dir;
char *serv_interface;
char *serv_port;
char *serv_user;
char *serv_group;
serv_config_file points to the value passed to the -f option. Defaults
to NULL.
serv_root_dir points to the value passed to the -r option. Defaults
to NULL.
serv_interface points to the value passed to the -i option. Defaults
to "".
serv_port points to the value passed as argument to the -p
option. Defaults to "1966".
serv_user points to the value passed as argument to the -u
option. Defaults to "nobody".
serv_group points to the value passed as argument to the -g
option. Defaults to "nobody".
THREADED SERVERS
If your threaded server encounters an unrecoverable error call
serv_thread_exit() in the thread with the error. DO NOT call
pthread_exit() directly.
void serv_thread_exit();
To create and manage globally-visible data that is unique for each con‐
nection use the pthread thread-specific data functions. The following
are the minimal set of functions that you need to understand. All are
documented in manual pages.
pthread_key_create();
pthread_setspecific();
pthread_getspecific();
Each thread maps keys to its thread-specific storage space.
· In scgi_init_func(), create your keys with pthread_key_create().
Pass a destructor function to pthread_key_create() to free the space
workers associate with keys, or your server will leak memory on
thread termination.
· In scgi_worker_init_func(), malloc(3) the current thread's thread-
specific storage and install it with pthread_setspecific().
· In scgi_request_handler(), retrieve your thread-specific storage with
pthread_getspecific(). Put fresh data in your storage as you like in
each invocation of scgi_request_handler().
· Release any dynamically allocated storage that are not freed by your
keys' destructors before returning from scgi_request_handler().
CONFIGURATION
Libserver writes its pidfile into /var/run/ if is started as root. The
library is stopped with SIGTERM. Libserver does graceful stops. Idle
workers exit immediately. Workers with established connections continue
to service those connections until they close. If you want to kill a
server outright, send it a SIGKILL. A sample control script is provided
in the server distribution. To use the script, you must replace all
occurrences of "server" with the value you pass to serv_set_name(). The
script must be renamed as the value you passed to serv_set_name() and
installed in /usr/local/etc/rc.d.
Two variables must be added to /etc/rc.conf to use the script. Substi‐
tute your server's name for "server":
server_enable="YES"
server_flags="-u www -g www -r /usr/local/server"
If the "enable" variable is set to "YES", the server is started at system
start. Use the following rc commands:
/usr/local/etc/rc.d/server start
/usr/local/etc/rc.d/server stop
/usr/local/etc/rc.d/server restart
/usr/local/etc/rc.d/server status
If you do not want the server started on system start, then set
libserver_enable="NO"
and use the following commands:
/usr/local/etc/rc.d/server forcestart
/usr/local/etc/rc.d/server forcestop
/usr/local/etc/rc.d/server forcerestart
/usr/local/etc/rc.d/server forcestatus
Servers do not exit until all threads with active connections have closed
those connections. To prevent idle connections from delaying exit indef‐
initely, place a timeout on socket reads or writes with setsockopt().
Placing a read timeout on a socket is demonstrated in the echo_tls.c
example program included in the libserver source distribution.
COMMAND-LINE OPTIONS
The following command line options are recognized by libserver servers.
All of these are optional.
-r User the -r option to specify the server root directory. Libserver
chdir(2)s there.
-l By default, the library listens on all TCP interfaces it can find
capable of IPv4 or IPv6. The -l option instructs the library to lis‐
ten on a UNIX-domain socket instead. Specify the path to the socket
as argument. The server creates the socket when it starts, unlinking
it first if it already exists in the filesystem. The owner and group
of the socket are changed to the values of the -u and -g options.
The permisssions of the socket are set to srwxrwx---. You cannot
specify the -l option together with the -p or -i options.
-p The -p option specifies the port to listen on. This defaults to
1966. To bind to a port lower than 1024, the server must be started
as root.
-i By default, libserver accepts connections on all interfaces it can
find capable of IPv4 or IPv6. The -i option limits libserver to
accepting connections from a specified interface. Pass the IP
address of the desired interface as argument.
-n The -n options specifies the number of idle workers the master keeps
ready. the value defaults to 5. The library actually allows the
number of idle workers to reach half this value before it creates
more.
-m The -m option specifies the maximum number of workers which may be
running at any time. The value defaults to 25. This value is the
maximum number of simultaneous connections a server can accept. The
value specified must be equal to or greater than the value specified
for -n.
-q The -q option specifies the backlog of client connections queued by
the OS kernel for the server to subsequently service. This value
defaults to 1024. Note that the kernel actually uses a queue of 1.5
times the size of the specified value. Connections arriving when the
queue is full are dropped by the kernel. Libserver does not let you
set this value to less than 1024.
-u
-g The -u and the -g options are used to specify the user and group for
the server. Both values default to "nobody". For libserver to
change user, it must be started as root.
Libserver restarts servers on receipt of SIGSEGV or SIGBUS.
If your server starts as root and changes user and group, the library
will be unable to restart if your server is not executable by the
user or group.
The library will be unable to perform the operations that require
root privileges after restart unless you turn on the setuid bit of
the server (chmod +s).
-x The -x option prevents libserver from becoming a daemon and writing
its pidfile to /var/run/. Libserver runs in the foreground. Stderr
is connected to the terminal so that diagnostic output can be sent
there.
-t The -t option is only available to threaded servers and causes those
servers to exit immediately when they receive SIGTERM. Normally,
threaded servers postpone exiting until all established connections
have closed naturally.
-f The -f option takes a filename as argument. Libserver assigns the
filename to the global character pointer serv_config_file. This
enables code in serv_init_func() and serv_worker_init_func() to
access a configuration file.
AUTHORS
James Bailie ⟨jimmy@mammothcheese.ca⟩
http://www.mammothcheese.ca
Nov 11, 2015
