August 8, 1993 WRG THIS SOFTWARE IS PROVIDED "AS IS" WITH NO WARRANT OR EXPRESSION OF FITNESS OR SUITABILITY OF ANY KIND. The blast server daemon source is in blastd.c and blastsrv.h. blastsrv.h contains the list of server hostnames to be used by the UNIX client. Modify this list for your installation. Do a "make blastd" to build the server daemon. You will most certainly first need to modify the Makefile to point to your C compiler, #include files, and libraries. In blastd.c, you'll want to set the working directory (macro named DEFAULT_WD) to an appropriate location on your system, or use the "-W dirname" option on the blastd command line (see below). There are other defaults you may wish to change in blastd.c, as well, e.g. the maximum cpu time per request. Add an entry in the NIS services database for "blast". The port number to use is "5555/tcp". It is also advised to create a special user account just for the blast network service -- e.g., a user named "blast" or "blastnet" -- so that there is less danger of intrusion, if the service goes haywire (never happened) or is confronted by a malicious client (aren't they all? :-) Create a mail alias or account named "blastmgr" (blast manager) for receiving warning messages from blastd. Warning messages are issued via e-mail when the cpu time limit is exceeded and when blast application programs crash due to segmentation violations and bus errors. blastd is only meant to be executed indirectly, by inetd. See the man pages for inetd and inetd.conf. On each server that will be running blastd, add a line to its inetd.conf configuration file like the following: blast stream tcp nowait blast /usr/ncbi/blast/bin/blastd blastd -n1 -R4 -Q40 -r3 -q10 Note: inetd implementations can be rather -- and sometimes very! -- limited in the number of command line options that they will accept in inetd.conf. I've even experienced command line options that have no effect even when they're by themselves. If more than just a few options are required to configure blastd to run the way you want, you'll probably need to change some of blastd's defaults so that fewer command line options are necessary. When inetd reads the above line in its configuration file, if it can't find a service named "blast" listed in the NIS services database or no user named "blast" on the system, inetd will not activate the blast service. See the man page for inetd.conf. Anytime this configuration file is changed, the inetd process needs to be sent a HUP signal (kill -HUP pid) to tell it to re-read its configuration file. (For a more drastic approach, the inetd process can be killed and restarted.) One way to turn the blast service off is to comment-out the blast entry in inetd.conf and send inetd a HUP signal. One must be root to do this of course. The -R and -Q options limit the total number of simultaneously running searches and queued (waiting to run) searches for the entire system. The -r and -q options limit the total number of running and queued searches for requests coming from a single subnet. Queues are managed automatically by blastd using System V Interprocess Communication semaphores. You will probably want to study the System V "ipcs" and "ipcrm" commands for querying and controlling semaphores. blastd's -n option sets the nominal "nice" value or priority of the blast application programs that get spawned by blastd. blastd itself typically runs at nice 0 regardless. blastd also does some crude estimation of job size and reduces the priorities of blast applications on the basis of these estimates. The parameters used in estimating job size and process prioritization are: the particular blast application program requested and the product of database size and query sequence length. blastd looks for multiple requests coming from the same client IP address within a configurable period of time. (The actual user name is ignored, since user names can not be trusted). Users who bang on the server with multiple requests have their nice priority reduced; and only one request at a time from a given user is allowed to run -- additional request(s) must wait in a queue until the first is finished. File accessed by blastd, relative to its working directory: netbin/blastp -- the real blast application programs netbin/blastn netbin/blastx netbin/tblastn netbin/blast3 etc/hosts -- list of valid client IP addresses or subnets in dotted decimal notation (e.g., 192.239.52.). Any client whose IP address doesn't match will be denied access. IF THIS FILE DOES NOT EXIST OR IS UNREADABLE BY BLASTD, THE SERVER PERMITS ACCESS TO ANY CLIENT. Full or partial IP addresses may be specified. Partial IP addresses are compared for identity against the prefix of the client's IP address. In this way, a single entry may be used to give access to entire subnets. etc/motd -- message of the day, containing words of wisdom for network users etc/collaborators -- list of collaborator IP addresses (or hostnames) that are less harshly down-prioritized for submitting rapid-fire requests etc/stop -- list of client IP addresses (or hostnames or subnet addresses) to block from using the service (supercedes the contents of etc/hosts). This list might be used to exclude particular clients that would otherwise be admitted into the system by virtue of having their subnet listed in the etc/hosts file. etc/exports -- list of databases and associated IP addresses (or hostnames) of clients that are permitted to access the databases. A minus sign in front of an IP address is used to deny access. The special database name "*" can be used to indicate all databases--or at least all that are readable by user "blast". IF THIS FILE DOES NOT EXIST OR IS UNREADABLE BY BLASTD, THE SERVER PERMITS ACCESS TO ANY READABLE DATABASE BY ANY CLIENT. private/hostname -- directory where in-coming query files and the log file are written. "hostname" should be replaced with the short form of the server's hostname (e.g., "hgsi", "cruncher", or "muncher") private/hostname/blastd.log -- log file of in-coming requests private/hostname/down -- a (hopefully!) transient file that is only created to turn off the network service. Clients will be fed the text contents of the file, which might include a description of why the server is down and when it should be back on-line. This provides an alternative method to turning off the blast service that doesn't require any super-user privileges. Upon receiving this message, many clients (e.g., the NCBI UNIX client) will then try to connect with the next server in their list of servers. private/hostname/dbname.down -- a transient file that is typically used to turn off access to the database named "dbname" while it is being updated. Clients will be fed the contents of the file, which might include a description of why the database is unavailable and when it should be back. Upon receiving this message, many clients (e.g., the NCBI UNIX client) will then try the next server in their list of servers. private/hostname/blasta# -- individual query files, removed at end of search. "hostname" is a directory named after the server. This directory must exist for the service to function. Semaphores are used by blastd and the blast application programs. The ftok() system call is used to synchronize between processes, using the names of specific files as one of the arguments to ftok(). The second, "id" argument to ftok() is 0x05 for semaphores, message queues, and shared memory segments created by the "memfile" program. Key values displayed in ipcs output will reflect this 0x05 value in their first byte for memfile-generated objects. blastd does not use these objects, but their presence is mentioned here because of the potential for confusion between which semaphores are blastd's and which are memfile's. The ftok() id argument is 0x06, 0x07, and 0x08 for any semaphores created by blastd. Master queues (implemented using semaphores) have the least significant 3 bytes of their semaphore keys all 0. If a queue seems to be stuck (maybe NEVER happens--semaphores are very robust), the blastd semaphores can be safely removed with the "ipcrm" command without having to turn off the blast service or reboot the system. The semaphores will be recreated automatically by the next instance of blastd that gets executed. No provision is made for changing the initial semaphore values that are determined by the very first execution of the blastd command line in inetd.conf. For instance, if the max. number of simultaneously runnable searches needs to be changed (the blastd -R option), not only does inetd.conf need to be changed (and inetd sent a HUP signal), but the blastd semaphores also need to be removed (with ipcrm) so that the next instance of blastd's execution will recreate the semaphores with the new values. Under SGI IRIX 4.0.5, occasionally a runaway blastd process appears (typically but inexplicably from a HyperBLAST request) that can not be killed but continues to eat cpu time. A reboot is necessary to clear these processes. If rebooting is inconvenient or undesirable(!), the runaway process should have its priority reduced to the minimum. It is not known if this behavior occurs on Solaris or other platforms.