.. _advanced/volatileservices: =================== Volatile Services =================== Introduction ============= Shinken has the ability to distinguish between ânormal" services and "volatile" services. The is_volatile option in each service definition allows you to specify whether a specific service is volatile or not. For most people, the majority of all monitored services will be non-volatile (i.e. ânormal"). However, volatile services can be very useful when used properly... What Are They Useful For? ========================== Volatile services are useful for monitoring... * Things that automatically reset themselves to an "OK" state each time they are checked * Events such as security alerts which require attention every time there is a problem (and not just the first time) What's So Special About Volatile Services? =========================================== Volatile services differ from ânormal" services in three important ways. Each time they are checked when they are in a :ref:`hard <thebasics/statetypes>` non-OK state, and the check returns a non-OK state (i.e. no state change has occurred)... * The non-OK service state is logged * Contacts are notified about the problem (if that's :ref:`what should be done <thebasics/notifications>`). Notification intervals are ignored for volatile services. * The :ref:`event handler <advanced/eventhandlers>` for the service is run (if one has been defined) These events normally only occur for services when they are in a non-OK state and a hard state change has just occurred. In other words, they only happen the first time that a service goes into a non-OK state. If future checks of the service result in the same non-OK state, no hard state change occurs and none of the events mentioned take place again. .. tip:: If you are only interested in logging, consider using :ref:`stalking <advanced/stalking>` options instead. The Power Of Two ================= * :ref:`Shinken Configuration <advanced/volatileservices#shinken_configuration>` * :ref:`PortSentry Configuration <advanced/volatileservices#portsentry_configuration>` * :ref:`Port Scan Script <advanced/volatileservices#port_scan_script>` If you combine the features of volatile services and :ref:`passive service checks <thebasics/passivechecks>`, you can do some very useful things. Examples of this include handling "SNMP" traps, security alerts, etc. How about an example... Let's say you're running `PortSentry`_ to detect port scans on your machine and automatically firewall potential intruders. If you want to let Shinken know about port scans, you could do the following... .. _advanced/volatileservices#shinken_configuration: Shinken Configuration ---------------------- * Create a service definition called Port Scans and associate it with the host that PortSentry is running on. * Set the "max_check_attempts" directive in the service definition to 1. This will tell Shinken to immediate force the service into a :ref:`hard state <thebasics/statetypes>` when a non-OK state is reported. * Set the "active_checks_enabled" directive in the service definition to 0. This prevents Shinken from actively checking the service. * Set the "passive_checks_enabled" directive in the service definition to 1. This enables passive checks for the service. * Set this "is_volatile" directive in the service definition to 1. .. _advanced/volatileservices#portsentry_configuration: PortSentry Configuration ------------------------- Edit your PortSentry configuration file ("portsentry.conf") and define a command for the KILL_RUN_CMD directive as follows: :: KILL_RUN_CMD="/usr/local/Shinken/libexec/eventhandlers/submit_check_result *"host_name"* 'Port Scans' 2 'Port scan from host $TARGET$ on port $PORT$. Host has been firewalled.'" Make sure to replace host_name with the short name of the host that the service is associated with. .. _advanced/volatileservices#port_scan_script: Port Scan Script ----------------- Create a shell script in the "/var/lib/shinken/libexec/eventhandlers" directory named **submit_check_result**. The contents of the shell script should be something similar to the following... :: #!/bin/sh # Write a command to the Shinken command file to cause # it to process a service check result echocmd="/bin/echo" CommandFile="/var/lib/shinken/rw/shinken.cmd" # get the current date/time in seconds since UNIX epoch datetime=`date +%s` # create the command line to add to the command file cmdline="[$datetime] PROCESS_SERVICE_CHECK_RESULT;$1;$2;$3;$4" # append the command to the end of the command file `$echocmd $cmdline >> $CommandFile` What will happen when PortSentry detects a port scan on the machine in the future? * PortSentry will firewall the host (this is a function of the PortSentry software) * PortSentry will execute the **submit_check_result** shell script and send a passive check result to Shinken * Shinken will read the external command file and see the passive service check submitted by PortSentry * Shinken will put the Port Scans service in a hard CRITICAL state and send notifications to contacts Pretty neat, huh? .. _PortSentry: http://sourceforge.net/projects/sentrytools/