From 8a788bf32dc6277da0d415e7957ee0d7b6fbad39 Mon Sep 17 00:00:00 2001 From: Viacheslav Hletenko Date: Wed, 24 May 2023 19:08:22 +0300 Subject: Add load-balancing reverse-proxy documentation and examples --- docs/configuration/loadbalancing/reverse-proxy.rst | 289 +++++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 docs/configuration/loadbalancing/reverse-proxy.rst (limited to 'docs/configuration/loadbalancing/reverse-proxy.rst') diff --git a/docs/configuration/loadbalancing/reverse-proxy.rst b/docs/configuration/loadbalancing/reverse-proxy.rst new file mode 100644 index 00000000..24f26af0 --- /dev/null +++ b/docs/configuration/loadbalancing/reverse-proxy.rst @@ -0,0 +1,289 @@ + +.. _load-balancing: + +############# +Reverse-proxy +############# +.. include:: /_include/need_improvement.txt + +VyOS reverse-proxy is balancer and proxy server that provides +high-availability, load balancing and proxying for TCP (level 4) +and HTTP-based (level 7) applications. + +Configuration +============= + + +Service configuration is responsible for binding to a specific port, +while the backend configuration determines the type of load balancing +to be applied and specifies the real servers to be utilized. + +Service +------- + +.. cfgcmd:: set load-balancing reverse-proxy service listen-address +
+ + Set service to bind on IP address, by default listen on any IPv4 and IPv6 + +.. cfgcmd:: set load-balancing reverse-proxy service port + + + Create service `` to listen on + +.. cfgcmd:: set load-balancing reverse-proxy service mode + + + Configure service `` mode TCP or HTTP + +.. cfgcmd:: set load-balancing reverse-proxy service backend + + + Configure service `` to use the backend + +.. cfgcmd:: set load-balancing reverse-proxy service ssl + certificate + + Set SSL certeficate for service + + +Rules +^^^^^ +Rules allow to control and route incoming traffic to specific backend based +on predefined conditions. Rules allow to define matching criteria and +perform action accordingly. + +.. cfgcmd:: set load-balancing reverse-proxy service rule + domain-name + + Match domain name + +.. cfgcmd:: set load-balancing reverse-proxy service rule + ssl + + SSL match Server Name Indication (SNI) option: + * ``req-ssl-sni`` SSL Server Name Indication (SNI) request match + * ``ssl-fc-sni`` SSL frontend connection Server Name Indication match + * ``ssl-fc-sni-end`` SSL frontend match end of connection Server Name + Indication + +.. cfgcmd:: set load-balancing reverse-proxy service rule + url-path + + Allows to define URL path matching rules for a specific service. + + With this command, you can specify how the URL path should be matched + against incoming requests. + + The available options for are: + * ``begin`` Matches the beginning of the URL path + * ``end`` Matches the end of the URL path. + * ``exact`` Requires an exactly match of the URL path + +.. cfgcmd:: set load-balancing reverse-proxy service rule + set backend + + Assign a specific backend to a rule + +.. cfgcmd:: set load-balancing reverse-proxy service rule + redirect-location + + Redirect URL to a new location + + +Backend +------- + +.. cfgcmd:: set load-balancing reverse-proxy backend balance + + + Load-balancing algorithms to be used for distributind requests among the + vailable servers + + Balance algorithms: + * ``source-address`` Distributes requests based on the source IP address + of the client + * ``round-robin`` Distributes requests in a circular manner, + sequentially sending each request to the next server in line + * ``least-connection`` Distributes requests tp tje server wotj the fewest + active connections + +.. cfgcmd:: set load-balancing reverse-proxy backend mode + + + Configure backend `` mode TCP or HTTP + +.. cfgcmd:: set load-balancing reverse-proxy backend parameters + http-check + + Enable layer 7 HTTP health check + +.. cfgcmd:: set load-balancing reverse-proxy backend server + address + + Set the address of the backend server to which the incoming traffic will + be forwarded + +.. cfgcmd:: set load-balancing reverse-proxy backend server + port + + Set the address of the backend port + +.. cfgcmd:: set load-balancing reverse-proxy backend server + check + + Active health check backend server + +.. cfgcmd:: set load-balancing reverse-proxy backend server + send-proxy + + Send a Proxy Protocol version 1 header (text format) + +.. cfgcmd:: set load-balancing reverse-proxy backend server + send-proxy-v2 + + Send a Proxy Protocol version 2 header (binary format) + + + +Gloabal +------- + +Global parameters + +.. cfgcmd:: set load-balancing reverse-proxy global-parameters max-connections + + + Limit maximum number of connections + +.. cfgcmd:: set load-balancing reverse-proxy global-parameters ssl-bind-ciphers + + + Limit allowed cipher algorithms used during SSL/TLS handshake + +.. cfgcmd:: set load-balancing reverse-proxy global-parameters tls-version-min + + + Specify the minimum required TLS version 1.2 or 1.3 + + +Redirect HTTP to HTTPS +====================== +Configure the load-balancing reverse-proxy service for HTTP. + +This configuration listen on port 80 and redirect incoming +requests to HTTPS: + +.. code-block:: none + + set load-balancing reverse-proxy service http port '80' + set load-balancing reverse-proxy service http redirect-http-to-https + +The name of the service can be different, in this example it is only for +convenience. + + +Examples +======== + +Level 4 balancing +----------------- + +This configuration enables the TCP reverse proxy for the "my-tcp-api" service. +Incoming TCP connections on port 8888 will be load balanced across the backend +servers (srv01 and srv02) using the round-robin load-balancing algorithm. + +.. code-block:: none + + set load-balancing reverse-proxy service my-tcp-api backend 'bk-01' + set load-balancing reverse-proxy service my-tcp-api mode 'tcp' + set load-balancing reverse-proxy service my-tcp-api port '8888' + + set load-balancing reverse-proxy backend bk-01 balance 'round-robin' + set load-balancing reverse-proxy backend bk-01 mode 'tcp' + + set load-balancing reverse-proxy backend bk-01 server srv01 address '192.0.2.11' + set load-balancing reverse-proxy backend bk-01 server srv01 port '8881' + set load-balancing reverse-proxy backend bk-01 server srv02 address '192.0.2.12' + set load-balancing reverse-proxy backend bk-01 server srv02 port '8882' + +Balancing based on domain name +------------------------------ +The following configuration demonstrates how to use VyOS +to achieve load balancing based on the domain name. + +The HTTP service listen on TCP port 80. + +Rule 10 matches requests with the domain name ``node1.example.com`` forwards +to the backend ``bk-api-01`` + +Rule 20 matches requests with the domain name ``node2.example.com`` forwards +to the backend ``bk-api-02`` + +.. code-block:: none + + set load-balancing reverse-proxy service http description 'bind app listen on 443 port' + set load-balancing reverse-proxy service http mode 'tcp' + set load-balancing reverse-proxy service http port '80' + + set load-balancing reverse-proxy service http rule 10 domain-name 'node1.example.com' + set load-balancing reverse-proxy service http rule 10 set backend 'bk-api-01' + set load-balancing reverse-proxy service http rule 20 domain-name 'node2.example.com' + set load-balancing reverse-proxy service http rule 20 set backend 'bk-api-02' + + set load-balancing reverse-proxy backend bk-api-01 description 'My API-1' + set load-balancing reverse-proxy backend bk-api-01 mode 'tcp' + set load-balancing reverse-proxy backend bk-api-01 server api01 address '127.0.0.1' + set load-balancing reverse-proxy backend bk-api-01 server api01 port '4431' + set load-balancing reverse-proxy backend bk-api-02 description 'My API-2' + set load-balancing reverse-proxy backend bk-api-02 mode 'tcp' + set load-balancing reverse-proxy backend bk-api-02 server api01 address '127.0.0.2' + set load-balancing reverse-proxy backend bk-api-02 server api01 port '4432' + + +Terminate SSL +------------- +The following configuration reverse-proxy terminate SSL. + +The ``http`` service is lestens on port 80 and force redirects from HTTP to +HTTPS. + +The ``https`` service listens on port 443 with backend `bk-default` to +handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination. + +Rule 10 matches requests with the exact URL path ``/.well-known/xxx`` +and redirects to location ``/certs/``. + +Rule 20 matches requests with URL paths ending in ``/mail`` or exact +path ``/email/bar`` redirect to location ``/postfix/``. + +Additional global parameters are set, including the maximum number +connection limit of 4000 and a minimum TLS version of 1.3. + + +.. code-block:: none + + set load-balancing reverse-proxy service http description 'Force redirect to HTTPS' + set load-balancing reverse-proxy service http port '80' + set load-balancing reverse-proxy service http redirect-http-to-https + + set load-balancing reverse-proxy service https backend 'bk-default' + set load-balancing reverse-proxy service https description 'listen on 443 port' + set load-balancing reverse-proxy service https mode 'http' + set load-balancing reverse-proxy service https port '443' + set load-balancing reverse-proxy service https ssl certificate 'cert' + + set load-balancing reverse-proxy service https rule 10 url-path exact '/.well-known/xxx' + set load-balancing reverse-proxy service https rule 10 set redirect-location '/certs/' + set load-balancing reverse-proxy service https rule 20 url-path end '/mail' + set load-balancing reverse-proxy service https rule 20 url-path exact '/email/bar' + set load-balancing reverse-proxy service https rule 20 set redirect-location '/postfix/' + + set load-balancing reverse-proxy backend bk-default description 'Default backend' + set load-balancing reverse-proxy backend bk-default mode 'http' + set load-balancing reverse-proxy backend bk-default server sr01 address '192.0.2.23' + set load-balancing reverse-proxy backend bk-default server sr01 port '80' + + set load-balancing reverse-proxy global-parameters max-connections '4000' + set load-balancing reverse-proxy global-parameters tls-version-min '1.3' + -- cgit v1.2.3