OKS SMTP 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.
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.
pollinterval <seconds>
This parameter sets the delay the process will wait between two fetching of mail on the keyserver's mailbox. The delay is expressed in seconds.
Example
pollinterval 120
This will set the process checking for mail every 120 seconds.
maxproc <int>
Because keyservers synchronize through an email-based protocol, the OKS SMTP gateway can quickly consume computing resources when receiving large number of emails at the same time. This is why this parameter acts by limiting the number of OKS SMTP gateways running on your system at the same time.
Example
maxproc 5
No more than 5 emails will be processed at the same time.
incpriority <int>
Because most of the mail traffic for a keyserver is composed of synchronization messages (incrementals), it is interesting for a system administrator to process these requests with a lower priority than normal ones. This parameter sets the nice value the process will use in order to process incremental requests. This value follows the rule of the nice system call of your system. Most of the time, administrators sets this value to 20 ( lower privilege ).
Example
incpriority 20
Your SMTP gateways will have the lower priority on your system.
helpdir <path>
In the past, keyservers used to be queried through email based messages. Today, most of these queries are running through the HTTP protocol but, for backward compatibility, the OpenKeyServer still supports most of these email-based queries. One of them was a request for a particular help file. The purpose of this parameter is to provide a path where the keyserver can search for it.
Example
helpdir /usr/local/oks/share/help Your SMTP gateway will search into /usr/local/oks/share/help for your help files.
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.
POP3 section
pop3server <ipaddress> or <fully
qualified host name>
This parameter sets the POP3 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
pop3server mail.your-domain.name
This makes that the process connects to a POP3server located on the machine mail.your-domain.name.
Note that it is possible the modify the POP3 server you are connecting to when
the gateway is running just by editing the configuration file and restarting the
process.
pop3retries <int>
This parameter sets the numer of times the process will try to establish a connection to an POP3 server before entering into pause mode in case of errors.
Example
pop3retries 3
This will set the process retryring 3 times before complaining the POP3 serveris not reachable.
pop3login <pop3-account>
This parameter sets the POP3 account the process will use to connect to the POP3 server in order to receive its SMTP requests. This account must exist on the POP3 server.
Example
pop3login keyserver
This will set the process using the account "keyserver" to connect to the POP3 server.
pop3password <pop3-password>
This parameter sets the password the process will use to connect to the POP3 server. This POP3 password is used with the POP3 account in order to connect to the POP3 server.
Example
pop3password password
This will set the process using the password "password" to connect to the POP3 server.
pop3leavemail <int>
With a value different than zero, the process will leave every email message on the POP3 server after retrieving them. On the other hand, when set as zero, the process first deletes already red email messages and does not leave any email on the POP3 server.
Example
pop3leavemail 0
This will not leave email messages on the POP3 server.
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
pollinterval 120
syslogfacility local0
pausedelay 120
maxproc 5 incpriority 20 helpdir /usr/local/oks/share/help
[templates]
extract /usr/local/oks/share/templates/smtp/extract.template
search /usr/local/oks/share/templates/smtp/search.template submit /usr/local/oks/share/templates/smtp/errors.template
nomatch /usr/local/oks/share/templates/smtp/nomatch.template
error /usr/local/oks/share/templates/smtp/errors.template
[database]
databaseaddress db.your-domain.name
databaseport 11372
databaseretries 3
[smtp]
smtpserver mail.your-domain.name
smtpretries 10
[pop3] pop3server mail.you-domain.name pop3retries 10 pop3login my_pop3_account pop3password my_pop3_password pop3leavemail 0
[sync]
errors root@your-domain.name
me pgp-keys@your-domain.name
site pgp-keys@first.domain.name
site pgp-keys@second.domain.name