upsilon-node Quickstart

From Upsilon Project
Jump to: navigation, search

This page walks you through the various steps needed to setup upsilon-node. It explains the process as you are going along. If you are familiar with upsilon or don't care about the details, then there is a super quickstart guide for virtual machines..

Quickstart (upsilon-node)


Understand what upsilon-node is. Read the about page.

You need at least one upsilon-node before you touch upsilon-web, upsilon-mobileWeb or similar.

When experimenting with upsilon-node for the first time it is expected that you start small and grow your architecture organically. Configuration is very portable and you don't have to mess about installing lots of little components.

The easiest and safest way to start with upsilon-node is with a virtual machine, if you already have virt-manager/kvm, VirtualBox or VMWare installed. If you find virtualisation a hassle, then upsilon has also been known to work on a Raspbery Pi! Upsilon works best on Linux at the moment. So find yourself a Linux machine and follow the instructions below that are relevant to your distribution!

There is a quickstart available just for Rpi16.png Raspberry PIs, but we think that installation on a virtual machine is better ;)


First of all, you need to install your package.

You should follow the installation instructions for your release, which can found on the upsilon-node releases page.


Writing your first configuration file

We are now going to write a configuration file that tries to ping 2 popular websites to check that they are up - and . Upsilon, by design, relies on external applications to actually execute the service check. As we are setting up a simple ping, we'll use the system "ping" command. This is good to start with because it comes with your operating system, so nothing else to install. However, it is best to switch to the nagios check_ping command later as it offers more options.

Create the file /etc/upsilon-node/config.xml, most distributions ship with a sample configuration file called config.xml.sample that will save you some typing. An example is given below;

    <system crypto = "false">
        Remove this comment if you would like a local database.                    
        Good for first time testing of upsilon-node.                               
        <database dbname = "upsilon" username = "upsilon" password = "databasepasswordforsqluser" port = "3306" hostname = "localhost" />

    The nagios ping command is defined here to save you some time, if you have  
    it installed on your system. The two example services defined in this file  
    use the standard system `ping` to make it quicker to get up and running,       
    but consider using the nagios ping command in the future, it is far better. 
    <command id = "checkPingNagios" exec = "/usr/lib64/nagios/plugins/check_ping -H $ARG1 -w 75,10% -c 125,10% -p 3" />
    <command id = "checkPing" exec = "/bin/ping -c 1 $ARG1 -W 2" />    

    <service id = "pingGoogle" commandRef = "checkPing">

    <service id = "pingBbc" commandRef = "checkPing">

Testing your configuration file

Once your configuration file has been created, upsilon needs to run it. You could use your distribution /etc/init.d/ script or similar to start upsilon as a system service, but for now lets run upsilon in your normal shell in the foreground.

This section assumes /usr/share/upsilon/ is the upsilon directory that contains upsilon.jar. This might be different on your distribution.

user@host$: cd /usr/share/upsilon-node/
user@host$: java -jar upsilon.jar 

If upsilon starts up successfully, you should see;

23:57:02.902 INFO  [main] Upsilon 0.113.0
23:57:02.909 INFO  [main] ----------
23:57:02.909 DEBUG [main] CP: upsilon.jar
23:57:02.909 INFO  [main] XMLConfigurationLoader is loading file: file:/etc/upsilon-node/config.xml
23:57:02.973 INFO  [main] Reparse of configuration of file file:/etc/upsilon-node/config.xml. Schema: MAIN. Validation status: VALID
23:57:03.003 WARN  [main] CAT<StructureCommand> #1 Started (new: 1, old: 0, upd: 0)
23:57:03.004 WARN  [main] CAT<StructureCommand> #1 Adding: checkPing
23:57:03.005 WARN  [main] CAT<StructureCommand> #1 Finished
23:57:03.005 WARN  [main] CAT<StructureService> #2 Started (new: 2, old: 0, upd: 0)
23:57:03.006 WARN  [main] CAT<StructureService> #2 Adding: pingBbc
23:57:03.009 WARN  [main] CAT<StructureService> #2 Adding: pingGoogle
23:57:03.009 WARN  [main] CAT<StructureService> #2 Finished
23:57:03.019 DEBUG [main] Best guess at node type: useless-testing-node
23:57:04.198 DEBUG [DaemonRest] Server started at:

Dialog-information.png Note: The above output is totally normal because it contains no "ERROR" log messages. Even the "WARN" messages are just to warn the user that configuration is changing (from empty, to your config.xml). The startup messages will vary slightly with later releases of upsilon.

Dialog-warning.png Warning: If you see ERROR log messages above, upsilon has not started successfully. Hopefully the error message is easy to diagnose, if not, visit the knowledge base and do not proceed until the problem appears to be fixed.

Upsilon will wait for about 60 seconds after normal startup before it starts executing service checks.

When the checks are run, you will see "Executing ..." messages in your logs, like this;

00:50:42.029 DEBUG [RPE executor (0)] Executing pingGoogle: [/usr/lib/nagios/plugins/check_ping, -H,, -w, 75,10%, -c, 125,10%, -p, 3]
00:50:42.031 DEBUG [RPE executor (1)] Executing pingBbc: [/usr/lib/nagios/plugins/check_ping, -H,, -w, 75,10%, -c, 125,10%, -p, 3]
00:50:42.102 DEBUG [RPE executor (0)] Output pingGoogle: CRITICAL - Network Unreachable (
00:50:42.106 INFO  [RPE executor (0)] Executed service check: pingGoogle = BAD (0 consecutive). Delay until next check PT10S , which is 10 seconds from now
00:50:44.107 DEBUG [RPE executor (1)] Output pingBbc: PING OK - Packet loss = 0%, RTA = 16.20 ms|rta=16.195999ms;75.000000;125.000000;0.000000 pl=0%;10;10;0
00:50:44.109 INFO  [RPE executor (1)] Executed service check: pingBbc = GOOD (1 consecutive). Delay until next check PT15S , which is 15 seconds from now

Dialog-information.png Note: If you see execution results with = GOOD in the log messages, everything is ok!

Dialog-warning.png Warning: If you see execution results with = BAD in the log messages, upsilon was unable to run your service check. The most common cause is the incorrect "exec" argument on a <command />, that points to a path on the filesystem that does not exist. If this is not your problem, go to service check troubleshooting

Running as a service

Fedora16.png Fedora, Rhel16.png RHEL7 & systems using systemd The best way of running uspilon is via systemd. Most upsilon packages come with a systemd unit file, which means upsilon can be started like this;

user@host$: systemctl start upsilon-node.service

Rhel16.png RHEL6, Debian16.png Debian, Ubuntu16.png Ubuntu, etc & systems using init.d scripts On sysV init style systems (like RHEL4/5/6 and Debian) a very basic init script is included /etc/init.d/upsilon. At the moment it is quite buggy.

user@host$: /etc/init.d/upsilon-node start

Logging from the service

upsilon ships with a rsyslog configuration to dump all rsyslog messages to /var/log/upsilon-node.log. If you cannot see this file, try restarting rsyslog. The rsyslog configuration file is deployed to /etc/rsyslog.d/.

For more information about logging, see upsilon-node Logging

Storing the service check results

Right! Now you are executing a basic ping, you probably want to do something with the results. The most simple thing to do with the results is to write them to a local database.

Every upsilon-node does not need a database. upsilon-nodes can be "chained" together in a heirarchy, where nodes send their results to another node. If you want to do this, then follow the link below;

  • Setup peers - Setup a node to send it's results to another node.