1*ec4c1254Sbenno.\" $OpenBSD: relayctl.8,v 1.33 2017/11/29 15:24:50 benno Exp $ 2feb9ff76Sreyk.\" 3583626ebSreyk.\" Copyright (c) 2007 - 2013 Reyk Floeter <reyk@openbsd.org> 436f5dc5eSpyr.\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@openbsd.org> 5feb9ff76Sreyk.\" 6feb9ff76Sreyk.\" Permission to use, copy, modify, and distribute this software for any 7feb9ff76Sreyk.\" purpose with or without fee is hereby granted, provided that the above 8feb9ff76Sreyk.\" copyright notice and this permission notice appear in all copies. 9feb9ff76Sreyk.\" 10feb9ff76Sreyk.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11feb9ff76Sreyk.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12feb9ff76Sreyk.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13feb9ff76Sreyk.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14feb9ff76Sreyk.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15feb9ff76Sreyk.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16feb9ff76Sreyk.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17feb9ff76Sreyk.\" 18*ec4c1254Sbenno.Dd $Mdocdate: November 29 2017 $ 19748ceb64Sreyk.Dt RELAYCTL 8 20feb9ff76Sreyk.Os 21feb9ff76Sreyk.Sh NAME 22748ceb64Sreyk.Nm relayctl 232641a232Sjmc.Nd control the relay daemon 24feb9ff76Sreyk.Sh SYNOPSIS 25feb9ff76Sreyk.Nm 26*ec4c1254Sbenno.Op Fl s Ar socket 27feb9ff76Sreyk.Ar command 28d3c92c41Ssobrado.Op Ar argument ... 29feb9ff76Sreyk.Sh DESCRIPTION 30feb9ff76SreykThe 31feb9ff76Sreyk.Nm 32feb9ff76Sreykprogram controls the 33748ceb64Sreyk.Xr relayd 8 34feb9ff76Sreykdaemon. 35feb9ff76Sreyk.Pp 36*ec4c1254SbennoThe following options are available: 37*ec4c1254Sbenno.Bl -tag -width Ds 38*ec4c1254Sbenno.It Fl s Ar socket 39*ec4c1254SbennoUse 40*ec4c1254Sbenno.Ar socket 41*ec4c1254Sbennoinstead of the default 42*ec4c1254Sbenno.Pa /var/run/relayd.sock 43*ec4c1254Sbennoto communicate with 44*ec4c1254Sbenno.Xr relayd 8 . 45*ec4c1254Sbenno.El 46*ec4c1254Sbenno.Pp 47feb9ff76SreykThe following commands are available: 48feb9ff76Sreyk.Bl -tag -width Ds 493e84652aSjmc.It Cm host disable Op Ar name | id 503e84652aSjmcDisable a host. 513e84652aSjmcTreat it as though it were always down. 523e84652aSjmc.It Cm host enable Op Ar name | id 533e84652aSjmcEnable the host. 543e84652aSjmcStart checking its health again. 55a2195becSreyk.It Cm load Ar filename 56a2195becSreykReload the configuration from the specified file. 570b94c862Sgsoares.It Cm log brief 580b94c862SgsoaresDisable verbose debug logging. 590b94c862Sgsoares.It Cm log verbose 600b94c862SgsoaresEnable verbose debug logging. 611569a65fSpyr.It Cm monitor 621569a65fSpyrContinuously report any changes in the host checking engine and the 632641a232Sjmc.Xr pf 4 642641a232Sjmcengine. 655a785264Spyr.It Cm poll 665a785264SpyrSchedule an immediate check of all hosts. 67c84cf264Sreyk.It Cm redirect disable Op Ar name | id 68c84cf264SreykDisable a redirection. 69df44d681SreykIf it has 70feb9ff76Sreyk.Xr pf 4 71df44d681Sreykredirection rules installed, remove them. 72c84cf264SreykMark the redirection's main table and \(en 732641a232Sjmcif applicable \(en disable the backup table as well. 74c84cf264Sreyk.It Cm redirect enable Op Ar name | id 75c84cf264SreykEnable a redirection. 762641a232SjmcMark the redirection's main table and \(en if applicable \(en enable 772641a232Sjmcthe backup table as well. 782641a232Sjmc.It Cm reload 792641a232SjmcReload the configuration file. 802edd718bSreyk.It Cm show hosts 81dec6607bSreykShow detailed status of hosts and tables. 82c0dc99f6SreykIt will also print the last error for failed host checks; 83c0dc99f6Sreyksee the 8424a9a99eSschwarze.Sx DIAGNOSTICS 85c0dc99f6Sreyksection below. 86dec6607bSreyk.It Cm show redirects 87dec6607bSreykShow detailed status of redirections including the current and average 88dec6607bSreykaccess statistics. 89dec6607bSreykThe statistics will be updated every minute. 90cdee8da5SreykRedirections using the 91cdee8da5Sreyk.Ic sticky-address 92cdee8da5Sreykoption will count the number of sticky states, 93cdee8da5Sreyknot the total number of redirected connections. 942edd718bSreyk.It Cm show relays 952edd718bSreykShow detailed status of relays including the current and average 962edd718bSreykaccess statistics. 972edd718bSreykThe statistics will be updated every minute. 98417c432fSreyk.It Cm show routers 99417c432fSreykShow detailed status of routers including the configured network 100417c432fSreykroutes. 101fa0d8478Sreyk.It Cm show sessions 102fa0d8478SreykDump the complete list of running relay sessions. 1032edd718bSreyk.It Cm show summary 104417c432fSreykDisplay a list of all relays, redirections, routers, tables, and hosts. 105ef1f2334Sreyk.It Cm table disable Op Ar name | id 106df44d681SreykDisable a table. 107df44d681SreykConsider all hosts disabled. 108c84cf264SreykIf it is a main table of a redirection which has a non-empty backup table, 109feb9ff76Sreykswap the contents of the 110feb9ff76Sreyk.Xr pf 4 111feb9ff76Sreyktable with those of the backup table. 112ef1f2334Sreyk.It Cm table enable Op Ar name | id 113df44d681SreykEnable a table. 114df44d681SreykStart doing checks for all hosts that aren't individually disabled 115df44d681Sreykagain. 116feb9ff76Sreyk.El 117feb9ff76Sreyk.Sh FILES 118748ceb64Sreyk.Bl -tag -width "/var/run/relayd.sockXX" -compact 11924a9a99eSschwarze.It Pa /var/run/relayd.sock 120f829369eSsobrado.Ux Ns -domain 121f829369eSsobradosocket used for communication with 122748ceb64Sreyk.Xr relayd 8 . 123feb9ff76Sreyk.El 12424a9a99eSschwarze.Sh DIAGNOSTICS 125c0dc99f6SreykIf a host is down and a previous check failed, 126c0dc99f6Sreyk.Nm 127c0dc99f6Sreykwill display the last error in the output of the 128c0dc99f6Sreyk.Cm show hosts 129c0dc99f6Sreykcommand. 130c0dc99f6SreykThis is especially useful for debugging server or configuration failures. 131c0dc99f6SreykThe following errors will be reported: 132c0dc99f6Sreyk.Pp 133c0dc99f6Sreyk.Bl -tag -width Ds -compact 134c0dc99f6Sreyk.It Em none 135c0dc99f6SreykNo specific error was reported by the check engine. 136c0dc99f6Sreyk.Pp 137c0dc99f6Sreyk.It Em aborted 138c0dc99f6SreykAll checks were aborted by an external event, like a configuration reload. 139c0dc99f6Sreyk.Pp 140c0dc99f6Sreyk.It Em interval timeout 141c0dc99f6SreykThe check did not finish in the configured time of an interval. 142c0dc99f6SreykThis can happen if there are too many hosts that have to be checked by 143c0dc99f6Sreyk.Xr relayd 8 144c0dc99f6Sreykand can be avoided by increasing the global 145c0dc99f6Sreyk.Ic interval 146c0dc99f6Sreykoption in 147c0dc99f6Sreyk.Xr relayd.conf 5 . 148c0dc99f6Sreyk.Pp 149c0dc99f6Sreyk.It Em icmp read timeout 1507bb52228Sreyk.It Em tls read timeout 151c0dc99f6Sreyk.It Em tcp read timeout 152c0dc99f6SreykThe check failed because the remote host did not send a reply within 153c0dc99f6Sreykthe configured timeout. 154c0dc99f6Sreyk.Pp 155c0dc99f6Sreyk.It Em icmp write timeout 1567bb52228Sreyk.It Em tls write timeout 157c0dc99f6Sreyk.It Em tcp write timeout 1587bb52228Sreyk.It Em tls connect timeout 159c0dc99f6Sreyk.It Em tcp connect timeout 160c0dc99f6SreykThe check failed because 161c0dc99f6Sreyk.Xr relayd 8 162c0dc99f6Sreykwas not ready to send the request within the configured timeout. 163c0dc99f6Sreyk.Pp 1647bb52228Sreyk.It Em tls connect error 1657bb52228Sreyk.It Em tls read error 1667bb52228Sreyk.It Em tls write error 167c0dc99f6Sreyk.It Em tcp connect error 168c0dc99f6Sreyk.It Em tcp read failed 169c0dc99f6Sreyk.It Em tcp write failed 170c0dc99f6SreykAn I/O error occurred. 171c0dc99f6SreykThis indicates that 172c0dc99f6Sreyk.Xr relayd 8 173c0dc99f6Sreykwas running low on resources, 174c0dc99f6Sreykfile descriptors, or was too busy to run the request. 175391829d7SjmcIt can also indicate that a TLS or TCP protocol error occurred or 1767bb52228Sreykthat the connection was unexpectedly aborted. 177c0dc99f6Sreyk.Pp 1787bb52228Sreyk.It Em tls connect failed 179c0dc99f6Sreyk.It Em tcp connect failed 180c0dc99f6SreykThe check failed because the protocol handshake did not succeed in 181c0dc99f6Sreykopening a stateful connection with the remote host. 182c0dc99f6Sreyk.Pp 183c0dc99f6Sreyk.It Em script failed 184c0dc99f6SreykThe external script executed by the check did not return a valid return code. 185c0dc99f6Sreyk.Pp 186c0dc99f6Sreyk.It Em send/expect failed 187c0dc99f6SreykThe payload data returned by the remote host did not match the 188c0dc99f6Sreykexpected pattern. 189c0dc99f6Sreyk.Pp 190c0dc99f6Sreyk.It Em http code malformed 191c0dc99f6Sreyk.It Em http digest malformed 192c0dc99f6SreykThe remote host did not return a valid HTTP header or body. 193c0dc99f6Sreyk.Pp 194c0dc99f6Sreyk.It Em http code mismatch 195c0dc99f6SreykThe remote host did not return a matching HTTP error code. 196c0dc99f6SreykThis may indicate a real server problem (a server error, the page was 197c0dc99f6Sreyknot found, permission was denied) or a configuration error. 198c0dc99f6SreykFor example, it is a very common mistake that 199c0dc99f6Sreyk.Xr relayd 8 200c0dc99f6Sreykwas configured to expect a 201c0dc99f6SreykHTTP 200 OK 202c0dc99f6Sreykstatus but the host is returning a 203c0dc99f6SreykHTTP 302 Found 204c0dc99f6Sreykredirection. 205c0dc99f6SreykSee 206c0dc99f6Sreyk.Xr relayd.conf 5 207c0dc99f6Sreykfor more information on validating the HTTP return code. 208c0dc99f6Sreyk.Pp 209c0dc99f6Sreyk.It Em http digest mismatch 210c0dc99f6SreykThe remote host did not return the expected content and the computed 211c0dc99f6Sreykdigest was different to the configured value. 212c0dc99f6SreykSee 213c0dc99f6Sreyk.Xr relayd.conf 5 214c0dc99f6Sreykfor more information on validating the digest. 215c0dc99f6Sreyk.El 216feb9ff76Sreyk.Sh SEE ALSO 217748ceb64Sreyk.Xr relayd 8 2182edd718bSreyk.Sh HISTORY 2192edd718bSreykThe 2202edd718bSreyk.Nm 221af50a7a9Sreykprogram, formerly known as 222af50a7a9Sreyk.Ic hoststatectl , 223af50a7a9Sreykfirst appeared in 2242edd718bSreyk.Ox 4.1 . 225af50a7a9SreykIt was renamed to 226af50a7a9Sreyk.Nm 227af50a7a9Sreykin 228af50a7a9Sreyk.Ox 4.3 . 229