Major changes to README.SSL and mostly minor changes to others.

README.SSL.md

@@ -1,34 +1,123 @@
 NRPE With SSL/TLS
+=================
 
-NRPE now has the option for Encrypting Network traffic using
-SSL/TLS from openssl. 
+NRPE has had basic support for SSL/TLS for some time now, but it was
+severely lacking. It only allowed anonymous Diffie Hellman (ADH) key
+exchange, it used a fixed 512-bit key (generated at `./configure`
+time and extremely insecure) and originally allowed SSLv2. In 2004,
+SSLv2 and SSLv3 support was disabled.
 
-The Encryption is done using a set encryption routine of 
-AES-256 Bit Encryption using SHA and Anon-DH. This encrypts
-all traffic using the NRPE sockets from the client to the server.
+nrpe and check_nrpe have been updated to offer much more secure
+encryption and more options. And the updates are done in a backward-
+compatible way, allowing you to migrate to the newer versions
+without having to do it all at once, and possibly miss updating some
+machines, causing lost reporting.
 
-Since we are using Anon-DH this allows for an encrypted 
-SSL/TLS Connection without using pre-generated keys or 
-certificates. The key generation information used by the 
-program to dynaically create keys on daemon startup can be found
-in the dh.h file in the nrpe src directory. This file was created
-using the command:
+The changes to the NRPE daemon are outlined below first, followed by
+the changes to the check_nrpe client.
 
-openssl dhparam -C 512 
 
-which outputs the C code in dh.h. For your own security you can replace
-that file with your own dhparam generated code.
+------------------------------------------
+####CHANGES IN THE CURRENT VERSION OF NRPE
+------------------------------------------
 
-As of this time you will need to have the latest greatest version of
-OpenSSL (tested against version 0.9.7a) since not all versions have
-the AES algorythm in them.
+Running `./configure` will now create a 2048-bit DH key instead
+of the old 512-bit key. The most current versions of openSSL will
+still not allow it. In my testing, openSSL 1.0.1e allowed DH keys
+of 512 bits, and 1.0.1k would not allow 2048 bit keys.
 
-I am not aware that at this time this code is restricted under export 
-restrictions but I leave that verification process up to you.
+The NRPE configuration file has added new SSL/TLS options. The
+defaults currently will allow old check_nrpe clients to continue to
+connect to the nrpe daemon, but can report on "old style" 
+connections, or enforce more secure communication as your migration
+progresses. The new options are in the "SSL/TLS OPTIONS" section of
+nrpe.cfg, about two-thirds of the way down.
 
-Thoughts and suggestions are welcome and I can be reached on the
-Nagios and NagiosPlug Mailing Lists.
+The `ssl_version` directive lets you set which versions of SSL/TLS
+you want to allow. SSLv2, SSLv3, TLSv1, TLSv1.1 and TLSv1.2 are
+allowed, or those litereals with a `+` after them (as in TLSv1.1+).
+Without the `+`, that version _only_ will be used. With the `+`,
+that version _or above_ will be used. openSSL will always negotiate
+the highest available allowed version available on both ends. This
+directive currently defaults to `TLSv1+`.
 
-	- Derrick
+The `ssl_use_adh` directive is **DEPRECATED**, even though it is new.
+Possible values are `0` to not allow ADH at all, `1` to allow ADH,
+and `2` to require ADH. The `2` should never be required, but it's
+there just in case it's needed, for whatever reason. `1` is currently
+the default, which allows older check_nrpe clients to connect using
+ADH. When all the clients are migrated to the newer version, it
+should be set to `0`. In an upcoming version of NRPE, ADH will no
+longer be allowed at all. Note that if you use a `2` here, NRPE will
+override any `ssl_cipher_list` entries (below) to *only* allow ADH.
 
+The `ssl_cipher_list` directive lets you specify which ciphers you
+want to allow. It currently defaults to `ALL:!MD5:@STRENGTH` but can
+take any value allowed by openSSL. In an upcoming version of NRPE, it
+will be changed to something more secure, something like
+`ALL:!aNULL:!eNULL:!SSLv2:!LOW:!EXP:!RC4:!MD5:@STRENGTH`. Note that
+if you have `ssl_use_adh=2`, this string will be overridden with
+`ADH` which only only allow ADH.
 
