TECHNICAL

   1 The life of a Nagios event
   2 --------------------------
   3 The path of events from 'luke' to 'yoda' goes as follows:
   4 Nagios on 'luke' runs a check (or whatever, but we'll stick
   5 with a check here) and runs a snippet of code inside the
   6 merlin broker module.
   7
   8 The module packs the event in a way that makes it suitable
   9 for network transport and sends the event to its daemon via
  10 a unix domain socket.
  11
  12 The daemon takes care of the event and sends it to its
  13 peers and its masters. If a poller was supposed to run this
  14 check, it also stashes the event in a binary backlog so it
  15 can send the event to the poller when it comes back online.
  16 When it has sent the event, it unpacks it and inserts it
  17 into the database, and then it goes on to handle other
  18 events in pretty much the same manner.
  19
  20 The receiving daemon(s) forward the event to their broker
  21 module(s) and then unpack it to insert it in their database.
  22
  23 The broker module(s) update the status of their Nagios instance
  24 with the information about the new check, and there it more or
  25 less ends.
  26
  27
  28 Node activation/deactivation
  29 ----------------------------
  30 The first thing each Merlin module does when it gets loaded is
  31 is to gather a little bit if info about itself and send that
  32 information as a control event to its daemon. The activation
  33 control packet contains protocol version, wordsize, byte order,
  34 object structure version of Nagios, the latest mtime of the
  35 configured object configuration files, and a sha1 hash of the
  36 object configuration files.
  37
  38 This CTRL_ACTIVE packet gets sent to all neighbours from the
  39 Merlin daemon, so all its configured nodes will get to see it.
  40 Every daemon that receives such a packet stashes the info in
  41 memory and forwards it to their module in case the module
  42 would be restarted. If there are compatibility issues, both
  43 daemon and module should warn about that.
  44
  45 When a module crashes, goes offline or is shut down in a
  46 controlled manner, a CTRL_INACTIVE event is generated from
  47 the Merlin daemon it's supposed to talk to. This CTRL_INACTIVE
  48 event is shipped to all the nodes in the neighbourhood and
  49 causes the previously received information to be wiped, and
  50 the module to be marked as inactive. An inactive node is
  51 considered dead when it comes to distributing workload.
  52
  53 In order for a Merlin node to be considered capable of running
  54 checks, it must be connected (via the daemon) and it must have
  55 sent a CTRL_ACTIVE event, which only ever comes from inside
  56 the module.
  57
  58 CTRL_ACTIVE has control-code 3.
  59 CTRL_INACTIVE has control-code 2.
  60
  61
  62 Peered loadbalancing
  63 --------------------
  64 Two peers automagically distribute the workload between them
  65 by means of an alphabetically sorted list of all configured
  66 hosts and services and a peer-id calculation (not negotiation)
  67 that yields the same result on all peers in the ring.
  68
  69 Peer-id calculation is done in the module when it receives a
  70 CTRL_ACTIVE or CTRL_INACTIVE event.
  71
  72 When Nagios tries to run a check, the module looks up the
  73 slot number for that particular check in its alphabetically
  74 sorted lists, and if slot-number modulo the number of active
  75 peers matches the peer-id of the module, it will run the check.
  76 Otherwise it will block the check from happening.
  77
  78 Peered nodes with pollers attached will still use the same list
  79 to distribute checks, except that all checks that are handled
  80 by an active poller will always be blocked on all peers. This
  81 means that peers with pollers will not share the workload
  82 exactly equally, and in theory one node could end up running
  83 all checks, but in practice the workload split is still very
  84 even.
  85
  86
  87 Pollerbased monitoring
  88 ----------------------
  89 Pollers will always execute all checks assigned to it, unless
  90 they have peers or pollers themselves. Work is assigned to
  91 pollers via hostgroups. Each hostgroup represents a "selection"
  92 in merlin, and every poller responsible for each "selection"
  93 is checked to see if the master node has to perform the check
  94 itself or if it's supposed to be delegated to a poller. If at
  95 least one active poller exists for the selection a particular
  96 check belongs to, the master will refuse to run the check.
  97
  98
  99 Configuration synchronization
 100 -----------------------------
 101 The CTRL_ACTIVE packets sent by the Merlin module when it gets
 102 loaded contains a SHA1 checksum of its configuration, along
 103 with the latest timestamp of that configuration. Currently,
 104 configuraion can be pushed from master to pollers and from
 105 peer to peer. Although a 'pull' config option exists, it's
 106 not tested and not supported. It just should work in theory.
 107
 108 If an activated peer has a different SHA1 hash than the node
 109 receiving the CTRL_ACTIVE event, a comparison is made to see
 110 which one has the newest configuration. The node with the
 111 newest configuration initiates the push command, which needs
 112 to be configured in the merlin.conf config-file. See the
 113 HOWTO for more information about configuring syncrhonization
 114 of object config.
 115
 116 For pollers this is more complicated, since pollers are not
 117 meant to have identical configuration. In that case, only
 118 the timestamp is compared. If the poller has an older config,
 119 the master initiates a push. Otherwise we assume everything
 120 is working properly. Pollers (currently) never push to masters.
 121 Such setups have been discussed and discarded for this first
 122 stable release of Merlin.