1*********** 2NSCA README 3*********** 4 5 6Purpose 7------- 8The purpose of this addon is to allow you to send service check 9results to a central monitoring server running Nagios in a secure 10manner. 11 12 13Contents 14-------- 15 16There are two pieces to this addon: 17 18 1) nsca - This program runs as a daemon on the central server 19 that runs Nagios. It listens for host and service 20 check results from remote machines (sent using the 21 send_nsca program described below). Upon receiving 22 data from a remote client, the daemon will make a 23 *very* basic attempt at validating the data it has 24 received from the client. This is done by decrypting 25 the data with the password stored in the nsca.cfg 26 file. If the decrypted data looks okay (i.e. it was 27 originally encrypted by the send_ncsa program using 28 the same password), the daemon will make entries in 29 the Nagios external command file telling Nagios 30 to process the host or service check result. 31 32 Notes: The nsca daemon must have sufficient rights 33 to open the Nagios command file for writing. Also, 34 Nagios will only process passive service check 35 results that it finds in the external command file 36 if the service has been defined in the host config 37 file (i.e. hosts.cfg) and it is being monitored. 38 39 40 2) send_nsca - This is the client program that is used to send 41 service check information from a remote machine to 42 the nsca daemon on the central machine that runs 43 Nagios. Service check information is read from 44 the standard input in tab-delimited format as 45 follows: 46 47 <host_name>[tab]<svc_description>[tab]<return_code>[tab]<plugin_output>[newline] 48 49 where: 50 51 <host_name>=short name of host that the 52 service is associated with 53 <svc_description>=description of the service 54 <return_code>=numeric return code 55 <plugin_output>=output from service check 56 57 Host check information is submitted in a similiar 58 fashion - just leave out the service description: 59 60 <host_name>[tab]<return_code>[tab]<plugin_output>[newline] 61 62 63Compiling 64--------- 65 66The code is very basic and may not work on your particular 67system without some tweaking. I just haven't put a lot of effort 68into this addon. Most users should be able to compile 69the daemon and client piece with the following commands... 70 71./configure 72make all 73 74The binaries will be located in the src/ directory after you 75run 'make all' and will have to be installed manually. 76 77 78 79Installing 80---------- 81 82The send_nsca program and associate config file (nsca.cfg) should 83be placed on remote machines that you want to have communicate 84with the nsca daemon. This means that you may have to compile the 85send_nsca program on the remote machine, if its not the same 86OS/architecture as that of the central server. 87 88The nsca daemon and the configuration file (nsca.cfg) should 89be placed somewhere on the central server running Nagios. 90 91NOTES: Make sure that you specify and use the same password in 92 both the nsca.cfg and send_nsca.cfg files! If you use a 93 different password to encrypt the data than you do to 94 decrypt it, the nsca daemon will reject the data you send 95 it. 96 97 98 99Security 100-------- 101 102There are some security implications with allowing remote clients 103to provide service check results to Nagios. Because of this, you 104have the option of encrypting the packets that the NSCA client sends 105to the NSCA daemon. Read the SECURITY file for more information on 106the security risks of running NSCA, along with an explanation of what 107kind of protection the encryption provides you. 108 109 110 111Running Under INETD or XINETD 112----------------------------- 113 114If you plan on running nsca under inetd or xinetd and making use 115of TCP wrappers, you need to do the following things: 116 117 118 1191) Add a line to your /etc/services file as follows (modify the port 120 number as you see fit) 121 122 nsca 5667/tcp # NSCA 123 124 125 1262) Add entries for the NSCA daemon to either your inetd or xinetd 127 configuration files. Which one your use will depend on which 128 superserver is installed on your system. Both methods are described 129 below. NOTE: If you run nsca under inetd or xinetd, the server_port 130 and allowed_hosts variables in the nrpe configuration file are 131 ignored. 132 133 134 ***** INETD ***** 135 If your system uses the inetd superserver WITH tcpwrappers, add an 136 entry to /etc/inetd.conf as follows: 137 138 nsca stream tcp nowait <user> /usr/sbin/tcpd <nscabin> -c <nscacfg> --inetd 139 140 If your system uses the inetd superserver WITHOUT tcpwrappers, add an 141 entry to /etc/inetd.conf as follows: 142 143 nsca stream tcp nowait <user> <nscabin> -c <nscacfg> --inetd 144 145 146 - Replace <user> with the name of the user that nsca server should run as. 147 Example: nagios 148 - Replace <nscabin> with the path to the nsca binary on your system. 149 Example: /usr/local/nagios/nsca 150 - Replace <nscacfg> with the path to the nsca config file on your system. 151 Example: /usr/local/nagios/nsca.cfg 152 153 154 ***** XINETD ***** 155 If your system uses xinetd instead of inetd, you'll probably 156 want to create a file called 'nsca' in your /etc/xinetd.d 157 directory that contains the following entries (a sample config 158 file called nsca.xinetd should be created in the root folder of 159 the distribution after you run the configure script): 160 161 162 # default: on 163 # description: NSCA 164 service nsca 165 { 166 flags = REUSE 167 socket_type = stream 168 wait = no 169 user = <user> 170 group = <group> 171 server = <nscabin> 172 server_args = -c <nscacfg> --inetd 173 log_on_failure += USERID 174 disable = no 175 only_from = <ipaddress1> <ipaddress2> ... 176 } 177 178 179 - Replace <user> with the name of the user that the nsca server should run as. 180 - Replace <group> with the name of the group that the nsca server should run as. 181 - Replace <nscabin> with the path to the nsca binary on your system. 182 - Replace <nscacfg> with the path to the nsca config file on your system. 183 - Replace the <ipaddress> fields with the IP addresses of hosts which 184 are allowed to connect to the NSCA daemon. This only works if xinetd was 185 compiled with support for tcpwrappers. 186 187 188 1893) Restart inetd or xinetd will the following command (pick the 190 one that is appropriate for your system: 191 192 /etc/rc.d/init.d/inet restart 193 194 /etc/rc.d/init.d/xinetd restart 195 196 197 1984) Add entries to your /etc/hosts.allow and /etc/hosts.deny 199 file to enable TCP wrapper protection for the nsca service. 200 This is optional, although highly recommended. 201 202 203 204 205Questions? 206---------- 207 208If you have questions about this addon, or problems getting things 209working, send me email. 210 211 -- Ethan Galstad (nagios@nagios.org) 212 213 214 215 216