_________________________________________________________________________
/                                                                         \
|                     Sentinel IRC Server Monitoring Bot                  |
|_________________________________________________________________________|
|                                                                         |
| Version      : 1.0.0                                                    |
| Base Concept : Pascal Gloor & Mehmet Akcin                              |
| Coder        : MrIron                                                   |
| Source       : https://github.com/UndernetIRC/sentinel                  |
|                                                                         |
\_________________________________________________________________________/


HISTORY

 Sentinel is a server monitoring bot largely based on GenEthic released by
 the administrator of the former Geneva.CH.EU.Undernet.Org.

 The bot monitors server and client activity and provides notifications to
 administrators in potentially server critical events such as high rping and
 sendq to its uplinks, and massive drop from its client base. Client monitoring
 is deactivated when the bot is in hubmode. 

 The bot reports to a designated back channel to its operators, and supports
 delievery of push notifications over the Pushover service. In addition,
 the bot can be linked to munin-plugins to generate statistics on local and global
 clients, channels, rping and sendq. The same can be generated by the included
 MRTG script.

REQUIREMENTS

 Operating System requirements:

    - perl 5.004 or better
    - perl IO:Socket module
    - web server (optional)
    - MRTG (optional)

 IRC Server requirements:

    - Running ircu. This bot is NOT compatible with any other IRC daemons.
    - An o:line (local oper) for the bot with the following privileges:
	walk_lchan = yes;
	deop_lchan = yes;
	see_chan = yes; # Only if the locgline setting is enabled
	unlimit_query = yes; # Only if the locgline setting is enabled
	rehash = no;
	local_jupe = no;
	local_gline = no; # 'Yes' if the locgline function is enabled.

    - A Class block with at least 3Mbytes of SendQ.
    - Unless the bot is in hubmode, enable the following features in your ircd.conf:

	"CONNEXIT_NOTICES" = "TRUE";

INSTALLATION

 Simply run the configuration software:

     ./install <absolute_path_to_install> [--force]

     --force   force the creation of the directory

 Example:

     ./install /home/sentinel

 Once the installation is done, edit the configuration file,
 which an be found in the etc/ folder.

    cd /path/to/sentinel/etc
    cp sample.conf sentinel.conf
    vi sentinel.conf


UNDERSTANDING BOT CHANNEL OUTPUT

 Once your bot is running it will output some informations to the
 channel at the interval set in the config (default every 5 minutes).

 Example:

   -bot:@&channel- @ COUNT  -> 6454(5.60%)/115338 (+208/-246). No 4/29. 48620(+9)chans, 67 unknown
   -bot:@&channel- @ RPING  -> hub2:25(+3) -- hub3:19(-7) -- hub4:47
   -bot:@&channel- @ UPLINK -> hub1[rp:19(+4) sq:0 up:1d0h53m]
   -bot:@&channel- @ TRAFFIC-> xl0 904/2471 kbps 1705/1599 pps xl1 209/49 kbps 52/38 pps

   on the first line, in the order the fields appear (this line will not appear i hubmode):

     - number of users on the local server
     - percentage of local users compared to global users
     - number of global users
     - number of users who connected in the last 5 minutes
     - number of users who disconnected in the last 5 minutes
     - position of the local server (regarding the amount of users)
     - number of global server (having at least 5 users)
     - number of channels
     - number of more/less channels since 5 minutes
     - number of unknown connections (as seen in /LUSERS)

  on the second line:

     - the last received rping results of all the hubs configured in your
       server config to which the server is not linked.

  on the third line:
     - last received rping result and sendq result for linked server(s) and uptime. 
       rping values are in miliseconds.

  on the fourth line(1):

     - traffic status for all the local interfaces(2). its always shown in the
       format in/out, first 'kbps' then 'pps' (packets per second).


USAGE OF THE BOT

 Once everything is correctly configured, the bot should take place in
 its channel. You can talk to the bot by PRIVMSG or NOTICE.
 The bot will also INVITE you to the channel as soon as you use the
 OPER command.

 Once in the channel you may communicate with the bot. Most of the stuff
 happens through the DCC interface. simply '/msg bot dcc <listen ip>' and the bot will
 start a dcc. you'll need a password to connect to the dcc and it will
 be given by the bot in the channel.
 -> *bot* dcc
 -bot:@&channel- @ your_nickname requested DCC, code is xy

 note: if you're running mIRC add this to your 'REMOTE' commands to automatically
  retrieve the password:

on 1:NOTICE:*:&channel:{
  if ( $me $+ ?requested?DCC??code?is iswm $2-6 ) {
    .timerDCC1 4 1 .echo = $+ $nick mIRC Script: Please wait, your password will be sent to the session in a few seconds
    .timerDCC2 1 5 .msg = $+ $nick $7
    halt
  }
}