diff --git a/docs/_static/images/permanent_install.png b/docs/_static/images/permanent_install.png new file mode 100644 index 00000000..e772e86d Binary files /dev/null and b/docs/_static/images/permanent_install.png differ diff --git a/docs/_static/images/vyosnew-downloads.png b/docs/_static/images/vyosnew-downloads.png new file mode 100644 index 00000000..294a4589 Binary files /dev/null and b/docs/_static/images/vyosnew-downloads.png differ diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index d2916d9f..c13affaf 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -211,23 +211,24 @@ firewall exception. .. code-block:: none - set firewall name OUTSIDE_LOCAL rule 10 action accept - set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related' - set firewall name OUTSIDE_LOCAL rule 10 state established enable - set firewall name OUTSIDE_LOCAL rule 10 state related enable - set firewall name OUTSIDE_LOCAL rule 20 action accept - set firewall name OUTSIDE_LOCAL rule 20 description WireGuard_IN - set firewall name OUTSIDE_LOCAL rule 20 destination port 51820 - set firewall name OUTSIDE_LOCAL rule 20 log enable - set firewall name OUTSIDE_LOCAL rule 20 protocol udp - set firewall name OUTSIDE_LOCAL rule 20 source + set firewall ipv4 name OUTSIDE_LOCAL rule 10 action accept + set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' + set firewall ipv4 name OUTSIDE_LOCAL rule 10 state established enable + set firewall ipv4 name OUTSIDE_LOCAL rule 10 state related enable + set firewall ipv4 name OUTSIDE_LOCAL rule 20 action accept + set firewall ipv4 name OUTSIDE_LOCAL rule 20 description WireGuard_IN + set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 + set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable + set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp You should also ensure that the OUTISDE_LOCAL firewall group is applied to the -WAN interface and a direction (local). +WAN interface and in an input (local) direction. .. code-block:: none - set interfaces ethernet eth0 firewall local name 'OUTSIDE-LOCAL' + set firewall ipv4 input filter rule 10 action jump + set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' + set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' Assure that your firewall rules allow the traffic, in which case you have a working VPN using WireGuard. diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst index 15705449..15613ab2 100644 --- a/docs/configuration/vpn/l2tp.rst +++ b/docs/configuration/vpn/l2tp.rst @@ -92,18 +92,18 @@ Example: .. code-block:: none - set firewall name OUTSIDE-LOCAL rule 40 action 'accept' - set firewall name OUTSIDE-LOCAL rule 40 protocol 'esp' - set firewall name OUTSIDE-LOCAL rule 41 action 'accept' - set firewall name OUTSIDE-LOCAL rule 41 destination port '500' - set firewall name OUTSIDE-LOCAL rule 41 protocol 'udp' - set firewall name OUTSIDE-LOCAL rule 42 action 'accept' - set firewall name OUTSIDE-LOCAL rule 42 destination port '4500' - set firewall name OUTSIDE-LOCAL rule 42 protocol 'udp' - set firewall name OUTSIDE-LOCAL rule 43 action 'accept' - set firewall name OUTSIDE-LOCAL rule 43 destination port '1701' - set firewall name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec' - set firewall name OUTSIDE-LOCAL rule 43 protocol 'udp' + set firewall ipv4 name OUTSIDE-LOCAL rule 40 action 'accept' + set firewall ipv4 name OUTSIDE-LOCAL rule 40 protocol 'esp' + set firewall ipv4 name OUTSIDE-LOCAL rule 41 action 'accept' + set firewall ipv4 name OUTSIDE-LOCAL rule 41 destination port '500' + set firewall ipv4 name OUTSIDE-LOCAL rule 41 protocol 'udp' + set firewall ipv4 name OUTSIDE-LOCAL rule 42 action 'accept' + set firewall ipv4 name OUTSIDE-LOCAL rule 42 destination port '4500' + set firewall ipv4 name OUTSIDE-LOCAL rule 42 protocol 'udp' + set firewall ipv4 name OUTSIDE-LOCAL rule 43 action 'accept' + set firewall ipv4 name OUTSIDE-LOCAL rule 43 destination port '1701' + set firewall ipv4 name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec' + set firewall ipv4 name OUTSIDE-LOCAL rule 43 protocol 'udp' To allow VPN-clients access via your external address, a NAT rule is required: diff --git a/docs/installation/install.rst b/docs/installation/install.rst index 2bbce8ee..664e6bc3 100644 --- a/docs/installation/install.rst +++ b/docs/installation/install.rst @@ -18,13 +18,10 @@ any other type of storage. | (Current)** | Always up to date with cutting edge development | | features, experimenting. | | | | | but guaranteed to contain bugs. | | | | | +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **Nightly | Automatically built from the development branch | Every night | Developing and testing the latest | Everyone | Everyone | - | (Beta)** | and released alongside snapshots. Most likely | | major version under development. | | | - | | contains bugs. | | | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **Snapshot** | A particularly stable release frozen from nightly | Every month until | Home labs and simple networks that | Everyone | Everyone | - | | each month after manual testing. Still contains | RC comes out | call for new features. | | | - | | experimental code. | | | | | + | **Stream** | VyOS Stream serves as a technology preview and | Every quarter | Non-critical production environments, | Everyone | Everyone | + | | a quality gate for the upcoming LTS release. | | preparing for the LTS release. | | | + | | Allows everyone to try new features and check | | | | | + | | if they work well or need improvements | | | | | +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ | **Release | Rather stable. All development focuses on testing | Irregularly until | Labs, small offices and non-critical | Everyone | Everyone | | Candidate** | and hunting down remaining bugs following the | EPA comes out | production systems backed by a | | | @@ -44,7 +41,7 @@ any other type of storage. Hardware requirements ===================== -The minimum system requirements are 1024 MiB RAM and 2 GiB storage. +The minimum system requirements are 4 GB RAM and 10 GB storage. Depending on your use, you might need additional RAM and CPU resources e.g. when having multiple BGP full tables in your system. @@ -58,17 +55,9 @@ Registered subscribers can log into https://support.vyos.io/ to access a variety of different downloads via the "Downloads" link. These downloads include LTS (Long-Term Support), the associated hot-fix releases, early public access releases, pre-built VM images, as well as device specific installation -ISOs. +ISOs. See this article_ for more information on downloads. -.. figure:: /_static/images/vyos-downloads.png - -Building from source --------------------- - -Non-subscribers can always get the LTS release by building it from source. -Instructions can be found in the :ref:`build` section of this manual. VyOS -source code repository is available for everyone at -https://github.com/vyos/vyos-build. +.. figure:: /_static/images/vyosnew-downloads.png Rolling Release --------------- @@ -81,167 +70,31 @@ https://downloads.vyos.io/ please follow the guide at :ref:`bug_report`. We depend on your feedback to improve VyOS! -The following link will always fetch the most recent VyOS build for AMD64 +The following link contains the list of the most recent VyOS builds for AMD64 systems from the current branch: -https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso +https://vyos.net/get/nightly-builds/ Download Verification --------------------- -LTS images are signed by the VyOS lead package-maintainer private key. With -the official public key, the authenticity of the package can be -verified. :abbr:`GPG (GNU Privacy Guard)` is used for verification. - -.. note:: This subsection only applies to LTS images, for - Rolling images please jump to :ref:`live_installation`. - -Preparing for the verification -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -First, install GPG or another OpenPGP implementation. On most GNU+Linux -distributions it is installed by default as package managers use it to -verify package signatures. If not pre-installed, it will need to be -downloaded and installed. - -The official VyOS public key can be retrieved in a number of ways. Skip -to :ref:`gpg-verification` if the key is already present. - -It can be retrieved directly from a key server: - -``gpg --recv-keys FD220285A0FE6D7E`` - -Or it can be accessed via a web browser: - -https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E - -Or from the following block: - -.. code-block:: none - - -----BEGIN PGP PUBLIC KEY BLOCK----- - Version: GnuPG v1.4.12 (GNU/Linux) - - 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 - 8vzPzaWHhkOkU8/J/Ci7+vNtUOZb - =Ld8S - -----END PGP PUBLIC KEY BLOCK----- - -Store the key in a new text file and import it into GPG via: ``gpg --import -file_with_the_public_key`` - -The import can be verified with: - -.. code-block:: none - - $ gpg --list-keys - ... - pub rsa4096 2015-08-12 [SC] - 0694A9230F5139BF834BA458FD220285A0FE6D7E - uid [ unknown] VyOS Maintainers (VyOS Release) - sub rsa4096 2015-08-12 [E] - -.. _gpg-verification: - -GPG verification -^^^^^^^^^^^^^^^^ - -With the public key imported, the signature for the desired image needs -to be downloaded. - -.. note:: The signature can be downloaded by appending `.asc` to the URL of the - downloaded VyOS image. That small *.asc* file is the signature for the - associated image. - -Finally, verify the authenticity of the downloaded image: - -.. code-block:: none - - $ gpg2 --verify vyos-1.2.1-amd64.iso.asc vyos-1.2.1-amd64.iso - gpg: Signature made So 14 Apr 12:58:07 2019 CEST - gpg: using RSA key FD220285A0FE6D7E - gpg: Good signature from "VyOS Maintainers (VyOS Release) " [unknown] - Primary key fingerprint: 0694 A923 0F51 39BF 834B A458 FD22 0285 A0FE 6D7E +LTS images are signed by the VyOS lead package-maintainer private key. With the +official public key, the authenticity of the package can be verified. +Minisign is used for verification. .. _minisign-verification: Minisign verification ^^^^^^^^^^^^^^^^^^^^^ -Currently we are using GPG for release signing (pretty much like everyone else). - -Popularity of GPG for release signing comes from the fact that many people -already had it installed for email encryption/signing. Inside a VyOS image, -signature checking is the only reason to have it installed. However, it still -comes with all the features no one needs, such as support for multiple outdated -cipher suits and ability to embed a photo in the key file. More importantly, -web of trust, the basic premise of PGP, is never used in release signing -context. Once you have a knowingly authentic image, authenticity of upgrades is -checked using a key that comes in the image, and to get their first image people -never rely on keyservers either. - -Another point is that we are using RSA now, which requires absurdly large keys -to be secure. +Currently we are using Minisign for release signing which is a simple tool to +sign files and verify signatures. In 2015, OpenBSD introduced signify. An alternative implementation of the same protocol is minisign, which is also available for Windows and macOS, and in most -GNU/Linux distros it's in the repositories now. +GNU/Linux distros it's in the repositories now. It is portable, lightweight, and +uses the highly secure Ed25519 public-key signature system. -Its installed size (complete with libsodium) is less than that of GPG binary -alone (not including libgcrypt and some other libs, which I think we only use -for GPG). Since it uses elliptic curves, it gets away with much smaller keys, -and it doesn't include as much metadata to begin with. - -Another issue of GPG is that it creates a /root/.gnupg directory just for -release checking. The dir is small so the fact that it's never used again is -an aesthetic problem, but we've had that process fail in the past. But, small -key size of the Ed25519 algorithm allows passing public keys in command line -arguments, so verification process can be completely stateless: :vytask:`T2108` switched the validation system to prefer minisign over GPG keys. @@ -253,7 +106,7 @@ To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run: Signature and comment signature verified Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso -During an image upgrade VyOS performas the following command: +During an image upgrade VyOS performs the following command: .. code-block:: none @@ -261,6 +114,12 @@ During an image upgrade VyOS performas the following command: Signature and comment signature verified Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso +.. note:: Starting with 1.4.3, VyOS uses Minisign exclusively. This should not + be a problem for anyone because Minisign signature verification has already + been present in all releases for years. But if you see an unexpected verification + error, you can solve that by updating your system to 1.4.2 first. + Removed support for GnuPG signatures(:vytask:`T7301`). + .. _live_installation: Live installation @@ -358,57 +217,7 @@ In order to proceed with a permanent installation: 2. Run the ``install image`` command and follow the wizard: - .. code-block:: none - - vyos@vyos:~$ install image - Welcome to the VyOS install program. This script - will walk you through the process of installing the - VyOS image to a local hard drive. - Would you like to continue? (Yes/No) [Yes]: Yes - Probing drives: OK - Looking for pre-existing RAID groups...none found. - The VyOS image will require a minimum 2000MB root. - Would you like me to try to partition a drive automatically - or would you rather partition it manually with parted? If - you have already setup your partitions, you may skip this step - - Partition (Auto/Parted/Skip) [Auto]: - - I found the following drives on your system: - sda 4294MB - - Install the image on? [sda]: - - This will destroy all data on /dev/sda. - Continue? (Yes/No) [No]: Yes - - How big of a root partition should I create? (2000MB - 4294MB) [4294]MB: - - Creating filesystem on /dev/sda1: OK - Done! - Mounting /dev/sda1... - What would you like to name this image? [1.2.0-rolling+201809210337]: - OK. This image will be named: 1.2.0-rolling+201809210337 - Copying squashfs image... - Copying kernel and initrd images... - Done! - I found the following configuration files: - /opt/vyatta/etc/config.boot.default - Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]: - - Copying /opt/vyatta/etc/config.boot.default to sda. - Enter password for administrator account - Enter password for user 'vyos': - Retype password for user 'vyos': - I need to install the GRUB boot loader. - I found the following drives on your system: - sda 4294MB - - Which drive should GRUB modify the boot partition on? [sda]: - - Setting up grub: OK - Done! - +.. figure:: /_static/images/permanent_install.png 3. After the installation is completed, remove the live USB stick or CD. @@ -603,5 +412,6 @@ Installation can then continue as outlined above. .. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config .. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration .. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html +.. _article: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913 .. start_vyoslinter