= How to Use SCDB = [[TracNav]] [[TOC(inline)]] == Getting Started == To know how to install a Quattor server with SCDB or how to migrate from CDB, refer to the specific page about [wiki:Download/SCDB 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 [wiki:Doc/SCDB/Usage#TemplateCompilation 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 [http://svnbook.org/ 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 [wiki:Doc/SCDB/Eclipse 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`. === Commiting Changes === After editing templates, [wiki:Doc/SCDB/Usage#TemplateCompilation compiling] them successfully and probably [wiki:Doc/SCDB/Usage#CheckingCompilationResults 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 only `n` revisions. * `-r first:last` : display log from `first` revision to `last`. `first` can be greater or lower than `last` depending 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.'' 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 [wiki:Doc/SCDB/Usage#TemplateCompilation 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 == 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, [source:SCDB/trunk/src/utils/profiles/compare_xml src/utils/profiles/compare_xml]. This tool is part of [source:SCDB/trunk 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 @@ - MyPrefPwd root /opt/lcg/etc/DPMCONFIG DpmMgrPwd }}} 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.