change the way relayd reports check results: instead of logging an

arbitrary string in debugging mode, it will store an error code
(HCE_*) for each host.  the error code can be translated to a string
(in log.c) for debugging but it will also be passed to relayctl via
the control socket.

from a user point of view, this will print a human-readable error
message in the "relayctl show hosts" output if a host is down because
the check failed.  the relayctl(8) manpage includes detailed
explanations of the error messages including mitigations for the
most-common problems.

ok jmc@ (manpages)
ok phessler@

1 files changed, 98 insertions, 2 deletions

diff --git a/usr.sbin/relayctl/relayctl.8 b/usr.sbin/relayctl/relayctl.8
index 3bffefae443..a57d471ba48 100644
--- a/usr.sbin/relayctl/relayctl.8
+++ b/usr.sbin/relayctl/relayctl.8
@@ -1,4 +1,4 @@
-.\" $OpenBSD: relayctl.8,v 1.21 2007/12/20 20:22:11 reyk Exp $
+.\" $OpenBSD: relayctl.8,v 1.22 2008/12/05 16:37:56 reyk Exp $
 .\"
 .\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: December 20 2007 $
+.Dd $Mdocdate: December 5 2008 $
 .Dt RELAYCTL 8
 .Os
 .Sh NAME
@@ -60,6 +60,10 @@ the backup table as well.
 Reload the configuration file.
 .It Cm show hosts
 Show detailed status of hosts and tables.
+It will also print the last error for failed host checks;
+see the
+.Sx ERRORS
+section below.
 .It Cm show redirects
 Show detailed status of redirections including the current and average
 access statistics.
@@ -94,6 +98,98 @@ again.
 Unix-domain socket used for communication with
 .Xr relayd 8 .
 .El
+.Sh ERRORS
+If a host is down and a previous check failed,
+.Nm
+will display the last error in the output of the
+.Cm show hosts
+command.
+This is especially useful for debugging server or configuration failures.
+The following errors will be reported:
+.Pp
+.Bl -tag -width Ds -compact
+.It Em none
+No specific error was reported by the check engine.
+.Pp
+.It Em aborted
+All checks were aborted by an external event, like a configuration reload.
+.Pp
+.It Em interval timeout
+The check did not finish in the configured time of an interval.
+This can happen if there are too many hosts that have to be checked by
+.Xr relayd 8
+and can be avoided by increasing the global
+.Ic interval
+option in
+.Xr relayd.conf 5 .
+.Pp
+.It Em icmp read timeout
+.It Em ssl read timeout
+.It Em tcp read timeout
+The check failed because the remote host did not send a reply within
+the configured timeout.
+.Pp
+.It Em icmp write timeout
+.It Em ssl write timeout
+.It Em tcp write timeout
+.It Em ssl connect timeout
+.It Em tcp connect timeout
+The check failed because
+.Xr relayd 8
+was not ready to send the request within the configured timeout.
+.Pp
+.It Em ssl connect error
+.It Em ssl read error
+.It Em ssl write error
+.It Em tcp connect error
+.It Em tcp read failed
+.It Em tcp write failed
+An I/O error occurred.
+This indicates that
+.Xr relayd 8
+was running low on resources,
+file descriptors, or was too busy to run the request.
+It can also indicate that an SSL/TCP protocol error occurred or that the
+connection was unexpectedly aborted.
+.Pp
+.It Em ssl connect failed
+.It Em tcp connect failed
+The check failed because the protocol handshake did not succeed in
+opening a stateful connection with the remote host.
+.Pp
+.It Em script failed
+The external script executed by the check did not return a valid return code.
+.Pp
+.It Em send/expect failed
+The payload data returned by the remote host did not match the
+expected pattern.
+.Pp
+.It Em http code malformed
+.It Em http digest malformed
+The remote host did not return a valid HTTP header or body.
+.Pp
+.It Em http code mismatch
+The remote host did not return a matching HTTP error code.
+This may indicate a real server problem (a server error, the page was
+not found, permission was denied) or a configuration error.
+For example, it is a very common mistake that
+.Xr relayd 8
+was configured to expect a
+HTTP 200 OK
+status but the host is returning a
+HTTP 302 Found
+redirection.
+See
+.Xr relayd.conf 5
+for more information on validating the HTTP return code.
+.Pp
+.It Em http digest mismatch
+The remote host did not return the expected content and the computed
+digest was different to the configured value.
+See
+.Xr relayd.conf 5
+for more information on validating the digest.
+.El
 .Sh SEE ALSO
 .Xr relayd 8
 .Sh HISTORY