In this tutorial, we describe the steps to set up a scheduled task that at regular intervals acquires a configuration snapshot using Xoom and stores the resulting Xoom file into a Subversion repository. This results in the ability to see what changes, intended or not, were made to the configuration of the system at what time, and allows the user to effectively revert back to the configuration at any point in the past.

Prerequisites

The following software needs to be installed in order to set up Xoom versioning:

• A recent version of the Xoom client or server installation (version 2.2 or later). The client version is only suitable if the versioning is being set up on a remote system, and there is a running Xoom server on the actual managed system(s).
• Windows PowerShell v2.0. The installation can be downloaded for all current Windows systems, including Windows Server 2003 or Windows Server 2008 x64.
• Subversion command line tools accessible from the system path. In this tutorial, we will use TortoiseSVN shell extension (command line tools are not included by default in the TortoiseSVN installer, so they have to be selected manually), but any other distribution will do just as well, although in those cases the actual UI tools will differ from the screenshots below.

There are many other revision control systems out there, and Xoom versioning can in principle be configured with any of them. However, that would require a few lines of the script (see below) to change in order to use the commands of the revision control system in use instead of subversion. Subversion was chosen for this tutorial because it’s free, fairly simple to use, has user-friendly client tools, and is widely known and trusted.

Building blocks

The versioning setup is composed of the following building blocks:

• The Subversion repository in which the successive versions of the configuration snapshot will be stored. This can be a local or central (corporate) repository. It is best if the directory structure and the naming convention for the Xoom files for various servers is decided in advance. For example, if a single configuration snapshot will be used for each server, then the recommended configuration would be to have all configuration snapshots in the same folders, with file names equaling server names to which the files belong.
• The working copy of the relevant folder(s) used in versioning on the Xoom client machine on which the versioning script will be run. The working copy will be created automatically when the script is run if it wasn’t created previously. This working copy can then be used to view the history of the configuration on each server, and compare the configurations of different servers.
• The configuration file for the versioning script that defines what configurations will be retrieved and where they will be stored.
• The versioning script (requiring Windows PowerShell) that will be run either manually or through the scheduled task and will do the actual work of retrieving the configuration snapshot and storing it in Subversion if something has changed.
• The Windows scheduled task that runs the versioning script at regular intervals.

Configuration

The configuration file for versioning is an XML file called Store-Config-In-Svn.xml and has the following structure:

<Config>
  <SvnRepos>
    <SvnRepo id="xoom-revisions">
      <Uri>file:///C:/Xoom/TestSvnRepo</Uri>
      <WorkingCopy>C:\Xoom\TestSvnWC</WorkingCopy>
    </SvnRepo>
  </SvnRepos>
  <XoomQueries>
    <XoomQuery>
      <HostName>localhost</HostName>
      <GetQuery>DEFAULT</GetQuery>
      <Transform>Reports\RemoveTransactionalInformation.xsl</Transform>
      <SvnPath>C:\Xoom\TestSvnWC\XoomConfigs\server-name.xml</SvnPath>
    </XoomQuery>
  </XoomQueries>
</Config>

Each SvnRepo element (under the SvnRepos element) defines one repository / working copy pair. The repositories (located as URIs specified in the Uri element) have to be configured prior to running the versioning script for the first time, but the working copies will be created on demand (at location specified in the WorkingCopy element) when the versioning script is run if they don’t exist already. The only condition for this to work is that the user running the script has the right to access the relevant repository and to commit to it.

Each XoomQuery element (under the XoomQueries element) defines the Xoom server from which the configuration snapshot is going to be retrieved (element HostName), the named query used to retrieve the configuration snapshot (element GetQuery), the XSLT transformation that is going to be applied to the resulting Xoom file (element Transform, we recommend that this is left as is unless there is a good reason to change it, in which case we would be happy to help) and the file name under which the configuration snapshot will be stored (element SvnPath).

There can be multiple SvnRepo elements within the SvnRepos element, multiple XoomQuery elements within the XoomQueries element, and zero or more Transform elements within each XoomQuery element. In each case, multiple such elements will be processed successively in the order of their appearance in the configuration file.

Installation files

Two different versions of the installation files are distributed depending on the Xoom version installed. For Xoom 3 or newer, the files in Store-Config-In-Svn 3+ should be used. For version 2.2, Store-Config-In-Svn 2.2 should be used instead. In both cases, the files in the archive should be unzipped into the Xoom installation folder (“C:\Program Files\Zany Ants\Xoom” by default).

Making sure everything works

Before attempting to set up a scheduled task, the versioning script should be run from the Windows PowerShell command prompt in order to make sure that Subversion tools are accessible, that the user has all the required rights to access and modify the Subversion repositories, and that all relevant Xoom servers are accessible and operational. In order to do that, we start Windows PowerShell and run the versioning script:

In the screenshot we see that we successfully retrieved the configuration from the servers that were set for versioning, and that the configuration changes were successfully committed into the subversion repository, in this case as revision 4. Should anything not work, for example a lack of access to Xoom server(s) or rights to commit the changes to the repository, we would receive the relevant error messages.

Setting up a Windows scheduled task

Once we know that the versioning script is working correctly with our configuration, we want to make it run automatically at regular intervals. We do this by creating a Windows scheduled task. The specifics of how to configure a scheduled task are different in different versions of Windows, but they are all well documented elsewhere. The desired interval and other settings are subject to specific wishes of each customer, but the important thing is that the scheduled task runs the following command line:

C:\WINDOWS\system32\WindowsPowerShell\v1.0\powershell.exe -command "& 'C:\Program Files\Zany Ants\Xoom\Store-Config-In-Svn.ps1'"

The specific paths may vary depending on the version of Windows and where PowerShell and Xoom are installed, but the parameters should all be present in the same way and in the same order.

Checking the configuration history

Once configuration versioning has been set for some time, we’ll have a number of revisions of the configuration in our repository. All subversion clients offer several ways of accessing the revision history. In the case of TortoiseSVN, most commands, including accessing the revision log, are accessible through the context menu in Windows Explorer, as shown here:

In this case, we are looking at the history of the XoomWC (for Xoom working copy) folder, but the same command is also accessible for each individual file that is being versioned.

Once we select the highlighted option, the revision log is shown as demonstrated here:

Even though the versioning script is run once or several times every day during which it retrieves a fresh configuration from Xoom and rewrites the file in the working copy, the commit to subversion will only happen when the new file is actually different from the old one, i.e. when the configuration has changed. Therefore, the log will only show the occasions when such configuration changes were detected. Most subversion clients, including TortoiseSVN, also include diff tools that allow the actual configuration changes in each revision to be visually presented, which allows us to inspect in detail which settings were modified and whether the changes were deliberate and correct or not.