+The `ssl_cacert_file`, `ssl_cert_file` and `ssl_privatekey_file`
+directives are used to specify which *.pem files are to be used for
+Public-Key Encryption (PKE). Setting these will allow clients to use
+PKE to communicate with the server, similar to how the HTTPS
+protocol works.
+
+The `ssl_client_certs` directive specifies whether or not a client
+certificate will be requested when a client tries to connect. A value
+of `0` means the nrpe daemon will not ask for or require a client
+certificate. A `1` will cause it to ask for a client certificate, but
+not require one. A `2` will require the client to present a valid
+certificate. This currently defaults to `0`. If you want to use
+client certificates and are upgrading the clients over time, you can
+set this to `1` once many have been upgraded, then set to `2` to
+force the use of client certs. Note that the client certs _must_ be
+signed by the CA cert specified in the `ssl_cacert_file` directive.
+
+The `ssl_logging` directive allows you to log some additional data
+to syslog. OR (or add) values together to have more than one option
+enabled. Values are `0` for no additional logging (the default),
+`1` to log startup SSL/TLS parameters from the nrpe.cfg file, `2` to
+log the SSL/TLS version of connections, `4` to log which cipher is
+being used for the connection, `8` to log if client has a cert, and
+`16` to log details of client's certificate. `-1` will enable all.
+This can be especially helpful during client migration, so you can
+tell which clients have certificates, what SSL/TLS version is being
+used, and which ciphers are being used.
+
+The `ssl_adh_key` directive is **DEPRECATED**, even though it's new. It
+should be used (if at all) during client migration. This will allow
+you to change the ADH key without having to recompile the NRPE
+daemon. It can either contain the path to a key file, or it can
+contain a base-64 encoded key. See the examples in the nrpe.cfg file.
+
+
+------------------------------------------------
+####CHANGES IN THE CURRENT VERSION OF CHECK_NRPE
+------------------------------------------------
+
+The check_nrpe client has also been updated to provide more secure
+encryption and allow the use of client certificates. The command line
+has several new options, which are outlined below. Both the long and
+short arguments are presented.
+
+`--no-adh` or `-d` will disable the use of ADH. This option is **DEPRECATED**,
+even though it's new. It will be removed in a future version.
+
+`--ssl-version=<ver>` or `-S <ver>` specifies minimum SSL/TLS version
+to use. See the `ssl_version` directive above for possible values.
+
+`--cipher-list=<value.` or `-L <value>` determines which ciphers will
+and won't be allowed. See the `ssl_cipher_list` directive above.
+
+`--client-cert=<path>` or `-C <path>` specifies an optional client
+certificate to use. If this value is entered, the next one below is
+required.
+
+`--key-file=<path>` or `-K <path>` specifies the client certificate
+key file to use. This goes along with `--client-cert` above.
+
+`--ca-cert-file=<path>` or `-A <path>` specifies the CA certificate
+to use in order to validate the nrpe daemon's public key.

README.md

@@ -1,15 +1,9 @@
------------
 NRPE README
------------
-
-
-** UPDATED DOCUMENTATION!
+===========
 
 For installation instructions and information on the design overview
 of the NRPE addon, please read the PDF documentation that is found in 
-this directory: NRPE.pdf
-
-
+this directory: `docs/NRPE.pdf`
 
 
 Purpose
@@ -23,46 +17,45 @@ Contents
 
 There are two pieces to this addon:
 
-  1) NRPE       - This program runs as a background process on the 
-                  remote host and processes command execution requests
-	          from the check_nrpe plugin on the Nagios host.
-		  Upon receiving a plugin request from an authorized
-                  host, it will execute the command line associated
-                  with the command name it received and send the
-                  program output and return code back to the 
-                  check_nrpe plugin
-
-  2) check_nrpe - This is a plugin that is run on the Nagios host
-                  and is used to contact the NRPE process on remote
-	          hosts.  The plugin requests that a plugin be
-                  executed on the remote host and wait for the NRPE
-                  process to execute the plugin and return the result.
-                  The plugin then uses the output and return code
-                  from the plugin execution on the remote host for
-                  its own output and return code.
+  1) **NRPE**       - This program runs as a background process on the 
+                      remote host and processes command execution requests
+                      from the check_nrpe plugin on the Nagios host.
+                      Upon receiving a plugin request from an authorized
+                      host, it will execute the command line associated
+                      with the command name it received and send the
+                      program output and return code back to the 
+                      check_nrpe plugin
+
+  2) **check_nrpe** - This is a plugin that is run on the Nagios host
+                      and is used to contact the NRPE process on remote
+                      hosts.  The plugin requests that a plugin be
+                      executed on the remote host and wait for the NRPE
+                      process to execute the plugin and return the result.
+                      The plugin then uses the output and return code
+                      from the plugin execution on the remote host for
+                      its own output and return code.
 
 
 Compiling
 ---------
 
 The code is very basic and may not work on your particular
