General configuration settings are children of the <ICSCONFIG> tag and valid for all listener configurations.
The general configurations listed below are read by the ics configuration implementation. See extension libraries for the specific configurations of the extension libraries.
The <EXTLIBS> tag introduces a list of libraries <LIB> that should be loaded by the ics's library manager.
The extension libraries will provide the actual features of the ics infrastructure. Without any extension library configuration no facility will be provided.
The libraries need to be specified with their full path.
You need to specify the ics.exe as extension library provider. It provides the logger and the certificate manager.
On Windows you need to specifiy <LIB>ics.exe</LIB>, while on linux you need to specify <LIB>ics</LIB>
<EXTLIBS>
<LIB>ics.exe</LIB>
<LIB>httpauth</LIB>
<LIB>ldapauth</LIB>
</EXTLIBS>
Note: for security reasons you should only list libraries that are required for your specific site configuration.
The <DAEMONIZE> tag configures an abritrary number of daemonized extensions.
Each of the daemonized extension is started as a separate process and can provide services to the ics infrastructure
<DAEMONIZE>
<DAEMON ID="1" LIB="ics.exe" RUN="logger" PROCESSES="1">
<PORT>9000</PORT>
<DIR>F:/icstest\icstest\log</DIR>
</DAEMON>
</DAEMONIZE>
ID
The ID attribute must be a unique attribute attached to the daemon.
LIB
The LIB attribute must the library as specified in the EXTLIB section that provides the service.
RUN
The RUN attribute specifies the command of the extension library that implements the daemon service.
PROCESSES
The PROCESSES attribute specifies the number of instances of the daemon service to start.
The actional configuration of the daemon service must be contained in the DAEMON tag.
The <PROTOCOLS> tag introduces a list of protocols <PROTOCOL> that are provided by the protocol plug-in libraries.
The identifier of the protocols are hardcoded by the protocol plug-ins and this section serves as reference only.
<PROTOCOLS>
<PROTOCOL ID="1">HTTP</PROTOCOL>
<PROTOCOL ID="2">HTTPS</PROTOCOL>
</PROTOCOLS>
The <PROCESSES> tag configures the number of processes that should be started by ics as well as the name of the underprivileged user to run the worker processes with.
<PROCESSES RUNAS="wwwrun">1</PROCESSES>
RUNAS
The RUNAS attribute specifies the user with which the worker child process should be executed.
The <THREADSPERPROCESS> tag configures the number of threads that should be started by ics per process.
<THREADSPERPROCESS>5</THREADSPERPROCESS>
The <MULTIPLEXER> tag configures the multiplexer to use by the worker processes.
<MULTIPLEXER MAXCONNS="3000" IMPL="best" TIMEOUT="30" />
MAXCONNS
The MAXCONNS attribute specifies the max. number of connections to be served by one worker process.
IMPL
The IMPL attribute specifies the multiplexer implementation to use.
TIMEOUT
The TIMEOUT attribute specifies the max. connection timeout in seconds.
Various protocols e.g. HTTP determine the format of an entitiy via the file extension. The configuration tag
<MIMETYPESFILE>
allows to specify a file which contains mappings between the mime type and the standard file extensions that these files carry. The file has the following format
comment lines are introduced by #
media types with several file extensions e.g.
application/x-compressed-tar tar.gz tar.Z tgz taz
Linux provides a mime-type file /etc/mime.types with that format.
The configuration of the mimetype file looks as follows:
<?xml version="1.0" encoding="UTF-8"?>
<ICSCONFIG VERSION="1.0">
<MIMETYPESFILE>/etc/mime.types</MIMETYPESFILE>
</ICSCONFIG>
If no mime type configuration is available the protocols use some standard mappings.
The <DEFAULTS> tag introduces extension library specific defaults configuration, which should apply to all listener specific sections and subsections.
<DEFAULTS>
<EXTENSIONSPECIFIC>
<EXTENSIONDETAIL>
...
</EXTENSIONDETAIL>
</EXTENSIONSPECIFIC>
</DEFAULTS>
Please see section specific configurations for details on supported configuration defaults.
ICS provides build-in transport layer security with secure key exchange using Diffie-Hellman key exchange.
This method requires empheral DH group keys that should be generated per installation and listed within the <SECURECONFIG> tag.
The <DH> tag identifies one empheral DH key of a specific key length defined by attribute KEYLENGTH.
The full path and file name to the generated DH key file is specified within the tag.
DH keys for 512 and 1024 bits should not be used to avoid weak Diffie-Hellman (DH) key exchange parameters. If no files for 512/1024 keys are specified a default of 2048 key will be returned even though a key fo 512/1024 is requested.
For Java 1.7 compatibility you will need to generate and specify a 1024 key file
Following an example configuration:
<SECURECONFIG>
<DH KEYLENGTH="2048">/etc/ics/certs/dh2048.pem</DH>
<DH KEYLENGTH="4096">/etc/ics/certs/dh4096.pem</DH>
</SECURECONFIG>
It is important that the empheral keys are generated for each installation and kept secret, thus the files should have read permission for the user that starts ics but not for the underprivileged or other users.
The keys can be generated using the openssl tool kit as follows.
openssl dhparam -out dh512.pem -2 512
openssl dhparam -out dh1024.pem -2 1024
openssl dhparam -out dh2048.pem -2 2048
openssl dhparam -out dh4096.pem -2 4096
Note:If no SECURECONFIG is available ICS will generate the keys on demand which will cause severe performance issues.
ICS provides a logging facility that can be used by protocol implementations to write log files e.g. access logs. The logs can be directed to ICS' own implementation or to a rsyslog service.
ICS provides an own logger daemon that collects the logs and writes them to respective logs files. Alternatively as of version 0.5.1000 ICS can be configured to write to a rsyslog service.
As of version 0.5.1000 the Log writer supports the syslog format according to specifications RFC5424 and RFC5234 utilizing octet counting transport as defined by rfc6587 based on a TCP connection.
The logger process is provided as a daemonized extension library (by the ics binary itself) and must therefore be configured within the daemonize section.
<DAEMONIZE>
<DAEMON ID="1" LIB="ics.exe" RUN="logger" PROCESSES="1">
<PORT>9000</PORT>
<DIR>F:/icstest\icstest\log</DIR>
</DAEMON>
</DAEMONIZE>
The configuration is introduced by the DAEMON tag configuring the library and command to run.
The logger daemon is part of the ics binary itself, therefore you need to specify ics (Windows: ics.exe) without path for the LIB attribute.
The command to be executed must be set by the RUN attribute as logger.
Processes must be set to 1.
Note:Multiple logger instances are not supported, even though you could instanciate multiple logger daemons by adding further DAEMON tags.
The logger daemon configuration required is
- The TCP port that the logger shall listen on introduced by the <PORT> tag. The logger will only listen on the localhost interface.
- The directory where the log files shall be stored introduced by the <DIR> tag.
Be aware that if you run multiple ICS instances (logger instances) you must use different ports for each instance.
The logger process currently runs as the user that started the main ICS process. It listens on a TCP port.
The log writer configuration is introduced by the <LOG> tag. The LOG tag configures the destination for the log writer.
<LOG HOST="localhost" PORT="9000"/>
It comprises two attributes
- HOST
- PORT
HOST
Attribute HOST specifies the target host hat runs the logger process and to which a connection should be established.
PORT
Attribute PORT specifies the port that the logger process is listening on.
TYPE
This attribute is obsolete and is only available for downward compatibility. As of version 0.5.1000 the default for attribute TYPE is "OTHER" and should not be set anymore. The Attribute TYPE determines whether the logger process should be started locally (TYPE="OWN") or not. However a local logger process should be configured via the DEAMON tag now (see above).
Note:for performance and security reasons the logger process should be started locally HOST="localhost".
As mentioned above the log writer utilizes octet counting transport as defined by rfc6587 based on a TCP connection. Therefore you need to enable rsyslog to receive TCP messages. Please see the specific rsyslog documentation. As a hint:
# Receive messages from remote host via TCP
# for parameters see http://www.rsyslog.com/doc/imtcp.html
module(load="imtcp") # needs to be done just once
input(
type="imtcp"
port="601"
)
The log writer writes with syslog facility local, specifically local0, thus you can configure the records to be logged to a specific log file as follows.
local0.* /var/log/http-access.log
In previous ICS versions you could configure the logger process also by the LOG tag as follows. In order to keep downward compatibility the log configuration still supports this configuration of a logger process. However it is obsolete and you should migrate your configuration accordingly.
<LOG TYPE="OWN" HOST="localhost" PORT="9000">
<DIR>/var/log/ics</DIR>
</LOG>
The <DIR> tag configures the directory where the log files should be written to.