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