-system without some tweaking.  I just haven't put a lot of effort
-into this addond.  Most Linux users should be able to compile
-NRPE and the check_nrpe plugin with the following commands...
+system without some tweaking. If you are having any problems
+compiling on your system, please let us know, hopefully with
+fixes. Most users should be able to compile NRPE and the
+check_nrpe plugin with the following commands...
 
-./configure
-make all
+	./configure
+	make all
 
-The binaries will be located in the src/ directory after you
-run 'make all' and will have to be installed manually somewhere
+The binaries will be located in the `src/` directory after you
+run `make all` and will have to be installed manually somewhere
 on your system.
 
-
-NOTE: Since the check_nrpe plugin and nrpe daemon run on different
+_NOTE: Since the check_nrpe plugin and nrpe daemon run on different
       machines (the plugin runs on the Nagios host and the daemon
       runs on the remote host), you will have to compile the nrpe
-      daemon on the target machine.
-
+      daemon on the target machine._
 
 
 Installing
@@ -70,21 +63,19 @@ Installing
 
 The check_nrpe plugin should be placed on the Nagios host along
 with your other plugins.  In most cases, this will be in the
-/usr/local/nagios/libexec directory.
+`/usr/local/nagios/libexec` directory.
 
-The nrpe program and the configuration file (nrpe.cfg) should
+The nrpe program and the configuration file `nrpe.cfg` should
 be placed somewhere on the remote host.  Note that you will also
 have to install some plugins on the remote host if you want to
 make much use of this addon.
 
 
-
 Configuring
 -----------
 
 Sample config files for the NRPE daemon are located in the
-sample-config/ subdirectory.
-
+`sample-config/` subdirectory.
 
 
 Running Under INETD or XINETD
@@ -93,49 +84,46 @@ Running Under INETD or XINETD
 If you plan on running nrpe under inetd or xinetd and making use
 of TCP wrappers, you need to do the following things:
 
-
-
-1) Add a line to your /etc/services file as follows (modify the port
+1) Add a line to your `/etc/services` file as follows (modify the port
    number as you see fit)
 
 	nrpe            5666/tcp	# NRPE
 
-
-
 2) Add entries for the NRPE daemon to either your inetd or xinetd
    configuration files.  Which one your use will depend on which
    superserver is installed on your system.  Both methods are described
-   below.  NOTE: If you run nrpe under inetd or xinetd, the server_port
+   below.
+
+   _NOTE: If you run nrpe under inetd or xinetd, the server_port
    and allowed_hosts variables in the nrpe configuration file are
-   ignored.
+   ignored._
 
 
-   ***** INETD *****
-   If your system uses the inetd superserver WITH tcpwrappers, add an
-   entry to /etc/inetd.conf as follows:
+   #### INETD ####
+   If your system uses the inetd superserver **with** tcpwrappers, add an
+   entry to `/etc/inetd.conf` as follows:
 
 	nrpe 	stream 	tcp 	nowait 	<user> /usr/sbin/tcpd <nrpebin> -c <nrpecfg> --inetd
 
-   If your system uses the inetd superserver WITHOUT tcpwrappers, add an
-   entry to /etc/inetd.conf as follows:
+   If your system uses the inetd superserver **without** tcpwrappers,
+   add an entry to `/etc/inetd.conf` as follows:
 
 	nrpe 	stream 	tcp 	nowait 	<user> <nrpebin> -c <nrpecfg> --inetd
 
 
-   - Replace <user> with the name of the user that the nrpe server should run as.
-     	Example: nagios
-   - Replace <nrpebin> with the path to the nrpe binary on your system.
-	Example: /usr/local/nagios/nrpe
-   - Replace <nrpecfg> with the path to the nrpe config file on your system.
-	Example: /usr/local/nagios/nrpe.cfg
+   - Replace `<user>` with the name of the user that the nrpe server should run as.
+     Example: `nagios`
+   - Replace `<nrpebin>` with the path to the nrpe binary on your system.
+     Example: `/usr/local/nagios/nrpe`
+   - Replace `<nrpecfg>` with the path to the nrpe config file on your system.
+     Example: `/usr/local/nagios/nrpe.cfg`
 
 
-   ***** XINETD *****
+   #### XINETD ####
    If your system uses xinetd instead of inetd, you'll probably
