How to Use SCDB
TracNav
Table of Contents
Getting Started
To know how to install a Quattor server with SCDB or how to migrate from CDB, refer to the specific page about SCDB installation.
Cluster Groups
In SCDB, machine profiles are grouped in clusters. SCDB clusters are arbitrary group of machines and have nothing to do with a batch cluster or an underlying cluster technology. All the nodes in a cluster will share in particular the same include path for templates (that means that templates will be looked at the same locations for all nodes in the cluster), except for OS templates (see section on selecting OS version in OS templates documentation).
Since SCDB 2.3.1, it is possible to define cluster groups. Previously all clusters where corresponding to one directory under clusters directory. It is now possible to group them into several cluster groups matching your site organization (groups can match a geographical location, an organisational group... SCDB makes no assumption about this). Every group will correspond to one directory in clusters directory and every cluster will have one directory in the group it belongs to.
To activate cluster groups, you need to create a file quattor.build.properties (see documentation for the syntax description of this file) in the root directory of your SCDB installation (the same directory where quattor.build.xml resides). In this file, you can define the following properties:
# Enable cluster groups (default is false for backward compatibility) clusters.groups.enable=true # Enable creation of directory per group in build/xml. # Default should be appropriate for standard deployment model. clusters.groups.xml=false # Generate profiles-info.xml as part of cluster group compilation # Default should be appropriate for standard deployment model. clusters.groups.build.info=false # Define root directory (under cfg/ for all cluster groups or clusters) clusters.directory=clusters
Each of the properties above is optional, values showed in the example above are the default ones, except for clusters.groups.enable.
Note: you need to check SVN property svn:ignore on SCDB root directory to ensure quattor.build.properties is not ignored as it used to be recommended to put it in the svn:ignore list. To check and fix it, use the following command:
svn propedit [--editor-cmd vi] svn:ignore .
At compilation, it is possible to compile only one cluster group with ant option cluster.group. For example:
ant -Dcluster.group=test
Cluster Group Parameters
In addition to specifying cluster parameters, like PAN include path, into the cluster specific file cluster.build.properties, it is possible to define parameters common to all clusters in the cluster group in the file cluster.group.build.properties (in the group root directory). The same parameters can be defined in both configuration files: parameters defined in the cluster-specific file takes precedence.
Modifying Templates
Template editing in SCDB takes place in a working copy of SCDB repository. Edition itself is done with an editor. After the changes are ready for deployment (this generally involves compiling them locally to check that everything is ok), the changes must be committed to SCDB repository using svn commit command or the equivalent in any other SVN client. To be able to deploy changes, you also need to important any changes in the repository and not yet in your working copy. This is usually done with svn update command.
Instructions below are a survival kit for new Subversion users. There is in fact nothing SCDB specific. The examples are provided using the SVN command line interface. For more detailed information, refer to Subversion documentation. But all these operations can be done with any SVN client : they are many GUIs available that can ease the interaction with Subversion. One very interesting and featureful GUI is Eclipse that integrates very well with SCDB.
Creating a SCDB Working Copy
This is the first thing to do. Generally this is done in a permanent area, to avoid redoing it every time you need to do a modification. The SVN operation to do this is called checkout and can be done with the following command line :
svn co http://mysvn.server.example.com/SCDB/trunk
This example assumes that the URL of template branch in SCDB repository is http://mysvn.server.example.com/SCDB/trunk.
Getting Status of Working Copy
You can get list of all the modified files in your working copy with command svn status. By default this command checks status of files against the base revision of the working copy but doesn't check against the repository. Thus it can be used even if you are disconnected from the network. If you want to check the status of files in the working copy against the repository, you need to add option -u.
To be able to deploy your changes, there must be no files with uncommited changes, no files unregistered with Subversion (marked with a ?) and no missing file (marked !). Also all files in the working copy must be up-to-date with repository version. All these checks are done by ant deploy command so there is no need to do a svn status -u before.
Commiting Changes
After editing templates, compiling them successfully and probably checking the profile differences are ok, you need to commit your changes before being able to deploy them. To do this you need to use the following command :
svn ci -m 'Message explaining the change'
Note : it is a good practice to always set a message when commiting summarizing the reason for the changes. Generally the description doesn't need to list the modified files as this information can be retrieved using svn log -v.
Browsing SVN Log
You can easily get the list of revisions and their associated description with svn log command. Without any parameters, this command displays the revision from the last one to the first one, starting at the revision the working copy is based on. As a commit doesn't update the revision the working copy is based on, this is a good practice to do a svn update first. Else you'll not see the last commited revisions.
Also, this is generally convenient to limit the number of revision displayed. This can be easily done with one of the following options :
--limit n: display onlynrevisions.-r first:last: display log fromfirstrevision tolast.firstcan be greater or lower thanlastdepending on the order you want. If there is only one number, only this revision is displayed.
To know about the files modified during the revision, add option -v.
Updating a Working Copy
If you have an existing, out-dated, working copy and want to make new changes, there is no need to do a fresh checkout. Else, it is much quicker to update the existing working copy with last revision of repository contents. This is done with command :
svn update
Revert Changes
With Subversion it is very easy to revert changes, whether they have been commited or not. But the procedure is not exactly the same.
To revert changes made to the working copy but not yet commited, you need to use svn revert command. This command requires one or several file/directory names. By default, it will revert only the given file or directory but not the directory contents. To revert a directory and all its contents (files and directories), you need to use option --recursive.
Note : after a svn revert, changes are definitely lost. Revert only applies to files registered to Subversion : those listed with a ? by svn status are not modified.
To roll back changes commited to the repository, you need to do a SVN merge. This doesn't change anything in the repository but merge differences between 2 repository revisions in your working copy. To complete the rollback, you need to commit this merge, after editing some of the templates if needed. Then to deploy the rolled back configuration, you just need the normal procedure. Conversely to svn revert, you cannot loose anything with a SVN merge : as the rolled back configuration is in the repository, you can roll it in again doing another merge.
Typical command line for SVN merge is :
svn merge -r HEAD:good_rev_num .
good_rev_num is the revision number you want to roll back. There are many ways to find it. Generally you browser the log with svn log. If you know the deployment tag (created by ant deploy) corresponding to the good revision, you can also display the log information for this tag with the following command :
svn log -v --stop-on-copy http://mysvn.server.example.com/SCDB/tags/YY/MM/timestamp
The displayed information will tell you the trunk revision this tag is based on.
There are in fact many possible variations in svn merge command. You can choose to revert a change between 2 arbitrary revisions and not only between the last one and a good one. Also you can roll back the changes for only some directories or files. In this case you have to give 2 additional parameters : first one is the repository branch containing the directory/files, second one is the directory/file in the working copy the changes must be merged into.
Template Compilation
All the template processing needed to build machine profiles is done with ant tools, a Java based equivalent of make. ant brings the advantage of platform independance, allowing to do Quattor management tasks on any platform (Unix, Windows, MacOS).
Specific management tasks (called targets) are passed as a parameter to ant command, in much the same way this is done with make. There are 3 main targets for managing Quattor (other targets are used internally by ant) :
compile.all: this task recompiles all the machine profiles affected by template changes. This is the default if no target is specified.deploy: this task deploys the new machine profiles on the Quattor server. This can occurs only after successful compilation of all clusters, a commit of any changes and a merge of any change done in the repository and not yet present in the working copy.update.rep.templates: this task updates templates describing RPM repositories contents by scanning each repository associated directory.
Compiling a selected cluster or cluster group
When doing modification to templates in a configuration with a large number of nodes, it is often desirable to be able to assess the modification on a small number of nodes, as compiling all node profiles generally result in a long turnaround. SCDB offers several options to do this, passed to ant with option -Doption=value:
cluster.name: compile profile only in the selected cluster. The value must match the name of an existing cluster. If a cluster with the same name exists in different cluster groups, they will be all compiled except ifcluster.groupis also defined.cluster.group: compile profiles only for clusters belonging to the selected cluster groups. Ifcuster.nameis also defined, compile profiles only for this cluster in the selected cluster group.
Note: To enforce consistency of the whole configuration, SCDB doesn't accept these two options at deployment time. They can be used only during the compilation phase before the deployment.
After compiling the selected cluster or cluster groups, it is possible to assess the effect of the modification using utils/profiles/compare_xml tool.
Checking Compilation Results and Profile Consistency
Displaying Resulting Changes in Profile
When doing changes in configuration, this is often useful to check the resulting profiles before deploying. There is a small tool to help doing that, utils/profiles/compare_xml. This tool is part of SCDB base.
To use this tool, before compiling your changes, you need to copy your current (or reference) build directory to something else, by example build.saved (default name used by the script). After the compilation, if you run the script without arguments, it will display the list of all profiles that have changed. You can inspect the changes (require a bit of knowledge of profile contents) using option -v. Or you can restrict the check to one specific profile with option -p. By example :
# utils/profiles/compare_xml
Comparing XML files (*.xml)...
Differences found in build/xml/profile_grid05.xml
Differences found in build/xml/profile_grid06.xml
Differences found in build/xml/profile_grid07.xml
# utils/profiles/compare_xml -v -p profile_grid05
Comparing XML files (profile_grid05.xml)...
Differences found in build/xml/profile_grid05.xml
--- build.saved/xml/profile_grid05.xml 2006-07-28 11:41:45.000000000 +0200
+++ build/xml/profile_grid05.xml 2006-07-28 11:50:58.000000000 +0200
@@ -960,7 +960,6 @@
<options>
<dpm>
<db>
- <adminpwd type="string">MyPrefPwd</adminpwd>
<adminuser type="string">root</adminuser>
<configfile type="string">/opt/lcg/etc/DPMCONFIG</configfile>
<password type="string">DpmMgrPwd</password>
Another option available, -d, extends the comparaison to profile dependencies. This is generally not useful but can be used to do a regression test with a new version of the compiler, for example.
Checking Package Dependencies
Profile compilation cannot check if all the dependencies for all packages present in the profile can be satisfied. By default, this is checked by SPMA on the client before trying to deploy de RPM changes. A tool can be used to check dependencies after compilation but before deployment. This is done by analyzing the profile and checking the metadata for each RPM present, using YUM as a source for the dependency metadata (this requires each RPM repository to be configured as a YUM repository). The tool is utils/checkdeps/checkdeps. Its usage and requirements are described in Quattor Tool Catalog?.
One nice feature of checkdeps is that it can report missing packages are Pan lines to add to the configuration. This is done with option -p. A typical calling sequence for checkdeps is:
util/checkdeps/checkdeps [-p] -x build/xml/mynode.xml
checkdeps has a requirement of a recent enough version of YUM. This is not possible to run it on a SL4 machine. In addition it has a few dependencies that are not installed by default. If you want to be able to run on a Quattor-managed machine, you can add the following to the machine template:
include { 'config/quattor/scdb' };
If the machine (must be a Linux one as one requirement is YUM) is not manged by Quattor, read the template for your OS version to know what you need to install.
To configure the RPM repositories as YUM repositories, if the RPM server is managed by Quattor, you can include the following to the machine profile:
# Mandatory: list of directory whose subdirectories may contain RPM. No default.
# Example: list('/www/htdocs/packages').
variable QUATTOR_RPM_REPOS_ROOTS ?= list();
# Optional: path of script to use for creating/updating YUM repositories.
# variable QUATTOR_YUM_UPDATE_REPOS ?= '/root/quattor/scripts/update_yum_repos';
# Optional: cron frequency (in hours). Default is 2.
# variable QUATTOR_YUM_UPDATE_REPOS_INTERVAL ?= 2;
include { 'quattor/server/yum_repos' };
The template quattor/server/yum_repos will configure a cron, running every 2 hours by default, to update the YUM repositories. The cron will use a script provided with SCDB, src/misc/update_yum_repos, that you need to copy on the machine running the cron (generally the Quattor server).
Using panc logging
Version 8 of the Pan compiler introduces some useful logging facilities that are helpful for debugging (for example, the order of template inclusion and function calls can be logged). These features can be used from SCDB by setting options as follows:
| Option | Possible values | Default |
| pan.logging | "all" "none" "include" "call" "task" "memory" | "none" |
| pan.logfile | Any filename you can write to | /tmp/panc.log |
If you're using ant from the command line, simply add the options you require as follows:
external/ant/bin/ant -Dpan.logging=call -Dpan.logfile=/home/myuser/mypanc.log
Using panc debugging
Version 8.2.4+ of the Pan compiler allows selective output of debugging statements. You can use debug statements freely in templates, and then select when running the compiler which templates should output the debug information. This is done by specifying a set of include and exclude patterns that select sets of templates. You can use this from SCDB via options to ant as follows:
For example to only output debug from templates with name starting "xen/":
ant -Dpan.debug.include='xen/.*'
Or to exclude debugging from all the spma and pan templates but display it from all the rest:
ant -Dpan.debug.exclude='.*/spma/.*|pan/.*' -Dpan.debug.include='.*'
Configuring SCDB Ant Tools
It is possible to use the file quattor.build.properties in SCDB instance root directory (the same directory as the one where quattor.build.xml resides) to customize default configuration values used by SCDB Ant tools. Lines in this file must have the format key=value, with # as the comment delimiter. Not that everything after = is considered part of the value, including leading spaces, quotes and doubles quotes (quotes are not interpreted as a string delimiter).
Note: if you cannot see quattor.build.properties changes with svn status or if this file is flagged as I (ignored), check SVN property svn:ignore on SCDB root directory, as it used to be recommended to put this file in the list of file that should be ignored. You can use the following command to check and change svn:ignore:
svn propedit svn:ignore . [--editor-cmd vi]
The configuration options (called properties) available are documented at the beginning of quattor.build.xml. They allow to customize much of the layout used to organize and locate templates. It is recommended to avoid unnecessary changes as it may become more difficult to troubleshoot problems.
Management of Package Repository Templates
Note: this section applies only to SPMA-based deployment. If you have moved to YUM-based deployments (highly recommended), ignore this part.
Each package repository has an associated templates describing its contents. The template must be updated after any change to the package repository with the following command:
external/ant/bin/ant update.rep.templates
The only important information in this template are the first comments at the head of the templates. They are used to generate the locate the package repository and generate the template with the appropriate information. Theses comments look like:
# name = glite_3_2 # owner = grid.support@lal.in2p3.fr # url = http://quattor.web.lal.in2p3.fr/packages/glite/3.2/release/
where:
nameis the internal name used in the node profile to refer to the repository. It is an arbitrary name.urlis the URL to use to access the repository
The generated template will have a namespace formed with repository/ followed by the repository name.
To create a new repository, just create a new template with the appropriate name (it must match the repository name) and add the initial comments. Then run the command to update the template.
It is possible, when updating templates describing package repositories (ant update.rep.templates), to generate an additional template, repository/allrepositories.tpl, that defines the variable ALL_REPOSITORIES. This variable is a nlist where the key is the repository name and the value the repository information as expected by /software/repositories.
Currently, there is no specific handling for colliding repository names (repository with the same name existing in different part of the configuration database and normally not used in the same clusters). This results in duplicated keys in ALL_REPOSITORIES that must be sorted out manually. Even though this is a perfectly valid configuration, you should avoid colliding repository names if you want to use this feature.
To activate this feature, define property rep.templates.allReposTemplateDir in quattor.build.properties (see documentation) as the relative directory under directory specified by property cfg.repos(default cfg/) where to create repository/allrepositories.tpl.
