OKS HTTP gateway configuration file
Syntax
The configuration file is composed of several sections identified by a section name and containing zero, one or more parameters. Sections are often separated with an empty line (not required) and may be repeated several times. A parameter makes part of only one section at a time and can be repeated several times; in this case, only the latest parameter value is taken into account.
A section begins which a section name put between square brackets and ends at
the next section or at the end of file. Only one parameter per line is allowed and
lines beginning by a # are ignored. Parameters and values are separated by spaces
or tabs.
GENERAL section
userid <login-name> or <userid>
This parameter allows the process to set its effective and real user IDs to the one specified as value. Either a login name or a userid can be specified. By default, the gateway keeps the privileges of the user running the process.
By changing its effective and real user IDs the process can be run with lower privileges. It means that you can restrict the files and resources the gateway can access.
Example
userid oks
This will set the process effective and real user IDs to the user OKS.
This
parameter is ignored when the process is restarted: you will need to stop and start
it after if you want to apply your changes.
Note that you may need to be the super user to use this fonctionality.
chroot <path>
Under normal circumstances the process is run under the current directory. However, for security reasons, administrators used to run processes under a restricted environment reducing the risks of damage in case of break-in through process bugs or misconfigurations.
This parameter allows the process to change its root directory to the one specified as value. This change is done very early in the process and its means that further references to files have to take this into account.
Example
chroot /usr/local/oks
This will set the current root directory to the OKS directory.
This parameter
is ignored when the process is restarted: you will need to stop and start it after
if you want to apply your changes.
Attention
Solaris users : on this system, the socket system call used by this process needs
to access the /dev/tcp device in order to run properly. The access to this
device can still be granted via the following commands :
# mkdir /usr/local/oks/dev # mknod /usr/local/oks/dev/tcp c 11 42 # chmod 755 /usr/local/oks/dev/tcp
Note that you may need to be the super user to use this fonctionality.
bindaddress <ipaddress> or <fully
qualified host name>
This parameter allows you to set the ip address on which your OKS HTTP gateway listens to establish TCP connections with the HTTP browsers. Either a dotted ip address or a fully qualified host name can be specified. The later case will cause the process to resolve the host name into an ip address. By default this bind address is configured during the installation.
Example
bindaddress www.keyserver.net
This will set the process ip address as your web server.
Note that it is possible the modify the process's ip address when it is running just
by editing the configuration file and restarting the process.
Specifying
an IP address different from the machine's ip addresses needs super-user privileges.
bindport <port number>
This parameter sets the port on which the process listens to establish TCP connections with the HTTP browsers. By default this bind port number is 11371.
Example
bindport 11371
This will set the process port number to 11371. Combined with the process bind address, it uniquely identify the process on the network.
Note that it is possible to set the process's port number when it is running just
by editing the configuration file and restarting the process.
Specifying
a port number lower than 1024 needs super-user privileges.
syslogfacility <facility>
This parameter sets the syslog facility the process will use to log its messages.
The facility value can be one of the followings : auth, authpriv, cron, daemon, kern,
lpr, mail, news, security, syslog, user, uucp, and local0 through local7.
Please refer to the syslog manual on how to use and configure syslog. By default,
the process uses the local0 facility.
Example
syslogfacility local0
This will set the syslog facility the process will use to local0. You still need to configure syslog to store local0 messages as you want.
Note that
if you use the chroot parameter in the configuration file, you will not be able to
change the process syslog facility by restarting the process. In this case, shutdown
the gateway and start it again.
pausedelay <seconds>
This parameter sets the delay the process will wait when an error condition occurs during the restarting of the process. The delay is expressed in seconds.
Example
pausedelay 30
This will set the pause delay to 30 seconds.
hostnameslookup <int>
With a value different than zero, the process will make a reverse lookup when remote clients try to connect in order to log their fully qualified domain name.
Example
hostnameslookup 1
The process will log fully qualified remote clients network addresses instead of just their ip address.
DATABASE section
databaseaddress <ipaddress> or <fully
qualified host name>
This parameter sets the OKS database server address the process will connect to. Either a dotted ip address or a fully qualified host name can be specified. The later case will cause the process to resolve the host name into an ip address. By default this address is configured during the installation.
Example
databaseaddress db.your-domain.name
This makes that the process connects to an OKS database server located on the machine db.your-domain.name.
Note that it is possible the modify the OKS database server you are connected
to when the gateway is running just by editing the configuration file and restarting
the process.
databaseport <port number>
This parameter sets the OKS database server port on which the process will connect
to.
By default this bind port number is 11372.
Example
databaseport 11372
This will makethe process connectingto an OKS database server listeningport number to 11372. Combined with the OKS databaseaddress, it uniquelyidentify an OKS database server onthe network.
Note that it is possible to set the OKS database server's port number when it is
running just by editing the configuration file and restarting the process.
databaseretries <int>
This parameter sets the numer of times the process will try to establish a connection to an OKS database server before entering into pause mode in case of errors.
Example
DatabaseRetries 3
This will set the process retryring 3 times before complaining the database is not reachable.
SMTP section
smtpserver <ipaddress> or <fully
qualified host name>
This parameter sets the SMTP server address the process will connect to. Either a dotted ip address or a fully qualified host name can be specified. The later case will cause the process to resolve the host name into an ip address. By default this address is configured during the installation.
Example
smtpserver mail.your-domain.name
This makes that the process connects to an SMTPserver located on the machine mail.your-domain.name.
Note that it is possible the modify the SMTP server you are connecting to when
the gateway is running just by editing the configuration file and restarting the
process.
smtpretries <int>
This parameter sets the numer of times the process will try to establish a connection to an SMTP server before entering into pause mode in case of errors.
Example
smtpretries 3
This will set the process retryring 3 times before complaining the SMTP serveris
not reachable.
SYNC section
me <email-address>
This parameter specifies the email address your keyserver will use during synchronization with other keyserver. This email address has to uniquely identify the server on the Internet. By default, this parameter is set during the installation.
Example
me pgp-keys@your.domain.name
This sets your keyserver synchronization email address to pgp-keys@your.domain.name
Note that it is possible to modify the process email address when it is running
just by editing the configuration file and restarting the process.
site <email-address>
This parameter which can be repeated several times sets the email addresses of other keyserver the process will synchronize with.
Example
site pgp-keys@first.domain.name
site pgp-keys@second.domain.name
site pgp-keys@third.domain.name
This will make your keyserver synchronizing with the keyservers of first.domain.name, second.domain.name and third.domain.name.
Note that you can add email address when your process is running just by editing
the configuration file and restarting the process.
errors <email-address>
This parameter sets the return-path header in synchronization email messages sent to other keyservers. In case of errors, bad or mistaken email messages will be sent to this email address.
Example
errors root@your.domain.name
If an error occurs after the sending of the email message on the SMTP server, the message will be send back to the email address root@your.domain.name.
Note that you can change this email address when your process is running just
by editing the configuration file and restarting the process.
TEMPLATES section
The gateway uses templates to format its replies during their sending to remote clients.
In this section you define the templates used for each type of request.
These templates
shouldn't been modified yet. Their usage and syntax will be defined in a further
manual.
extract <path>
This parameter sets the template file which is used when replying to an extract
request. By default it is automatically set during the installation.
search <path>
This parameter sets the template file which is used when replying to a search
request. By default it is automatically set during the installation.
submit <path>
This parameter sets the template file which is used when replying to a submit
request. By default it is automatically set during the installation.
nomatch <path>
This parameter sets the template file which is used when no matches are found
when processing a request. By default it is automatically set during the installation.
error <path>
This parameter sets the template file which is used when an error occurs during
the replying of a request. By default it is automatically set during the installation.
Configuration file example
[general]
userid oks
chroot /usr/local/oks
bindaddress 0.0.0.0
bindport 11371
syslogfacility local0
pausedelay 60
hostnameslookup 1
[templates]
extract /usr/local/oks/share/templates/http/extract.html.template
search /usr/local/oks/share/templates/http/search.html.template
submit /usr/local/oks/share/templates/http/submit.html.template nomatch /usr/local/oks/share/templates/http/nomatch.html.template
error /usr/local/oks/share/templates/http/errors.html.template
[database]
databaseaddress db.your-domain.name
databaseport 11372
databaseretries 3
[smtp]
smtpserver mail.your-domain.name
smtpretries 10
[sync] errors root@your-domain.name
me pgp-keys@your-domain.name
site pgp-keys@first.domain.name
site pgp-keys@second.domain.name