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..
Understand what upsilon-node is. Read the about page.
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 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 - http://google.co.uk and http://bbc.co.uk . 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;
<config> <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" /> !--> </system> <!-- 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"> <argument>google.com</argument> </service> <service id = "pingBbc" commandRef = "checkPing"> <argument>bbc.co.uk</argument> </service> </config>
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: http://0.0.0.0:4000/
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, google.com, -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, bbc.co.uk, -w, 75,10%, -c, 125,10%, -p, 3] 00:50:42.102 DEBUG [RPE executor (0)] Output pingGoogle: CRITICAL - Network Unreachable (google.com) 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
Running as a service
Fedora, 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
RHEL6, Debian, 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
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.
- Setup a database for upsilon-node - Setup a MySQL database, so that upsilon-node can write results to a 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.