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