SCDB Server Configuration

TOC(inline)

This page describes the server side of SCDB, made of the SVN server and a Quattor deployment server, the specific components used and how to customize their configuration. It doesn't explain how to install the SVN server and the Quattor server and how to configure them for SCDB.

Server-side components of SCDB consist in 2 scripts involved in configuration deployment and triggered by ant deploy:

• SVN post-commit hook script
• Deployment script

Both scripts are distributed as part of SCDB tools, inside src/hooks directory. See the the installation documentation for more information.

Subversion Hook Script

This script is trigger by ant deploy when creating the deployment tag. Its main role is to do several checks and if necessary to launch the deployment 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 by the account the SVN server is running under (typically the Apache account). The source file for this script is post-commit.py.

Note: an obsolete version of this script was called post-commit (and is a shell script). All the information here doesn't apply to this obsolete version whose configuration file had a different format, despite the same name. When migrating from the obsolete version to the new one, the configuration file must be replaced.

This script requires a configuration file, /etc/quattor-deploy.conf (common with the deployment script when running on the same machine). All the configuration options supported and their default values are defined at the beginning of the script. The configuration file has several sections. One of them, [scdb], is common to the hook script and the deployment script. The main options available and their default values are:

[post-commit]
# Script launched by the script to actually do the deployment
deploy_script : /root/quattor/scripts/build-tag.py
# Name of the deployment server where to run the deploy_script. Used only with ssh.
# This can be a space-separated list (not yet implemented, see https://trac.lal.in2p3.fr/LCGQWG/ticket/46).
#deploy_server : quattorsrv.example.org
# Userid to use to run deploy_script
deploy_user : root
# notify_xxx are used to configure email notification in case of errors.
# If notif_from or notif_to is undefined, email notification is disabled
notif_mailer : localhost
#notif_from=Quattor Deployment <noreply@lal.in2p3.fr>
#notif_to=jouvin@lal.in2p3.fr
notif_subject_prefix : [Quattor-Deploy]
notif_subject : Failed to deploy revision %s of SCDB configuration
# Default should be appropriate. Set to false if your client doesn't handle properly returned output.
# When set to false, no message is printed on stdout, except if verbose is > 0.
report_error_to_svn: yes
# When false, ssh is used instead. This requires deploy_server to be defined too.
use_sudo : yes
# Log operations in /tmp/quattor-post-commit.log
verbose: 0

[ssh]
cmd: /usr/bin/ssh
options: -o PasswordAuthentication=no

[sudo]
cmd: /usr/bin/sudo
options: -H

[scdb]
# URL associated with the repository root
#repository_url: http://svn.example.com/scdb
# Branch where to create SCDB deployment tags
# Keep consistent with quattor.build.properties if not using default values.
tags_branch: /tags
# Branch corresponding to SCDB trunk (only branch allowed to deploy)
# Keep consistent with quattor.build.properties if not using default values.
trunk_branch: /trunk

The only required options for which no default value is provided is repository_url in [scdb] section. It must match the root URL of your SVN repository (as returned by svn info).

Note on using sudo: recent versions of sudo disable the use of sudo without a tty by default. This must be change in order to use sudo in the context of the deployement script. To to this, run visudo and comment out line Defaults requiretty.

Deployment Script

This script is launched by the hook script and does the real work by updating local working copy of the SCDB repository to the tag to deploy and by calling appropriate ant tasks.

It needs to be installed on the Quattor server and will be called through sudo or ssh by the hook script (you need to configure a SSH key without password between your Subversion server and your Quattor server to use ssh). The default 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 configuration ([post-commit] section) accordingly. The source of this script is build-tag.py.

Note: an obsolete version of this script was called build-tag.pl (written in Perl). All the information here doesn't apply to this obsolete version whose configuration file had a different format. When migrating from the obsolete version to the new one, the configuration file must be replaced.

This script requires a configuration file, /etc/quattor-deploy.conf (common with the hook script when running on the same machine). All the configuration options supported and their default values are defined at the beginning of the script. The configuration file has several sections. One of them, [scdb], is common to the hook script and the deployment script. The main options available and their default values are:

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) and a configuration file /etc/build-tag.conf.

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
   

Archived Documentation

The information in this section is kept here for reference. It documents the configuration file format of the obsolete hook script and deployment script.

Hook script (obsolete)

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="/bin/mail"
# SVNLOOK="/usr/bin/svnlook"
# SSH="/usr/bin/ssh"

# Use sudo rather than ssh between SVN server and quattor deployment server
# Default: SSH
# USE_SUDO=1

# Default prefix for mail subject in case of error
# Default : ERROR_PREFIX='[Quattor-Deploy]'

Deployment Script (obsolete)

/etc/build-tag.conf allows to customize build-tag.pl according to local needs. It must be present. This file must contain key/value pairs (with '=' 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.
• tags_svn_url (required) : SVN URL for SCDB repository tags branch

An /etc/build-tag.conf example is :

use_svn = 1
java_version = jdk1.6.0
tags_svn_url = http://grid280.lal.in2p3.fr/svn/quattor/tags