NAME¶
kloned.conf - The configuration file for the kloned daemon
SYNOPSIS¶
kloned.conf is the configuration file for the
kloned(8) daemon,
i.e. it contains its runtime configuration information. The complete
description of the file format and possibile parameters therein, is provided
for reference in the following sections.
The file consists of sections and parameters. A section begins with the name of
the section, is followed by a '{' and continues until the corresponding '}' is
found. Sections can contain subsections or parameter assignements of the form:
name value.
The file is line-based - that is, each newline-terminated line represents either
a comment, a section name or a parameter.
Section and parameter names are case sensitive.
Leading, trailing and internal whitespace in section and parameter names is
irrelevant. Leading and trailing whitespace in a parameter value is discarded.
Internal whitespace within a parameter value is retained verbatim.
Any line beginning with a hash ('#') character is ignored, as well as lines
containing only whitespace.
The value in parameters is always a string (no quotes needed) whose case is
preserved.
It is also possible to use variable substitution which allows you to define a
symbol name to be replaced by an arbitrary text string, with the classic
bottom-up scoping.
CONFIGURATION FILE STRUCTURE¶
Basically, you have an activation record for each running
kloned(8)
instance: each instance implements an access method to the embedded data or to
external data (file system) when requested. The two access methods currently
implemented are HTTP and HTTPS.
The top level parameter
server_list lists the klone instances by name.
For each name listed here there exist a corresponding activation record
labelled with the same name.
For the sake of simplicity, the available options are grouped into four
categories: those of general applicability (GENERAL), those common to both
HTTP and HTTPS servers (SERVER), those specific to HTTP over SSL/TLS sessions
(SSL/TLS) and those concerning activity logging (LOG).
GENERAL¶
- type
- The access method used by this kloned(8) instance:
at present HTTP or HTTPS. This parameter is
mandatory.
- daemon.name
- Identifier for the service (Windows(TM) ONLY).
- daemon.description
- Service description (Windows(TM) ONLY).
- addr.type
- The protocol family (IPv4, IPv6, UNIX)
of the interface socket. At present IPv4 is the only value
supported.
- addr.ip
- The IPv4 address at which this instance is accepting
connections. The default value is INADDR_ANY.
- addr.port
- The TCP port at which this instance is accepting
connections. The default value is the standard HTTP server port,
80.
- backlog
- Defines the maximum length the queue of pending connections
may grow to, it is passed verbatim to the listen(2) call on this
instance's socket.
- idle_timeout
- Set the maximum number of seconds the server waits for an
HTTP request on an already connected socket. The default value is 10
seconds.
- post_timeout
- Set the maximum number of seconds the server waits for an
HTTP POST request on an already connected socket. The default value is 10
minutes.
- post_maxsize
- Set the maximum number of bytes the server is willing to
accept for a given HTTP POST request. If Content-Length of a POST request
is greater than post_maxsize the connection is immediately
terminated. The default value is 5 MB.
SERVER¶
Per server-type configuration parameters.
Note that we use the URI
sup:// convention to specify the location of
content that
kloned tries to retreive from its suppliers. By default
there is only one active supplier, which is the embedded file system. Anyway,
there could be many different suppliers, e.g. the local disk that is enabled
by setting the
ENABLE_SUP_FS variable during compilation. The embedded
file system supplier is
always searched first. In case the requested
resource were not found in the embedded file system, the other suppliers are
searched sequentially.
- dir_root
- The top level directory under which this server's instance
keeps the site data. When a request for the resource /dir/page.kl1
is done, it is mapped to sup://${dir_root}/dir/page.kl1. The
default value is /.
- chroot
- Set the directory where the running server resides. It
requires no additional files to exist in jail: the chroot call is made
after server initialisation (log setup, backend configuration,
bind/listen) but before forking and dropping of priviledges.
- blind_chroot
- A variant of the chroot directive which,
additionally, unlinks the server root directory, making the chance for a
hijacked/malfunctioning server to access the file system very unlikely. It
can be useful in combination with in-memory logging or syslog remote
logging to achieve a very high level of bounding.
- uid
- Set the real and effective user ID of the running
server.
- gid
- Set the real, effective group IDs and the saved
set-group-ID of the running server.
- allow_root
- A boolean which specifies if the server is allowed to run
with root credentials (i.e. user ID 0).
- max_child
- Set the maximum number of child processes per server (i.e.
total number of running backend child processes) available at run-time.
The default value is 300.
- error.http_errno
- Select the file which will be displayed on the given HTTP
error event ( http_errno can be any of 4XX and 5XX). The value is a
URI relative to the site: e.g. /a/b/c/d.klone is translated into
(http|https)://sitehost[:port]/a/b/c/d.klone.
- dir_alias src
dst
- Maps dst to src in the requested URI. For
example, when the following is set:
dir_alias /img /var/httpd/img
a request to (http|https)://sitehost[:port]/img/a.gif will be mapped
to sup://var/httpd/img/a.gif.
- server_sig
- Set the server signature string which will be returned in
the HTTP head (Server: %s). When setting a custom Product token, the
guidelines stated in paragraph 3.7 of RFC 1945 should be followed. The
default value is "klone/1.0".
- model
- Set the type of the serving model for this klone instance:
fork, a child process is spawned for every client request,
iterative, pending clients are processed one at a time, or
prefork, a pool of child processes is created on start up and an
available process from the pool is chosen to handle each incoming client
request. When a request burst happens in prefork mode, the server
reacts adaptively, i.e. it creates other child processes up to a
configurable maximum in order to gracefully handle the busy condition.
Note that the -F command line switch overrides this value,
enforcing the iterative model. The default value is inherited from the
parent, which by default is prefork.
- fork.max_child, prefork.max_child
- Set the maximum number of child processes at running time.
The default value is 150.
- prefork.max_request_per_child
- Set the maximum number of request that a child process can
handle before giving up.
- index
- Specify the index page location. This is the page that is
returned to the client requesting (http|https)://sitehost[:port]/.
The default values are (in order): index.klone, index.kl1,
index.html, index.htm.
All the session variables are gathered into an ad hoc
session subsection
of an HTTP or HTTPS activation record.
- type
- Specify where to store session data: memory for the
host volatile memory, file for the host file system, client
for storing data on the client. The default value is file.
- max_age
- Set the inactivity threshold timeout for the session. The
default value is 60*20 seconds (20 minutes).
- encrypt
- A boolean specifying whether the session data should be
encrypted before being sent to the client. The default is yes.
- compress
- A boolean specifying whether the session data should be
compressed before being pushed to the client. The default is
no.
- memory.limit
- Set the maximum size in bytes for the memory used to hold
the collection of all sessions' data. The default value is 0, i.e.
unbounded.
- memory.max_count
- Set the maximum number of sessions the server can store in
memory. The default value is 0, i.e. unbounded.
NOTE: in case one of the two latter limits is exceeded, the data of the older
inactive session will be discarded.
- file.path
- Specify where to store session data when the file
driver is in use. The default value depends on the host platform: on
UNIX(TM) it is /tmp, on Windows(TM) the system temporary path.
- client.hash_function
- The hash function that should be used in the HMAC
calculation over the cookies. The available values are: md5,
sha1, ripemd160. The default is sha1.
SSL/TLS¶
All the cryptographic material examined in this section MUST not be password
protected. This is because on unattended devices such as appliances or
similar, password protection is useless if not harmful.
- cert_file
- PEM-encoded certificate file for the server and optionally
also its corresponding RSA or DSA Private Key file (contained in the same
file). The certificate should be configured with the Common Name matching
the fully qualified domain name of the server. This parameter is
mandatory.
- key_file
- PEM-encoded private key file for the server. If the private
key is not combined with the certificate in the cert_file, use this
additional directive to point to the file with the stand-alone private
key. When cert_file is used and the file contains both the
certificate and the private key this directive need not be used. However,
such practice is strongly discouraged. Instead the certificate should be
separated from the private key. By default the value of cert_file
is used.
- certchain_file
- Optional all-in-one file where you can assemble the
certificates of Certification Authorities (CA) which form the certificate
chain of the server certificate. This starts with the issuing CA
certificate of the server certificate and can range up to the root CA
certificate. Such a file is simply the concatenation of the various
PEM-encoded CA Certificate files, usually in certificate chain order. This
is intended for instance for the Verisign Global-ID situation where one
has to send the intermediate CA of Verisign with the GID while one
wants to avoid that under client authentication all clients issued by this
CA are accepted, which would happen when one references the CA cert via
ca_file.
- ca_file
- All-in-one file where you can assemble the certificates of
Certification Authorities (CA) for all certificates expected from clients.
These are used for Client authentication. Such a file is simply the
concatenation of the various PEM-encoded certificate files, in order of
preference. It is mandatory when verify_mode is
required.
- dh_file
- PEM-encoded file containing Diffie-Hellman parameters to be
used on session data negotiation phase. When missing a default set of
1024-bit DH parameters is used. Note that RSA ephemeral parameters are
always created automatically.
- verify_depth
- This directive sets how deeply openssl should verify before
deciding that the clients don't have a valid certificate. The depth
actually is the maximum number of intermediate certificate issuers, i.e.
the max number of CA certificates which are allowed to be followed while
verifying the client certificate. A depth of 0 means that only self-signed
client certificates are accepted, the default depth of 1 means the client
certificate can be self-signed or has to be signed by a CA which is
directly known to the server, i.e. the CA's certificate is under
ca_file, etc.
- crl_file
- PEM-encoded file containing CRLs against which certificates
supplied by the client (at least its own) will be checked for revocation
status.
- crl_opts
- This directive can be set to the value that follows in
order to enforce a stricter check upon the supplied certificate chain: not
only the client certificate, but every certificate in chain up to the
anchor CA will be tested for its revocation status.
- verify_mode
- This directive sets the certificate verification level for
the Client authentication. The following values are available:
- NO
- no client certificate is required at all
- OPTIONAL
- the client may present a valid certificate
- REQUIRED
- the client has to present a valid certificate
-
Note that optional makes sense only in testing scenarios. The default value
is NO.
LOG¶
Klone provides three types of log device: memory, syslog and file. The first is
especially targeted for ROM appliances, while the second and third need a
device with available (and writeable) storage in order to work. The file type
is for systems with no available system message logger (RFC 3164 like).
Instead, if the host system has syslog, either as a locally running daemon or
just as a set of client API interfacing an external device, then the syslog
type (which is nothing but a wrapper to the
syslog(3) family of
functions) can be used.
Each klone instance can be given its private log device. Furthermore there may
exist a top level log device, associated to the klone dispatcher to which log
messages who could not find a suitable sink (i.e. messages sent by klone
instances with no configured log device) are forwarded. If no log devices are
configured (neither instance specific, nor the top level one), nothing at all
is logged.
Each log message is bounded to a severity level. Available levels, starting from
the lowest, are:
KLOG_DEBUG,
KLOG_INFO,
KLOG_NOTICE,
KLOG_WARNING,
KLOG_ERR,
KLOG_CRIT,
KLOG_ALERT,
KLOG_EMERG.
Each log device has its
log subsection which gathers all its
configuration parameters.
- type
- Specify the type of log device: can be one of
memory, file or syslog. This parameter is
mandatory.
- ident
- Set a fixed string which will be prepended to each log
message.
- threshold
- Specify the threshold severity level for messages that you
want to be displayed: log messages with a level lower than this will be
discarded. If not specified, the lowest value is set (i.e.
KLOG_DEBUG).
- memory.limit
- The memory log device is basically a fixed size array of
log strings with a FIFO discard policy. This parameter specifies the array
dimension, i.e. the maximum number of resident log messages. If not
specified a default value of 250 is set.
- syslog.facility
- Set a default syslog(3) facility for log messages.
It must be one of LOG_LOCAL[0-7]. If not set the highest value
possible is set (i.e. LOG_LOCAL7).
- syslog.options
- Optionally specify a list of blank separated values from
the set of the syslog(3) log options: LOG_CONS,
LOG_NDELAY, LOG_PERROR, LOG_PID.
A file log device is physically subdivided into a certain number of files
(pages) named
basename.
page_id, used as pieces of a sliding
circular buffer. A page must be thought as a fixed size array of log lines:
each page in a file log has the same dimension, so that each log line can be
referenced uniquely. State information is grouped into a
head file to
be preserved between one run and the subsequent. Information in head (i.e.
number of page files, page dimension, active page id, offset in page and
basename) is used iff it corresponds to actual config parameters, otherwise
the past log is discarded.
- file.basename
- The page basename. This parameter is mandatory.
- file.limit
- Set the number of log lines in each page file. If not set,
a default value of 250 is silently assumed.
- file.splits
- Set the number of pages for this log device. If not set, a
default value of 4 is silently assumed. The minimal number of pages is
2.
SEE ALSO¶
klone(1),
kloned(8).
The standard KLone software distribution contains a complete and carefully
annotated
kloned-sample.conf file which can be used as a
reference.