xref: /openbsd-src/usr.sbin/relayctl/relayctl.8 (revision ec4c1254e5936d5164923fa07b29c66d13a923b8)
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