1 .\"	$OpenBSD: relayd.8,v 1.25 2015/07/27 14:50:58 sobrado Exp $
2 .\"
3 .\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@openbsd.org>
4 .\"
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
8 .\"
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 .\"
17 .Dd $Mdocdate: July 27 2015 $
18 .Dt RELAYD 8
19 .Os
20 .Sh NAME
21 .Nm relayd
22 .Nd relay daemon
23 .Sh SYNOPSIS
24 .Nm
25 .Op Fl dnv
26 .Op Fl D Ar macro Ns = Ns Ar value
27 .Op Fl f Ar file
28 .Sh DESCRIPTION
29 .Nm
30 is a daemon to relay and dynamically redirect incoming connections to
31 a target host.
32 Its main purposes are to run as a load-balancer, application layer
33 gateway, or transparent proxy.
34 The daemon is able to monitor groups of hosts for availability, which
35 is determined by checking for a specific service common to a host
36 group.
37 When availability is confirmed,
38 layer 3 and/or layer 7 forwarding services are set up by
39 .Nm .
40 .Pp
41 Layer 3 redirection happens at the packet level; to configure
42 it,
43 .Nm
44 communicates with
45 .Xr pf 4 .
46 To allow
47 .Nm
48 to properly set up
49 .Xr pf 4
50 rules, the following line is required in the filter section of
51 .Xr pf.conf 5 :
52 .Bd -literal -offset indent
53 anchor "relayd/*"
54 .Ed
55 .Pp
56 Layer 7 relaying happens at the application level and is
57 handled by
58 .Nm
59 itself.
60 Various application level filtering and protocol-specific
61 load-balancing options are available for relays.
62 .Pp
63 .Nm
64 works in terms of the following
65 .Em entities :
66 relays, protocols, redirections, and tables.
67 A
68 .Em relay
69 represents a layer 7 load-balancing instance.
70 Each instance translates to a listening TCP or UDP port.
71 A
72 .Em protocol
73 defines which actions, if any, are taken on the
74 packet payload as data crosses a relay.
75 A
76 .Em redirection
77 represents a layer 3 load-balancing instance.
78 Each instance translates to a
79 .Xr pf 4
80 rdr-to rule being added.
81 A
82 .Em table
83 represents a group of hosts which can be checked for
84 availability using the same method.
85 Each table contains at least one host.
86 If a table is used in a layer 3 load-balancing instance, it
87 will be mapped to a
88 .Xr pf 4
89 table containing only those hosts which are up.
90 .Pp
91 All these entities can be configured in
92 .Xr relayd.conf 5 ,
93 and
94 .Xr relayctl 8
95 can be used to alter or report on the status of each entity.
96 .Pp
97 The options are as follows:
98 .Bl -tag -width Ds
99 .It Fl D Ar macro Ns = Ns Ar value
100 Define
101 .Ar macro
102 to be set to
103 .Ar value
104 on the command line.
105 Overrides the definition of
106 .Ar macro
107 in the configuration file.
108 .It Fl d
109 Do not daemonize.
110 If this option is specified,
111 .Nm
112 will run in the foreground and log to
113 .Em stderr .
114 .It Fl f Ar file
115 Specify an alternative configuration file.
116 The default is
117 .Pa /etc/relayd.conf .
118 .It Fl n
119 Configtest mode.
120 Only check the configuration file for validity.
121 .It Fl v
122 Produce more verbose output.
123 .El
124 .Sh FILES
125 .Bl -tag -width "/var/run/relayd.sockXX" -compact
126 .It Pa /etc/relayd.conf
127 Default configuration file.
128 .It Pa /var/run/relayd.sock
129 .Ux Ns -domain
130 socket used for communication with
131 .Xr relayctl 8 .
132 .El
133 .Sh SEE ALSO
134 .Xr relayd.conf 5 ,
135 .Xr relayctl 8
136 .Sh HISTORY
137 The
138 .Nm
139 program, formerly known as
140 .Ic hoststated ,
141 first appeared in
142 .Ox 4.1 .
143 It was renamed to
144 .Nm
145 in
146 .Ox 4.3 .
147 .Sh AUTHORS
148 .An -nosplit
149 The
150 .Nm
151 program was written by
152 .An Pierre-Yves Ritschard Aq Mt pyr@openbsd.org
153 and
154 .An Reyk Floeter Aq Mt reyk@openbsd.org .