diff options
| m--------- | docs/_include/vyos-1x | 0 | ||||
| -rw-r--r-- | docs/changelog/1.4.rst | 48 | ||||
| -rw-r--r-- | docs/configuration/service/dns.rst | 75 | ||||
| -rw-r--r-- | docs/contributing/build-vyos.rst | 95 |
4 files changed, 147 insertions, 71 deletions
diff --git a/docs/_include/vyos-1x b/docs/_include/vyos-1x -Subproject 2078253176046ea4d07e69caeb7932ea439b561 +Subproject 48c09cb91079733e4c5517a22b5345ff14d6605 diff --git a/docs/changelog/1.4.rst b/docs/changelog/1.4.rst index cf8e22ab..7a4c96c0 100644 --- a/docs/changelog/1.4.rst +++ b/docs/changelog/1.4.rst @@ -8,6 +8,54 @@ _ext/releasenotes.py +2024-01-07 +========== + +* :vytask:`T5891` ``(bug): OpenVPN IPv6 config issue with 1.4-rc1`` +* :vytask:`T5887` ``(feature): Upgrade Linux Kernel to 6.6.y (2023 LTS edition)`` + + +2024-01-06 +========== + +* :vytask:`T3670` ``(feature): Option to disable HTTP port 80 redirect`` + + +2024-01-05 +========== + +* :vytask:`T3642` ``(feature): PKI configuration`` +* :vytask:`T5894` ``(feature): Extend get_config_dict() with additional parameter with_pki that defaults to False`` + + +2024-01-04 +========== + +* :vytask:`T4072` ``(feature): Feature Request: Firewall on bridge interfaces`` +* :vytask:`T3459` ``(default): Inform the user when unable to install outdated image`` + + +2024-01-03 +========== + +* :vytask:`T5880` ``(bug): verify_source_interface should not allow dynamic interfaces like ppp, l2tp, ipoe or sstpc client interfaces`` +* :vytask:`T5879` ``(bug): tunnel: sourceing from dynamic pppoe0 interface will fail on reboots`` +* :vytask:`T4500` ``(bug): Missing firewall logs`` + + +2024-01-02 +========== + +* :vytask:`T5885` ``(default): image-tools: relax restriction on image-name length from 32 to 64`` + + +2024-01-01 +========== + +* :vytask:`T5883` ``(bug): Preserve file ownership in /config subdirs on add system image`` +* :vytask:`T5474` ``(feature): Establish common file name pattern for XML conf mode commands`` + + 2023-12-30 ========== diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst index c96c0ab4..7624d309 100644 --- a/docs/configuration/service/dns.rst +++ b/docs/configuration/service/dns.rst @@ -143,6 +143,19 @@ 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. +.. cfgcmd:: set service dns forwarding serve-stale-extension <0-65535> + + Maximum number of times an expired record’s TTL is extended by 30s when + serving stale. Extension only occurs if a record cannot be refreshed. A + value of 0 means the Serve Stale mechanism is not used. To allow records + becoming stale to be served for an hour, use a value of 120. + +.. cfgcmd:: set service dns forwarding exclude-throttle-address <ip|prefix> + + When an authoritative server does not answer a query or sends a reply the + recursor does not like, it is throttled. Any servers matching the supplied + netmasks will never be throttled. + Example ======= @@ -216,36 +229,36 @@ Configuration :rfc:`2136` Based ----------------- -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> +.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name> Create new :rfc:`2136` DNS update configuration which will update the IP address assigned to `<interface>` on the service you configured under `<service-name>`. -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> +.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name> key <keyfile> File identified by `<keyfile>` containing the secret RNDC key shared with remote DNS server. -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> +.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name> server <server> Configure the DNS `<server>` IP/FQDN used when updating this dynamic assignment. -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> +.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name> zone <zone> Configure DNS `<zone>` to be updated. -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> +.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name> record <record> Configure DNS `<record>` which should be updated. This can be set multiple times. -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> +.. cfgcmd:: set service dns dynamic address <interface> rfc2136 <service-name> ttl <ttl> Configure optional TTL value on the given resource record. This defaults to @@ -308,40 +321,40 @@ VyOS is also able to use any service relying on protocols supported by ddclient. To use such a service, one must define a login, password, one or multiple hostnames, protocol and server. -.. cfgcmd:: set service dns dynamic interface <interface> service <service> +.. cfgcmd:: set service dns dynamic address <interface> service <service> host-name <hostname> Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS - provider identified by `<service>` when the IP address on interface + provider identified by `<service>` when the IP address on address `<interface>` changes. -.. cfgcmd:: set service dns dynamic interface <interface> service <service> - login <username> +.. cfgcmd:: set service dns dynamic address <interface> service <service> + username <username> Configure `<username>` used when authenticating the update request for DynDNS service identified by `<service>`. For Namecheap, set the <domain> you wish to update. -.. cfgcmd:: set service dns dynamic interface <interface> service <service> +.. cfgcmd:: set service dns dynamic address <interface> service <service> password <password> Configure `<password>` used when authenticating the update request for DynDNS service identified by `<service>`. -.. cfgcmd:: set service dns dynamic interface <interface> service <service> +.. cfgcmd:: set service dns dynamic address <interface> service <service> protocol <protocol> When a ``custom`` DynDNS provider is used the protocol used for communicating to the provider must be specified under `<protocol>`. See the embedded completion helper for available protocols. -.. cfgcmd:: set service dns dynamic interface <interface> service <service> +.. cfgcmd:: set service dns dynamic address <interface> service <service> server <server> When a ``custom`` DynDNS provider is used the `<server>` where update requests are being sent to must be specified. -.. cfgcmd:: set service dns dynamic interface <interface> ipv6-enable +.. cfgcmd:: set service dns dynamic address <interface> ipv6-enable Allow explicit IPv6 address for the interface. @@ -353,10 +366,10 @@ Use DynDNS as your preferred provider: .. code-block:: none - set service dns dynamic interface eth0 service dyndns - set service dns dynamic interface eth0 service dyndns login my-login - set service dns dynamic interface eth0 service dyndns password my-password - set service dns dynamic interface eth0 service dyndns host-name my-dyndns-hostname + set service dns dynamic address eth0 service dyndns + set service dns dynamic address eth0 service dyndns username my-login + set service dns dynamic address eth0 service dyndns password my-password + set service dns dynamic address eth0 service dyndns host-name my-dyndns-hostname .. note:: Multiple services can be used per interface. Just specify as many services per interface as you like! @@ -366,12 +379,12 @@ Example IPv6 only: .. code-block:: none - set service dns dynamic interface eth0 ipv6-enable - set service dns dynamic interface eth0 service dyndns6 login my-login - set service dns dynamic interface eth0 service dyndns6 password my-password - set service dns dynamic interface eth0 service dyndns6 host-name my-dyndns-hostname - set service dns dynamic interface eth0 service dyndns6 protocol dyndns2 - set service dns dynamic interface eth0 service dyndns6 server dyndns-v6-server + set service dns dynamic address eth0 ipv6-enable + set service dns dynamic address eth0 service dyndns6 username my-login + set service dns dynamic address eth0 service dyndns6 password my-password + set service dns dynamic address eth0 service dyndns6 host-name my-dyndns-hostname + set service dns dynamic address eth0 service dyndns6 protocol dyndns2 + set service dns dynamic address eth0 service dyndns6 server dyndns-v6-server Running Behind NAT @@ -381,15 +394,21 @@ By default, ddclient_ will update a dynamic dns record using the IP address directly attached to the interface. If your VyOS instance is behind NAT, your record will be updated to point to your internal IP. -ddclient_ has another way to determine the WAN IP address. This is controlled -by: +Above, command syntax isn noted to configure dynamic dns on a specific interface. +It is possible to overlook the additional address option, web, when completeing +those commands. ddclient_ has another way to determine the WAN IP address, using +a web-based url to determine the external IP. Each of the commands above will +need to be modified to use 'web' as the 'interface' specified if this functionality +is to be utilized. + +This functionality is controlled by adding the following configuration: -.. cfgcmd:: set service dns dynamic interface <interface> use-web url <url> +.. cfgcmd:: set service dns dynamic address web web-options url <url> Use configured `<url>` to determine your IP address. ddclient_ will load `<url>` and tries to extract your IP address from the response. -.. cfgcmd:: set service dns dynamic interface <interface> use-web skip <pattern> +.. cfgcmd:: set service dns dynamic address web web-options skip <pattern> ddclient_ will skip any address located before the string set in `<pattern>`. diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 301d2f3e..6718940c 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -33,8 +33,9 @@ following Debian versions installed: - Debian Jessie for VyOS 1.2 (crux) - Debian Buster for VyOS 1.3 (equuleus) -- Debian Bullseye for VyOS 1.4 (sagitta) -- Debian unknown for VyOS 1.5 (circinus, current) - aka the rolling release +- Debian Bookworm for VyOS 1.4 (sagitta) +- Debian Bookworm or updated for VyOS 1.5 (circinus, current) - aka the + rolling release To start, clone the repository to your local machine: @@ -58,7 +59,7 @@ To start, clone the repository to your local machine: $ ./configure --architecture amd64 --build-by "j.randomhacker@vyos.io" $ sudo make iso - # For VyOS 1.4 (sagitta) + # For VyOS 1.4 (sagitta) and VyOS 1.5 (circinus, current) $ sudo make clean $ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" @@ -67,25 +68,43 @@ in the repository_. The ``./build-vyos-image`` script will also warn you if any dependencies are missing. -This will guide you through the process of building a VyOS ISO using Docker_. -This process has been tested on clean installs of Debian Bullseye (11) and -Bookworm (12). - .. _build_docker: Docker ====== +This will guide you through the process of building a VyOS ISO using Docker_. +This process has been tested on clean installs of Debian Bullseye (11) and +Bookworm (12). + Installing Docker_ and prerequisites: +.. hint:: Due to the updated version of Docker, the following examples may + become invalid. + + Due to differences in version updates and build processes, content related + to VyOS 1.3 and below is no longer included below. + +`On Debian`_ + .. code-block:: none + # Add Docker's official GPG key: $ sudo apt-get update - $ sudo apt-get install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common - $ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - - $ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" + $ sudo apt-get install ca-certificates curl gnupg + $ sudo install -m 0755 -d /etc/apt/keyrings + $ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg + $ sudo chmod a+r /etc/apt/keyrings/docker.gpg + + # Add the repository to Apt sources: + $ echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \ + https://download.docker.com/linux/debian \ + $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + $ sudo apt-get update - $ sudo apt-get install -y docker-ce + $ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin To be able to use Docker_ without ``sudo``, the current non-root user must be added to the ``docker`` group by calling: ``sudo usermod -aG docker @@ -120,8 +139,6 @@ To manually download the container from DockerHub, run: .. code-block:: none - $ docker pull vyos/vyos-build:crux # For VyOS 1.2 - $ docker pull vyos/vyos-build:equuleus # For VyOS 1.3 $ docker pull vyos/vyos-build:sagitta # For VyOS 1.4 $ docker pull vyos/vyos-build:current # For rolling release @@ -132,27 +149,27 @@ The container can also be built directly from source: .. code-block:: none - # For VyOS 1.2 (crux) - $ git clone -b crux --single-branch https://github.com/vyos/vyos-build - # For VyOS 1.3 (equuleus) - $ git clone -b equuleus --single-branch https://github.com/vyos/vyos-build - # For VyOS 1.4 (sagitta, current) + # For VyOS 1.4 (sagitta) + $ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build + + # For VyOS 1.5 (circinus, current) $ git clone -b current --single-branch https://github.com/vyos/vyos-build + $ cd vyos-build - $ docker build -t vyos/vyos-build:crux docker # For VyOS 1.2 - $ docker build -t vyos/vyos-build:current docker # For rolling release + $ docker build -t vyos/vyos-build:sagitta docker # For VyOS 1.4 + $ docker build -t vyos/vyos-build:current docker # For rolling release -.. note:: Since VyOS has switched to Debian (11) Bullseye in its ``current`` - branch, you will require individual container for `current`, `equuleus` and - `crux` builds. +.. note:: Since VyOS has switched to Debian (12) Bookworm in its ``current`` + branch, It is recommended to use the official Docker Hub container image + to build ``equleus`` and ``crux``. Tips and Tricks --------------- You can create yourself some handy Bash aliases to always launch the latest - -per release train (`current` or `crux`) - container. Add the following to your -``.bash_aliases`` file: +per release train (`current` or `sagitta`) - container. Add the following to +your ``.bash_aliases`` file: .. code-block:: none @@ -174,8 +191,8 @@ per release train (`current` or `crux`) - container. Add the following to your -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ vyos/vyos-build:sagitta bash' -Now you are prepared with two new aliases ``vybld`` and ``vybld_sagitta`` to spawn -your development containers in your current working directory. +Now you are prepared with two new aliases ``vybld`` and ``vybld_sagitta`` to +spawn your development containers in your current working directory. .. note:: Some VyOS packages (namely vyos-1x) come with build-time tests which verify some of the internal library calls that they work as expected. Those @@ -197,13 +214,10 @@ Please note as this will differ for both `current` and `crux`. .. code-block:: none - # For VyOS 1.2 (crux) - $ git clone -b crux --single-branch https://github.com/vyos/vyos-build - - # For VyOS 1.3 (equuleus) - $ git clone -b equuleus --single-branch https://github.com/vyos/vyos-build + # For VyOS 1.4 (sagitta) + $ git clone -b sagitta --single-branch https://github.com/vyos/vyos-build - # For VyOS 1.4 (sagitta, current) + # For VyOS 1.5 (circinus, current) $ git clone -b current --single-branch https://github.com/vyos/vyos-build Now a fresh build of the VyOS ISO can begin. Change directory to the @@ -212,13 +226,11 @@ Now a fresh build of the VyOS ISO can begin. Change directory to the .. code-block:: none $ cd vyos-build - # For VyOS 1.2 (crux) - $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:crux bash - # For VyOS 1.3 (equuleus) - $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:equuleus bash + # For VyOS 1.4 (sagitta) + $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:sagitta bash - # For VyOS 1.4 (sagitta, current) + # For VyOS 1.5 (circinus, current) $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash .. code-block:: none @@ -240,11 +252,7 @@ Start the build: .. code-block:: none - # For VyOS 1.2 (crux) and VyOS 1.3 (equuleus) - vyos_bld@8153428c7e1f:/vyos$ ./configure --architecture amd64 --build-by "j.randomhacker@vyos.io" - vyos_bld@8153428c7e1f:/vyos$ sudo make iso - - # For VyOS 1.4 (sagitta) + # For VyOS 1.4 (sagitta) and For VyOS 1.5 (circinus, current) vyos_bld@8153428c7e1f:/vyos$ sudo make clean vyos_bld@8153428c7e1f:/vyos$ sudo ./build-vyos-image iso --architecture amd64 --build-by "j.randomhacker@vyos.io" @@ -851,6 +859,7 @@ information. .. _VyOS DockerHub organisation: https://hub.docker.com/u/vyos .. _repository: https://github.com/vyos/vyos-build .. _VyOS GitHub project: https://github.com/vyos +.. _`On Debian`: https://docs.docker.com/engine/install/debian/ .. start_vyoslinter |