mirror of
https://github.com/opnsense/docs
synced 2024-11-18 21:28:29 +00:00
77e1158c4a
Make sure people can find our relayd plugin in the documentation and describe a common yet easy example setup. cc @fbrendel
157 lines
5.6 KiB
ReStructuredText
157 lines
5.6 KiB
ReStructuredText
=============
|
|
Relayd
|
|
=============
|
|
|
|
The relayd plugin offers a load balancer which is capable of handling OSI layer 3 or 7 forwarding services to
|
|
various backend servers while validating their availability.
|
|
|
|
One of the main advantages over other forwarding services available for OPNsense is that relayd offers a transparant
|
|
forwarding mode in layer 3 (redirection), which is lightweight and forwards the unmodified session to the target host.
|
|
|
|
|
|
--------------------------------------
|
|
Types of configuration items
|
|
--------------------------------------
|
|
|
|
Relayd defines the following types of objects which build up to a virtual server definition.
|
|
|
|
.......................................
|
|
Hosts
|
|
.......................................
|
|
|
|
These types define the actual target machines being used in your pool, for basic
|
|
setups these only define an IP address and a unique name to identify the machine.
|
|
|
|
|
|
.......................................
|
|
Tables
|
|
.......................................
|
|
|
|
A table defines a list of hosts and acts as a grouping, a single host might be used in multiple tables.
|
|
|
|
|
|
.......................................
|
|
Table check
|
|
.......................................
|
|
|
|
A table check defines how relayd should determine for a group of hosts if the target is ready to use, this could
|
|
for example be a simple :code:`icmp` (ping) test or a more advanced check like requesting an uri from a webserver and
|
|
check the response code.
|
|
|
|
By default a list of common checks is installed with the plugin, you can add additional checks later if needed.
|
|
|
|
|
|
.......................................
|
|
Virtual Server
|
|
.......................................
|
|
|
|
A virtual server is where it all comes together, this type of object defines where to accept traffic from (bind address and port)
|
|
and how to handle traffic when being recieved.
|
|
|
|
The server type is one of the most important settings and defines if this virtual host is acting either as a redirection (using the firewall/transparant)
|
|
or a relay (layer 7 mode).
|
|
|
|
It is possible to choose two different tables to forward too here, in standard (non advanced mode) only the primary table is visible
|
|
including settings how traffic should be divided (:code:`Scheduler`) and hosts should be checked as described earlier.
|
|
|
|
When a backup is specified, it will be used when all hosts in the primary table are down (according to the configured check).
|
|
|
|
.. Tip::
|
|
|
|
If the hosts in the table respond to a different port than the one listening on, make sure to collapse the advanced settings
|
|
to gain access to the (target) port directive.
|
|
|
|
|
|
.......................................
|
|
Protocols
|
|
.......................................
|
|
|
|
Protocols are templates defining settings and rules for relays. They allow setting generic TCP options, SSL settings,
|
|
and rules for the selected application layer protocol.
|
|
|
|
These are only selectable in advanced view mode, for documentation we refer to the `relayd.conf <https://www.freebsd.org/cgi/man.cgi?query=relayd.conf&sektion=5&apropos=0&manpath=FreeBSD+12.2-RELEASE+and+Ports#PROTOCOLS>`__ man page.
|
|
|
|
--------------------------------------
|
|
General settings
|
|
--------------------------------------
|
|
|
|
The general settings tab is used to enable the service and configure global settings, such as how often hosts are being checked and the number
|
|
of resources relayd is allowed to use.
|
|
|
|
|
|
--------------------------------------
|
|
Status
|
|
--------------------------------------
|
|
|
|
Using the status page you can gain insights into the running configuration and perform maintenance tasks on various objects.
|
|
The easy to use presets on top of the page offer the ability to save filter selections locally in your browsers storage for later reuse.
|
|
|
|
|
|
--------------------------------------
|
|
Simple example
|
|
--------------------------------------
|
|
|
|
One of the easiest setups is a virtual server which monitors backend servers using icmp (ping) and forwards traffic to a group of mail servers listening on port 25 (smtp),
|
|
the graph below shows the connection from a client to one of the backend servers defined in a table.
|
|
|
|
|
|
.. blockdiag::
|
|
:scale: 100%
|
|
|
|
blockdiag {
|
|
default_fontsize = 9;
|
|
node_width = 200;
|
|
node_height = 80;
|
|
default_group_color = "#def7ff";
|
|
client [shape = box, label="client"];
|
|
server_1 [shape = box, label="backend server 1\n10.10.0.1"];
|
|
server_2 [shape = box, label="backend server 2\n10.10.0.2"];
|
|
|
|
frontend [shape = beginpoint, label="virtual server\n192.168.1.1:25"];
|
|
table [shape = beginpoint, label="table"];
|
|
backend_1 [shape = endpoint, label="host 1"];
|
|
backend_2 [shape = endpoint, label="host 2"];
|
|
|
|
client -> frontend -> table;
|
|
|
|
group {
|
|
orientation = portrait
|
|
backend_1;
|
|
backend_2;
|
|
server_1;
|
|
server_2;
|
|
table -> backend_1 [style = dashed];
|
|
table -> backend_2 [style = dashed];
|
|
backend_1 -> server_1;
|
|
backend_2 -> server_2;
|
|
}
|
|
|
|
}
|
|
|
|
|
|
In order to set up the example scenario, configure the following settings:
|
|
|
|
* Backend Hosts (add 2 new with the following properties)
|
|
|
|
* Enable: [x], Name: host_1, Address: 10.0.0.1
|
|
* Enable: [x], Name: host_2, Address: 10.0.0.2
|
|
|
|
* Table, add new with the following properties
|
|
|
|
* Name: table
|
|
* Hosts: host_1,host_2
|
|
* Enable: [x]
|
|
|
|
* Virtual Server, add with the following properties
|
|
|
|
* Name: ExampleServer
|
|
* Enable: [x]
|
|
* Server Type: Redirection
|
|
* Listen Address: 192.168.1.1
|
|
* Listen Port: 25
|
|
* Table: table
|
|
* Scheduler: Round Robin
|
|
* Table Check: ICMP
|
|
|
|
Make sure to enable relayd on the generic settings tab, save settings and the new vritual host should be active.
|