1.\" $OpenBSD: relayctl.8,v 1.27 2011/05/19 08:56:49 reyk Exp $ 2.\" 3.\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 19 2011 $ 18.Dt RELAYCTL 8 19.Os 20.Sh NAME 21.Nm relayctl 22.Nd control the relay daemon 23.Sh SYNOPSIS 24.Nm 25.Ar command 26.Op Ar argument ... 27.Sh DESCRIPTION 28The 29.Nm 30program controls the 31.Xr relayd 8 32daemon. 33.Pp 34The following commands are available: 35.Bl -tag -width Ds 36.It Cm host disable Op Ar name | id 37Disable a host. 38Treat it as though it were always down. 39.It Cm host enable Op Ar name | id 40Enable the host. 41Start checking its health again. 42.It Cm load Ar filename 43Reload the configuration from the specified file. 44.It Cm monitor 45Continuously report any changes in the host checking engine and the 46.Xr pf 4 47engine. 48.It Cm poll 49Schedule an immediate check of all hosts. 50.It Cm redirect disable Op Ar name | id 51Disable a redirection. 52If it has 53.Xr pf 4 54redirection rules installed, remove them. 55Mark the redirection's main table and \(en 56if applicable \(en disable the backup table as well. 57.It Cm redirect enable Op Ar name | id 58Enable a redirection. 59Mark the redirection's main table and \(en if applicable \(en enable 60the backup table as well. 61.It Cm reload 62Reload the configuration file. 63.It Cm show hosts 64Show detailed status of hosts and tables. 65It will also print the last error for failed host checks; 66see the 67.Sx ERRORS 68section below. 69.It Cm show redirects 70Show detailed status of redirections including the current and average 71access statistics. 72The statistics will be updated every minute. 73Redirections using the 74.Ic sticky-address 75option will count the number of sticky states, 76not the total number of redirected connections. 77.It Cm show relays 78Show detailed status of relays including the current and average 79access statistics. 80The statistics will be updated every minute. 81.It Cm show routers 82Show detailed status of routers including the configured network 83routes. 84.It Cm show sessions 85Dump the complete list of running relay sessions. 86.It Cm show summary 87Display a list of all relays, redirections, routers, tables, and hosts. 88.It Cm table disable Op Ar name | id 89Disable a table. 90Consider all hosts disabled. 91If it is a main table of a redirection which has a non-empty backup table, 92swap the contents of the 93.Xr pf 4 94table with those of the backup table. 95.It Cm table enable Op Ar name | id 96Enable a table. 97Start doing checks for all hosts that aren't individually disabled 98again. 99.El 100.Sh FILES 101.Bl -tag -width "/var/run/relayd.sockXX" -compact 102.It /var/run/relayd.sock 103.Ux Ns -domain 104socket used for communication with 105.Xr relayd 8 . 106.El 107.Sh ERRORS 108If a host is down and a previous check failed, 109.Nm 110will display the last error in the output of the 111.Cm show hosts 112command. 113This is especially useful for debugging server or configuration failures. 114The following errors will be reported: 115.Pp 116.Bl -tag -width Ds -compact 117.It Em none 118No specific error was reported by the check engine. 119.Pp 120.It Em aborted 121All checks were aborted by an external event, like a configuration reload. 122.Pp 123.It Em interval timeout 124The check did not finish in the configured time of an interval. 125This can happen if there are too many hosts that have to be checked by 126.Xr relayd 8 127and can be avoided by increasing the global 128.Ic interval 129option in 130.Xr relayd.conf 5 . 131.Pp 132.It Em icmp read timeout 133.It Em ssl read timeout 134.It Em tcp read timeout 135The check failed because the remote host did not send a reply within 136the configured timeout. 137.Pp 138.It Em icmp write timeout 139.It Em ssl write timeout 140.It Em tcp write timeout 141.It Em ssl connect timeout 142.It Em tcp connect timeout 143The check failed because 144.Xr relayd 8 145was not ready to send the request within the configured timeout. 146.Pp 147.It Em ssl connect error 148.It Em ssl read error 149.It Em ssl write error 150.It Em tcp connect error 151.It Em tcp read failed 152.It Em tcp write failed 153An I/O error occurred. 154This indicates that 155.Xr relayd 8 156was running low on resources, 157file descriptors, or was too busy to run the request. 158It can also indicate that an SSL/TCP protocol error occurred or that the 159connection was unexpectedly aborted. 160.Pp 161.It Em ssl connect failed 162.It Em tcp connect failed 163The check failed because the protocol handshake did not succeed in 164opening a stateful connection with the remote host. 165.Pp 166.It Em script failed 167The external script executed by the check did not return a valid return code. 168.Pp 169.It Em send/expect failed 170The payload data returned by the remote host did not match the 171expected pattern. 172.Pp 173.It Em http code malformed 174.It Em http digest malformed 175The remote host did not return a valid HTTP header or body. 176.Pp 177.It Em http code mismatch 178The remote host did not return a matching HTTP error code. 179This may indicate a real server problem (a server error, the page was 180not found, permission was denied) or a configuration error. 181For example, it is a very common mistake that 182.Xr relayd 8 183was configured to expect a 184HTTP 200 OK 185status but the host is returning a 186HTTP 302 Found 187redirection. 188See 189.Xr relayd.conf 5 190for more information on validating the HTTP return code. 191.Pp 192.It Em http digest mismatch 193The remote host did not return the expected content and the computed 194digest was different to the configured value. 195See 196.Xr relayd.conf 5 197for more information on validating the digest. 198.El 199.Sh SEE ALSO 200.Xr relayd 8 201.Sh HISTORY 202The 203.Nm 204program, formerly known as 205.Ic hoststatectl , 206first appeared in 207.Ox 4.1 . 208It was renamed to 209.Nm 210in 211.Ox 4.3 . 212