NAME

DBI::ProxyServer - a server for the DBD::Proxy driver

SYNOPSIS

use DBI::ProxyServer;
DBI::ProxyServer::main(@ARGV);

DESCRIPTION

DBI::Proxy Server is a module for implementing a proxy for the DBI proxy driver, DBD::Proxy. It allows access to databases over the network if the DBMS does not offer networked operations. But the proxy server might be useful for you, even if you have a DBMS with integrated network functionality: It can be used as a DBI proxy in a firewalled environment.

DBI::ProxyServer runs as a daemon on the machine with the DBMS or on the firewall. The client connects to the agent using the DBI driver DBD::Proxy, thus in the exactly same way than using DBD::mysql, DBD::mSQL or any other DBI driver.

The agent is implemented as a RPC::pServer application. Thus you have access to all the possibilities of this module, in particular encryption and a similar configuration file. DBI::ProxyServer adds the possibility of query restrictions: You can define a set of queries that a client may execute and restrict access to those. (Requires a DBI driver that supports parameter binding.) See "CONFIGURATION FILE".

OPTIONS

When calling the DBI::ProxyServer::main() function, you supply an array of options. (@ARGV, the array of command line options is used, if you don't.) These options are parsed by the Getopt::Long module. Available options include:

--configfile filename

The DBI::ProxyServer can use a configuration file for authorizing clients. The file is almost identical to that of RPC::pServer, with the exception of some additional attributes. See "CONFIGURATION FILE".

If you don't use a config file, then access control is completely disabled. Only use this for debugging purposes or something similar!

--debug

Turns on debugging mode. Debugging messages will usually be logged to syslog with facility daemon unless you use the options --facility or --stderr, see below.

--facility

Sets the syslog facility, by default daemon.

--help

Tells the proxy server to print a help message and exit immediately.

--ip ip-number

Tells the DBI::ProxyServer, on which ip number he should bind. The default is, to bind to INADDR_ANY or any ip number of the local host. You might use this option, for example, on a firewall with two network interfaces. If your LAN has non public IP numbers and you bind the proxy server to the inner network interface, then you will easily disable the access from the outer network or the Internet.

--port port

This option tells the DBI::ProxyServer, on which port number he should bind. Unlike other applications, DBI::ProxyServer has no builtin default, so using this option is required.

--pidfile filename

Tells the daemon, where to store its PID file. The default is /tmp/dbiproxy.pid. The PID file looks like this:

567
IP number 127.0.0.1, port 3334
dbiproxy -ip 127.0.0.1 -p 3334

The first line is the process number. The second line are IP number and port number, so that they can be used by local clients and the third line is the command line. These can be used in administrative scripts, for example to first kill the DBI::ProxyServer and then restart it with the same options you do a

kill `head -1 /tmp/dbiproxy.pid`
`tail -1 /tmp/dbiproxy.pid`

--stderr

Forces printing of messages to stderr. The default is using the syslog.

--version

Forces the DBI::ProxyServer to print its version number and copyright message and exit immediately.

CONFIGURATION FILE

The configuration file is just that of RPC::pServer with some additional attributes. Currently its own use is authorization and encryption.

Syntax

Empty lines and comment lines (starting with hashes, # charactes) are ignored. All other lines have the syntax

var value

White space at the beginning and the end of the line will be removed, so will white space between var and val. On the other hand value may contain white space, for example

description Free form text

would be valid with value = Free form text.

Accepting and refusing hosts

Semantically the configuration file is a collection of host definitions, each of them starting with

accept|deny mask

where mask is a Perl regular expression matching host names or IP numbers (in particular this means that you have to escape dots), accept tells the server to accept connections from mask and deny forces to refuse connections from mask. The first match is used, thus the following will accept connections from 192.168.1.* only

accept 192\.168\.1\.
deny .*

and the following will accept all connections except those from evil.guys.com:

deny evil\.guys\.com
accept .*

Default is to refuse connections, thus the deny .* in the first example is redundant, but of course good style.

Host based encryption

You can force a client to use encryption. The following example will accept connections from 192.168.1.* only, if they are encrypted with the DES algorithm and the key 0123456789abcdef:

accept 192\.168\.1\.
    encryption DES
    key 0123456789abcdef
    encryptModule Crypt::DES

deny .*

You are by no means bound to use DES. DBI::ProxyServer just expects a certain API, namely the methods new, keysize, blocksize, encrypt and decrypt. For example IDEA is another choice. The above example will be mapped to this Perl source:

$encryptModule = "Crypt::DES";
$encryption = "DES";
$key = "0123456789abcdef";

eval "use $encryptModule;"
   . "$crypt = \$encryption->new(pack('H*', \$key));";

encryptModule defaults to encryption, this is only needed because of the brain damaged design of Crypt::IDEA and Crypt::DES, where module name and class name differ.

User based authorization

The users attribute allows to restrict access to certain users. For example the following allows only the users joe and jack from host alpha and joe and mike from beta:

accept alpha
    users joe jack

accept beta
    users joe mike

User based encryption

Although host based encryption is fine, you might still wish to force different users to use different encryption secrets. Here's how it goes:

accept alpha
    users joe jack
    jack encrypt="Crypt::DES,DES,fedcba9876543210"
    joe encrypt="Crypt::IDEA,IDEA,0123456789abcdef0123456789abcdef"

This would force jack to encrypt with DES and key fedcba9876543210 and joe with IDEA and 0123456789abcdef0123456789abcdef. The three fields of the encrypt entries correspond to the encryptionModule, encryption and key attributes of the host based encryption.

You note the problem: Of course user based encryption can only be used when the user has already logged in. Thus we recommend to use both host based and user based encryption: The former will be used in the authorization phase and the latter once the client has logged in. Without user based secrets the host based secret (if any) will be used for the complete session.

Query restrictions

You have the possibility to restrict the queries a client may execute to a predefined set.

Suggest the following lines in the configuration file:

accept alpha
    sqlRestrict 1
    insert1 INSERT INTO foo VALUES (?, ?)
    insert2 INSERT INTO bla VALUES (?, ?, ?)

accept beta
    sqlRestrict 0

This allows users connecting from beta to execute any SQL query, but users from alpha can only insert values into the tables foo and bar. Clients select the query by just passing the query name (insert1 and insert2 in the example above) as an SQL statement and binding parameters to the statement. Of course the client side must know how much parameters should be passed. Thus you should use the following for inserting values into foo from the client:

my $dbh;
my $sth = $dbh->prepare("insert1 (?, ?)");
$sth->execute(1, "foo");
$sth->execute(2, "bar");

AUTHOR

Copyright (c) 1997    Jochen Wiedmann
                      Am Eisteich 9
                      72555 Metzingen
                      Germany

                      Email: joe@ispsoft.de
                      Phone: +49 7123 14881

The DBI::ProxyServer module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. In particular permission is granted to Tim Bunce for distributing this as a part of the DBI.

SEE ALSO

dbiproxy(1), DBD::Proxy(3), DBI(3), RPC::pServer(3), RPC::pClient(3), Sys::Syslog(3), syslog(2)

cpanm mod_perl

perl -MCPAN -e shell
install mod_perl