SCDB Server-side Customizations

TOC(inline)

This page describes the server-side SCDB specific tools and how to customize them. It doesn't explain how to install Quattor server and configure it for SCDB. Server-side tools consist in 2 scripts involved in configuration deployment and triggered by ant deploy.

Subversion Hook Script

This script must be installed on the Subversion server (not necessarily the Quattor server), inside the hooks directory of the SCDB repository (the repository itself, not a working copy). For this you need write access to the directory containing the repository on the Subversion server.

This script must be named post-commit and be executable. It is distributed as part of SCDB tools, inside src/hooks directory.

This script requires a configuration file to be present, /etc/quattor-deploy.conf. The configuration file must contain only shell variable definition (sh syntax). The required variables are :

# Quattor server name
QUATTORSRV="quattorsrv.lal.in2p3.fr"

# Recipients of status mail and location for checkout.
NOTIFY="quattor-mgrs@lal.in2p3.fr"

Other supported variables are :

# Script on Quattor server to deploy new configuration
# Default : DEPLOYSCRIPT=/root/quattor/scripts/build-tag.pl

# User to run the deployment script
# Default : DEPLOYUSER=root

# Full paths to commands.
# Defaults are appropriate for RHEL/SL Linux.
MAILER="/usr/bin/mail"
SVNLOOK="/usr/bin/svnlook"
SSH="/usr/bin/ssh"

Deployment Script

This script is called by the hook script and does the real work by updating local copy of SCDB repository with passed tag and calling standard ant tasks.

It needs to be installed on the Quattor server and will be called through SSH by hook script (you need to configure a SSH key without password between your Subversion server and your Quattor server). The defaut location to install the script is `/root/quattor/scripts' but you can put it wherever you want as soon as you update the hook script accordingly. This script, build-tag.pl, is provided as part of SCDB tools inside src/hooks directory.

This script needs to find a file quattor.build.properties in the parent directory of SCDB local cache (generally parent directory for the script location).

In addition, it is possible to customize this script by adding a file /etc/build-tag.conf. This file must contain key/value pairs (with spaces or tabs between key and value, keys are not case sensitive). Supported configuration options are :

• debug : display additional information if non zero.
• java_home : path of Java virtual machine.
• java_version : alternative to java_home. Must match a directory under /usr/java. Default : $JAVA_HOME if defined.
• svn_cache : location to use for SCDB repository local cache. Default : svncache at same level as the directory where the script is installed.
• use_svn : if non zero, force the use of svn command even if jsvn exists. Default : use jsvn from svn_cache if it is present. Note : using jsvn may affect performances.

Troubleshooting Server-side Scripts

If there is a problem during deployment, after entering command ant deploy, people listed in NOTIFY variable of hook script should receive an email describing the problem. With some misconfiguration, it can happen you don't receive an email about the deployment failure.

Note : ant deploy reports a success even if something wrong happens during deployment : ant success or failure only reflects Subversion commit (implied by ant deploy) status.

To troubleshoot server side configuration problems, it is necessary to execute manually the server scripts. This is a two-step processes :

1. Check successful execution of deployment script, build-tag.pl.
2. Check successful execution of SVN hook script.

Troubleshooting deployment script

To troubleshoot deployment script, build-tag.pl, you must log on the Quattor server as the user configured to run deployment script (generally root).

The step-by-step procedure to troubleshoot deployment script (examples below assume it is in default location /root/quattor/scripts) is :

1. Look in /etc/build-tag.conf', if it exists, location of SVN cache on the Quattor server. Default location (/root/quattor/svncache`) is assumed in following examples : replace with the appropriate location for your site.
2. Check the last tag checked out with the following command :

   svn info /root/quattor/svncache
   ---> look at the current tag name, everything after /tags/ in the URL (without leading /)
   

3. Check the tag has been successfully checked out. If the following command updates anything, it means the previous attempt to switch to this tag was unsuccessful. If the command fails again, retry it until it is successful. Failure to switch to a tag is generally related to a Subversion server problem, not to Quattor itself : check Subversion server logs for more information.

   svn update
   

4. Try to redeploy the same tag with the following command :

   /root/quattor/scripts/build-tag.pl TAG-VALUE
   

If SVN cache is empty (not recognized as a valid SVN working copy by svn info), you need to identify last tag in tags branch of Quattor SCDB repository using svn ls.

Troubleshooting SVN hook script

Most of the deployment problems, after initial configuration, are related to deployment script. As the hook script mainly launches the deployment script, it is important complete previous checks before troubleshooting SVN hook script.

Main causes for problems with hook script are invalid SSH keys for communication with Quattor server and invalid configuration for the hook script. Follow the following steps to identify the problem :

1. Log on Subversion server as the same user as your Subversion server (generally Apache account).
2. Try to ssh to Quattor server as the user used to run deployment script (generally root).
3. Retrieve the repository revision where the last tag was created. If the tag has been successfully deployed, the easiest is to use svn log --limit 1 in SVN cache directory on Quattor server. Else, you need to identify the last tag created in repository with svn ls and run svn log --limit 1 on the corresponding URL.
4. Go to the hooks directory of Subversion SCDB repository and run the following command (REPOSITORY_PATH is the filesystem path to repository) :

   ./post-commit REPOSITY_PATH REVISION