Library Version 12.1.6.2

Configuring the Server
Prev | Chapter 2. Berkeley DB Server | Next

## Configuring the Server

Berkeley DB server uses two configuration files, one for log4j, and the other for the server itself. After a change to a configuration file, the server must be restarted to pick up the change.

### log4j Configuration File

Berkeley DB server uses log4j, and thus requires a log4j configuration file. Berkeley DB server accepts configuration files in XML only. By default, it looks for a `log4j.xml` file under the current working directory. This can be overridden by the `-log-config` command-line argument when the server is started.

An example log4j configuration file for a Berkeley DB server:

    <?xml version="1.0" encoding="UTF-8" ?>
    <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

    <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
        <appender name="File" class="org.apache.log4j.RollingFileAppender">
            <param name="File" value="path-to-log-file"/>
            <param name="MaxBackupIndex" value="20"/>
            <param name="MaxFileSize" value="50MB"/>
            <layout class="org.apache.log4j.PatternLayout">
                <param name="ConversionPattern"
                    value="%d [%t] %-5p %c - %m%n"/>
            </layout>
        </appender>
        <appender name="Async" class="org.apache.log4j.AsyncAppender">
            <param name="BufferSize" value="256"/>
            <appender-ref ref="File" />
        </appender>
        <root>
            <level value="INFO"/>
            <appender-ref ref="Async"/>
        </root>
    </log4j:configuration>

### Server Configuration File

Berkeley DB server also uses a Java properties file to control its own behavior. By default, the server looks for a `bdb.properties` file under the current working directory. This can be overridden by the `-config-file` command-line argument when the server is started.

### Note

Because this file may contain sensitive information, its permissions should be limited to the minimum. If the file is accessible globally (globally readable, writable or executable), the server would not start.

An example configuration file for a Berkeley DB server:

    ###################################
    # Server configuration
    ###################################

    # The server's listening port

    port=8080

    # If SSL is enabled, this indicates the maximum number of concurrent
    # client connections.
    #
    # If SSL is disabled, there is no limit on the number of concurrent
    # connections, and this parameter indicates the maximum number of
    # requests that can be processed concurrently.

    workers=10

    # Configure the host name of this server. SSL is enabled if ssl.host
    # is set.

    #ssl.host=server-host-name

    # Configure the key store for SSL.

    #ssl.keyStore=path-to-key-store
    #ssl.keyStore.password=key-store-password
    #ssl.keyStore.type=jks
    #ssl.keyStore.manager=SunX509

    # Configure the trust store for SSL.

    #ssl.trustStore=path-to-trust-store
    #ssl.trustStore.password=trust-store-password
    #ssl.trustStore.type=jks
    #ssl.trustStore.manager=PKIX

    ###################################
    # Database service configurations
    ###################################

    # The root directory for all environments, the home directory for an
    # environment with name "<env>" is $root.home/<env>

    root.home=path-to-environment-root-directory

    # The root directory for all data directories, the data directory
    # for an environment with name "<env>" is $root.data/<env>

    root.data=path-to-data-root-directory

    # The root directory for all blob directories, the blob directory
    # for an environment with name "<env>" is $root.blob/<env>

    root.blob=path-to-blob-root-directory

    # The root directory for all log directories, the log directory for
    # an environment with name "<env>" is $root.log/<env>

    root.log=path-to-db-log-root-directory

    # Configure the timeout value for open handles. The timeout value
    # is set in seconds.
    #
    # For example, if the timeout is set to 600 seconds (10 minutes),
    # and a handle has not been accessed for longer than 600 seconds,
    # then this handle will be closed automatically when the cleanup
    # worker runs the next time.

    handle.timeout=600

    # The frequency the cleanup worker runs. The frequency is set in
    # seconds.
    #
    # For example, if the frequency is set to 300 seconds, the
    # cleanup worker runs every 300 seconds.

    cleanup.interval=300

#### Server Configuration Options

The server can be configured with the following options:

- port

  Specifies the port number the server listens for client connections. The default value is 8080.

- workers

  Specifies the number of worker threads used for handling client requests. The default value is 20.

  If SSL is not enabled, client requests are handled by a shared pool of worker threads. A free worker thread is chosen to handle each client request, and the worker thread becomes free again after handling the request. The number of worker threads determines the maximum number of client requests that can be handled concurrently. If the number of concurrent requests exceeds the number of worker threads, later requests will be blocked until a free worker thread is available.

  ### Note

  In this mode, the number of concurrent client connections is limited only by system resources. For example, the server can serve 200 concurrent client connections even if the workers is set to 20.

  If SSL is enabled, each client is handled by a dedicated worker thread. Therefore, the number of worker threads determines the maximum number of concurrent client connections. For example, if workers is set to 100, the server can serve a maximum of 100 concurrent client connections. If more clients try to connect to the server, they are blocked until some client disconnects from the server or the connection times out (the timeout is specified by the user).

- ssl.host

  SSL is enabled if this property is specified. This property specifies the host name of the server. Clients should use this name when connecting to the server. There is no default value, and SSL is disabled by default.

- ssl.keyStore

  Specifies the path to the Java key store file which manages the server's private key. There is no default value.

  ### Note

  This file maintains sensitive information. If the file is accessible globally (globally readable, writable or executable), the server would not start.

- ssl.keyStore.password

  Specifies the password of the key store file specified in ssl.keyStore. There is no default value.

- ssl.keyStore.type

  Specifies the type of the key store file specified in ssl.keyStore. There is no default value.

- ssl.keyStore.manager

  Specifies the algorithm name of the key manager factory. There is no default value.

- ssl.trustStore

  Specifies the path to the Java trust store file which manages the server's trusted public certificates. There is no default value.

  ### Note

  This file maintains sensitive information. If the file is accessible globally (globally readable, writable or executable), the server would not start.

- ssl.trustStore.password

  Specifies the password of the trust store file specified in ssl.trustStore. There is no default value.

- ssl.trustStore.type

  Specifies the type of the trust store file specified in ssl.trustStore. There is no default value.

- ssl.trustStore.manager

  Specifies the algorithm name of the trust manager factory. There is no default value.

- root.home

  The root directory for all environment's home directory. For example, if the environment home specified by a client is env_home, the actual home directory on the server is <root.home>/env_home. The default value is the current working directory.

  ### Note

  The environment home specified by a client cannot escape the specified root directory. Absolute paths or relative paths that escape the root directory are not allowed.

- root.data

  The root directory for all environment's data directories. For example, if the environment home specified by a client is env_home, the actual directory for access method database files of this environment is <root.data>/env_home.

  If this property is not specified, root.home is used.

- root.blob

  The root directory for all environment's blob directories. For example, if the environment home specified by a client is env_home, the actual directory for blob files of this environment is <root.blob>/env_home.

  If this property is not specified, root.home is used.

- root.log

  The root directory for all environment's log directories. For example, if the environment home specified by a client is env_home, the actual directory for log files of this environment is <root.log>/env_home.

  If this property is not specified, root.home is used.

- handle.timeout

  Specifies the timeout for open handles on the server, in seconds. The server scans all open handles periodically, and closes those handles that have not been accessed for the last handle.timeout seconds. The default value is 600.

- cleanup.interval

  Specifies the interval between consecutive scans of open handles, in seconds. The default value is 300.

Prev | Up | Next
Enabling SSL for the Server | Home | Impacts on Utility Programs