A how-to by Senior Architect Chris Davies

Gateway hooks allow Geneos users to tie in with source control systems. 
The system administrator can therefore track which user has changed what and when in the gateway setup.

The easiest source control system to use is Git,  not because git is easy, in many ways it is a lot harder to understand than CVS or SVN, but because you are not required to setup a server.
So long as the git command is installed on your machine you can use git locally.

The gateway package comes with an example post-apply-hooks file. It is located in the resources/hooks/examples/post-setup-apply.

This script makes the following assumptions

  • Git is installed on the machine
  • All the setup files are either in the working directory or a direct sub directory
  • There will be at least one file that matches *.xml in the working directory
  • There will be at least one file that matches */*.xml in the working directory

 

Setup

I am using a simpler version of the hooks file that does not create a file-info.xml file (which the example script does) or look for include files in subdirectories. 

When this script is installed it will create a git repository in the working directory and it will commit changes to this repository every time the gateway reads the setup and a change has occurred.

Once you have a gateway that is storing a setup files in a Git repository, you can start to add functionality.

History

Attached is a toolkit script (gitHistory) that will allow you to see the last n commits to the git repository 
by using the git log command. (This script assumes that the toolkit is run in the working directory of the gateway).

Each commit can then be examined using git show. The attached script (gitDetails) pulls information from git and formats it so it can be viewed in the Geneos command output.

This command should be run as a script with a single argument of the commit hash to show the details for. This has is conveniently provided in the toolkit script so a simple right click command can be setup that will give the details of the commit row that the user selects before running the command.

Rollback

It is possible now to create a roll-back command, that will roll-back to a previous version of the setup.
This script is fairly simple and assumes that the gateway (and this script) is the only thing that is committing changes to git while the script is running.
The attached script (gitRevert) will undo the commits (as reversion commits) until the setup is back to the one specified in the commit row selected.

Demo

I have attached a full git repository that tells a simple story. To use  this repository on your machine. Download this tar file. The commands in this tar file have been tested against git version 1.8.2.3.

Then follow the following instructions:

  • Go to your gateway working directory
  • Remove any xml files
  • untar git.tar.gz in the directory
  • type 'git checkout master; git checkout .' [This will create the example-hooks and all the required shell scripts]
  • start probe in the working directory
  • start gateway in the working directory with the -hooks-dir value set to example-hooks

 

You will then see the result of the following:

  • I created a new git repository
  • I added the hooks and git scripts to the repository
  • I added a basic setup file (name and nothing else)
  • I started my gateway and probe
  • Using the GSE I created an include file called auth.xml and added it to the gateway
  • I reset my gateway connection and then added a probe to the gateway running the gitHistory script. As shown below: 

 


 

You can see that there are 3 different users;

    1. Chris Davies - User who setup the Git repository
    2. ActiveConsole2 - myself logged into the gateway before authentication is setup
    3. cdavies - myself logged into the gateway after authentication is setup
  • I then add virtual probe that monitors gateway data and include files (I will use one of these samplers later)
  • I then added a command to show details of an individual git commit, as shown below:

 


 

  • I then added a second command that shows who changed which lines in a file. This calls git directly rather than using a script. The command uses the Gateway-includesData sampler to provide a list of setup files to the command. The output of the command run on the gateway is shown below:

 


 

  • I then added a revert command (using gitRevert). Before running this command I need something to revert. Anna (asubranmaniam) kindly attached to my gateway and made some changes I did not like. These are shown below:

 


 

  • I then ran the revert command on a cell in row 1454072386 (the commit I wish to revert to). The result is shown below.
    • First the new dataview with the 2 Revert commits that have been applied by running the Revert command.

 

 

  • Second the result of running the Revert command.

 


 

 

 

 

Tags: Geneos