diff options
| -rw-r--r-- | docs/configuration/loadbalancing/reverse-proxy.rst | 47 | ||||
| -rw-r--r-- | docs/configuration/service/dns.rst | 98 | ||||
| -rw-r--r-- | docs/contributing/issues-features.rst | 103 |
3 files changed, 215 insertions, 33 deletions
diff --git a/docs/configuration/loadbalancing/reverse-proxy.rst b/docs/configuration/loadbalancing/reverse-proxy.rst index 19ef3773..77d6d67b 100644 --- a/docs/configuration/loadbalancing/reverse-proxy.rst +++ b/docs/configuration/loadbalancing/reverse-proxy.rst @@ -43,7 +43,7 @@ Service .. cfgcmd:: set load-balancing reverse-proxy service <name> ssl certificate <name> - Set SSL certeficate <name> for service <name> + Set SSL certificate <name> for service <name> Rules @@ -97,8 +97,8 @@ Backend .. cfgcmd:: set load-balancing reverse-proxy backend <name> balance <balance> - Load-balancing algorithms to be used for distributind requests among the - vailable servers + Load-balancing algorithms to be used for distributed requests among the + available servers Balance algorithms: * ``source-address`` Distributes requests based on the source IP address @@ -144,9 +144,12 @@ Backend Send a Proxy Protocol version 2 header (binary format) +.. cfgcmd:: set load-balancing reverse-proxy backend <name> ssl ca-certificate <ca-certificate> + Configure requests to the backend server to use SSL encryption and + authenticate backend against <ca-certificate> -Gloabal +Global ------- Global parameters @@ -243,12 +246,12 @@ to the backend ``bk-api-02`` Terminate SSL ------------- -The following configuration reverse-proxy terminate SSL. +The following configuration terminates SSL on the router. -The ``http`` service is lestens on port 80 and force redirects from HTTP to +The ``http`` service is listens on port 80 and force redirects from HTTP to HTTPS. -The ``https`` service listens on port 443 with backend `bk-default` to +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`` @@ -287,3 +290,33 @@ connection limit of 4000 and a minimum TLS version of 1.3. set load-balancing reverse-proxy global-parameters max-connections '4000' set load-balancing reverse-proxy global-parameters tls-version-min '1.3' +SSL Bridging +------------- +The following configuration terminates incoming HTTPS traffic on the router, then re-encrypts the traffic and sends +to the backend server via HTTPS. This is useful if encryption is required for both legs, but you do not want to +install publicly trusted certificates on each backend server. + +Backend service certificates are checked against the certificate authority specified in the configuration, which +could be an internal CA. + +The ``https`` service listens on port 443 with backend ``bk-bridge-ssl`` to +handle HTTPS traffic. It uses certificate named ``cert`` for SSL termination. + +The ``bk-bridge-ssl`` backend connects to sr01 server on port 443 via HTTPS and checks backend +server has a valid certificate trusted by CA ``cacert`` + + +.. code-block:: none + + set load-balancing reverse-proxy service https backend 'bk-bridge-ssl' + 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 backend bk-bridge-ssl description 'SSL backend' + set load-balancing reverse-proxy backend bk-bridge-ssl mode 'http' + set load-balancing reverse-proxy backend bk-bridge-ssl ssl ca-certificate 'cacert' + set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 address '192.0.2.23' + set load-balancing reverse-proxy backend bk-bridge-ssl server sr01 port '443' + diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst index c6deb179..365e7885 100644 --- a/docs/configuration/service/dns.rst +++ b/docs/configuration/service/dns.rst @@ -143,6 +143,100 @@ avoid being tracked by the provider of your upstream DNS server. 168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream DNS server(s) to be used for reverse lookups of these zones. +Authoritative zones +------------------- + +The VyOS DNS forwarder can also be configured to host authoritative records for a domain. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> disable + + Disable hosting authoritative zone for `<domain-name>` without deleting from + configuration. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records <type> + <name> disable + + Disable specific record without deleting it from configuration. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records <type> + <name> ttl <seconds> + + Set the :abbr:`TTL (Time-to-live)` for the record in seconds. Default is 300 seconds. + +Record types +^^^^^^^^^^^^ + +Below are a list of record types available to be configured within VyOS. Some records +support special `<name>` keywords: + +* ``@`` Use @ as record name to set the record for the root domain. + +* ``any`` Use any as record name to configure the record as a wildcard. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + a <name> address <x.x.x.x> + + Set an :abbr:`A (Address)` record. Supports ``@`` and ``any`` keywords. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + aaaa <name> address <h:h:h:h:h:h:h:h> + + Set an :abbr:`AAAA (IPv6 Address)` record. Supports ``@`` and ``any`` keywords. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + cname <name> target <target-domain-name> + + Set an :abbr:`CNAME (Canonical name)` record. Supports ``@`` keyword. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + naptr <name> rule <rule-number> <option> <value> + + Set an :abbr:`NAPTR (Naming authority pointer)` record. Supports ``@`` keyword. + NAPTR records support the following options: + + * **lookup-a** A Flag. + + * **lookup-srv** S flag. + + * **order** Rule order. Requires `<value>`. + + * **preference** Rule preference. Requires `<value>`. Defaults to 0 if not set. + + * **protocol-specific** P flag. + + * **regexp** Regular expression. Requires `<value>`. + + * **replacement** Replacement DNS name. + + * **resolve-uri** U flag. + + * **service** Service type. Requires `<value>`. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + ns <name> target <target-name> + + Set an :abbr:`NS (Nameserver)` record. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + ptr <name> target <target-name> + + Set an :abbr:`PTR (Pointer record)` record. Supports ``@`` keyword. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + spf <name> value <value> + + Set an :abbr:`SPF (Sender policy framework)` record. Supports ``@`` keyword. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + srv <name> entry <entry-number> [hostname | port | priority | weight] <value> + + Set an :abbr:`SRV (Service)` record. Supports ``@`` keyword. + +.. cfgcmd:: set service dns forwarding authoritative-domain <domain-name> records + txt <name> value <value> + + Set an :abbr:`TXT (Text)` record. Supports ``@`` keyword. + Example ======= @@ -208,7 +302,7 @@ one involves a third party service, like DynDNS.com or any other such service provider. This method uses HTTP requests to transmit the new IP address. You can configure both in VyOS. -.. _dns:dynmaic_config: +.. _dns:dynamic_config: Configuration ============= @@ -254,7 +348,7 @@ Configuration Specify interval in seconds to wait between Dynamic DNS updates. The default is 300 seconds. -.. _dns:dynmaic_example: +.. _dns:dynamic_example: Example ^^^^^^^ diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 9b6602f9..e57766fc 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -28,27 +28,31 @@ issue prior to opening a bug request. Ensure the problem is reproducible ---------------------------------- -When you are able to verify that it is actually a bug, spend some time to -document how to reproduce the issue. This documentation can be invaluable. - -When you wish to have a developer fix a bug that you found, helping them -reproduce the issue is beneficial to everyone. Be sure to include information -about the hardware you are using, commands that you were running, any other -activities that you may have been doing at the time. This additional -information can be very useful. - -* What were you attempting to achieve? -* What was the configuration prior to the change? -* What commands did you use? Use e.g. ``run show configuration commands`` - -Include output --------------- - -The output you get when you find a bug can provide lots of information. If you -get an error message on the screen, copy it exactly. Having the exact message -can provide detail that the developers can use. Like wise if you have any log -messages that also are from the time of the issue, include those. They may -also contain information that is helpful for the development team. +You should include the following information: + +* A sequence of configuration commands or a complete configuration file + required to recreate a setup where the bug occurs. + Please avoid partial configs: a sequence of commands is easy to paste into the console, + a complete config is easy to load in a VM, but a partial config is neither! + At least not until we implement a "merge from the CLI" + feature that allows pasting config file chunks into a session. +* The behavior you expect and how it's different from the behavior you observe. + Don't just include command outputs or traffic dumps — + try to explain at least briefly why they are wrong and what they should be. +* A sequence of actions that triggers the bug. + We understand that it's not always possible, but it makes developer's job a lot easier + and also allows any community member to independently confirm + that the bug still exists or if it's already fixed. +* If it's a regression, tell us a VyOS version where the feature still worked correctly. + It's perfect if you can tell exactly which version broke it, + but we understand that it's not always easy or feasible — any working version is acceptable. + +If you aren't certain what the correct behavior is and if what you see is really a bug, +or if you don't have a reproducing procedure that reliably triggers it, +please create a post on the forum or ask in the chat first — +or, if you have a subscription, create a support ticket. +Our team and community members can help you identify the bug and work around it, +then create an actionable and testable bug report. Report a Bug ------------ @@ -64,15 +68,66 @@ request. .. _feature_request: -Feature Request -=============== +Feature Requests +================ You have an idea of how to make VyOS better or you are in need of a specific feature which all users of VyOS would benefit from? To send a feature request -please search Phabricator_ if there is already a request pending. You can +please search Phabricator_ to check if there is already a request pending. You can enhance it or if you don't find one, create a new one by use the quick link in the left side under the specific project. +You must create a task before you start working on a feature. +Yes, even if it's a tiny feature — we use the task tracker to generate release notes, +so it's essential that everything is reflected there. + +You must include at least the following: + +* A reasonably detailed description of the feature: what it is, how it's supposed to work, + and how you'd use it. + The maintainers aren't familiar with every feature of every protocol and tool, + and community contributors who are looking for tasks to work on will also + appreciate more information that helps them implement and test a feature. +* Proposed CLI syntax, if the feature requires new commands. + Please include both configuration and operational mode commands, if both are required. + +You should include the following information: + +* Is the feature supported by the underlying component + (FreeRangeRouting, nftables, Kea...) already? +* How you'd configure it by hand there? +* Are there any limitations (hardware support, resource usage)? +* Are there any adverse or non-obvious interactions with other features? + Should it be mutually exclusive with anything? + +It's fine if you cannot provide some of that information, but if you can, +it makes the work of developers considerably simpler, +so try to do the research to answer those questions. + +Task auto-closing +================= + +There is a special status for tasks +where all work on the side of maintainers and contributors is complete: +"Needs reporter action". + +We assign that status to: + +* Feature requests that do not include required information and need clarification. +* Bug reports that lack reproducing procedures. +* Tasks that are implemented and tested by the implementation author, + but require testing in the real-world environment that only the reporter can replicate + (e.g., hardware we do not have, specific network conditions...). + +This is what will happen when a task is set to "Needs reporter action": + +* If there is no response from the reporter within two weeks, + the task bot will add a comment ("Any news?") to remind the reporter to reply. +* If there is no response after further two weeks, the task will be automatically closed. + +We will not auto-close tasks with any other status +and will not close tasks for the lack of maintainer activity! + .. _documentation: https://docs.vyos.io .. _Slack: https://slack.vyos.io .. _Forum: https://forum.vyos.io |