Provided by: klone_2.1.0~rc1-1_all bug

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.

FILE FORMAT

       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.

              CHECK_ALL

       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.