Run dbiproxy safely on a local test port

You will start dbiproxy as a local-only DBI proxy, verify that it is listening, and understand which settings must be secured before a wider deployment. Allow about 20 minutes for a smoke test, plus time to install the Perl modules and DBD driver your database needs. This guide uses the installed libdbi-perl package, version 1.643-4ubuntu0.1, and the behaviour described by its dbiproxy(1p) manual page.

1. Check the executable and its runtime dependency

Start with ordinary, read-only checks. The command is a front end for DBI::ProxyServer; the server also depends on the RPC and daemon modules that are separate from the core DBI package on this machine.

$ command -v dbiproxy
/usr/bin/dbiproxy
$ perl -MRPC::PlServer -e 'print "RPC::PlServer is available\n"'
RPC::PlServer is available

If the second command reports Can't locate RPC/PlServer.pm, stop there. The installed script cannot start until the package providing that module is installed. On Debian or Ubuntu, identify the package with your normal package-management policy before installing anything. Do not treat a failure from dbiproxy --version as a port or configuration failure: this dependency is loaded before the option can be handled.

Once the dependency check passes, ask the script for its version. It prints the version and exits without starting a listener.

$ dbiproxy --version
DBI::ProxyServer version 0.3005

The exact line can vary with the installed Perl module. If it differs, record the value for your change notes rather than copying the example as fact.

2. Choose a private test boundary

Use loopback for the first run. Without --localaddr, the daemon listens on any IP address on the machine, which can expose a database proxy to networks you did not intend to trust. Use an unprivileged port such as 12400; the manual says there is no default, and ports below 1024 require elevated privileges to bind.

The proxy is not a database firewall by itself. It can apply client and query restrictions through its Perl configuration, but a mistake in that file can grant more access than intended. Do not put a production database password in a temporary test file, and do not bind a test server to a public address.

3. Write a minimal configuration

Create a temporary configuration that writes diagnostics to standard error and handles one connection at a time. The file must be Perl code that returns one hash reference. This example does not select a database driver, so it is suitable for checking process startup and the listener before adding database-specific settings.

$ mkdir -p /tmp/dbiproxy-demo
$ cat > /tmp/dbiproxy-demo/proxy.cfg <<'EOF'
{
    localaddr => '127.0.0.1',
    localport => 12400,
    logfile   => 'STDERR',
    mode      => 'single',
    pidfile   => '/tmp/dbiproxy-demo/dbiproxy.pid',
}
EOF
$ perl -c /tmp/dbiproxy-demo/proxy.cfg
/tmp/dbiproxy-demo/proxy.cfg syntax OK

mode => 'single' makes the test predictable: after accepting a connection, the server handles it before accepting another. The manual also documents threads and fork; leave those for a deployment where you have measured the workload and checked the available Perl features.

The PID file is state created by the daemon. If you abandon this test, remove only the file named above after the process has stopped. Do not delete a PID file merely because its name is familiar: first check which process owns it.

4. Start the proxy in the foreground

Run the server without sudo. Foreground operation keeps the error output visible and makes stopping the test straightforward. The command line takes precedence over values in the configuration file, so the explicit address and port below are a useful final guard against an accidental config edit.

$ dbiproxy \
    --configfile=/tmp/dbiproxy-demo/proxy.cfg \
    --localaddr=127.0.0.1 \
    --localport=12400

Leave that terminal running. A successful start may produce little or no output until a client connects because logging defaults to the system log, while this example asks for STDERR. If startup fails, read the first error as the primary diagnosis. A missing DBD driver, malformed configuration, occupied port or unavailable Perl module each needs a different fix.

5. Verify the listener from another terminal

Check the address and port without sending a database request. The output format differs between ss versions, so the important values are the loopback address, port 12400, and a listening state.

$ ss -ltn '( sport = :12400 )'
State  Recv-Q Send-Q Local Address:Port  Peer Address:Port
LISTEN 0      128    127.0.0.1:12400      0.0.0.0:*

If nothing is listening, return to the server terminal. If another process owns the port, choose another unprivileged port and change both the configuration and command line. If the address is 0.0.0.0 or a public interface, stop the process immediately and correct localaddr before continuing.

6. Add access rules before a real client

A database-capable proxy needs a DBD driver on the machine where dbiproxy runs. Add that driver with your normal package process, then extend the returned hash reference with a clients list. Rules are evaluated in order and the first matching rule wins, so put specific permits before broader rules and include an explicit denial where appropriate.

{
    localaddr => '127.0.0.1',
    localport => 12400,
    logfile   => 'STDERR',
    clients   => [
        {
            mask   => '^127\\.0\\.0\\.1$',
            accept => 1,
            users  => [ 'REPLACE_WITH_DB_USER' ],
            sql    => {
                health => 'SELECT 1',
            },
        },
    ],
}

Replace the placeholder and query only after checking that your DBD driver supports parameter binding where your restrictions need it. The configuration's sql names are query labels, not arbitrary client-supplied SQL. Test the exact client connection string and credentials in a controlled environment before allowing a network address other than loopback.

7. Stop the test and clean up

Return to the foreground terminal and press Ctrl-C. This is a test process, so no service manager change is needed. Confirm that the listener disappeared, then remove only the temporary directory if it contains nothing you need.

$ ss -ltn '( sport = :12400 )'
$ test ! -e /tmp/dbiproxy-demo/dbiproxy.pid && echo 'proxy stopped'
proxy stopped
$ rm -rf /tmp/dbiproxy-demo

If the PID file remains, inspect its number with ps -p PID -o pid,comm,args before removing it. If a daemon was started with a persistent PID file or under a service manager, use that manager's documented stop operation instead. Do not kill an unrelated process because a stale file points at its number.