| Version 19 (modified by , 16 years ago) (diff) |
|---|
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.
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.
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, src/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 :
# src/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
# src/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. The took is src/utils/profiles/checkdeps.py. Its usage is described in a dedicated page.
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 -Dlogfile=/home/myuser/mypanc.log
