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