Operations

Starting and Stopping the Server

The start and stop scripts are in $EXEDIR/tools with names start and stop respectively. Both require root privileges. When starting a server each daemon instance creates a pid file in /var/run/snapgene-server/x.pid where x is the server index. A log file is also created in /var/log /snapgene-server/x.log where x is the server index.

To start the server the server run:

sudo $EXEDIR/start

To stop the server run:

sudo $EXEDIR/stop

Daemons can also be stopped gracefully by sending SIGTERM to the specific process. The sender will need to wait until the currently processing request is completed before this is noticed by the daemon and the shutdown process is commences. On shutdown the specific pid file will be deleted from /var/run/snapgene-server.

To check if a snapgene server is still running, the user can run pgrep snangene-server. This will return a list of PIDs of active daemons. To check if each daemon is still processing messages the user can run $EXEDIR/info. This will send a status request message to the server and wait for a response before returning.

Currently the server is not started at boot time. This is left as a task for IT.

Sending Requests to a daemon

Each snapgene server daemon running a single processing loop waiting for requests on their specific TCP port. The port is opened by the ZMQ library and will only handle ZMQ requests. Each ZMQ request is a single text string encoding a single JSON object. The response is also a single text string encoded as a JSON object.

The JSON object is always of the form:

{

 "request": "$REQUEST_NAME",

  ...other request parameters...

}

where $REQUEST_NAME is the name of the request to be made. Parameters are specific to that request.

The response is always of the form

{

 "response": "$REQUEST_NAME",

 "responseCode": $RESPONSE_CODE,

 "responseMessage": "$RESPONSE_MESSAGE",

 "serverIndex": $SERVER_INDEX

 ...other response parameters...

}

The response value is always the request name. If the request succeeds then responseCode will be 0. Otherwise a non-zero number is returned which is specific to that response. A responseMessage is also returned which contains a human readable text message for the reason for the response.

The server index is also returned in response messages. This is helpful when dispatching messages to multiple requests and seeing which daemon actually performed the work.

To send a request or multiple requests to a dameon use the script $EXEDIR/tools/request.py command. It can send a single request or multiple commands. Run ./tools/request.py --help for more details.

Requests can be sent directly from your own php/python servers as well. See the code info-one.py or request.py for examples.

User and Group Permissions

Snapgene server daemons can and are run as a unique user and group. Both and user name and group name are “snapuser”. The user running each daemon is determined in the script /opt/gslbiotech/snapgene-server/tools/start. The final line is:

sudo -u snapuser xvfb-run $BINDIR/snapgene-server.sh --daemon --index=$INDEX

This is the only reference to snapuser and therefore could be changed to a different user if necessary (or launch the daemons using the current user by omitting the “sudo -u snapuser” completely).

Special note about snapuser:

Since daemons run as user “snapuser”, file permissions must be considered when sending requests to daemons that read and write files. For example, generating a map requires the daemon to read a sequence file and to write out several files related to the DOM, CSS, JS, etc. The deamon’s snapuser will need the path to be read and/or write access at the user or group level. Another option is to create a “scratchpad” directory and permit full read and write access with the following commands:

mkdir /tmp/snapgene-scratch

chmod 444 /tmp/snapgene-scratch

and an example of using this to generate a .png map:

/opt/gslbiotech/snapgene-server/tools/request -c '{"request": "generatePNGMap", "inputFile": "/opt/gslbiotech/snapgene-server/resources/pIB2-SEC13-mEGFP.dna" "outputPng": "/tmp/snapgene-scratch/mynewimage.png" }'

Licensing

Snapgene server uses the same license schema as snapgene desktop version with a few differences. The server looks in /etc/snapgene-server/ directory for the required .klf file. Without it, no meaningful requests to the server will succeed (the server will still respond but with error

details). The .klf file can expire. The expiration date is returned with status messages (see below).

A python script has been provided to download and install the license file from our servers. The script path is $EXE_DIR/tools/license-utility. py. From this utility you can pull a new license or update an old license using your snapgene provided groupname and registration code.