Run Berkeley DB's RPC server with bounded environments and timeouts

You will prepare a Berkeley DB RPC server command line that exposes one database environment, runs recovery before accepting clients, and limits idle client resources. The examples use the Berkeley DB 5.3 manual installed on this machine. Allow about fifteen minutes for a read-only check and a first configuration; allow longer if the database environment is live or the service needs a maintenance window.

Before starting, you need an absolute path to an existing Berkeley DB environment, a client setup that expects Berkeley DB RPC, and a service account that can read and write the environment as required by the database. Do not create or repair an environment from a guessed path. The server's recovery step can change database files and logs.

1. Check the installed command and version

The command is named berkeley_db5.3_svc. The older alias berkeley_db_svc refers to the same Berkeley DB RPC server manual entry. Check the executable and package versions as an ordinary user:

$ command -v berkeley_db5.3_svc
$ command -v berkeley_db_svc
$ dpkg-query -W -f='${Package} ${Version}\n' db5.3-util db-util
db-util 1:5.3.21ubuntu2
db5.3-util 5.3.28+dfsg2-7

On this host the two command -v checks print nothing: the installed packages provide the manual pages, but not an executable at either path. That is a useful checkpoint, not a reason to invent a replacement command. If your deployment supplies the server binary, continue only after confirming its path. Ask that binary for its library version:

$ /path/to/berkeley_db5.3_svc -V
<version information printed by the installed binary>

The exact version output is build-specific, so record what your binary prints rather than comparing it with a hard-coded sample. A non-zero status means the command could not complete, so stop before changing any database environment.

2. Choose one environment and confirm its name

Give the server an absolute environment path with -h. The final directory component must be unique among the paths passed to this process because Berkeley DB clients use that component when choosing an environment.

$ DB_ENV=/srv/berkeley/app-prod
$ test -d "$DB_ENV" && echo "environment directory exists"
environment directory exists
$ readlink -f "$DB_ENV"
/srv/berkeley/app-prod

Do not treat the directory check as a database health check. It only confirms that the path exists. Check ownership and permissions, then run the server as the account that normally owns the environment. Use sudo only when your service manager or deployment requires it; changing ownership to make a test pass can break an existing database service.

For one environment, the basic command shape is:

$ /path/to/berkeley_db5.3_svc -h /srv/berkeley/app-prod

This is a foreground process unless your service wrapper handles its lifetime. It performs recovery on the selected environment before it accepts requests. Do not start a second copy for the same environment, even as a quick test. Recovery must be single-threaded, and two servers can interfere with each other.

3. Set the environment without -h when appropriate

If you omit -h, the manual says the server uses DB_HOME when that environment variable is set. This is convenient for a wrapper, but it makes the effective database path less visible in a process list. Prefer -h in a hand-reviewed service command, or set DB_HOME in a service configuration that records the value clearly.

$ export DB_HOME=/srv/berkeley/app-prod
$ /path/to/berkeley_db5.3_svc

Do not set both values to different directories. The explicit -h path is the clearest choice when it is present. To undo this shell-only change after a test, run unset DB_HOME; this does not alter the database.

4. Apply sensible client-resource limits

The server has two kinds of timeout. -t sets the default timeout for idle transactions and cursors. Its documented default is five minutes. An idle transaction is aborted when that limit expires, while an idle cursor is closed.

-T sets the maximum timeout a client may request. Its documented default is twenty minutes. If a client requests more, the server caps that request. The maximum should not be lower than the normal default:

$ /path/to/berkeley_db5.3_svc \
    -h /srv/berkeley/app-prod \
    -t 300 \
    -T 1200

These values are seconds. The command does not print a success banner merely because it is listening, so check its process and service logs through the wrapper that launched it. A client that depends on a transaction remaining idle for longer than five minutes will be aborted with the example above. That is a behavioural change, so test the client workload before applying it to production.

5. Set the client-environment idle timeout separately

-I, an uppercase letter i, controls the default idle timeout for client environments. Its documented default is twenty-four hours. It is not the same setting as lowercase -t, which handles idle transactions and cursors.

$ /path/to/berkeley_db5.3_svc \
    -h /srv/berkeley/app-prod \
    -I 3600 \
    -t 300 \
    -T 1200

This example removes an idle client environment after one hour by default, while retaining five-minute resource expiry and a twenty-minute client-request ceiling. Confirm the values against the client application's connection behaviour before deployment. A client environment that disappears while an application still expects it can look like a network or database failure.

6. Add logging and use verbose mode only while diagnosing

Use -L to record the server start in a named log file. The manual documents a line containing the process ID and start date. The file is removed when the server exits gracefully, so copy or forward the information elsewhere if it is needed for an audit trail.

$ /path/to/berkeley_db5.3_svc \
    -h /srv/berkeley/app-prod \
    -I 3600 -t 300 -T 1200 \
    -L /var/log/berkeley_db5.3_svc.log \
    -v

-v enables verbose mode. Keep it for a short diagnostic run if the output is useful, then remove it from the persistent service command unless your logging policy expects the extra detail. The log path must be writable by the service account. Creating a file under /var/log generally needs elevated privileges, so prepare ownership and permissions through the normal service-management process rather than making the database server run as root.

7. Stop safely and recover from a bad launch

Starting the server can trigger recovery, and stopping it can interrupt clients. Schedule a maintenance window before changing an existing instance. If the command fails before serving clients, inspect the path, permissions, log destination and whether another server is already using the environment. The documented exit convention is zero for success and a value greater than zero for an error.

$ printf 'server status: %s\n' "$?"
server status: 1

The status shown is an example of a failed launch, not a promise about the exact number your build returns. Do not repeatedly restart a failing server against the same environment without checking the first error. If you changed only shell variables, run unset DB_HOME. If you changed a service unit or wrapper, restore the previous command and restart it through the same service manager. Do not delete database files, logs or lock files as a first response.