1.\" $OpenBSD: relayctl.8,v 1.33 2017/11/29 15:24:50 benno 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: November 29 2017 $ 19.Dt RELAYCTL 8 20.Os 21.Sh NAME 22.Nm relayctl 23.Nd control the relay daemon 24.Sh SYNOPSIS 25.Nm 26.Op Fl s Ar socket 27.Ar command 28.Op Ar argument ... 29.Sh DESCRIPTION 30The 31.Nm 32program controls the 33.Xr relayd 8 34daemon. 35.Pp 36The following options are available: 37.Bl -tag -width Ds 38.It Fl s Ar socket 39Use 40.Ar socket 41instead of the default 42.Pa /var/run/relayd.sock 43to communicate with 44.Xr relayd 8 . 45.El 46.Pp 47The following commands are available: 48.Bl -tag -width Ds 49.It Cm host disable Op Ar name | id 50Disable a host. 51Treat it as though it were always down. 52.It Cm host enable Op Ar name | id 53Enable the host. 54Start checking its health again. 55.It Cm load Ar filename 56Reload the configuration from the specified file. 57.It Cm log brief 58Disable verbose debug logging. 59.It Cm log verbose 60Enable verbose debug logging. 61.It Cm monitor 62Continuously report any changes in the host checking engine and the 63.Xr pf 4 64engine. 65.It Cm poll 66Schedule an immediate check of all hosts. 67.It Cm redirect disable Op Ar name | id 68Disable a redirection. 69If it has 70.Xr pf 4 71redirection rules installed, remove them. 72Mark the redirection's main table and \(en 73if applicable \(en disable the backup table as well. 74.It Cm redirect enable Op Ar name | id 75Enable a redirection. 76Mark the redirection's main table and \(en if applicable \(en enable 77the backup table as well. 78.It Cm reload 79Reload the configuration file. 80.It Cm show hosts 81Show detailed status of hosts and tables. 82It will also print the last error for failed host checks; 83see the 84.Sx DIAGNOSTICS 85section below. 86.It Cm show redirects 87Show detailed status of redirections including the current and average 88access statistics. 89The statistics will be updated every minute. 90Redirections using the 91.Ic sticky-address 92option will count the number of sticky states, 93not the total number of redirected connections. 94.It Cm show relays 95Show detailed status of relays including the current and average 96access statistics. 97The statistics will be updated every minute. 98.It Cm show routers 99Show detailed status of routers including the configured network 100routes. 101.It Cm show sessions 102Dump the complete list of running relay sessions. 103.It Cm show summary 104Display a list of all relays, redirections, routers, tables, and hosts. 105.It Cm table disable Op Ar name | id 106Disable a table. 107Consider all hosts disabled. 108If it is a main table of a redirection which has a non-empty backup table, 109swap the contents of the 110.Xr pf 4 111table with those of the backup table. 112.It Cm table enable Op Ar name | id 113Enable a table. 114Start doing checks for all hosts that aren't individually disabled 115again. 116.El 117.Sh FILES 118.Bl -tag -width "/var/run/relayd.sockXX" -compact 119.It Pa /var/run/relayd.sock 120.Ux Ns -domain 121socket used for communication with 122.Xr relayd 8 . 123.El 124.Sh DIAGNOSTICS 125If a host is down and a previous check failed, 126.Nm 127will display the last error in the output of the 128.Cm show hosts 129command. 130This is especially useful for debugging server or configuration failures. 131The following errors will be reported: 132.Pp 133.Bl -tag -width Ds -compact 134.It Em none 135No specific error was reported by the check engine. 136.Pp 137.It Em aborted 138All checks were aborted by an external event, like a configuration reload. 139.Pp 140.It Em interval timeout 141The check did not finish in the configured time of an interval. 142This can happen if there are too many hosts that have to be checked by 143.Xr relayd 8 144and can be avoided by increasing the global 145.Ic interval 146option in 147.Xr relayd.conf 5 . 148.Pp 149.It Em icmp read timeout 150.It Em tls read timeout 151.It Em tcp read timeout 152The check failed because the remote host did not send a reply within 153the configured timeout. 154.Pp 155.It Em icmp write timeout 156.It Em tls write timeout 157.It Em tcp write timeout 158.It Em tls connect timeout 159.It Em tcp connect timeout 160The check failed because 161.Xr relayd 8 162was not ready to send the request within the configured timeout. 163.Pp 164.It Em tls connect error 165.It Em tls read error 166.It Em tls write error 167.It Em tcp connect error 168.It Em tcp read failed 169.It Em tcp write failed 170An I/O error occurred. 171This indicates that 172.Xr relayd 8 173was running low on resources, 174file descriptors, or was too busy to run the request. 175It can also indicate that a TLS or TCP protocol error occurred or 176that the connection was unexpectedly aborted. 177.Pp 178.It Em tls connect failed 179.It Em tcp connect failed 180The check failed because the protocol handshake did not succeed in 181opening a stateful connection with the remote host. 182.Pp 183.It Em script failed 184The external script executed by the check did not return a valid return code. 185.Pp 186.It Em send/expect failed 187The payload data returned by the remote host did not match the 188expected pattern. 189.Pp 190.It Em http code malformed 191.It Em http digest malformed 192The remote host did not return a valid HTTP header or body. 193.Pp 194.It Em http code mismatch 195The remote host did not return a matching HTTP error code. 196This may indicate a real server problem (a server error, the page was 197not found, permission was denied) or a configuration error. 198For example, it is a very common mistake that 199.Xr relayd 8 200was configured to expect a 201HTTP 200 OK 202status but the host is returning a 203HTTP 302 Found 204redirection. 205See 206.Xr relayd.conf 5 207for more information on validating the HTTP return code. 208.Pp 209.It Em http digest mismatch 210The remote host did not return the expected content and the computed 211digest was different to the configured value. 212See 213.Xr relayd.conf 5 214for more information on validating the digest. 215.El 216.Sh SEE ALSO 217.Xr relayd 8 218.Sh HISTORY 219The 220.Nm 221program, formerly known as 222.Ic hoststatectl , 223first appeared in 224.Ox 4.1 . 225It was renamed to 226.Nm 227in 228.Ox 4.3 . 229