Setting up a WWW interface to ACEDB

as presented at the ACE97 meeting by

Curtis Jamison and Steve Beckstrom-Sternberg
 Genome Informatics Group
University of Maryland

A note to the Advanced Curator Working Group

Contents

Documentation

Documentation for setting up ACEDB and creating WWW interfaces, along with lots of other useful information about ACEDB, can be found on the AGIS pages:
http://probe.nalusda.gov/

Why setup an Aceserver?

Data Distribution!

xace is a single user program and is impractical to use remotely. An aceserver allows remote users to connect to an ACEDB databases using either a C or Perl aceclient program. An aceserver will also allow you to set up a netclient and publish WWW and/or Jade versions of your database.

The diagram on the left shows how some of the pieces might fit together. The acedb database sits beneath everything, and the aceserver handles all communications. Since the aceserver only talks rpc, netclients and webace programs exist to translate into other protocols (sockets and http, respectively)

Using these programs ensures the widest possible range of communications, enusuring that nearly everyone will be able to connect to you database.

How to setup an aceserver

Finding a free port

In this usage, the term "port" is a bit of a misnomer. The correct term would be "program number," but that is too much to type since Unix folks are basically lazy, so the term port is widely used. Don't confuse it with serial or parallel ports -- there is no physical connection other than your Ethernet cable.
On most Unix systems, there is no single command which gives you a list of ports in use. The only way to get a list is to look in /etc/rpc and /etc/services. All ports should be listed there. example entries:
/etc/services:              worm           20211/tcp
/etc/rpc:                   acedb          200110        rpc.acedb

Launching an aceserver

An aceserver can be started by hand with the command: 
aceserver db_path -port port_number -time_out client_t_o -server_time_out server_t_o -maxKbytes max_chunk
where the variables are
db_path
filename path to acedb database
port_number
a free port number where the server will listen
client_t_o
client time out, given in seconds
server_t_o
server time out, given in seconds
max_chunk
maximum size of information chunk (best at 10 kBytes

An Example

Typing the following at a command line on our system 
aceserver /kaos/dbs/acedb -port 200110 -time_out 600 -server_time_out 600 -maxKbytes 10
would start an aceserver on port 200110 for the ACeDB database, with time outs set to 10 minutes and a maximum transmit buffer size of 10 kB.

Potential Problems

About the only thing that can go wrong is if the port is already in use. That happens sometimes when ill-mannered programs (and programmers) fail to register a server in services or rpc. In that case, you'll get an error message telling you that the particular port is in use. Simply pick another number.
Of course, if you've been paying attention, you'll notice that we didn't register our aceserver when we started it from the command line. Oops.
It is relatively simple to set up the aceserver to be fully registered. Better yet, this configuration will make the server start every time you restart your computer.

Automated launch via inetd

User accounts and daemons

To run automatically, the aceserver program must be run under as a Unix daemon with a specific user account. It is strongly recommended that the aceserver account be created specifically for the aceservers for security reasons. Our systems all run aceservers as a user named "nomad" which has extremely limited privileges.
To make the aceserver into a daemon program, simply make a symbolic link to the aceserver program named rpc.acedbd and give your aceserver account permission to run it. These steps are somewhat machine specific, and you should consult your individual system administration procedures.

Registration

Edit /etc/rpc to add a name and a port number for each server you're putting up: 
          acedb       2000144  rpc.acedbd
          mendel      2000145  rpc.acedbd

Autostarting

Edit /etc/inetd.conf with a line for each server: 
db_name/version stream rpc/tcp wait user path rpc.acedbd db_path port cto:sto:mKb
where the variables are
db_name
same as the one in /etc/rpc
version
currently 1
user
aceserver account name
path
full path to the rpc program (link)
db_path
full path to the database
cto
client time out
sto
server time out
mKb
chunk size

examples

acedb/1 stream rpc/tcp wait nomad /kaos/software/ace/rpc.acedbd rpc.acedbd /kaos/dbs/acedb 2000144 600:600:10

mendel/1 stream rpc/tcp wait nomad /kaos/software/ace/rpc.acedbd rpc.acedbd /kaos/dbs/mendel 2000145 600:600:10

Advanced Course: Netclient accessibility

The aceserver is fine for standard rpc-style communications. Some applications (like Jade) require a socket connection. To work with these programs, the netclient layer must be inserted. The netclient translates between socket and rpc communications protocols. Set up of the netclient is similar to an aceserver.

Setting up a netclient

/etc/services

Named socket programs are registered in /etc/services similar to rpc: 
                    worm     2100144/tcp
                    gregor    2100145/tcp

Adding the netclient to inetd.conf

Edit /etc/inetd.conf to include a netclient entry: 
name stream tcp nowait user path netclient -host machine -port aceserver
where
name
name of the service
user
user name to run under
path
path to the netclient software
machine
machine which is running the aceserver
aceserver
port the aceserver is listening on

examples

worm stream tcp nowait nomad /kaos/software/ace/netclient netclient -host origin -port 2000144

gregor stream tcp nowait nomad /kaos/software/ace/netclient netclient -host origin -port 2000145

Putting it all together...

So, to have a complete server installation which starts automagically, you need to edit three files: 
                             /etc/inetd.conf
                             /etc/rpc
                             /etc/services
The following example shows the changes in all three files required to put up ACeDB and Mendel under aceservers giving access to every type of communication protocol possible. putting it all together...

The Example

/etc/inetd.conf 
acedb/1 stream rpc/tcp wait nomad /kaos/software/ace/rpc.acedbd rpc.acedbd /kaos/dbs/acedb 2000144 600:600:10
mendel/1 stream rpc/tcp wait nomad /kaos/software/ace/rpc.acedbd rpc.acedbd /kaos/dbs/mendel 2000145 600:600:10
worm stream tcp nowait nomad /kaos/software/ace/netclient netclient -host origin -port 2000144
gregor stream tcp nowait nomad /kaos/software/ace/netclient netclient -host origin -port 2000145
/etc/rpc 
acedb       2000144  rpc.acedbd
mendel      2000145  rpc.acedbd
/etc/services 
worm 2100144/tcp
gregor 2100145/tcp