Geneos - geneos-utils: Tools to manage multiple Geneos components on a single server

⚠ NOTE: The tools in this article have been superseded and are now considered archived. Instead please use the geneos program from the cordial public repo here:

https://github.com/ITRS-Group/cordial/tree/main/tools/geneos

Within ITRS we have been using a set of tools unimaginatively called geneos-utils to manage multiple Geneos components and versions on a single server for some time. Different versions of these tools have been provided to some users either as part of a Professional Services engagement for new installations or on request.

These tools are unsupported and are not part of the Geneos product itself but rather an ongoing collection of knowledge and experience by ITRS staff to make managing enterprise scale deployments a little easier.

We want to make these tools more widely available at this time so that existing users have somewhere to come to get the current version and for new users who need them.

Please see the end of this page for a downloadable file. The file attached - tagged 4.10.1 - contains some internal references in the comments, some missing convenience templates and additional unnecessary information. An updated version will replace it soon. It will however work fine for most users.

There is no suitable documentation for these tools right now, but to help get you started here is a quick run-down:

1. Unpack the attached file in a directory. It will create a subdirectory with the same name as the prefix of the attachment, for example geneos-utils-4.10.1. In that directory you will find another directory system which contain the actual files and empty directory structure you need.
   

   $ tar xvf geneos-utils-4.10.1.tar.gz
   [...]
   $ cd geneos-utils-4.10.1/system

2. The bin/ directory contains the scripts and global config files you need to use. Either move the whole bin/ directory to your Geneos user's home area or, if there is already a local bin/ directory then just copy the contents over.

   $ cp bin/* ~/bin/

   Make sure your user account .profile refers to your local bin directory in a PATH setting or you will have to type the script path in full each time.
3. The other directories we are interested in are: packages/, gateway/, netprobe/, licd/ and webserver/. These should copied or recreated wherever you intend to locate your Geneos files. The default location in the configuration files is /opt/itrs but as long as you update the *.rc files in bin/ (above) they can be located anywhere.

   $ mv packages gateway netprobe licd webserver /opt/itrs/

   It is important to recreate them in full as there is a specific directory structure required by the tools you have copied to bin/
4. Edit the new bin/*.rc files and change the ITRS_HOME variable to the destination you used above.

   $ vi bin/gatewayctl.rc
   [... change as required ...]
   ITRS_HOME=/home/geneos 

You now have the basic structure for installing and running the Geneos components mentioned by directory name above.

Next you need to populate the packages/ directory with the release files you need. There is a sub-directory under packages/ for each component, so just repeat the steps below for each component you intend to deploy on this server.

1. Download the component file you need, for example geneos-gateway-5.3.1.linux-x64.tar.gz, into a temporary location. It can be removed once we have the unpackaged version in place.
2. Go to the packages/gateway/ directory wherever you have located it and untar it

   $ cd /opt/itrs/packages/gateway
   $ tar xvf /tmp/geneos-gateway-5.3.1.linux-x64.tar.gz
   [...]

3. You should now have a directory called gateway/ that you should rename to record the version number for your reference:

   $ mv gateway GA5.3.1

4. Finally, in normal usage, the geneos-utils scripts expect to the see a directory called active_prod representing the current production version. Make a symlink to your downloaded (real) directory:

   $ ln -s GA5.3.1 active_prod

Note: The Geneos Webdashboard archive does not unpack into it's own directory so you need to add one more step to create a directory and unarchive in there:

$ cd /opt/itrs/packages/webserver
$ mkdir GA5.3.0
$ cd GA5.3.0
$ tar xvf /tmp/geneos-web... etc.

Now you are finally ready to use the scripts to create, start, stop and otherwise control the Geneos components you have installed. Each of the "ctl" script now in your bin/ directory will print a usage message and will share basic commands.

For example, to create a new gateway instance use:

$ gatewayctl create

and follow the prompts. For the first instance of each component you can normally accept the default port numbers etc. but you can change these later on too.

 The configuration for each component is stored in it's own directory which will also act at the process working directory for files, logs, etc. For example if you create a gateway called "testGateway" then the directory you subsequently need is:

$ cd /opt/itrs/gateway/gateways/testGateway

Before the first run you will just find a gateway.set.xml file and a gateway.rc file. The latter contains all the changes from defaults for the geneos-utils and this is where you add options or change settings over time. The specific names are explained in the gatewayctl and gatewayctl.rc files in bin/ - and similarly for the other types of component.

You can then start your gateway like this:

$ gatewayctl testGateway start

or you can start all your gateways, once you have created more, like this:

$ gatewayctl all start

Similarly for restart or stop, just change the last argument on the command line.

Finally, as a shortcut to starting your Geneos components on server start-up, you can add crontab entries like this:

$ crontab -e
[...]
@reboot $HOME/bin/licdctl all start >/dev/null 2>&1 &
@reboot $HOME/bin/gatewayctl all start >/dev/null 2>&1 &
@reboot $HOME/bin/netprobectl all start >/dev/null 2>&1 &

You can also, typically more for a DEV system, add crontab entries to try starting components every few minutes in case of failure - the start commands above will not duplicate already running instances. So like this - again more for a DEV environement:

$ crontab -e
[...]
*/5 * * * * $HOME/bin/gatewayctl all start >/dev/null 2>&1 &

Using cron like this is usually simpler than trying to use systemd especially where you may not have root access on a server.