-   want to create a file called 'nrpe' in your /etc/xinetd.d
+   want to create a file called `nrpe` in your `/etc/xinetd.d`
    directory that contains the following entries:
 
-
 	# default: on
 	# description: NRPE
 	service nrpe
@@ -151,16 +139,13 @@ of TCP wrappers, you need to do the following things:
 		only_from       = <ipaddress1> <ipaddress2> ...
 	}
 
-
-   - Replace <user> with the name of the user that the nrpe server should run as.
-   - Replace <nrpebin> with the path to the nrpe binary on your system.
-   - Replace <nrpecfg> with the path to the nrpe config file on your system.
-   - Replace the <ipaddress> fields with the IP addresses of hosts which
+   - Replace `<user>` with the name of the user that the nrpe server should run as.
+   - Replace `<nrpebin>` with the path to the nrpe binary on your system.
+   - Replace `<nrpecfg>` with the path to the nrpe config file on your system.
+   - Replace the `<ipaddress>` fields with the IP addresses of hosts which
      are allowed to connect to the NRPE daemon.  This only works if xinetd was
      compiled with support for tcpwrappers.
 
-
-
 3) Restart inetd or xinetd will the following command (pick the
    on that is appropriate for your system:
 
@@ -172,50 +157,44 @@ of TCP wrappers, you need to do the following things:
 
 	kill -HUP `cat /var/run/inet.pid`
 
-
-
-4) Add entries to your /etc/hosts.allow and /etc/hosts.deny
+4) Add entries to your `/etc/hosts.allow` and `/etc/hosts.deny`
    file to enable TCP wrapper protection for the nrpe service.
    This is optional, although highly recommended.
 
 
-
-
 Configuring Things On The Nagios Host
 ---------------------------------------
 
 Examples for configuring the nrpe daemon are found in the sample
-nrpe.cfg file included in this distribution.  That config file
+`nrpe.cfg` file included in this distribution.  That config file
 resides on the remote host(s) along with the nrpe daemon.  The
 check_nrpe plugin gets installed on the Nagios host.  In order
-to use the check_nrpe plugin from within Nagios, you'll have
+to use the check_nrpe plugin from within Nagios, you will have
 to define a few things in the host config file.  An example
 command definition for the check_nrpe plugin would look like this:
 
-define command{
-	command_name	check_nrpe
-	command_line	/usr/local/nagios/libexec/check_nrpe -H $HOSTADDRESS$ -c $ARG1$
-	}
+    define command{
+        command_name	check_nrpe
+        command_line	/usr/local/nagios/libexec/check_nrpe -H $HOSTADDRESS$ -c $ARG1$
+        }
 
 In any service definitions that use the nrpe plugin/daemon to
 get their results, you would set the service check command portion
 of the definition to something like this (sample service definition
 is simplified for this example):
 
-define service{
-	host_name		someremotehost
-	service_description	someremoteservice
-	check_command		check_nrpe!yourcommand
-	... etc ...
-	}
+    define service{
+        host_name		someremotehost
+        service_description	someremoteservice
+        check_command		check_nrpe!yourcommand
+        ... etc ...
+        }
 
-where "yourcommand" is a name of a command that you define in 
+where `yourcommand` is a name of a command that you define in 
 your nrpe.cfg file on the remote host (see the docs in the 
 sample nrpe.cfg file for more information).
 
 
-
-
 Questions?
 ----------
 
@@ -224,11 +203,5 @@ working, first try searching the nagios-users mailing list archives.
 Details on searching the list archives can be found at 
 http://www.nagios.org
 
-If all else fails, you can email me and I'll try and respond as
-soon as I get a chance.
-
-	-- Ethan Galstad (nagios@nagios.org)
-
-
-
-
+If you don't find an answer there, post a message in the Nagios
+Plugin Development forum at https://support.nagios.com/forum/viewforum.php?f=35

SECURITY.md

@@ -1,25 +1,20 @@
-********************
 NRPE SECURITY README
-********************
+====================
 
+---
 
-TCP WRAPPER SUPPORT
-===================
+### TCP WRAPPER SUPPORT ###
 
