libdombey(8) FreeBSD System Manager's Manual libdombey(8)
NAME
libdombey -- SCGI Application Server Library
SYNOPSIS
-I/usr/local/include -L/usr/local/lib -ldombey
DESCRIPTION
libdombey implements an SCGI application server which is incapable of
generating responses on its own. The programmer writes an initialization
function and a function to generate responses, then compiles and links
his or her code against the library to create a complete multi-process
SCGI application server.
libdombey is intended for use in applications where client requests are
either GET requests or POST requests encoded with x-www-form-urlencoding.
It drops connections over which it receives POST requests encoded as mul-
tipart/form-data.
USAGE
An example server is included in the libdombey distribution, named
test.scgi. It is built automatically when libdombey.so is built, but not
installed by the Makefile.
The programmer must not define any global symbol beginning with the five
characters 'scgi_', other than the names of the two programmer supplied
functions, because the library reserves that namespace for its own use.
The prototypes for the two functions the programmer must supply are
declared in dombey.h. You must define the functions to match the proto-
types:
void scgi_init_func();
void scgi_request_handler();
In scgi_init_func(), or in functions which it calls, the programmer must
perform all initialization he or she needs to do before the server can
commence servicing requests. scgi_request_handler() is called by the
server to generate responses to requests. There is one libdombey library
function which should be called from inside scgi_init_func():
void scgi_set_name( char * );
The argument to scgi_set_name is passed as the first argument to open-
log(3), and is used to create the server's pid file. It must not contain
a slash, therefore. A NULL argument will be ignored.
When the server is not running in debug mode (the -x option), stderr is
connected to /dev/null. Errors, therefore, must be reported using sys-
log(3). Calling openlog() first ensures log entries are identified by
the server's name. If not set, the server's name defaults to "Lib-
Dombey".
The server's pidfile will be written to /var/run/, if the server is
started as root. The filename will be the server's name with ".pid"
appended to it. This file can be used by /usr/local/etc/rc.d/ scripts to
stop the server. A sample script is included in the libdombey distribu-
tion.
The second programmer-supplied function, scgi_request_handler() is called
once for every request received by the server. The programmer may write
as many functions as he or she desires to help generate responses, but
this is the only one libdombey calls. The programmer must use the
buffered IO functions to output a complete CGI response to stdout before
scgi_request_handler() returns. The programmer MUST NEVER read from
stdin or the server will block, forever.
Inside scgi_request_handler(), six library functions may be employed to
access the SCGI environment, the decoded SCGI parameters, and any cookies
defined in HTTP_COOKIE:
char *scgi_get_env( char * );
char **scgi_get_envs();
char *scgi_get_param( char * );
char **scgi_get_params();
char *scgi_get_cookie( char * );
char **scgi_get_cookies();
scgi_get_env() may be used to retrieve the value of one particular SCGI
environment variable. The name of the variable is passed as argument,
and the function returns the variable's value, or NULL if the variable is
not defined. Note that some variables may be defined with their values
being empty strings. scgi_get_envs() returns an array of character
pointers, listing all the SCGI environment variables and their values,
each variable name followed by its value, with the array terminated with
a NULL pointer.
scgi_get_param() may be used to retrieve the decoded value of one partic-
ular SCGI parameter. The uncoded name of the parameter is passed as
argument, and the function returns the decoded value, or NULL if the
parameter is not defined. Note that some parameters may have values of
empty strings, if a value was not explicitly set by the client.
scgi_get_params() returns an array of character pointers, listing all the
SCGI parameters and their values, each decoded parameter name followed by
its decoded value, with the array terminated by a NULL pointer. It does
not matter if the parameters were passed in the QUERY_STRING of a GET
request, or as the body of a POST request with CONTENT_TYPE of x-www-
form-url-encoded.
scgi_get_cookie() may be used to retrieve the value of one named cookie
defined in the value of the HTTP_COOKIE environment variable. The name
of the desired cookie is passed as argument, and the function returns the
value, or NULL if the cookie is not set. scgi_get_cookies() returns an
array of character pointers, listing all the cookies defined in
HTTP_COOKIE, each cookie name followed by its value, with the array ter-
minated by a NULL pointer.
libdombey stores only the first 25 SCGI environment variable/value pairs,
the first 25 SCGI parameter/value pairs, and the first 25 cookie/value
pairs. More items provided in a client request will be ignored. These
limits are defined with two macros in the source code, MAX_ENV,
MAX_PARAMS, and MAX_COOKIE, respectively. You may change them and recom-
pile libdombey, if you need more items.
The pointers and strings returned by these functions MUST NOT be modi-
fied. The values returned by scgi_get_env(), scgi_get_param(), and
scgi_get_cookie() do not persist between invocations of scgi_request_han-
dler(), so do not store them. The locations of the arrays returned by
scgi_get_envs(), scgi_get_params(), and scgi_get_cookies() never change,
so these functions may be called once and the returned values stored and
used thereafter. One may call these two functions in scgi_init_func() to
get their values, but the content of the arrays will be indeterminate at
that time, and should not be accessed.
There is one last library convenience function available to the program-
mer:
char *scgi_form_encode( char * );
This function encodes a string using x-www-form-urlencoding. The
returned string is dynamically allocated, and must be free(3)d when no
longer needed.
Please examine the test.c source for the example server. It demonstrates
the use of libdombey concisely.
CONFIGURATION
A server linked against libdombey writes its pidfile into /var/run/, if
it can (ie., it is started as root), and may be stopped with a SIGTERM.
A sample rc.d script is provided in the libdombey distribution. To use
the script, all occurrences of "dombey" must be replaced with the value
you pass to scgi_set_name(), and the script installed in
/usr/local/etc/rc.d. Two variables must be added to /etc/rc.conf. For
example (substituting "dombey" for your server's name):
dombey_enable="YES"
dombey_flags="-u www -g www -r /usr/local/dombey"
If the "enable" variable is set to "YES", the server will be started at
system start. The following rc commands will be available:
/usr/local/etc/rc.d/dombey start
/usr/local/etc/rc.d/dombey stop
/usr/local/etc/rc.d/dombey restart
/usr/local/etc/rc.d/dombey status
If you do not want the server started on system start, then set
dombey_enable="NO"
and use the following commands:
/usr/local/etc/rc.d/dombey forcestart
/usr/local/etc/rc.d/dombey forcestop
/usr/local/etc/rc.d/dombey forcerestart
/usr/local/etc/rc.d/dombey forcestatus
COMMAND-LINE OPTIONS
The following command-line options are recognized by libdombey servers.
All of these are optional.
-r The -r option specifies the server root directory, which libdombey
will make its current working directory.
-p The -p option specifies the port to listen on. This defaults to 4000
if not specified. Note that to bind to a port lower than 1024, the
server must be started as root.
-i By default, libdombey accepts connections on all interfaces it can
find capable of IPv4 or IPv6. The -i option, when present, overrides
this behavior, by limiting libdombey to accepting connections from a
specified interface only. The option accepts the IP address of the
desired interface as an argument. The address must be expressed in
the presentation format for either IPv4 or IPv6.
-m
-n libdombey uses a multi-process model, with one master process forking
or killing slave processes in response to client activity. Only the
slave processes service client requests. The -n options specifies
the number of idle slaves the master will attempt to keep ready at
all times. The -m option specifies the maximum number of slaves
which may be running at any time. The value specified must be equal
to or greater than the value specified for -n. The default value for
-n is 3 and the default value for -m is 25.
-b the -b option, if present, describes the maximum acceptable size, in
characters, of POST request bodies. If not specified it defaults to
10000. Connections will be dropped when CONTENT_LENGTH exceeds this
value. Note that the SCGI protocol mandates reading an entire
request body before generating its response. libdombey reads a com-
plete request body into memory before calling scgi_request_handler().
This option is therefore a means of limiting memory usage.
-u
-g The -u and the -g options may be used to specify the user and group
for the server to change to after it has bound to the listening
socket. If not specified, both values default to "nobody". Note
that in order for a libdombey server to change user the server must
be started as root. If not started as root, two error messages will
be syslog()ed at start-up, complaining about the inability of the
server to change user and group. You can suppress them by providing
values to -u and -g to override the default "nobody" with the actual
user and group under which the server runs.
-x The -x option, if present, prevents libdombey from becoming a daemon.
It will then run in the foreground of the terminal where it was
started, and may be stopped with signals (ie., Control-C). Stderr
will be connected to the terminal, so diagnostic output may be sent
there when this option is present on the command-line. The server
also will not write its pidfile to /var/run/ when the -x option is
used.
AUTHORS
James Bailie <jimmy@mammothcheese.ca>
http://www.mammothcheese.ca
Apr 14, 2010