.. _advanced/discovery-with-shinken-advanced:

===============================
Advanced discovery with Shinken
===============================


.. important::  This topic assumes you have read and understood :ref:`simple discovery with Shinken <advanced/discovery-with-shinken>`.


How the discovery script works 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Did you like the discovery script? Now it's time to look at how it works, and get even more from it.

The discovery is done in two distinct phases:
  * the discovery script runs generate raw data
  * the discovery rules use this data to generate objects like hosts or services


Discovery scripts 
~~~~~~~~~~~~~~~~~~


A discovery script can be anything you can launch from a shell, just like plugins. As mentioned their main goal is to generate raw data for objects. Yes, it can be open ports of a server, or the number of wheels your car has, as you want. :)

The raw data is being sent to standard out.

Here is an example of the output of the nmap script for a standard Linux box:

::

  $ libexec/nmap_discovery_runner.py -t localhost
  
  localhost::isup=1
  localhost::os=linux
  localhost::osversion=2.6.X
  localhost::macvendor=
  localhost::openports=22,80,1521,3306,5432,5666,6502,8080,50000
  localhost::fqdn=localhost
  localhost::ip=127.0.0.1
  
  
So the output format is:
  

::

  objectname::key=value
  
  
If there are multiple values, like here for open ports, they are separated by commas "'',''".

The discovery script definitions (like nmap or vmware used by default) are located in the file ''/etc/shinken/discovery_runs.cfg''.


Discovery rules 
~~~~~~~~~~~~~~~~


Without rules, the raw data that is being generated by the discovery scripts is useless.
The rules are defined in the ''/etc/shinken/discovery_rules.cfg'' file.


Host rule 
**********


Here is an example of how to create a "generic" host for anything that is detected by nmap and answers to a ping request:

::

  define discoveryrule {
         discoveryrule_name       HostGeneric
         creation_type            host
         
         isup                     1
         
         use                      generic-host
  }
  
  
There are three main parts for a rule:
  * ''discoveryrule_name'' and ''creation_type'' parameter. The first one should be unique, and the second can be 'host' or 'service' (default). More types will be added in the future.
  * ''isup'': refers the key name that will be looked up in the raw data from the discovery scripts. It's value (here 1) will be used for a comparison. If all key/values pairs are good, the rule is valid, and will be applied.
  * ''use'': This mentions the template from which the generated object will inherit from. You can add as many properties as you want.


Service rule 
*************


Here is an example for a port matching rule service creation:
  

::

  define discoveryrule {
       discoveryrule_name       Ftp
       
       openports                ^21$
       
       check_command            check_ftp
       service_description      Ftp
       use                      generic-service
  }
  
Here, if the port 21 is open. The ^and $ is for the regexp thing, so 21 and only 21 will be match, and not 210 for example.

The service generated will be with FTP for the host_name the object_name send by the discovery script, the check_command check_ftp and it will use the generic-service template.


The ! (not) key 
****************


You can ask **not** to match a rule. It's very easy, just add a ! character before the key name.

For example:

::
  
  define discoveryrule {
       discoveryrule_name       Ftp
       
       openports                ^21$
       !os                      linux
       
       check_command            check_ftp
       service_description      Ftp
       use                      generic-service
  }
  
This will create the Ftp service for all hosts that have port 21 open, but not for the linux ones.


Add something instead of replace 
*********************************


By default, when you put a new host/service property, it will replace all previously detected values. For some properties like templates or groups, this is not a good idea. That's why you can say a property should be "added" by using the character "+" before it.

For example, we want to add the "ftp" and "http" templates on the host, without removing all previously inserted values.


::

  define discoveryrule {
       discoveryrule_name       Ftp
       creation_type            host
       openports                ^21$
       +use                     ftp
  }
  
  define discoveryrule {
       discoveryrule_name       Http
       creation_type            host
       openports                ^21$
       +use                     http
  }
  
  
If both ports are open, it will create a host with:

::
  
  define host {
    host_name   localhost
    use         ftp,http
  }


.. important::  The rules order is important, here ftp apply before http. So put the "generic" template at the end of you rules file.


.. important::  Why is the rule order important, explain the impact.


Delete something after add 
***************************


Sometimes you need to simply remove a property that conflicts with a new one. For example, some routers are derived from linux system but does not work with the linux template. That's why you can say a property should be "remove" by using the character "-" before it.

For example we want to add the "router-os" template but not the "linux" template on the host and do not remove previously inserted values.
   

::
  
  define discoveryrule {
       discoveryrule_name       Ftp
       creation_type            host
       openports                ^21$
       +use                     ftp
  }
  
  define discoveryrule {
       discoveryrule_name       Http
       creation_type            host
       openports                ^21$
       +use                     http
  }
  
  define discoveryrule {
       discoveryrule_name       Linux
       creation_type            host
       os                       linux
       +use                     linux
  }
  
  define discoveryrule {
       discoveryrule_name       RouterOS
       creation_type            host
       macvendor                routerboard
       +use                     router-os
       -use                     linux
  }


If both ports are open, os detected is linux and the macvendor is routerboard it will create a host with:

::
  
  define host {
    host_name   myrouter
    use         ftp,http,router-os
  }