-NRPE 2.x includes native support for TCP wrappers.  The older
-host access list directive was removed from the config file.
-Make sure your system supports TCP wrappers before running NRPE.
-Once you compile NRPE you can check to see if it has wrapper
-support built in by running the daemon from the command line
-without any arguments like this:
-
-	./nrpe --help
 
+NRPE 2.x includes native support for TCP wrappers. Once you
+compile NRPE you can check to see if it has wrapper support
+built in by running the daemon from the command line without
+any arguments like this:
 
+	./nrpe --help
 
 
-COMMAND ARGUMENTS
-=================
+#### COMMAND ARGUMENTS ####
 
 NRPE 2.0 includes the ability for clients to supply arguments to
 commands which should be run.  Please note that this feature
@@ -27,60 +22,55 @@ should be considered a security risk, and you should only use
 it if you know what you're doing!
 
 
-BASH COMMAND SUBSTITUTION
--------------------------
+#### BASH COMMAND SUBSTITUTION ####
 
 Even with the metacharacter restrictions below, if command arguments 
 are enabled, it is still possible to send bash command substitions 
-in the form $(...) as an agrument. This is explicity disabled by 
+in the form `$(...)` as an agrument. This is explicity disabled by 
 default, but can be enabled by a configure-time option and a
-configuration file option. Enabling this option is VERY RISKY and 
-its use is HIGHLY DISCOURAGED.
+configuration file option. Enabling this option is **VERY RISKY**
+and its use is **HIGHLY DISCOURAGED**.
 
 
-ENABLING ARGUMENTS
-------------------
+#### ENABLING ARGUMENTS ####
 
 To enable support for command argument in the daemon, you must
 do two things:
 
-   1.  Run the configure script with the --enable-command-args 
+   1.  Run the configure script with the `--enable-command-args`
        option
 
-   2.  Set the 'dont_blame_nrpe' directive in the NRPE config
-       file to 1.
+   2.  Set the `dont_blame_nrpe` directive in the NRPE config
+       file to `1`.
 
 
-ENABLING BASH COMMAND SUBSTITUTION
-----------------------------------
+#### ENABLING BASH COMMAND SUBSTITUTION ####
 
 To enable support for arguments containing bash command substitions, 
 you must do two things:
 
    1.  Enable arguments as described above
 
-   2.  Include the --enable-bash-command-substitution configure
+   2.  Include the `--enable-bash-command-substitution` configure
        option when running the configure script
 
-   3.  Set the 'allow_bash_command_substitutions' directive in the 
-       NRPE config file to 1.
+   3.  Set the `allow_bash_command_substitutions` directive in the 
+       NRPE config file to `1`.
 
 
-ILLEGAL METACHARS
------------------
+#### ILLEGAL METACHARS ####
 
 To help prevent some nasty things from being done by evil 
 clients, the following metacharacters are not allowed
 in client command arguments:
 
-   | ` & > < ' " \ [ ] { } ; !
+	| ` & > < ' " \ [ ] { } ; !
 
-Any client request which contains the abovementioned metachars
+Any client request which contains the above mentioned metachars
 is discarded.
 
 
-USER/GROUP RESTRICTIONS
------------------------
+#### USER/GROUP RESTRICTIONS ####
 
 The NRPE daemon cannot be run with (effective) root user/group
 privileges.  You must run the daemon with an account that does
@@ -89,21 +79,19 @@ directives in the config file to specify which user/group the
 daemon should run as.
 
 
-ENCRYPTION
-----------
+#### ENCRYPTION ####
 
 If you do enable support for command arguments in the NRPE daemon,
 make sure that you encrypt communications either by using:
 
    1.  Stunnel (see http://www.stunnel.org for more info)
-   2.  Native SSL support
+   2.  Native SSL support (See the `README.SSL.md` file for more info)
 
-Do NOT assume that just because the daemon is behind a firewall
+*Do NOT* assume that just because the daemon is behind a firewall
 that you are safe!  Always encrypt NRPE traffic!
 
 
-USING ARGUMENTS
----------------
+#### USING ARGUMENTS ####
 
 How do you use command arguments?  Well, lets say you define a
 command in the NRPE config file that looks like this:
@@ -123,9 +111,3 @@ like this:
 
 You can supply up to 16 arguments to be passed to the command
 for substitution in $ARG$ macros ($ARG1$ - $ARG16$).
-
-
-
-
-    -- Ethan Galstad (nagios@nagios.org)
-