README

   1 Welcome to NSCA-ng!
   2 ===================
   3
   4 The NSCA-ng package provides a client-server pair which makes the "Nagios
   5 command file" accessible to remote systems.  This allows for submitting
   6 passive check results, downtimes, and many other [commands][1] to Nagios (or
   7 compatible monitoring solutions).
   8
   9 NSCA-ng supports TLS encryption and shared-secret authentication with
  10 client-specific passwords (based on [RFC 4279][2]), as well as fine-grained
  11 authorization control.
  12
  13 Prerequisites
  14 -------------
  15
  16 1.  [OpenSSL][3] 1.0.0 or newer is required for building NSCA-ng (as older
  17     releases don't support pre-shared key authentication).  This is the only
  18     hard dependency of the NSCA-ng client.  If the OpenSSL version provided
  19     by your operating system vendor is too old, you might want to build a
  20     private copy of OpenSSL and embed it into NSCA-ng.  This could be done
  21     by running the `./build-aux/make-openssl` script, which downloads the
  22     most recent OpenSSL version and installs it into the NSCA-ng source
  23     tree.  The `./configure` script (see below) will then pick that up
  24     automatically.
  25
  26 2.  The NSCA-ng *server* also requires [libConfuse][4] 2.6 or newer.  In
  27     order to embed a private copy of libConfuse into NSCA-ng, the
  28     `./build-aux/make-confuse` script could be run before calling
  29     `./configure`.
  30
  31 3.  If [libev][5] 4.00 or newer is available and found by the `./configure`
  32     script, NSCA-ng will (by default) use it.  Otherwise, a bundled copy of
  33     libev is embedded into NSCA-ng, so this dependency is optional.
  34
  35 4.  Optional [systemd][6] integration code is added to the NSCA-ng *server*
  36     if systemd's `sd-daemon(3)` library is found.  This can be disabled by
  37     specifying the `--without-systemd` option on the `./configure` command
  38     line.
  39
  40 Installation
  41 ------------
  42
  43 If only the client should be built, issuing the following three commands in
  44 NSCA-ng's source directory should do the trick:
  45
  46     $ ./configure
  47     $ make
  48     $ su root -c 'make install'
  49
  50 This installs the NSCA-ng client into appropriate subdirectories of
  51 `/usr/local`.
  52
  53 The installation process can be customized by setting environment variables
  54 and/or passing options to the `./configure` script.  Some of the more
  55 frequently used `./configure` options include:
  56
  57 * `--enable-server`
  58
  59     Build and install the NSCA-ng server (in addition to the client, unless
  60     `--disable-client` is specified).
  61
  62 * `--disable-client`
  63
  64     Don't build and install the NSCA-ng client.
  65
  66 * `--disable-posix-aio`
  67
  68     Don't use the POSIX AIO API.  By default, the NSCA-ng server will use
  69     the POSIX AIO API if available.
  70
  71 * `--prefix=PATH`
  72
  73     Install NSCA-ng into subdirectories of `PATH` instead of `/usr/local`.
  74
  75 * `--with-confuse=PATH`
  76
  77     Search for the libConfuse header files in `PATH/include`, and search for
  78     the libConfuse library files in `PATH/lib`.  If this option isn't
  79     specified, `./configure` will look for libConfuse in a few typical
  80     locations.
  81
  82 * `--with-ev=PATH`
  83
  84     Search for the libev header files in `PATH/include`, and search for the
  85     libev library files in `PATH/lib`.  If this option isn't specified,
  86     `./configure` will look for libev in a few typical locations; and if no
  87     usable version is found, a bundled copy of libev will be embedded into
  88     NSCA-ng.  In order to force usage of the included copy,
  89     `--with-ev=embedded` can be specified; while `--with-ev=external` would
  90     disallow falling back to the bundled libev code.
  91
  92 * `--with-openssl=PATH`
  93
  94     Search for the OpenSSL header files in `PATH/include`, and search for
  95     the OpenSSL library files in `PATH/lib`.  If this option isn't
  96     specified, `./configure` will look for OpenSSL in a few typical
  97     locations.
  98
  99 For a full list of available options and environment variables, run
 100 `./configure --help`.  See the file `INSTALL` for detailed installation
 101 instructions.
 102
 103 Configuration
 104 -------------
 105
 106 The NSCA-ng client is configured using the `send_nsca.cfg(5)` file, the
 107 NSCA-ng server uses the `nsca-ng.cfg(5)` file.  Examples of these files are
 108 installed if they don't already exist.
 109
 110 > **Important:**  Please set the permissions of the configuration files
 111 > appropriately to make sure that only authorized users can access them.
 112
 113 A script such as `nsca-ng.init` (as provided in the `contrib` directory of
 114 this package) could be used to start and stop the NSCA-ng server.
 115
 116 Usage
 117 -----
 118
 119 Please see the scripts in the `contrib` directory for various usage
 120 examples.
 121
 122 NSCA Compatibility
 123 ------------------
 124
 125 The NSCA-ng client (`send_nsca`) is a drop-in replacement for the
 126 `send_nsca` binary provided with the original NSCA 2.x package in the sense
 127 that NSCA-ng's `send_nsca` accepts all input, command line arguments, and
 128 configuration files accepted by the original `send_nsca`.  NSCA-ng clients
 129 cannot talk to NSCA servers (nor vice versa), but NSCA and NSCA-ng servers
 130 can happily run side by side, and they use different ports by default.
 131
 132 Documentation
 133 -------------
 134
 135 Detailed information regarding the build and installation process can be
 136 found in the file `INSTALL`.
 137
 138 The NSCA-ng usage and configuration is documented in the `nsca-ng(8)`,
 139 `send_nsca(8)`, `nsca-ng.cfg(5)`, and `send_nsca.cfg(5)` manual pages.  The
 140 commands `send_nsca -h` and `nsca-ng -h` spit out short summaries of the
 141 available command line options.
 142
 143 For each release, noteworthy changes are listed in the file `NEWS`.  Feature
 144 additions which are planned for future releases are added to the `TODO`
 145 file.
 146
 147 For copyright and license information, see the file `COPYING`.
 148
 149 Support
 150 -------
 151
 152 Bug reports and patches can be sent to the <developers@nsca-ng.org> list (no
 153 subscription required).  For usage support, please subscribe to the
 154 <users@nsca-ng.org> list.  See the [NSCA-ng][7] website for details.
 155
 156 [1]: http://www.nagios.org/developerinfo/externalcommands/
 157 [2]: http://tools.ietf.org/html/rfc4279
 158 [3]: http://www.openssl.org/
 159 [4]: http://www.nongnu.org/confuse/
 160 [5]: http://libev.schmorp.de/
 161 [6]: http://www.freedesktop.org/wiki/Software/systemd/
 162 [7]: http://www.nsca-ng.org/
 163
 164 <!-- vim:set filetype=markdown textwidth=76 joinspaces: -->