From b8b3044d3c3515d91de0f44785bfd965174867df Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 21:50:08 +0300 Subject: feat: flip swap mechanism on sagitta — MD as primary, RST as override MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror of #1899 (current) and #1900 (circinus) for sagitta. Same logic, same scripts, per-branch file set. Changes: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 210 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 210 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty - conf.py exclude_patterns flipped: rst-*.rst excluded by default - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt - scripts/swap_sources.py imported from current (post-#1899 rewrite, with inverted rename direction) - scripts/import_myst.py and tests/test_import_myst.py deleted (obsolete) - tests/test_swap_sources.py imported from current (post-#1899 rewrite) Side-effect: fixes the same 404 on /en/1.4/ View page source links that #1899 fixed for /en/rolling/ and #1900 fixed for /en/1.5/. Per-branch differences vs #1899: - sagitta has 210 stems vs current's 254 (sagitta has no vpp pages and fewer current-only features; cli + installation/cloud/aws are still RST-only on sagitta pending the title-level fix follow-up) - otherwise the script/conf.py/test changes are byte-identical with current Generated by robots https://vyos.io --- docs/installation/cloud/aws-ha.md | 135 ++++++ docs/installation/cloud/aws-ha.rst | 154 ------- docs/installation/cloud/aws-to-azure.md | 175 ++++++++ docs/installation/cloud/aws-to-azure.rst | 189 -------- docs/installation/cloud/azure-ha.md | 128 ++++++ docs/installation/cloud/azure-ha.rst | 152 ------- docs/installation/cloud/azure.md | 378 ++++++++++++++++ docs/installation/cloud/azure.rst | 433 ------------------ docs/installation/cloud/gcp.md | 260 +++++++++++ docs/installation/cloud/gcp.rst | 277 ------------ docs/installation/cloud/index.md | 14 + docs/installation/cloud/index.rst | 16 - docs/installation/cloud/md-aws-ha.md | 135 ------ docs/installation/cloud/md-aws-to-azure.md | 175 -------- docs/installation/cloud/md-azure-ha.md | 128 ------ docs/installation/cloud/md-azure.md | 378 ---------------- docs/installation/cloud/md-gcp.md | 260 ----------- docs/installation/cloud/md-index.md | 14 - docs/installation/cloud/md-oracel.md | 5 - docs/installation/cloud/oracel.md | 5 + docs/installation/cloud/oracel.rst | 8 - docs/installation/cloud/rst-aws-ha.rst | 154 +++++++ docs/installation/cloud/rst-aws-to-azure.rst | 189 ++++++++ docs/installation/cloud/rst-azure-ha.rst | 152 +++++++ docs/installation/cloud/rst-azure.rst | 433 ++++++++++++++++++ docs/installation/cloud/rst-gcp.rst | 277 ++++++++++++ docs/installation/cloud/rst-index.rst | 16 + docs/installation/cloud/rst-oracel.rst | 8 + docs/installation/image.md | 122 ++++++ docs/installation/image.rst | 115 ----- docs/installation/index.md | 28 ++ docs/installation/index.rst | 26 -- docs/installation/install.md | 396 +++++++++++++++++ docs/installation/install.rst | 417 ------------------ docs/installation/md-image.md | 122 ------ docs/installation/md-index.md | 28 -- docs/installation/md-install.md | 396 ----------------- docs/installation/md-update.md | 86 ---- docs/installation/md-vyos-on-baremetal.md | 626 -------------------------- docs/installation/rst-image.rst | 115 +++++ docs/installation/rst-index.rst | 26 ++ docs/installation/rst-install.rst | 417 ++++++++++++++++++ docs/installation/rst-update.rst | 82 ++++ docs/installation/rst-vyos-on-baremetal.rst | 632 +++++++++++++++++++++++++++ docs/installation/update.md | 86 ++++ docs/installation/update.rst | 82 ---- docs/installation/virtual/docker.md | 67 +++ docs/installation/virtual/docker.rst | 74 ---- docs/installation/virtual/eve-ng.md | 5 + docs/installation/virtual/eve-ng.rst | 8 - docs/installation/virtual/gns3.md | 187 ++++++++ docs/installation/virtual/gns3.rst | 175 -------- docs/installation/virtual/index.md | 13 + docs/installation/virtual/index.rst | 13 - docs/installation/virtual/libvirt.md | 171 ++++++++ docs/installation/virtual/libvirt.rst | 172 -------- docs/installation/virtual/md-docker.md | 67 --- docs/installation/virtual/md-eve-ng.md | 5 - docs/installation/virtual/md-gns3.md | 187 -------- docs/installation/virtual/md-index.md | 13 - docs/installation/virtual/md-libvirt.md | 171 -------- docs/installation/virtual/md-proxmox.md | 45 -- docs/installation/virtual/md-vmware.md | 39 -- docs/installation/virtual/proxmox.md | 45 ++ docs/installation/virtual/proxmox.rst | 56 --- docs/installation/virtual/rst-docker.rst | 74 ++++ docs/installation/virtual/rst-eve-ng.rst | 8 + docs/installation/virtual/rst-gns3.rst | 175 ++++++++ docs/installation/virtual/rst-index.rst | 13 + docs/installation/virtual/rst-libvirt.rst | 172 ++++++++ docs/installation/virtual/rst-proxmox.rst | 56 +++ docs/installation/virtual/rst-vmware.rst | 46 ++ docs/installation/virtual/vmware.md | 39 ++ docs/installation/virtual/vmware.rst | 46 -- docs/installation/vyos-on-baremetal.md | 626 ++++++++++++++++++++++++++ docs/installation/vyos-on-baremetal.rst | 632 --------------------------- 76 files changed, 5925 insertions(+), 5925 deletions(-) create mode 100644 docs/installation/cloud/aws-ha.md delete mode 100755 docs/installation/cloud/aws-ha.rst create mode 100644 docs/installation/cloud/aws-to-azure.md delete mode 100755 docs/installation/cloud/aws-to-azure.rst create mode 100644 docs/installation/cloud/azure-ha.md delete mode 100755 docs/installation/cloud/azure-ha.rst create mode 100644 docs/installation/cloud/azure.md delete mode 100644 docs/installation/cloud/azure.rst create mode 100644 docs/installation/cloud/gcp.md delete mode 100644 docs/installation/cloud/gcp.rst create mode 100644 docs/installation/cloud/index.md delete mode 100644 docs/installation/cloud/index.rst delete mode 100644 docs/installation/cloud/md-aws-ha.md delete mode 100644 docs/installation/cloud/md-aws-to-azure.md delete mode 100644 docs/installation/cloud/md-azure-ha.md delete mode 100644 docs/installation/cloud/md-azure.md delete mode 100644 docs/installation/cloud/md-gcp.md delete mode 100644 docs/installation/cloud/md-index.md delete mode 100644 docs/installation/cloud/md-oracel.md create mode 100644 docs/installation/cloud/oracel.md delete mode 100644 docs/installation/cloud/oracel.rst create mode 100755 docs/installation/cloud/rst-aws-ha.rst create mode 100755 docs/installation/cloud/rst-aws-to-azure.rst create mode 100755 docs/installation/cloud/rst-azure-ha.rst create mode 100644 docs/installation/cloud/rst-azure.rst create mode 100644 docs/installation/cloud/rst-gcp.rst create mode 100644 docs/installation/cloud/rst-index.rst create mode 100644 docs/installation/cloud/rst-oracel.rst create mode 100644 docs/installation/image.md delete mode 100644 docs/installation/image.rst create mode 100644 docs/installation/index.md delete mode 100644 docs/installation/index.rst create mode 100644 docs/installation/install.md delete mode 100644 docs/installation/install.rst delete mode 100644 docs/installation/md-image.md delete mode 100644 docs/installation/md-index.md delete mode 100644 docs/installation/md-install.md delete mode 100644 docs/installation/md-update.md delete mode 100644 docs/installation/md-vyos-on-baremetal.md create mode 100644 docs/installation/rst-image.rst create mode 100644 docs/installation/rst-index.rst create mode 100644 docs/installation/rst-install.rst create mode 100644 docs/installation/rst-update.rst create mode 100644 docs/installation/rst-vyos-on-baremetal.rst create mode 100644 docs/installation/update.md delete mode 100644 docs/installation/update.rst create mode 100644 docs/installation/virtual/docker.md delete mode 100644 docs/installation/virtual/docker.rst create mode 100644 docs/installation/virtual/eve-ng.md delete mode 100644 docs/installation/virtual/eve-ng.rst create mode 100644 docs/installation/virtual/gns3.md delete mode 100644 docs/installation/virtual/gns3.rst create mode 100644 docs/installation/virtual/index.md delete mode 100644 docs/installation/virtual/index.rst create mode 100644 docs/installation/virtual/libvirt.md delete mode 100644 docs/installation/virtual/libvirt.rst delete mode 100644 docs/installation/virtual/md-docker.md delete mode 100644 docs/installation/virtual/md-eve-ng.md delete mode 100644 docs/installation/virtual/md-gns3.md delete mode 100644 docs/installation/virtual/md-index.md delete mode 100644 docs/installation/virtual/md-libvirt.md delete mode 100644 docs/installation/virtual/md-proxmox.md delete mode 100644 docs/installation/virtual/md-vmware.md create mode 100644 docs/installation/virtual/proxmox.md delete mode 100644 docs/installation/virtual/proxmox.rst create mode 100644 docs/installation/virtual/rst-docker.rst create mode 100644 docs/installation/virtual/rst-eve-ng.rst create mode 100644 docs/installation/virtual/rst-gns3.rst create mode 100644 docs/installation/virtual/rst-index.rst create mode 100644 docs/installation/virtual/rst-libvirt.rst create mode 100644 docs/installation/virtual/rst-proxmox.rst create mode 100644 docs/installation/virtual/rst-vmware.rst create mode 100644 docs/installation/virtual/vmware.md delete mode 100644 docs/installation/virtual/vmware.rst create mode 100644 docs/installation/vyos-on-baremetal.md delete mode 100644 docs/installation/vyos-on-baremetal.rst (limited to 'docs/installation') diff --git a/docs/installation/cloud/aws-ha.md b/docs/installation/cloud/aws-ha.md new file mode 100644 index 00000000..f32e2ab5 --- /dev/null +++ b/docs/installation/cloud/aws-ha.md @@ -0,0 +1,135 @@ +# VyOS High Availability (HA) Deployment on AWS + +This document describes how to deploy VyOS in a High Availability (HA) configuration on AWS using Terraform and a VPC Route Server to provide sub-second failover. + +## Why Use HA on AWS? + +This solution helps organizations achieve **high availability** routing with dynamic connectivity to multiple AWS VPCs or hybrid environments. + +Key Advantages: + +- Utilizes **AWS VPC Route Server** to manage BGP routes dynamically. + +- Deploys two VyOS EC2 instances as BGP peers connected to the Route Server. Although both participate, one is typically preferred as the next-hop. + +- Employs **Bidirectional Forwarding Detection (BFD)** for rapid failure detection. + +- On failure: + + - Withdraws the failed peer’s routes from the RIB. + - Recomputes the optimal path in the FIB. + - Updates VPC route tables to point to the active instance. + +- Enables **sub-second failover** (< 1 s), outperforming AWS API-based route table failover. + +This architecture supports: + +- Cloud edge routing with failover. +- Hybrid cloud resiliency. +- Rapid recovery during instance crashes, upgrades, or network disruptions. +- Continuity for mission-critical operations. + +## HA Architecture Diagram + +:::{figure} /_static/images/cloud-aws-ha-architecture.png +:alt: VyOS HA topology diagram +::: + +## Terraform Automation + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on AWS. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. +- VPC Route Server. +- Transit Gateway. +- A Transit VPC and a Data VPC containing a test Amazon Linux EC2 instance for connectivity validation. + +To integrate with existing AWS infrastructure: + +- Remove the Data VPC, its subnets, and EC2 test instance. +- Update `main.tf`, `network.tf`, `transit_gateway.tf`, `variables.tf`, and `outputs.tf` accordingly. + +## Prerequisites + +AWS Environment: + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: +- Terraform installed: + +Set AWS credentials in your shell: + +```none +export AWS_ACCESS_KEY_ID="" +export AWS_SECRET_ACCESS_KEY="" +export AWS_SESSION_TOKEN="" +export AWS_DEFAULT_REGION="" # e.g., us-east-1 +``` + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +```none +aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table +``` + +Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. + +Generate an SSH keypair (or use the included demo key): + +```none +ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +## Usage + +Configure variables in `variables.tf`, including instance type, region, and `vyos_ami_id`. + +Terraform Workflow: + +```none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +```none +terraform output +``` + +This displays the management IP and connectivity test results. + +To clean up: + +```none +terraform destroy +``` + +## Management + +SSH into VyOS: + +```none +ssh vyos@ -i keys/vyos_custom_key.pem +``` + +## GitHub Repository + +You can clone or download the Terraform project and use them in your environment: + + diff --git a/docs/installation/cloud/aws-ha.rst b/docs/installation/cloud/aws-ha.rst deleted file mode 100755 index af125969..00000000 --- a/docs/installation/cloud/aws-ha.rst +++ /dev/null @@ -1,154 +0,0 @@ -########## -VyOS High Availability (HA) Deployment on AWS -########## - -This document describes how to deploy VyOS in a High Availability (HA) configuration on AWS using Terraform and a VPC Route Server to provide sub-second failover. - -Why Use HA on AWS? ------------------- - -This solution helps organizations achieve **high availability** routing with dynamic connectivity to multiple AWS VPCs or hybrid environments. - -Key Advantages: - -- Utilizes **AWS VPC Route Server** to manage BGP routes dynamically. - -- Deploys two VyOS EC2 instances as BGP peers connected to the Route Server. Although both participate, one is typically preferred as the next-hop. - -- Employs **Bidirectional Forwarding Detection (BFD)** for rapid failure detection. - -- On failure: - - - Withdraws the failed peer’s routes from the RIB. - - - Recomputes the optimal path in the FIB. - - - Updates VPC route tables to point to the active instance. - -- Enables **sub-second failover** (< 1 s), outperforming AWS API-based route table failover. - -This architecture supports: - -- Cloud edge routing with failover. - -- Hybrid cloud resiliency. - -- Rapid recovery during instance crashes, upgrades, or network disruptions. - -- Continuity for mission-critical operations. - -HA Architecture Diagram ------------------------- - -.. figure:: /_static/images/cloud-aws-ha-architecture.png - :alt: VyOS HA topology diagram - -Terraform Automation --------------------- - -To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on AWS. - -This Terraform project automates the deployment of: - -- Two VyOS instances in HA mode. - -- VPC Route Server. - -- Transit Gateway. - -- A Transit VPC and a Data VPC containing a test Amazon Linux EC2 instance for connectivity validation. - -To integrate with existing AWS infrastructure: - -- Remove the Data VPC, its subnets, and EC2 test instance. - -- Update `main.tf`, `network.tf`, `transit_gateway.tf`, `variables.tf`, and `outputs.tf` accordingly. - -Prerequisites -------------- - -AWS Environment: - -- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). - -Local Environment: - -- AWS CLI installed: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html - -- Terraform installed: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli - -Set AWS credentials in your shell: - -.. code-block:: none - - export AWS_ACCESS_KEY_ID="" - export AWS_SECRET_ACCESS_KEY="" - export AWS_SESSION_TOKEN="" - export AWS_DEFAULT_REGION="" # e.g., us-east-1 - -Obtain VyOS AMI ID and Owner ID: - -Subscribe to VyOS via AWS Marketplace. Then run: - -.. code-block:: none - - aws ec2 describe-images \ - --owners aws-marketplace \ - --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ - --query 'Images[*].[ImageId,OwnerId,Name]' \ - --output table - -Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. - -Generate an SSH keypair (or use the included demo key): - -.. code-block:: none - - ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem - chmod 400 keys/vyos_custom_key.pem - -Usage ------ - -Configure variables in `variables.tf`, including instance type, region, and `vyos_ami_id`. - -Terraform Workflow: - -.. code-block:: none - - terraform init - terraform fmt - terraform validate - terraform plan - terraform apply - -On completion, run: - -.. code-block:: none - - terraform output - -This displays the management IP and connectivity test results. - -To clean up: - -.. code-block:: none - - terraform destroy - -Management ----------- - -SSH into VyOS: - -.. code-block:: none - - ssh vyos@ -i keys/vyos_custom_key.pem - - -GitHub Repository ------------------ - -You can clone or download the Terraform project and use them in your environment: - -https://github.com/vyos/vyos-automation/tree/main/Terraform/AWS/ha-instances-with-configs diff --git a/docs/installation/cloud/aws-to-azure.md b/docs/installation/cloud/aws-to-azure.md new file mode 100644 index 00000000..246df5f3 --- /dev/null +++ b/docs/installation/cloud/aws-to-azure.md @@ -0,0 +1,175 @@ +# VyOS Deployment on AWS and Azure for Secure Cloud-to-Cloud Connectivity + +This document provides step-by-step guidance for deploying VyOS routers on both AWS and Azure. +It describes how to establish secure inter-cloud connectivity using IPsec tunnels with BGP, +automated through Terraform. Example workloads (Amazon Linux EC2 on AWS and Ubuntu VM on Azure) +are also deployed for connectivity validation. + +## Why Cloud-to-Cloud Connectivity? + +Cloud-to-cloud connectivity is needed in modern multi-cloud environments for several reasons: + +- **Inter-Cloud Connectivity** + + Enable secure and reliable communication between workloads in different clouds + (for example, AWS applications connecting to Azure-hosted identity services). + +- **Cloud-to-Cloud Migration** + + During migration projects, workloads may temporarily run in both clouds. + Direct tunnels ensure smooth transition and synchronization. + +- **Testing and Validation** + + Labs and proof-of-concepts often simulate multi-cloud architectures. + A VyOS-based tunnel lets teams test routing, encryption, and failover before production rollout. + +## Architecture + +The architecture consists of VyOS routers deployed in both AWS and Azure, connected via secure IPsec tunnels. +BGP is used for dynamic routing between the clouds, allowing for seamless communication. + +:::{figure} /_static/images/cloud-aws-to-azure.png +:alt: VyOS Cloud-to-Cloud topology diagram +::: + +## Terraform Automation + +To streamline and standardize the deployment process, a set of **Terraform projects** has been developed. +These projects automate the provisioning of **VyOS instances** and the required networking resources across **AWS** and **Azure**. + +In addition to deploying VyOS, these projects also provision an **Amazon Linux EC2 instance** on AWS and an **Ubuntu VM** on Azure. +These serve as test endpoints to validate connectivity between the cloud environments. + +## Prerequisites + +### AWS Environment + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: +- Terraform installed: + +Set AWS credentials in your shell: + +```none +export AWS_ACCESS_KEY_ID="" +export AWS_SECRET_ACCESS_KEY="" +export AWS_SESSION_TOKEN="" +export AWS_DEFAULT_REGION="" # e.g., us-east-1 +``` + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +```none +aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table +``` + +Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. + +Generate an SSH keypair (or use the included demo key): + +```none +ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +### Azure Environment + +- Active Azure subscription: + +```none +az account set --subscription "" +``` + +- Azure CLI installed: + + + +- Logged in with Azure credentials: + +```none +az version +az login +``` + +- Azure Resource Group (RG) created: + +```none +az group create --name demoResourceGroup --location westus +az group list +az group show --name demoResourceGroup +``` + +- Terraform installed: + + + +- SSH key generated: + +```none +ssh-keygen -t rsa -b 4096 -f keys/id_rsa +chmod 400 keys/id_rsa +``` + +## Usage + +### AWS + +All variables needed for customization are defined in `variables.tf`. +Adjust them according to your requirements, such as EC2 instance type and networking configurations. + +Before deployment, ensure you check `aws_region`, `availability_zone`, and update `vyos_ami_id` as necessary. + +### Azure + +All variables needed for customization are defined in `variables.tf`. +Adjust them according to your requirements, such as VM size and networking configurations. + +Before deployment, ensure you check `azure_region`, `availability_zone`, and update `subscription_id` and `resource_group_name` as necessary. + +### Terraform Workflow + +```none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +```none +terraform output +``` + +This displays the public IP addresses of the VyOS instances. + +To clean up: + +```none +terraform destroy +``` + +## Management + +SSH into VyOS: + +```none +ssh vyos@ -i keys/vyos_custom_key.pem +``` + +## GitHub Repository + +You can clone or download the Terraform projects and use them in your environment: + + diff --git a/docs/installation/cloud/aws-to-azure.rst b/docs/installation/cloud/aws-to-azure.rst deleted file mode 100755 index 81651feb..00000000 --- a/docs/installation/cloud/aws-to-azure.rst +++ /dev/null @@ -1,189 +0,0 @@ -########## -VyOS Deployment on AWS and Azure for Secure Cloud-to-Cloud Connectivity -########## - -This document provides step-by-step guidance for deploying VyOS routers on both AWS and Azure. -It describes how to establish secure inter-cloud connectivity using IPsec tunnels with BGP, -automated through Terraform. Example workloads (Amazon Linux EC2 on AWS and Ubuntu VM on Azure) -are also deployed for connectivity validation. - -Why Cloud-to-Cloud Connectivity? --------------------------------- - -Cloud-to-cloud connectivity is needed in modern multi-cloud environments for several reasons: - -- **Inter-Cloud Connectivity** - - Enable secure and reliable communication between workloads in different clouds - (for example, AWS applications connecting to Azure-hosted identity services). - -- **Cloud-to-Cloud Migration** - - During migration projects, workloads may temporarily run in both clouds. - Direct tunnels ensure smooth transition and synchronization. - -- **Testing and Validation** - - Labs and proof-of-concepts often simulate multi-cloud architectures. - A VyOS-based tunnel lets teams test routing, encryption, and failover before production rollout. - -Architecture ------------- - -The architecture consists of VyOS routers deployed in both AWS and Azure, connected via secure IPsec tunnels. -BGP is used for dynamic routing between the clouds, allowing for seamless communication. - -.. figure:: /_static/images/cloud-aws-to-azure.png - :alt: VyOS Cloud-to-Cloud topology diagram - -Terraform Automation --------------------- - -To streamline and standardize the deployment process, a set of **Terraform projects** has been developed. -These projects automate the provisioning of **VyOS instances** and the required networking resources across **AWS** and **Azure**. - -In addition to deploying VyOS, these projects also provision an **Amazon Linux EC2 instance** on AWS and an **Ubuntu VM** on Azure. -These serve as test endpoints to validate connectivity between the cloud environments. - -Prerequisites -------------- - -AWS Environment -^^^^^^^^^^^^^^^ - -- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). - -Local Environment: - -- AWS CLI installed: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html - -- Terraform installed: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli - -Set AWS credentials in your shell: - -.. code-block:: none - - export AWS_ACCESS_KEY_ID="" - export AWS_SECRET_ACCESS_KEY="" - export AWS_SESSION_TOKEN="" - export AWS_DEFAULT_REGION="" # e.g., us-east-1 - -Obtain VyOS AMI ID and Owner ID: - -Subscribe to VyOS via AWS Marketplace. Then run: - -.. code-block:: none - - aws ec2 describe-images \ - --owners aws-marketplace \ - --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ - --query 'Images[*].[ImageId,OwnerId,Name]' \ - --output table - -Alternatively, set the ``vyos_ami_id`` variable directly in ``variables.tf``. - -Generate an SSH keypair (or use the included demo key): - -.. code-block:: none - - ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem - chmod 400 keys/vyos_custom_key.pem - -Azure Environment -^^^^^^^^^^^^^^^^^ - -- Active Azure subscription: - -.. code-block:: none - - az account set --subscription "" - -- Azure CLI installed: - - https://learn.microsoft.com/en-us/cli/azure/install-azure-cli - -- Logged in with Azure credentials: - -.. code-block:: none - - az version - az login - -- Azure Resource Group (RG) created: - -.. code-block:: none - - az group create --name demoResourceGroup --location westus - az group list - az group show --name demoResourceGroup - -- Terraform installed: - - https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli - -- SSH key generated: - -.. code-block:: none - - ssh-keygen -t rsa -b 4096 -f keys/id_rsa - chmod 400 keys/id_rsa - -Usage ------ - -AWS -^^^ - -All variables needed for customization are defined in ``variables.tf``. -Adjust them according to your requirements, such as EC2 instance type and networking configurations. - -Before deployment, ensure you check ``aws_region``, ``availability_zone``, and update ``vyos_ami_id`` as necessary. - -Azure -^^^^^ - -All variables needed for customization are defined in ``variables.tf``. -Adjust them according to your requirements, such as VM size and networking configurations. - -Before deployment, ensure you check ``azure_region``, ``availability_zone``, and update ``subscription_id`` and ``resource_group_name`` as necessary. - -Terraform Workflow -^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - terraform init - terraform fmt - terraform validate - terraform plan - terraform apply - -On completion, run: - -.. code-block:: none - - terraform output - -This displays the public IP addresses of the VyOS instances. - -To clean up: - -.. code-block:: none - - terraform destroy - -Management ----------- - -SSH into VyOS: - -.. code-block:: none - - ssh vyos@ -i keys/vyos_custom_key.pem - -GitHub Repository ------------------ - -You can clone or download the Terraform projects and use them in your environment: - -https://github.com/vyos/vyos-automation/tree/main/Terraform/Cloud-to-Cloud diff --git a/docs/installation/cloud/azure-ha.md b/docs/installation/cloud/azure-ha.md new file mode 100644 index 00000000..fa94c222 --- /dev/null +++ b/docs/installation/cloud/azure-ha.md @@ -0,0 +1,128 @@ +# VyOS High Availability (HA) Deployment on Azure + +This document describes how to deploy VyOS in a High Availability (HA) configuration on Azure using Terraform and Azure Route Server to provide sub-second failover. + +## Why Use HA on Azure? + +This module provides a robust, repeatable foundation for building **resilient network architectures** in Azure. By combining VyOS routing features with Terraform and Azure-native services, it enables: + +- Rapid deployment of cloud edge routers. +- Full control over BGP route advertisement and filtering. +- Realistic HA and disaster recovery simulations. +- Seamless integration with hybrid or multi-cloud infrastructure. + +The architecture includes: + +- Two VyOS routers in a Transit VNet, configured with BGP. +- Azure Route Server for dynamic route distribution. +- Site-to-Site VPN connections to a simulated on-premises VyOS router. +- An Ubuntu VM for connectivity and routing validation. +- A Data VNet for testing and diagnostics. + +## Key Features + +- **High Availability**: Dual VyOS routers for redundancy and failover. +- **Dynamic Routing**: BGP-based routing via Azure Route Server. +- **Hybrid Connectivity**: Site-to-Site VPN integration with a simulated on-prem VyOS. +- **Testing Environment**: Includes Ubuntu VM for verification and diagnostics. +- **Modular & Flexible**: Easily configurable via variables. + +## HA Architecture Diagram + +:::{figure} /_static/images/cloud-azure-ha-architecture.png +:alt: VyOS HA topology diagram +::: + +This deployment architecture simulates a real-world enterprise network scenario for testing and validation purposes. + +## Terraform Automation + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on Azure. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. +- Azure Route Server. +- A Transit VNet and a Data VNet containing a test Ubuntu VM for connectivity validation. + +## Prerequisites + +Ensure you have: + +- Active Azure subscription: + +```none +az account set --subscription "" +``` + +- Azure CLI installed: + + + +- Logged in with Azure credentials: + +```none +az version +az login +``` + +- Azure Resource Group (RG) created: + +```none +az group create --name demoResourceGroup --location westus +az group list +az group show --name demoResourceGroup +``` + +- Terraform installed: + + + +- SSH key generated: + +```none +ssh-keygen -t rsa -b 4096 -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +## Usage + +All variables are defined in `variables.tf`. Adjust them to match your environment. + +Terraform Workflow: + +```none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +```none +terraform output +``` + +This displays the management IP and connectivity test results. + +To clean up: + +```none +terraform destroy +``` + +## Management + +SSH into VyOS: + +```none +ssh adminuser@ -i keys/vyos_custom_key.pem +``` + +## GitHub Repository + +You can clone or download the Terraform project and use them in your environment: + + diff --git a/docs/installation/cloud/azure-ha.rst b/docs/installation/cloud/azure-ha.rst deleted file mode 100755 index e943b550..00000000 --- a/docs/installation/cloud/azure-ha.rst +++ /dev/null @@ -1,152 +0,0 @@ -########## -VyOS High Availability (HA) Deployment on Azure -########## - - -This document describes how to deploy VyOS in a High Availability (HA) configuration on Azure using Terraform and Azure Route Server to provide sub-second failover. - -Why Use HA on Azure? --------------------- - -This module provides a robust, repeatable foundation for building **resilient network architectures** in Azure. By combining VyOS routing features with Terraform and Azure-native services, it enables: - -- Rapid deployment of cloud edge routers. - -- Full control over BGP route advertisement and filtering. - -- Realistic HA and disaster recovery simulations. - -- Seamless integration with hybrid or multi-cloud infrastructure. - -The architecture includes: - -- Two VyOS routers in a Transit VNet, configured with BGP. - -- Azure Route Server for dynamic route distribution. - -- Site-to-Site VPN connections to a simulated on-premises VyOS router. - -- An Ubuntu VM for connectivity and routing validation. - -- A Data VNet for testing and diagnostics. - -Key Features ------------- - -- **High Availability**: Dual VyOS routers for redundancy and failover. - -- **Dynamic Routing**: BGP-based routing via Azure Route Server. - -- **Hybrid Connectivity**: Site-to-Site VPN integration with a simulated on-prem VyOS. - -- **Testing Environment**: Includes Ubuntu VM for verification and diagnostics. - -- **Modular & Flexible**: Easily configurable via variables. - -HA Architecture Diagram ------------------------ - -.. figure:: /_static/images/cloud-azure-ha-architecture.png - :alt: VyOS HA topology diagram - -This deployment architecture simulates a real-world enterprise network scenario for testing and validation purposes. - -Terraform Automation --------------------- - -To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on Azure. - -This Terraform project automates the deployment of: - -- Two VyOS instances in HA mode. - -- Azure Route Server. - -- A Transit VNet and a Data VNet containing a test Ubuntu VM for connectivity validation. - -Prerequisites -------------- - -Ensure you have: - -- Active Azure subscription: - -.. code-block:: none - - az account set --subscription "" - -- Azure CLI installed: - - https://learn.microsoft.com/en-us/cli/azure/install-azure-cli - -- Logged in with Azure credentials: - -.. code-block:: none - - az version - az login - -- Azure Resource Group (RG) created: - -.. code-block:: none - - az group create --name demoResourceGroup --location westus - az group list - az group show --name demoResourceGroup - -- Terraform installed: - - https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli - -- SSH key generated: - -.. code-block:: none - - ssh-keygen -t rsa -b 4096 -f keys/vyos_custom_key.pem - chmod 400 keys/vyos_custom_key.pem - -Usage ------ - -All variables are defined in ``variables.tf``. Adjust them to match your environment. - -Terraform Workflow: - -.. code-block:: none - - terraform init - terraform fmt - terraform validate - terraform plan - terraform apply - -On completion, run: - -.. code-block:: none - - terraform output - -This displays the management IP and connectivity test results. - -To clean up: - -.. code-block:: none - - terraform destroy - -Management ----------- - -SSH into VyOS: - -.. code-block:: none - - ssh adminuser@ -i keys/vyos_custom_key.pem - - -GitHub Repository ------------------ - -You can clone or download the Terraform project and use them in your environment: - -https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure/azure-ha-deployment-with-configs diff --git a/docs/installation/cloud/azure.md b/docs/installation/cloud/azure.md new file mode 100644 index 00000000..aa577aa1 --- /dev/null +++ b/docs/installation/cloud/azure.md @@ -0,0 +1,378 @@ +# VyOS Deployment on Azure + +This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (Virtual Networks, Network Interfaces, Subnets, Security Groups) on Azure via the Azure Portal. + +## Prerequisites for Deploying VyOS on Azure + +### Azure Account + +Ensure you have an active Azure subscription. + +### Microsoft Entra ID Permissions + +To manage resources in **Azure Entra ID** (formerly Azure AD), you need appropriate permissions to handle **Virtual Networks**, **Public IP Addresses**, **Subnets**, and **Virtual Machines**. + +**Reference Documentation:** + + + + + + + +## Deployment Steps + +### Step 1: Create a Resource Group + +A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. + +#### Create resource groups + +- Go to the Azure Portal . +- Sign in with your Azure account credentials. +- In the portal, search for and select **Resource groups**. +- Select **Create**. + +:::{figure} /_static/images/cloud-azure-rg-01.png +::: + +- Enter the following values: +- **Subscription**: Select your Azure subscription. +- **Resource group**: Enter a new resource group name, e.g., `VyOSResourceGroup`. +- **Region**: Select an Azure location, such as Central US. +- Select **Review + Create** +- Select **Create**. It takes a few seconds to create a resource group. + +:::{figure} /_static/images/cloud-azure-rg-02.png +::: + +### Step 2: Create a Virtual Network (VNet) and Subnets + +Sign in to the Azure portal with your Azure account + +- In the portal, search for and select **Virtual networks**. +- On the **Virtual networks** page, select **+ Create**. +- On the **Basics** tab of **Create virtual network**, enter, or select the following information: +- **Subscription**: Select your Subscription +- **Resource Group**: Select e.g., `VyOSResourceGroup` +- **Name**: e.g., `VyOS-VirtualNetwork` +- **Region**: e.g., `West Europe`. + +:::{figure} /_static/images/cloud-azure-vnet-01.png +::: + +**IP addresses**: + +- Address Space: `10.1.0.0/16` + +:::{figure} /_static/images/cloud-azure-vnet-02.png +::: + +**Add two subnets**: + +- Name: e.g., `VyOS-Private-Subnet` + + Starting address: e.g., `10.1.1.0` + + Size: `/24` + +- Name: e.g., `VyOS-Public-Subnet` + + Starting address: e.g., `10.1.11.0` + + Size: `/24` + +:::{figure} /_static/images/cloud-azure-vnet-03.png +::: + +:::{figure} /_static/images/cloud-azure-vnet-04.png +::: + +:::{figure} /_static/images/cloud-azure-vnet-05.png +::: + +- Click **Review + Create** and then **Create**. + +### Step 3: Create and configure Network Security Group (NSG) + +- In the Azure Portal, search for and select **Network Security Groups**. +- On the **Network Security Groups** page, select **+ Create**. + +Enter the details: + +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Name**: e.g., `VyOS-SecurityGroup` +- **Region**: e.g., `West Europe`. + +:::{figure} /_static/images/cloud-azure-sg-01.png +::: + +- Click **Review + Create** and then **Create**. + +**Add inbound rules**: + +- Navigate to the **Network Security Groups** select **VyOS-SecurityGroup** go to **Inbound security rules** under **Settings** + +:::{figure} /_static/images/cloud-azure-sg-02.png +::: + +**Add Rule Example:** + +- **Rule 1**: AllowSSH + + > - **Port**: 22 + > - **Protocol**: TCP + > - **Source**: Any + > - **Priority**: 1001 + +**Add Additional Rules**: + +You can add inbound rules based on your specific services, such as: + +> - ESP +> - OpenVPN +> - WireGuard, etc. + +:::{figure} /_static/images/cloud-azure-sg-03.png +::: + +**Associate subnets**: + +- Navigate to the **Network Security Groups**, select **Subnets** click **+ Associate** button. Then select your virtual network and the subnet to which you want to associate the NSG. Select **OK**: + +:::{figure} /_static/images/cloud-azure-sg-04.png +::: + +### Step 4: Create Public IP Address + +- In the Azure Portal, search for and select **Public IP Addresses**. +- On the **Public IP Addresses** page, select **+ Create**. +- Provide the following details: +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Region**: `West Europe` + +:::{figure} /_static/images/cloud-azure-pub-ip-01.png +::: + +- **Name**: `VyOS-Pub-IP` +- **IP Version**: `IPv4` +- **SKU**: `Standard` +- **Availability zone**: Select Availability Zone + +:::{figure} /_static/images/cloud-azure-pub-ip-02.png +::: + +- **IP address assignment**: `Static` +- **Idle timeout (minutes)** `30` (max) + +:::{figure} /_static/images/cloud-azure-pub-ip-03.png +::: + +- Click **Review + Create**, then **Create**. + +### Step 5: Deploy the VyOS Network Virtual Machine (NVA) + +- In the Azure Portal, search for and select **Virtual Machines**. +- On the **Virtual Machines** page, click **+ Create** and select **Azure virtual machine**. +- Provide the following details: +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Virtual machine name**: e.g., `VyOS` +- **Region**: e.g., `West Europe` +- **Security type**: `Standard` +- **Image**: `VyOS` (On the marketplace search `VyOS` and choose the appropriate subscription). + +:::{figure} /_static/images/cloud-azure-vm-01.png +::: + +- **Size**: Select a VM size to support the workload that you want to run. The size that you choose then determines factors such as processing power, memory, and storage capacity. + +:::{figure} /_static/images/cloud-azure-vm-02.png +::: + +- **Password/SSH Key**: Choose whether the administrator account will use username/password or SSH keys for authentication. +- **Username**: The administrator username for the VM, e.g., `vyos`. +- **SSH Key**: You can use your existing SSH key pair or Azure automatically generates it for you and allows you to store it for future use. + +:::{figure} /_static/images/cloud-azure-vm-03.png +::: + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. +- **Public IP**: Select public IP address which created before `VyOS-Pub-IP`. + +:::{figure} /_static/images/cloud-azure-vm-04.png +::: + +- **Configure network security group**: Select existing Security Group `VyOS-SecurityGroup`. + +:::{figure} /_static/images/cloud-azure-vm-05.png +::: + +- Click **Review + Create**, then **Create**. +- Click **Download the private key and create resource** this will download private key to your computer and start creating Virtual Machine. + +:::{figure} /_static/images/cloud-azure-vm-06.png +::: + +- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. + +:::{figure} /_static/images/cloud-azure-vm-07.png +::: + +### Step 6: Access the VyOS instance + +- Access the VyOS instance using **SSH** protocol, **Public IP Address**, **Private Key**: + + ```none + $ ssh vyos@51.124.120.235 -i vyos_key.pem + vyos@VyOS:~$ + ``` + +### Step 7: Enable IP Forwarding in Network Interface + +This option allows the virtual machine on this network interface to act as a router and receive traffic addressed to other destinations. + +- On the **Virtual Machines** page, select `VyOS` VM, under **Networking** tab select **Network settings**, click network interface. + +:::{figure} /_static/images/cloud-azure-vm-12.png +::: + +- Enable IP forwarding and click the **Apply** button. + +:::{figure} /_static/images/cloud-azure-vm-13.png +::: + +### Step 8: Create and attach the second network interface (optional) + +Now instance has been deployed with one **eth0** `WAN` interface and want to add +new one. To add new interface an example **eth1** `LAN` you need shutdown the +instance. Attach the interface in the Azure portal and then start the instance. + +:::{note} +Azure does not allow you attach interface when the instance in the +**Running** state. +::: + +#### Create network interface: + +- In the Azure Portal, search for and select **Network Interfaces**. +- On the **Network Interfaces** page, select **+ Create**. + +:::{figure} /_static/images/cloud-azure-nic-01.png +::: + +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Name**: `VyOS-PRIV-NIC` +- **Subnet**: `VyOS-Private-Subnet` +- **Private IP**: `Dynamic` +- Click **Review + Create**, then **Create** + +:::{figure} /_static/images/cloud-azure-nic-02.png +::: + +- Enable **IP Forwarding** +- Navigate to **Network Interfaces** select `VyOS-PRIV-NIC` + +:::{figure} /_static/images/cloud-azure-nic-03.png +::: + +- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. + +:::{figure} /_static/images/cloud-azure-nic-04.png +::: + +#### Attach reate network interface: + +- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button + +:::{figure} /_static/images/cloud-azure-vm-08.png +::: + +- Go to **Networking** select **Network settings** and then select **Attach network interface** + +:::{figure} /_static/images/cloud-azure-vm-09.png +::: + +- Select existing (before created) network interface `VyOS-PRIV-NIC` and click the **OK** button. + +:::{figure} /_static/images/cloud-azure-vm-10.png +::: + +- Now you have attached second interface to your instance and you can start Virtual Machine. +- Go to **Overview** and click the **Start** button. + +:::{figure} /_static/images/cloud-azure-vm-11.png +::: + +### Setp 8: Absorbing Routes + +To route traffic from your Virtual Network (VNET) through the LAN interface of your VyOS Network Virtual Appliance (NVA), you need to create and configure a custom route table in Azure. + +- Step-by-Step Instructions: +- Navigate to **Route Tables** and click **+ Create**. + +Provide the following details: + +> - **Subscription**: Select your Subscription +> - **Resource Group**: Select `VyOSResourceGroup` +> - **Name**: `Route-VyOS` +> - **Region**: e.g., `West Europe` + +:::{figure} /_static/images/cloud-azure-route-01.png +::: + +- Click **Review + Create**, then **Create**. + +**Add a Route**: + +- Navigate to **Route Tables** and click the new created route (`Route-VyOS`). +- Go to **Routes** and click **+ Add** button. + +:::{figure} /_static/images/cloud-azure-route-02.png +::: + +Add following parameters: + +- **Name**: `Default-Route` +- **Destination type**: `IP Addresses` +- **Destination IP addresses/CIDR ranges**: `0.0.0.0/0` +- **Next Hop Type**: `Virtual Appliance` +- **Next Hop IP Address**: `10.1.11.4` (The private Network Interface Card IP Address) + +:::{figure} /_static/images/cloud-azure-route-03.png +::: + +- Click the **Add** button. + +**Associate the Route Table with subnet**: + +- Navigate to **Route Tables** and click the new created route (`VyOSResourceGroup`). +- Go to **Subnets** and click **+ Associate** button. + +:::{figure} /_static/images/cloud-azure-route-04.png +::: + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. + +:::{figure} /_static/images/cloud-azure-route-05.png +::: + +:::{note} +If you want to create a new default route for VMs on the subnet, use **Address Prefix** `0.0.0.0/0` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the `WAN` interface. +::: + +### Deploy VyOS Instance and Required Resources Automatically (via Terraform) + +You can deploy a VyOS instance and its associated resources in **Azure** using Terraform modules available in the GitHub repository. +All necessary parameters will be configured automatically, and you will receive **management and access information** from the outputs. + +You can also edit/change these parameters based on your requirements. + +- Download/Clone the Repository following GitHub repository: + + diff --git a/docs/installation/cloud/azure.rst b/docs/installation/cloud/azure.rst deleted file mode 100644 index 563fcb19..00000000 --- a/docs/installation/cloud/azure.rst +++ /dev/null @@ -1,433 +0,0 @@ -########## -VyOS Deployment on Azure -########## - - -This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (Virtual Networks, Network Interfaces, Subnets, Security Groups) on Azure via the Azure Portal. - -Prerequisites for Deploying VyOS on Azure -======== - -Azure Account ------------ - -Ensure you have an active Azure subscription. - -Microsoft Entra ID Permissions ------------ - -To manage resources in **Azure Entra ID** (formerly Azure AD), you need appropriate permissions to handle **Virtual Networks**, **Public IP Addresses**, **Subnets**, and **Virtual Machines**. - -**Reference Documentation:** - -https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/manage-roles-portal - -https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal - -https://learn.microsoft.com/en-us/azure/role-based-access-control/overview - -Deployment Steps -======== - -Step 1: Create a Resource Group ------------ - -A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. - -Create resource groups -^^^^^^^^^^^^^^ - -- Go to the Azure Portal https://portal.azure.com/. - -- Sign in with your Azure account credentials. - -- In the portal, search for and select **Resource groups**. - -- Select **Create**. - -.. figure:: /_static/images/cloud-azure-rg-01.png - -- Enter the following values: - -- **Subscription**: Select your Azure subscription. - -- **Resource group**: Enter a new resource group name, e.g., ``VyOSResourceGroup``. - -- **Region**: Select an Azure location, such as Central US. - -- Select **Review + Create** - -- Select **Create**. It takes a few seconds to create a resource group. - -.. figure:: /_static/images/cloud-azure-rg-02.png - - -Step 2: Create a Virtual Network (VNet) and Subnets ------------ - -Sign in to the Azure portal with your Azure account https://portal.azure.com/ - -- In the portal, search for and select **Virtual networks**. - -- On the **Virtual networks** page, select **+ Create**. - -- On the **Basics** tab of **Create virtual network**, enter, or select the following information: - -- **Subscription**: Select your Subscription - -- **Resource Group**: Select e.g., ``VyOSResourceGroup`` - -- **Name**: e.g., ``VyOS-VirtualNetwork`` - -- **Region**: e.g., ``West Europe``. - -.. figure:: /_static/images/cloud-azure-vnet-01.png - -**IP addresses**: - -- Address Space: ``10.1.0.0/16`` - -.. figure:: /_static/images/cloud-azure-vnet-02.png - -**Add two subnets**: - -- Name: e.g., ``VyOS-Private-Subnet`` - - Starting address: e.g., ``10.1.1.0`` - - Size: ``/24`` - -- Name: e.g., ``VyOS-Public-Subnet`` - - Starting address: e.g., ``10.1.11.0`` - - Size: ``/24`` - -.. figure:: /_static/images/cloud-azure-vnet-03.png - -.. figure:: /_static/images/cloud-azure-vnet-04.png - -.. figure:: /_static/images/cloud-azure-vnet-05.png - -- Click **Review + Create** and then **Create**. - - -Step 3: Create and configure Network Security Group (NSG) ------------ - -- In the Azure Portal, search for and select **Network Security Groups**. - -- On the **Network Security Groups** page, select **+ Create**. - -Enter the details: - -- **Subscription**: Select your Subscription - -- **Resource Group**: Select ``VyOSResourceGroup`` - -- **Name**: e.g., ``VyOS-SecurityGroup`` - -- **Region**: e.g., ``West Europe``. - -.. figure:: /_static/images/cloud-azure-sg-01.png - -- Click **Review + Create** and then **Create**. - -**Add inbound rules**: - -- Navigate to the **Network Security Groups** select **VyOS-SecurityGroup** go to **Inbound security rules** under **Settings** - -.. figure:: /_static/images/cloud-azure-sg-02.png - -**Add Rule Example:** - -- **Rule 1**: AllowSSH - - - **Port**: 22 - - - **Protocol**: TCP - - - **Source**: Any - - - **Priority**: 1001 - -**Add Additional Rules**: - -You can add inbound rules based on your specific services, such as: - - - ESP - - - OpenVPN - - - WireGuard, etc. - -.. figure:: /_static/images/cloud-azure-sg-03.png - -**Associate subnets**: - -- Navigate to the **Network Security Groups**, select **Subnets** click **+ Associate** button. Then select your virtual network and the subnet to which you want to associate the NSG. Select **OK**: - -.. figure:: /_static/images/cloud-azure-sg-04.png - - -Step 4: Create Public IP Address ------------ - -- In the Azure Portal, search for and select **Public IP Addresses**. - -- On the **Public IP Addresses** page, select **+ Create**. - -- Provide the following details: - -- **Subscription**: Select your Subscription - -- **Resource Group**: Select ``VyOSResourceGroup`` - -- **Region**: ``West Europe`` - -.. figure:: /_static/images/cloud-azure-pub-ip-01.png - -- **Name**: ``VyOS-Pub-IP`` - -- **IP Version**: ``IPv4`` - -- **SKU**: ``Standard`` - -- **Availability zone**: Select Availability Zone - -.. figure:: /_static/images/cloud-azure-pub-ip-02.png - -- **IP address assignment**: ``Static`` - -- **Idle timeout (minutes)** ``30`` (max) - -.. figure:: /_static/images/cloud-azure-pub-ip-03.png - -- Click **Review + Create**, then **Create**. - - -Step 5: Deploy the VyOS Network Virtual Machine (NVA) ------------ - -- In the Azure Portal, search for and select **Virtual Machines**. - -- On the **Virtual Machines** page, click **+ Create** and select **Azure virtual machine**. - -- Provide the following details: - -- **Subscription**: Select your Subscription - -- **Resource Group**: Select ``VyOSResourceGroup`` - -- **Virtual machine name**: e.g., ``VyOS`` - -- **Region**: e.g., ``West Europe`` - -- **Security type**: ``Standard`` - -- **Image**: ``VyOS`` (On the marketplace search ``VyOS`` and choose the appropriate subscription). - -.. figure:: /_static/images/cloud-azure-vm-01.png - -- **Size**: Select a VM size to support the workload that you want to run. The size that you choose then determines factors such as processing power, memory, and storage capacity. - -.. figure:: /_static/images/cloud-azure-vm-02.png - -- **Password/SSH Key**: Choose whether the administrator account will use username/password or SSH keys for authentication. - -- **Username**: The administrator username for the VM, e.g., ``vyos``. - -- **SSH Key**: You can use your existing SSH key pair or Azure automatically generates it for you and allows you to store it for future use. - -.. figure:: /_static/images/cloud-azure-vm-03.png - -- **Virtual network**: Select ``VyOS-VirtualNetwork``. - -- **Subnet**: Select ``VyOS-Public-Subnet``. - -- **Public IP**: Select public IP address which created before ``VyOS-Pub-IP``. - -.. figure:: /_static/images/cloud-azure-vm-04.png - -- **Configure network security group**: Select existing Security Group ``VyOS-SecurityGroup``. - -.. figure:: /_static/images/cloud-azure-vm-05.png - -- Click **Review + Create**, then **Create**. - -- Click **Download the private key and create resource** this will download private key to your computer and start creating Virtual Machine. - -.. figure:: /_static/images/cloud-azure-vm-06.png - -- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. - -.. figure:: /_static/images/cloud-azure-vm-07.png - - -Step 6: Access the VyOS instance ------------ - -- Access the VyOS instance using **SSH** protocol, **Public IP Address**, **Private Key**: - - .. code-block:: none - - $ ssh vyos@51.124.120.235 -i vyos_key.pem - vyos@VyOS:~$ - -Step 7: Enable IP Forwarding in Network Interface ------------ - -This option allows the virtual machine on this network interface to act as a router and receive traffic addressed to other destinations. - -- On the **Virtual Machines** page, select ``VyOS`` VM, under **Networking** tab select **Network settings**, click network interface. - -.. figure:: /_static/images/cloud-azure-vm-12.png - -- Enable IP forwarding and click the **Apply** button. - -.. figure:: /_static/images/cloud-azure-vm-13.png - -Step 8: Create and attach the second network interface (optional) -------------- - -Now instance has been deployed with one **eth0** ``WAN`` interface and want to add -new one. To add new interface an example **eth1** ``LAN`` you need shutdown the -instance. Attach the interface in the Azure portal and then start the instance. - -.. note:: Azure does not allow you attach interface when the instance in the - **Running** state. - - -Create network interface: -^^^^^^^^^^^^^^ - -- In the Azure Portal, search for and select **Network Interfaces**. - -- On the **Network Interfaces** page, select **+ Create**. - -.. figure:: /_static/images/cloud-azure-nic-01.png - -- **Subscription**: Select your Subscription - -- **Resource Group**: Select ``VyOSResourceGroup`` - -- **Name**: ``VyOS-PRIV-NIC`` - -- **Subnet**: ``VyOS-Private-Subnet`` - -- **Private IP**: ``Dynamic`` - -- Click **Review + Create**, then **Create** - -.. figure:: /_static/images/cloud-azure-nic-02.png - -- Enable **IP Forwarding** - -- Navigate to **Network Interfaces** select ``VyOS-PRIV-NIC`` - -.. figure:: /_static/images/cloud-azure-nic-03.png - -- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. - -.. figure:: /_static/images/cloud-azure-nic-04.png - - -Attach reate network interface: -^^^^^^^^^^^^^^ - -- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button - -.. figure:: /_static/images/cloud-azure-vm-08.png - -- Go to **Networking** select **Network settings** and then select **Attach network interface** - -.. figure:: /_static/images/cloud-azure-vm-09.png - -- Select existing (before created) network interface ``VyOS-PRIV-NIC`` and click the **OK** button. - -.. figure:: /_static/images/cloud-azure-vm-10.png - -- Now you have attached second interface to your instance and you can start Virtual Machine. - -- Go to **Overview** and click the **Start** button. - -.. figure:: /_static/images/cloud-azure-vm-11.png - - -Setp 8: Absorbing Routes ----------------- - -To route traffic from your Virtual Network (VNET) through the LAN interface of your VyOS Network Virtual Appliance (NVA), you need to create and configure a custom route table in Azure. - -- Step-by-Step Instructions: - -- Navigate to **Route Tables** and click **+ Create**. - -Provide the following details: - - - **Subscription**: Select your Subscription - - - **Resource Group**: Select ``VyOSResourceGroup`` - - - **Name**: ``Route-VyOS`` - - - **Region**: e.g., ``West Europe`` - -.. figure:: /_static/images/cloud-azure-route-01.png - -- Click **Review + Create**, then **Create**. - -**Add a Route**: - -- Navigate to **Route Tables** and click the new created route (``Route-VyOS``). - -- Go to **Routes** and click **+ Add** button. - -.. figure:: /_static/images/cloud-azure-route-02.png - -Add following parameters: - -- **Name**: ``Default-Route`` - -- **Destination type**: ``IP Addresses`` - -- **Destination IP addresses/CIDR ranges**: ``0.0.0.0/0`` - -- **Next Hop Type**: ``Virtual Appliance`` - -- **Next Hop IP Address**: ``10.1.11.4`` (The private Network Interface Card IP Address) - -.. figure:: /_static/images/cloud-azure-route-03.png - -- Click the **Add** button. - -**Associate the Route Table with subnet**: - -- Navigate to **Route Tables** and click the new created route (``VyOSResourceGroup``). - -- Go to **Subnets** and click **+ Associate** button. - -.. figure:: /_static/images/cloud-azure-route-04.png - -- **Virtual network**: Select ``VyOS-VirtualNetwork``. - -- **Subnet**: Select ``VyOS-Public-Subnet``. - -.. figure:: /_static/images/cloud-azure-route-05.png - -.. note:: If you want to create a new default route for VMs on the subnet, use **Address Prefix** ``0.0.0.0/0`` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the ``WAN`` interface. - - -Deploy VyOS Instance and Required Resources Automatically (via Terraform) --------------- - -You can deploy a VyOS instance and its associated resources in **Azure** using Terraform modules available in the GitHub repository. -All necessary parameters will be configured automatically, and you will receive **management and access information** from the outputs. - -You can also edit/change these parameters based on your requirements. - -- Download/Clone the Repository following GitHub repository: - -https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure - - diff --git a/docs/installation/cloud/gcp.md b/docs/installation/cloud/gcp.md new file mode 100644 index 00000000..7144f083 --- /dev/null +++ b/docs/installation/cloud/gcp.md @@ -0,0 +1,260 @@ +# VyOS Deployment on Google Cloud Platform + +This guide provides step-by-step instructions for deploying a VyOS instance with two NICs and the required resources on Google Cloud Platform (GCP). + +## Prerequisites + +Before proceeding, ensure the following: + +- A GCP account with billing enabled. +- Permissions to deploy Marketplace images. +- Access to enable APIs and create resources (e.g., Compute Engine Admin, Network Admin). +- An SSH key pair for VyOS instance access. +- GA Google Cloud Project. + +## Deployment Steps + +### Step 1: Add SSH Key + +1. If you don’t already have SSH keys, generate an SSH key pair of type `ssh-rsa` on your local machine: + +> Example: +> +> ```none +> ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" +> ``` + +:::{note} +In the comment `vyos@mypc`, the username must start with vyos. +This is because the default user in the VyOS image is `vyos`, and the Google Cloud API uses this value for SSH access. +::: + +2. Open GCP console and navigate to the **Compute Engine** > **Metadata** > **SSH Keys**. Choose + **SSH Keys**. + +:::{figure} /_static/images/cloud-gcp-01.png +::: + +3. Click **edit** and **Add item**. +4. Paste your public ssh key and **Save**. + +:::{figure} /_static/images/cloud-gcp-02.png +::: + +For more information, please visit the official Google Cloud documentation: + + + + + +### Step 2: Create a Service Account (If You Don't Have One) + +1. In the Google Cloud console **IAM & Admin > Service Accounts**. +2. Select select a project. + +:::{figure} /_static/images/cloud-gcp-proj.png +::: + +3. Click **Create Service Account**: + + - Name: e.g., `vyos-test` + - Service account ID: e.g., `vyos-test` + - Description: e.g., `VyOS Test Service Account` + +4. Click **Done**. + +:::{figure} /_static/images/cloud-gcp-svc.png +::: + +For more information, please visit the official Google Cloud documentation: + + + + + +### Step 3: Create VPC Networks and Subnets + +1. In the Google Cloud console **VPC Network > VPC Networks** +2. Select select a project. + +:::{figure} /_static/images/cloud-gcp-proj.png +::: + +3. Click **Create VPC Network**. + + **Public VPC**: + + - Name: e.g., `vyos-public-vpc` + - Subnet creation mode: `Custom` + - Subnet name: e.g., `vyos-public-subnet` + - Region: e.g., `europe-west1` + - IP range: e.g., `10.0.1.0/24` + - Leave all other settings at default, then click **Create**. + +:::{figure} /_static/images/cloud-gcp-vpc-01.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-02.png +**Private VPC**: + +- Name: `vyos-private-vpc` +- Subnet creation mode: `Custom` +- Subnet name: `vyos-private-subnet` +- Region: e.g., `europe-west1` +- IP range: `10.0.11.0/24` +- Leave all other settings at default, then click **Create**. +::: + +:::{figure} /_static/images/cloud-gcp-vpc-03.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-04.png +::: + +4. Add firewall rules to allow specific network traffic from the Internet if needed. By default, all incoming traffic from outside the network is blocked. Typically, a VyOS deployment from the GCP Marketplace configures this automatically, ensuring that SSH access is enabled after deployment. + +:::{figure} /_static/images/cloud-gcp-vpc-05.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-06.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-07.png +::: + +For more information, please visit the official Google Cloud documentation: + + + +### Step 4: Deploy VyOS instance from Marketplace + +1. Go to the Google Cloud Marketplace page in the Google Cloud console +2. Choose the project where you want to deploy the VyOS instance. + +:::{figure} /_static/images/cloud-gcp-proj.png +::: + +3. In the search bar, type `vyos` to find the VyOS image in the Marketplace. + +:::{figure} /_static/images/cloud-gcp-market-01.png +::: + +:::{figure} /_static/images/cloud-gcp-market-02.png +::: + +4. On the next page, review details such as support, pricing, and other details. + +:::{figure} /_static/images/cloud-gcp-market-03.png +::: + +5. Click the `GET STARTED` button to start deployment process. + +:::{figure} /_static/images/cloud-gcp-market-04.png +::: + +:::{figure} /_static/images/cloud-gcp-market-05.png +::: + +6. General settings. + + - Deployment name: e.g., `vyos-test-vm` + - Select a Service Account: Select the service account created earlier. + - Image: Select VyOS image for deployment. + - Zone: e.g., `europe-west1-b` + - Machine type: Choose based on performance and resource needs. + +:::{figure} /_static/images/cloud-gcp-vm-01.png +::: + +:::{figure} /_static/images/cloud-gcp-vm-02.png +::: + +7. Configure the network interfaces. + + **Public Network interface:** + + Edit the first (default) network interface and select following settings: + + > - Network: `vyos-public-vpc` + > - Subnetwork: `vyos-public-subnet` + > - External IP: `Ephemeral` + > - Private Network interface: + + **Private Network Interface:** + + Click **ADD A NETWORK INTERFACE** button to create a second (private) interface, and select following settings: + + > - Network: `vyos-private-vpc` + > - Subnetwork: `vyos-private-subnet` + > - External IP: `None` + +:::{figure} /_static/images/cloud-gcp-vm-03.png +::: + +8. Deployment automation. + + - You can use `cloud-init` `User Data` to automatically inject specific configuration commands into the VyOS instance during deployment. + - Example: + +> ```none +> #cloud-config +> vyos_config_commands: +> - set system host-name 'VyOS-for-GCP' +> - set system login banner pre-login 'Welcome to the VyOS for on GCP' +> - set interfaces ethernet eth0 description 'WAN' +> - set interfaces ethernet eth1 description 'LAN' +> - set interfaces ethernet eth1 address 'dhcp' +> - set interfaces ethernet eth1 dhcp-options no-default-route +> ``` + +For more information, please visit the documentation: + + + +:::{figure} /_static/images/cloud-gcp-vm-09.png +::: + +9. Click `Deploy` button. + +:::{figure} /_static/images/cloud-gcp-vm-06.png +::: + +:::{figure} /_static/images/cloud-gcp-vm-07.png +::: + +### Connect to the VyOS instance + +To connect to the VyOS instance, use the SSH key that was generated in the first step. + +To retrieve the public IP address, go to the **Google Cloud Console** and navigate to: **Compute Engine** > **VM instances** + +:::{figure} /_static/images/cloud-gcp-vm-08.png +::: + +Example: + +> ```none +> ssh vyos@35.233.97.132 -i .ssh/vyos_gcp +> +> The authenticity of host '35.233.97.132 (35.233.97.132)' can't be established. +> ED25519 key fingerprint is SHA256:KCsCnwCGhwX2ba5RcPUAO3ZUSNzS4sXIkujFoScCd0g. +> This key is not known by any other names +> Are you sure you want to continue connecting (yes/no/[fingerprint])? yes +> Warning: Permanently added '35.233.97.132' (ED25519) to the list of known hosts. +> Welcome to the VyOS for on GCP +> Welcome to VyOS! +> +> ┌── ┐ +> . VyOS 1.4.2 +> └ ──┘ sagitta +> +> * Documentation: https://docs.vyos.io/en/sagitta +> * Project news: https://blog.vyos.io +> * Bug reports: https://vyos.dev +> +> You can change this banner using "set system login banner post-login" command. +> +> VyOS is a free software distribution that includes multiple components, +> you can check individual component licenses under /usr/share/doc/*/copyright +> vyos@VyOS-for-GCP:~$ +> ``` diff --git a/docs/installation/cloud/gcp.rst b/docs/installation/cloud/gcp.rst deleted file mode 100644 index 0c23353e..00000000 --- a/docs/installation/cloud/gcp.rst +++ /dev/null @@ -1,277 +0,0 @@ -##################### -VyOS Deployment on Google Cloud Platform -##################### - -This guide provides step-by-step instructions for deploying a VyOS instance with two NICs and the required resources on Google Cloud Platform (GCP). - -Prerequisites -======== - -Before proceeding, ensure the following: - -- A GCP account with billing enabled. -- Permissions to deploy Marketplace images. -- Access to enable APIs and create resources (e.g., Compute Engine Admin, Network Admin). -- An SSH key pair for VyOS instance access. -- GA Google Cloud Project. - -Deployment Steps -======== - -Step 1: Add SSH Key -------------------- - -1. If you don’t already have SSH keys, generate an SSH key pair of type ``ssh-rsa`` on your local machine: - - Example: - - .. code-block:: none - - ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" - - -.. note:: In the comment ``vyos@mypc``, the username must start with vyos. - This is because the default user in the VyOS image is ``vyos``, and the Google Cloud API uses this value for SSH access. - -2. Open GCP console and navigate to the **Compute Engine** > **Metadata** > **SSH Keys**. Choose - **SSH Keys**. - -.. figure:: /_static/images/cloud-gcp-01.png - - -3. Click **edit** and **Add item**. - -4. Paste your public ssh key and **Save**. - -.. figure:: /_static/images/cloud-gcp-02.png - -For more information, please visit the official Google Cloud documentation: - -https://cloud.google.com/compute/docs/connect/add-ssh-keys - -https://cloud.google.com/compute/docs/connect/create-ssh-keys - - -Step 2: Create a Service Account (If You Don't Have One) -------------------------------- - -1. In the Google Cloud console **IAM & Admin > Service Accounts**. - -2. Select select a project. - -.. figure:: /_static/images/cloud-gcp-proj.png - -3. Click **Create Service Account**: - - - Name: e.g., ``vyos-test`` - - - Service account ID: e.g., ``vyos-test`` - - - Description: e.g., ``VyOS Test Service Account`` - -4. Click **Done**. - -.. figure:: /_static/images/cloud-gcp-svc.png - -For more information, please visit the official Google Cloud documentation: - -https://cloud.google.com/iam/docs/service-accounts-create - -https://cloud.google.com/iam/docs/service-account-overview - - -Step 3: Create VPC Networks and Subnets -------------------------------- - -1. In the Google Cloud console **VPC Network > VPC Networks** https://console.cloud.google.com/networking/networks/list - -2. Select select a project. - -.. figure:: /_static/images/cloud-gcp-proj.png - -3. Click **Create VPC Network**. - - **Public VPC**: - - - Name: e.g., ``vyos-public-vpc`` - - - Subnet creation mode: ``Custom`` - - - Subnet name: e.g., ``vyos-public-subnet`` - - - Region: e.g., ``europe-west1`` - - - IP range: e.g., ``10.0.1.0/24`` - - - Leave all other settings at default, then click **Create**. - -.. figure:: /_static/images/cloud-gcp-vpc-01.png - -.. figure:: /_static/images/cloud-gcp-vpc-02.png - - **Private VPC**: - - - Name: ``vyos-private-vpc`` - - - Subnet creation mode: ``Custom`` - - - Subnet name: ``vyos-private-subnet`` - - - Region: e.g., ``europe-west1`` - - - IP range: ``10.0.11.0/24`` - - - Leave all other settings at default, then click **Create**. - -.. figure:: /_static/images/cloud-gcp-vpc-03.png - -.. figure:: /_static/images/cloud-gcp-vpc-04.png - -4. Add firewall rules to allow specific network traffic from the Internet if needed. By default, all incoming traffic from outside the network is blocked. Typically, a VyOS deployment from the GCP Marketplace configures this automatically, ensuring that SSH access is enabled after deployment. - -.. figure:: /_static/images/cloud-gcp-vpc-05.png - -.. figure:: /_static/images/cloud-gcp-vpc-06.png - -.. figure:: /_static/images/cloud-gcp-vpc-07.png - -For more information, please visit the official Google Cloud documentation: - -https://cloud.google.com/vpc/docs/create-modify-vpc-networks - - -Step 4: Deploy VyOS instance from Marketplace ---------- - -1. Go to the Google Cloud Marketplace page in the Google Cloud console https://console.cloud.google.com/marketplace - -2. Choose the project where you want to deploy the VyOS instance. - -.. figure:: /_static/images/cloud-gcp-proj.png - -3. In the search bar, type ``vyos`` to find the VyOS image in the Marketplace. - -.. figure:: /_static/images/cloud-gcp-market-01.png - -.. figure:: /_static/images/cloud-gcp-market-02.png - -4. On the next page, review details such as support, pricing, and other details. - -.. figure:: /_static/images/cloud-gcp-market-03.png - -5. Click the ``GET STARTED`` button to start deployment process. - -.. figure:: /_static/images/cloud-gcp-market-04.png - -.. figure:: /_static/images/cloud-gcp-market-05.png - -6. General settings. - - - Deployment name: e.g., ``vyos-test-vm`` - - - Select a Service Account: Select the service account created earlier. - - - Image: Select VyOS image for deployment. - - - Zone: e.g., ``europe-west1-b`` - - - Machine type: Choose based on performance and resource needs. - -.. figure:: /_static/images/cloud-gcp-vm-01.png - -.. figure:: /_static/images/cloud-gcp-vm-02.png - -7. Configure the network interfaces. - - **Public Network interface:** - - Edit the first (default) network interface and select following settings: - - - Network: ``vyos-public-vpc`` - - - Subnetwork: ``vyos-public-subnet`` - - - External IP: ``Ephemeral`` - - - Private Network interface: - - **Private Network Interface:** - - Click **ADD A NETWORK INTERFACE** button to create a second (private) interface, and select following settings: - - - Network: ``vyos-private-vpc`` - - - Subnetwork: ``vyos-private-subnet`` - - - External IP: ``None`` - -.. figure:: /_static/images/cloud-gcp-vm-03.png - -8. Deployment automation. - - - You can use ``cloud-init`` ``User Data`` to automatically inject specific configuration commands into the VyOS instance during deployment. - - - Example: - - .. code-block:: none - - #cloud-config - vyos_config_commands: - - set system host-name 'VyOS-for-GCP' - - set system login banner pre-login 'Welcome to the VyOS for on GCP' - - set interfaces ethernet eth0 description 'WAN' - - set interfaces ethernet eth1 description 'LAN' - - set interfaces ethernet eth1 address 'dhcp' - - set interfaces ethernet eth1 dhcp-options no-default-route - -For more information, please visit the documentation: - -https://docs.vyos.io/en/stable/automation/cloud-init.html#module-vyos-userdata - -.. figure:: /_static/images/cloud-gcp-vm-09.png - -9. Click ``Deploy`` button. - -.. figure:: /_static/images/cloud-gcp-vm-06.png - -.. figure:: /_static/images/cloud-gcp-vm-07.png - - -Connect to the VyOS instance ------------ - -To connect to the VyOS instance, use the SSH key that was generated in the first step. - -To retrieve the public IP address, go to the **Google Cloud Console** and navigate to: **Compute Engine** > **VM instances** https://console.cloud.google.com/compute/instances?project=vyos-images - -.. figure:: /_static/images/cloud-gcp-vm-08.png - -Example: - - .. code-block:: none - - ssh vyos@35.233.97.132 -i .ssh/vyos_gcp - - The authenticity of host '35.233.97.132 (35.233.97.132)' can't be established. - ED25519 key fingerprint is SHA256:KCsCnwCGhwX2ba5RcPUAO3ZUSNzS4sXIkujFoScCd0g. - This key is not known by any other names - Are you sure you want to continue connecting (yes/no/[fingerprint])? yes - Warning: Permanently added '35.233.97.132' (ED25519) to the list of known hosts. - Welcome to the VyOS for on GCP - Welcome to VyOS! - - ┌── ┐ - . VyOS 1.4.2 - └ ──┘ sagitta - - * Documentation: https://docs.vyos.io/en/sagitta - * Project news: https://blog.vyos.io - * Bug reports: https://vyos.dev - - You can change this banner using "set system login banner post-login" command. - - VyOS is a free software distribution that includes multiple components, - you can check individual component licenses under /usr/share/doc/*/copyright - vyos@VyOS-for-GCP:~$ - - diff --git a/docs/installation/cloud/index.md b/docs/installation/cloud/index.md new file mode 100644 index 00000000..f64883fc --- /dev/null +++ b/docs/installation/cloud/index.md @@ -0,0 +1,14 @@ +# Running VyOS in Cloud Environments + +```{eval-rst} +.. toctree:: + :caption: Content + + aws + aws-ha + azure + azure-ha + aws-to-azure + gcp + oracle +``` diff --git a/docs/installation/cloud/index.rst b/docs/installation/cloud/index.rst deleted file mode 100644 index 7a17f18d..00000000 --- a/docs/installation/cloud/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -################################## -Running VyOS in Cloud Environments -################################## - - - -.. toctree:: - :caption: Content - - aws - aws-ha - azure - azure-ha - aws-to-azure - gcp - oracle \ No newline at end of file diff --git a/docs/installation/cloud/md-aws-ha.md b/docs/installation/cloud/md-aws-ha.md deleted file mode 100644 index f32e2ab5..00000000 --- a/docs/installation/cloud/md-aws-ha.md +++ /dev/null @@ -1,135 +0,0 @@ -# VyOS High Availability (HA) Deployment on AWS - -This document describes how to deploy VyOS in a High Availability (HA) configuration on AWS using Terraform and a VPC Route Server to provide sub-second failover. - -## Why Use HA on AWS? - -This solution helps organizations achieve **high availability** routing with dynamic connectivity to multiple AWS VPCs or hybrid environments. - -Key Advantages: - -- Utilizes **AWS VPC Route Server** to manage BGP routes dynamically. - -- Deploys two VyOS EC2 instances as BGP peers connected to the Route Server. Although both participate, one is typically preferred as the next-hop. - -- Employs **Bidirectional Forwarding Detection (BFD)** for rapid failure detection. - -- On failure: - - - Withdraws the failed peer’s routes from the RIB. - - Recomputes the optimal path in the FIB. - - Updates VPC route tables to point to the active instance. - -- Enables **sub-second failover** (< 1 s), outperforming AWS API-based route table failover. - -This architecture supports: - -- Cloud edge routing with failover. -- Hybrid cloud resiliency. -- Rapid recovery during instance crashes, upgrades, or network disruptions. -- Continuity for mission-critical operations. - -## HA Architecture Diagram - -:::{figure} /_static/images/cloud-aws-ha-architecture.png -:alt: VyOS HA topology diagram -::: - -## Terraform Automation - -To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on AWS. - -This Terraform project automates the deployment of: - -- Two VyOS instances in HA mode. -- VPC Route Server. -- Transit Gateway. -- A Transit VPC and a Data VPC containing a test Amazon Linux EC2 instance for connectivity validation. - -To integrate with existing AWS infrastructure: - -- Remove the Data VPC, its subnets, and EC2 test instance. -- Update `main.tf`, `network.tf`, `transit_gateway.tf`, `variables.tf`, and `outputs.tf` accordingly. - -## Prerequisites - -AWS Environment: - -- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). - -Local Environment: - -- AWS CLI installed: -- Terraform installed: - -Set AWS credentials in your shell: - -```none -export AWS_ACCESS_KEY_ID="" -export AWS_SECRET_ACCESS_KEY="" -export AWS_SESSION_TOKEN="" -export AWS_DEFAULT_REGION="" # e.g., us-east-1 -``` - -Obtain VyOS AMI ID and Owner ID: - -Subscribe to VyOS via AWS Marketplace. Then run: - -```none -aws ec2 describe-images \ - --owners aws-marketplace \ - --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ - --query 'Images[*].[ImageId,OwnerId,Name]' \ - --output table -``` - -Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. - -Generate an SSH keypair (or use the included demo key): - -```none -ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem -chmod 400 keys/vyos_custom_key.pem -``` - -## Usage - -Configure variables in `variables.tf`, including instance type, region, and `vyos_ami_id`. - -Terraform Workflow: - -```none -terraform init -terraform fmt -terraform validate -terraform plan -terraform apply -``` - -On completion, run: - -```none -terraform output -``` - -This displays the management IP and connectivity test results. - -To clean up: - -```none -terraform destroy -``` - -## Management - -SSH into VyOS: - -```none -ssh vyos@ -i keys/vyos_custom_key.pem -``` - -## GitHub Repository - -You can clone or download the Terraform project and use them in your environment: - - diff --git a/docs/installation/cloud/md-aws-to-azure.md b/docs/installation/cloud/md-aws-to-azure.md deleted file mode 100644 index 246df5f3..00000000 --- a/docs/installation/cloud/md-aws-to-azure.md +++ /dev/null @@ -1,175 +0,0 @@ -# VyOS Deployment on AWS and Azure for Secure Cloud-to-Cloud Connectivity - -This document provides step-by-step guidance for deploying VyOS routers on both AWS and Azure. -It describes how to establish secure inter-cloud connectivity using IPsec tunnels with BGP, -automated through Terraform. Example workloads (Amazon Linux EC2 on AWS and Ubuntu VM on Azure) -are also deployed for connectivity validation. - -## Why Cloud-to-Cloud Connectivity? - -Cloud-to-cloud connectivity is needed in modern multi-cloud environments for several reasons: - -- **Inter-Cloud Connectivity** - - Enable secure and reliable communication between workloads in different clouds - (for example, AWS applications connecting to Azure-hosted identity services). - -- **Cloud-to-Cloud Migration** - - During migration projects, workloads may temporarily run in both clouds. - Direct tunnels ensure smooth transition and synchronization. - -- **Testing and Validation** - - Labs and proof-of-concepts often simulate multi-cloud architectures. - A VyOS-based tunnel lets teams test routing, encryption, and failover before production rollout. - -## Architecture - -The architecture consists of VyOS routers deployed in both AWS and Azure, connected via secure IPsec tunnels. -BGP is used for dynamic routing between the clouds, allowing for seamless communication. - -:::{figure} /_static/images/cloud-aws-to-azure.png -:alt: VyOS Cloud-to-Cloud topology diagram -::: - -## Terraform Automation - -To streamline and standardize the deployment process, a set of **Terraform projects** has been developed. -These projects automate the provisioning of **VyOS instances** and the required networking resources across **AWS** and **Azure**. - -In addition to deploying VyOS, these projects also provision an **Amazon Linux EC2 instance** on AWS and an **Ubuntu VM** on Azure. -These serve as test endpoints to validate connectivity between the cloud environments. - -## Prerequisites - -### AWS Environment - -- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). - -Local Environment: - -- AWS CLI installed: -- Terraform installed: - -Set AWS credentials in your shell: - -```none -export AWS_ACCESS_KEY_ID="" -export AWS_SECRET_ACCESS_KEY="" -export AWS_SESSION_TOKEN="" -export AWS_DEFAULT_REGION="" # e.g., us-east-1 -``` - -Obtain VyOS AMI ID and Owner ID: - -Subscribe to VyOS via AWS Marketplace. Then run: - -```none -aws ec2 describe-images \ - --owners aws-marketplace \ - --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ - --query 'Images[*].[ImageId,OwnerId,Name]' \ - --output table -``` - -Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. - -Generate an SSH keypair (or use the included demo key): - -```none -ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem -chmod 400 keys/vyos_custom_key.pem -``` - -### Azure Environment - -- Active Azure subscription: - -```none -az account set --subscription "" -``` - -- Azure CLI installed: - - - -- Logged in with Azure credentials: - -```none -az version -az login -``` - -- Azure Resource Group (RG) created: - -```none -az group create --name demoResourceGroup --location westus -az group list -az group show --name demoResourceGroup -``` - -- Terraform installed: - - - -- SSH key generated: - -```none -ssh-keygen -t rsa -b 4096 -f keys/id_rsa -chmod 400 keys/id_rsa -``` - -## Usage - -### AWS - -All variables needed for customization are defined in `variables.tf`. -Adjust them according to your requirements, such as EC2 instance type and networking configurations. - -Before deployment, ensure you check `aws_region`, `availability_zone`, and update `vyos_ami_id` as necessary. - -### Azure - -All variables needed for customization are defined in `variables.tf`. -Adjust them according to your requirements, such as VM size and networking configurations. - -Before deployment, ensure you check `azure_region`, `availability_zone`, and update `subscription_id` and `resource_group_name` as necessary. - -### Terraform Workflow - -```none -terraform init -terraform fmt -terraform validate -terraform plan -terraform apply -``` - -On completion, run: - -```none -terraform output -``` - -This displays the public IP addresses of the VyOS instances. - -To clean up: - -```none -terraform destroy -``` - -## Management - -SSH into VyOS: - -```none -ssh vyos@ -i keys/vyos_custom_key.pem -``` - -## GitHub Repository - -You can clone or download the Terraform projects and use them in your environment: - - diff --git a/docs/installation/cloud/md-azure-ha.md b/docs/installation/cloud/md-azure-ha.md deleted file mode 100644 index fa94c222..00000000 --- a/docs/installation/cloud/md-azure-ha.md +++ /dev/null @@ -1,128 +0,0 @@ -# VyOS High Availability (HA) Deployment on Azure - -This document describes how to deploy VyOS in a High Availability (HA) configuration on Azure using Terraform and Azure Route Server to provide sub-second failover. - -## Why Use HA on Azure? - -This module provides a robust, repeatable foundation for building **resilient network architectures** in Azure. By combining VyOS routing features with Terraform and Azure-native services, it enables: - -- Rapid deployment of cloud edge routers. -- Full control over BGP route advertisement and filtering. -- Realistic HA and disaster recovery simulations. -- Seamless integration with hybrid or multi-cloud infrastructure. - -The architecture includes: - -- Two VyOS routers in a Transit VNet, configured with BGP. -- Azure Route Server for dynamic route distribution. -- Site-to-Site VPN connections to a simulated on-premises VyOS router. -- An Ubuntu VM for connectivity and routing validation. -- A Data VNet for testing and diagnostics. - -## Key Features - -- **High Availability**: Dual VyOS routers for redundancy and failover. -- **Dynamic Routing**: BGP-based routing via Azure Route Server. -- **Hybrid Connectivity**: Site-to-Site VPN integration with a simulated on-prem VyOS. -- **Testing Environment**: Includes Ubuntu VM for verification and diagnostics. -- **Modular & Flexible**: Easily configurable via variables. - -## HA Architecture Diagram - -:::{figure} /_static/images/cloud-azure-ha-architecture.png -:alt: VyOS HA topology diagram -::: - -This deployment architecture simulates a real-world enterprise network scenario for testing and validation purposes. - -## Terraform Automation - -To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on Azure. - -This Terraform project automates the deployment of: - -- Two VyOS instances in HA mode. -- Azure Route Server. -- A Transit VNet and a Data VNet containing a test Ubuntu VM for connectivity validation. - -## Prerequisites - -Ensure you have: - -- Active Azure subscription: - -```none -az account set --subscription "" -``` - -- Azure CLI installed: - - - -- Logged in with Azure credentials: - -```none -az version -az login -``` - -- Azure Resource Group (RG) created: - -```none -az group create --name demoResourceGroup --location westus -az group list -az group show --name demoResourceGroup -``` - -- Terraform installed: - - - -- SSH key generated: - -```none -ssh-keygen -t rsa -b 4096 -f keys/vyos_custom_key.pem -chmod 400 keys/vyos_custom_key.pem -``` - -## Usage - -All variables are defined in `variables.tf`. Adjust them to match your environment. - -Terraform Workflow: - -```none -terraform init -terraform fmt -terraform validate -terraform plan -terraform apply -``` - -On completion, run: - -```none -terraform output -``` - -This displays the management IP and connectivity test results. - -To clean up: - -```none -terraform destroy -``` - -## Management - -SSH into VyOS: - -```none -ssh adminuser@ -i keys/vyos_custom_key.pem -``` - -## GitHub Repository - -You can clone or download the Terraform project and use them in your environment: - - diff --git a/docs/installation/cloud/md-azure.md b/docs/installation/cloud/md-azure.md deleted file mode 100644 index aa577aa1..00000000 --- a/docs/installation/cloud/md-azure.md +++ /dev/null @@ -1,378 +0,0 @@ -# VyOS Deployment on Azure - -This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (Virtual Networks, Network Interfaces, Subnets, Security Groups) on Azure via the Azure Portal. - -## Prerequisites for Deploying VyOS on Azure - -### Azure Account - -Ensure you have an active Azure subscription. - -### Microsoft Entra ID Permissions - -To manage resources in **Azure Entra ID** (formerly Azure AD), you need appropriate permissions to handle **Virtual Networks**, **Public IP Addresses**, **Subnets**, and **Virtual Machines**. - -**Reference Documentation:** - - - - - - - -## Deployment Steps - -### Step 1: Create a Resource Group - -A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. - -#### Create resource groups - -- Go to the Azure Portal . -- Sign in with your Azure account credentials. -- In the portal, search for and select **Resource groups**. -- Select **Create**. - -:::{figure} /_static/images/cloud-azure-rg-01.png -::: - -- Enter the following values: -- **Subscription**: Select your Azure subscription. -- **Resource group**: Enter a new resource group name, e.g., `VyOSResourceGroup`. -- **Region**: Select an Azure location, such as Central US. -- Select **Review + Create** -- Select **Create**. It takes a few seconds to create a resource group. - -:::{figure} /_static/images/cloud-azure-rg-02.png -::: - -### Step 2: Create a Virtual Network (VNet) and Subnets - -Sign in to the Azure portal with your Azure account - -- In the portal, search for and select **Virtual networks**. -- On the **Virtual networks** page, select **+ Create**. -- On the **Basics** tab of **Create virtual network**, enter, or select the following information: -- **Subscription**: Select your Subscription -- **Resource Group**: Select e.g., `VyOSResourceGroup` -- **Name**: e.g., `VyOS-VirtualNetwork` -- **Region**: e.g., `West Europe`. - -:::{figure} /_static/images/cloud-azure-vnet-01.png -::: - -**IP addresses**: - -- Address Space: `10.1.0.0/16` - -:::{figure} /_static/images/cloud-azure-vnet-02.png -::: - -**Add two subnets**: - -- Name: e.g., `VyOS-Private-Subnet` - - Starting address: e.g., `10.1.1.0` - - Size: `/24` - -- Name: e.g., `VyOS-Public-Subnet` - - Starting address: e.g., `10.1.11.0` - - Size: `/24` - -:::{figure} /_static/images/cloud-azure-vnet-03.png -::: - -:::{figure} /_static/images/cloud-azure-vnet-04.png -::: - -:::{figure} /_static/images/cloud-azure-vnet-05.png -::: - -- Click **Review + Create** and then **Create**. - -### Step 3: Create and configure Network Security Group (NSG) - -- In the Azure Portal, search for and select **Network Security Groups**. -- On the **Network Security Groups** page, select **+ Create**. - -Enter the details: - -- **Subscription**: Select your Subscription -- **Resource Group**: Select `VyOSResourceGroup` -- **Name**: e.g., `VyOS-SecurityGroup` -- **Region**: e.g., `West Europe`. - -:::{figure} /_static/images/cloud-azure-sg-01.png -::: - -- Click **Review + Create** and then **Create**. - -**Add inbound rules**: - -- Navigate to the **Network Security Groups** select **VyOS-SecurityGroup** go to **Inbound security rules** under **Settings** - -:::{figure} /_static/images/cloud-azure-sg-02.png -::: - -**Add Rule Example:** - -- **Rule 1**: AllowSSH - - > - **Port**: 22 - > - **Protocol**: TCP - > - **Source**: Any - > - **Priority**: 1001 - -**Add Additional Rules**: - -You can add inbound rules based on your specific services, such as: - -> - ESP -> - OpenVPN -> - WireGuard, etc. - -:::{figure} /_static/images/cloud-azure-sg-03.png -::: - -**Associate subnets**: - -- Navigate to the **Network Security Groups**, select **Subnets** click **+ Associate** button. Then select your virtual network and the subnet to which you want to associate the NSG. Select **OK**: - -:::{figure} /_static/images/cloud-azure-sg-04.png -::: - -### Step 4: Create Public IP Address - -- In the Azure Portal, search for and select **Public IP Addresses**. -- On the **Public IP Addresses** page, select **+ Create**. -- Provide the following details: -- **Subscription**: Select your Subscription -- **Resource Group**: Select `VyOSResourceGroup` -- **Region**: `West Europe` - -:::{figure} /_static/images/cloud-azure-pub-ip-01.png -::: - -- **Name**: `VyOS-Pub-IP` -- **IP Version**: `IPv4` -- **SKU**: `Standard` -- **Availability zone**: Select Availability Zone - -:::{figure} /_static/images/cloud-azure-pub-ip-02.png -::: - -- **IP address assignment**: `Static` -- **Idle timeout (minutes)** `30` (max) - -:::{figure} /_static/images/cloud-azure-pub-ip-03.png -::: - -- Click **Review + Create**, then **Create**. - -### Step 5: Deploy the VyOS Network Virtual Machine (NVA) - -- In the Azure Portal, search for and select **Virtual Machines**. -- On the **Virtual Machines** page, click **+ Create** and select **Azure virtual machine**. -- Provide the following details: -- **Subscription**: Select your Subscription -- **Resource Group**: Select `VyOSResourceGroup` -- **Virtual machine name**: e.g., `VyOS` -- **Region**: e.g., `West Europe` -- **Security type**: `Standard` -- **Image**: `VyOS` (On the marketplace search `VyOS` and choose the appropriate subscription). - -:::{figure} /_static/images/cloud-azure-vm-01.png -::: - -- **Size**: Select a VM size to support the workload that you want to run. The size that you choose then determines factors such as processing power, memory, and storage capacity. - -:::{figure} /_static/images/cloud-azure-vm-02.png -::: - -- **Password/SSH Key**: Choose whether the administrator account will use username/password or SSH keys for authentication. -- **Username**: The administrator username for the VM, e.g., `vyos`. -- **SSH Key**: You can use your existing SSH key pair or Azure automatically generates it for you and allows you to store it for future use. - -:::{figure} /_static/images/cloud-azure-vm-03.png -::: - -- **Virtual network**: Select `VyOS-VirtualNetwork`. -- **Subnet**: Select `VyOS-Public-Subnet`. -- **Public IP**: Select public IP address which created before `VyOS-Pub-IP`. - -:::{figure} /_static/images/cloud-azure-vm-04.png -::: - -- **Configure network security group**: Select existing Security Group `VyOS-SecurityGroup`. - -:::{figure} /_static/images/cloud-azure-vm-05.png -::: - -- Click **Review + Create**, then **Create**. -- Click **Download the private key and create resource** this will download private key to your computer and start creating Virtual Machine. - -:::{figure} /_static/images/cloud-azure-vm-06.png -::: - -- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. - -:::{figure} /_static/images/cloud-azure-vm-07.png -::: - -### Step 6: Access the VyOS instance - -- Access the VyOS instance using **SSH** protocol, **Public IP Address**, **Private Key**: - - ```none - $ ssh vyos@51.124.120.235 -i vyos_key.pem - vyos@VyOS:~$ - ``` - -### Step 7: Enable IP Forwarding in Network Interface - -This option allows the virtual machine on this network interface to act as a router and receive traffic addressed to other destinations. - -- On the **Virtual Machines** page, select `VyOS` VM, under **Networking** tab select **Network settings**, click network interface. - -:::{figure} /_static/images/cloud-azure-vm-12.png -::: - -- Enable IP forwarding and click the **Apply** button. - -:::{figure} /_static/images/cloud-azure-vm-13.png -::: - -### Step 8: Create and attach the second network interface (optional) - -Now instance has been deployed with one **eth0** `WAN` interface and want to add -new one. To add new interface an example **eth1** `LAN` you need shutdown the -instance. Attach the interface in the Azure portal and then start the instance. - -:::{note} -Azure does not allow you attach interface when the instance in the -**Running** state. -::: - -#### Create network interface: - -- In the Azure Portal, search for and select **Network Interfaces**. -- On the **Network Interfaces** page, select **+ Create**. - -:::{figure} /_static/images/cloud-azure-nic-01.png -::: - -- **Subscription**: Select your Subscription -- **Resource Group**: Select `VyOSResourceGroup` -- **Name**: `VyOS-PRIV-NIC` -- **Subnet**: `VyOS-Private-Subnet` -- **Private IP**: `Dynamic` -- Click **Review + Create**, then **Create** - -:::{figure} /_static/images/cloud-azure-nic-02.png -::: - -- Enable **IP Forwarding** -- Navigate to **Network Interfaces** select `VyOS-PRIV-NIC` - -:::{figure} /_static/images/cloud-azure-nic-03.png -::: - -- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. - -:::{figure} /_static/images/cloud-azure-nic-04.png -::: - -#### Attach reate network interface: - -- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button - -:::{figure} /_static/images/cloud-azure-vm-08.png -::: - -- Go to **Networking** select **Network settings** and then select **Attach network interface** - -:::{figure} /_static/images/cloud-azure-vm-09.png -::: - -- Select existing (before created) network interface `VyOS-PRIV-NIC` and click the **OK** button. - -:::{figure} /_static/images/cloud-azure-vm-10.png -::: - -- Now you have attached second interface to your instance and you can start Virtual Machine. -- Go to **Overview** and click the **Start** button. - -:::{figure} /_static/images/cloud-azure-vm-11.png -::: - -### Setp 8: Absorbing Routes - -To route traffic from your Virtual Network (VNET) through the LAN interface of your VyOS Network Virtual Appliance (NVA), you need to create and configure a custom route table in Azure. - -- Step-by-Step Instructions: -- Navigate to **Route Tables** and click **+ Create**. - -Provide the following details: - -> - **Subscription**: Select your Subscription -> - **Resource Group**: Select `VyOSResourceGroup` -> - **Name**: `Route-VyOS` -> - **Region**: e.g., `West Europe` - -:::{figure} /_static/images/cloud-azure-route-01.png -::: - -- Click **Review + Create**, then **Create**. - -**Add a Route**: - -- Navigate to **Route Tables** and click the new created route (`Route-VyOS`). -- Go to **Routes** and click **+ Add** button. - -:::{figure} /_static/images/cloud-azure-route-02.png -::: - -Add following parameters: - -- **Name**: `Default-Route` -- **Destination type**: `IP Addresses` -- **Destination IP addresses/CIDR ranges**: `0.0.0.0/0` -- **Next Hop Type**: `Virtual Appliance` -- **Next Hop IP Address**: `10.1.11.4` (The private Network Interface Card IP Address) - -:::{figure} /_static/images/cloud-azure-route-03.png -::: - -- Click the **Add** button. - -**Associate the Route Table with subnet**: - -- Navigate to **Route Tables** and click the new created route (`VyOSResourceGroup`). -- Go to **Subnets** and click **+ Associate** button. - -:::{figure} /_static/images/cloud-azure-route-04.png -::: - -- **Virtual network**: Select `VyOS-VirtualNetwork`. -- **Subnet**: Select `VyOS-Public-Subnet`. - -:::{figure} /_static/images/cloud-azure-route-05.png -::: - -:::{note} -If you want to create a new default route for VMs on the subnet, use **Address Prefix** `0.0.0.0/0` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the `WAN` interface. -::: - -### Deploy VyOS Instance and Required Resources Automatically (via Terraform) - -You can deploy a VyOS instance and its associated resources in **Azure** using Terraform modules available in the GitHub repository. -All necessary parameters will be configured automatically, and you will receive **management and access information** from the outputs. - -You can also edit/change these parameters based on your requirements. - -- Download/Clone the Repository following GitHub repository: - - diff --git a/docs/installation/cloud/md-gcp.md b/docs/installation/cloud/md-gcp.md deleted file mode 100644 index 7144f083..00000000 --- a/docs/installation/cloud/md-gcp.md +++ /dev/null @@ -1,260 +0,0 @@ -# VyOS Deployment on Google Cloud Platform - -This guide provides step-by-step instructions for deploying a VyOS instance with two NICs and the required resources on Google Cloud Platform (GCP). - -## Prerequisites - -Before proceeding, ensure the following: - -- A GCP account with billing enabled. -- Permissions to deploy Marketplace images. -- Access to enable APIs and create resources (e.g., Compute Engine Admin, Network Admin). -- An SSH key pair for VyOS instance access. -- GA Google Cloud Project. - -## Deployment Steps - -### Step 1: Add SSH Key - -1. If you don’t already have SSH keys, generate an SSH key pair of type `ssh-rsa` on your local machine: - -> Example: -> -> ```none -> ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" -> ``` - -:::{note} -In the comment `vyos@mypc`, the username must start with vyos. -This is because the default user in the VyOS image is `vyos`, and the Google Cloud API uses this value for SSH access. -::: - -2. Open GCP console and navigate to the **Compute Engine** > **Metadata** > **SSH Keys**. Choose - **SSH Keys**. - -:::{figure} /_static/images/cloud-gcp-01.png -::: - -3. Click **edit** and **Add item**. -4. Paste your public ssh key and **Save**. - -:::{figure} /_static/images/cloud-gcp-02.png -::: - -For more information, please visit the official Google Cloud documentation: - - - - - -### Step 2: Create a Service Account (If You Don't Have One) - -1. In the Google Cloud console **IAM & Admin > Service Accounts**. -2. Select select a project. - -:::{figure} /_static/images/cloud-gcp-proj.png -::: - -3. Click **Create Service Account**: - - - Name: e.g., `vyos-test` - - Service account ID: e.g., `vyos-test` - - Description: e.g., `VyOS Test Service Account` - -4. Click **Done**. - -:::{figure} /_static/images/cloud-gcp-svc.png -::: - -For more information, please visit the official Google Cloud documentation: - - - - - -### Step 3: Create VPC Networks and Subnets - -1. In the Google Cloud console **VPC Network > VPC Networks** -2. Select select a project. - -:::{figure} /_static/images/cloud-gcp-proj.png -::: - -3. Click **Create VPC Network**. - - **Public VPC**: - - - Name: e.g., `vyos-public-vpc` - - Subnet creation mode: `Custom` - - Subnet name: e.g., `vyos-public-subnet` - - Region: e.g., `europe-west1` - - IP range: e.g., `10.0.1.0/24` - - Leave all other settings at default, then click **Create**. - -:::{figure} /_static/images/cloud-gcp-vpc-01.png -::: - -:::{figure} /_static/images/cloud-gcp-vpc-02.png -**Private VPC**: - -- Name: `vyos-private-vpc` -- Subnet creation mode: `Custom` -- Subnet name: `vyos-private-subnet` -- Region: e.g., `europe-west1` -- IP range: `10.0.11.0/24` -- Leave all other settings at default, then click **Create**. -::: - -:::{figure} /_static/images/cloud-gcp-vpc-03.png -::: - -:::{figure} /_static/images/cloud-gcp-vpc-04.png -::: - -4. Add firewall rules to allow specific network traffic from the Internet if needed. By default, all incoming traffic from outside the network is blocked. Typically, a VyOS deployment from the GCP Marketplace configures this automatically, ensuring that SSH access is enabled after deployment. - -:::{figure} /_static/images/cloud-gcp-vpc-05.png -::: - -:::{figure} /_static/images/cloud-gcp-vpc-06.png -::: - -:::{figure} /_static/images/cloud-gcp-vpc-07.png -::: - -For more information, please visit the official Google Cloud documentation: - - - -### Step 4: Deploy VyOS instance from Marketplace - -1. Go to the Google Cloud Marketplace page in the Google Cloud console -2. Choose the project where you want to deploy the VyOS instance. - -:::{figure} /_static/images/cloud-gcp-proj.png -::: - -3. In the search bar, type `vyos` to find the VyOS image in the Marketplace. - -:::{figure} /_static/images/cloud-gcp-market-01.png -::: - -:::{figure} /_static/images/cloud-gcp-market-02.png -::: - -4. On the next page, review details such as support, pricing, and other details. - -:::{figure} /_static/images/cloud-gcp-market-03.png -::: - -5. Click the `GET STARTED` button to start deployment process. - -:::{figure} /_static/images/cloud-gcp-market-04.png -::: - -:::{figure} /_static/images/cloud-gcp-market-05.png -::: - -6. General settings. - - - Deployment name: e.g., `vyos-test-vm` - - Select a Service Account: Select the service account created earlier. - - Image: Select VyOS image for deployment. - - Zone: e.g., `europe-west1-b` - - Machine type: Choose based on performance and resource needs. - -:::{figure} /_static/images/cloud-gcp-vm-01.png -::: - -:::{figure} /_static/images/cloud-gcp-vm-02.png -::: - -7. Configure the network interfaces. - - **Public Network interface:** - - Edit the first (default) network interface and select following settings: - - > - Network: `vyos-public-vpc` - > - Subnetwork: `vyos-public-subnet` - > - External IP: `Ephemeral` - > - Private Network interface: - - **Private Network Interface:** - - Click **ADD A NETWORK INTERFACE** button to create a second (private) interface, and select following settings: - - > - Network: `vyos-private-vpc` - > - Subnetwork: `vyos-private-subnet` - > - External IP: `None` - -:::{figure} /_static/images/cloud-gcp-vm-03.png -::: - -8. Deployment automation. - - - You can use `cloud-init` `User Data` to automatically inject specific configuration commands into the VyOS instance during deployment. - - Example: - -> ```none -> #cloud-config -> vyos_config_commands: -> - set system host-name 'VyOS-for-GCP' -> - set system login banner pre-login 'Welcome to the VyOS for on GCP' -> - set interfaces ethernet eth0 description 'WAN' -> - set interfaces ethernet eth1 description 'LAN' -> - set interfaces ethernet eth1 address 'dhcp' -> - set interfaces ethernet eth1 dhcp-options no-default-route -> ``` - -For more information, please visit the documentation: - - - -:::{figure} /_static/images/cloud-gcp-vm-09.png -::: - -9. Click `Deploy` button. - -:::{figure} /_static/images/cloud-gcp-vm-06.png -::: - -:::{figure} /_static/images/cloud-gcp-vm-07.png -::: - -### Connect to the VyOS instance - -To connect to the VyOS instance, use the SSH key that was generated in the first step. - -To retrieve the public IP address, go to the **Google Cloud Console** and navigate to: **Compute Engine** > **VM instances** - -:::{figure} /_static/images/cloud-gcp-vm-08.png -::: - -Example: - -> ```none -> ssh vyos@35.233.97.132 -i .ssh/vyos_gcp -> -> The authenticity of host '35.233.97.132 (35.233.97.132)' can't be established. -> ED25519 key fingerprint is SHA256:KCsCnwCGhwX2ba5RcPUAO3ZUSNzS4sXIkujFoScCd0g. -> This key is not known by any other names -> Are you sure you want to continue connecting (yes/no/[fingerprint])? yes -> Warning: Permanently added '35.233.97.132' (ED25519) to the list of known hosts. -> Welcome to the VyOS for on GCP -> Welcome to VyOS! -> -> ┌── ┐ -> . VyOS 1.4.2 -> └ ──┘ sagitta -> -> * Documentation: https://docs.vyos.io/en/sagitta -> * Project news: https://blog.vyos.io -> * Bug reports: https://vyos.dev -> -> You can change this banner using "set system login banner post-login" command. -> -> VyOS is a free software distribution that includes multiple components, -> you can check individual component licenses under /usr/share/doc/*/copyright -> vyos@VyOS-for-GCP:~$ -> ``` diff --git a/docs/installation/cloud/md-index.md b/docs/installation/cloud/md-index.md deleted file mode 100644 index f64883fc..00000000 --- a/docs/installation/cloud/md-index.md +++ /dev/null @@ -1,14 +0,0 @@ -# Running VyOS in Cloud Environments - -```{eval-rst} -.. toctree:: - :caption: Content - - aws - aws-ha - azure - azure-ha - aws-to-azure - gcp - oracle -``` diff --git a/docs/installation/cloud/md-oracel.md b/docs/installation/cloud/md-oracel.md deleted file mode 100644 index 9ed07ff9..00000000 --- a/docs/installation/cloud/md-oracel.md +++ /dev/null @@ -1,5 +0,0 @@ -# Oracle - -## References - - diff --git a/docs/installation/cloud/oracel.md b/docs/installation/cloud/oracel.md new file mode 100644 index 00000000..9ed07ff9 --- /dev/null +++ b/docs/installation/cloud/oracel.md @@ -0,0 +1,5 @@ +# Oracle + +## References + + diff --git a/docs/installation/cloud/oracel.rst b/docs/installation/cloud/oracel.rst deleted file mode 100644 index 72c40127..00000000 --- a/docs/installation/cloud/oracel.rst +++ /dev/null @@ -1,8 +0,0 @@ -###### -Oracle -###### - - -References ----------- -https://www.oracle.com/cloud/ \ No newline at end of file diff --git a/docs/installation/cloud/rst-aws-ha.rst b/docs/installation/cloud/rst-aws-ha.rst new file mode 100755 index 00000000..af125969 --- /dev/null +++ b/docs/installation/cloud/rst-aws-ha.rst @@ -0,0 +1,154 @@ +########## +VyOS High Availability (HA) Deployment on AWS +########## + +This document describes how to deploy VyOS in a High Availability (HA) configuration on AWS using Terraform and a VPC Route Server to provide sub-second failover. + +Why Use HA on AWS? +------------------ + +This solution helps organizations achieve **high availability** routing with dynamic connectivity to multiple AWS VPCs or hybrid environments. + +Key Advantages: + +- Utilizes **AWS VPC Route Server** to manage BGP routes dynamically. + +- Deploys two VyOS EC2 instances as BGP peers connected to the Route Server. Although both participate, one is typically preferred as the next-hop. + +- Employs **Bidirectional Forwarding Detection (BFD)** for rapid failure detection. + +- On failure: + + - Withdraws the failed peer’s routes from the RIB. + + - Recomputes the optimal path in the FIB. + + - Updates VPC route tables to point to the active instance. + +- Enables **sub-second failover** (< 1 s), outperforming AWS API-based route table failover. + +This architecture supports: + +- Cloud edge routing with failover. + +- Hybrid cloud resiliency. + +- Rapid recovery during instance crashes, upgrades, or network disruptions. + +- Continuity for mission-critical operations. + +HA Architecture Diagram +------------------------ + +.. figure:: /_static/images/cloud-aws-ha-architecture.png + :alt: VyOS HA topology diagram + +Terraform Automation +-------------------- + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on AWS. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. + +- VPC Route Server. + +- Transit Gateway. + +- A Transit VPC and a Data VPC containing a test Amazon Linux EC2 instance for connectivity validation. + +To integrate with existing AWS infrastructure: + +- Remove the Data VPC, its subnets, and EC2 test instance. + +- Update `main.tf`, `network.tf`, `transit_gateway.tf`, `variables.tf`, and `outputs.tf` accordingly. + +Prerequisites +------------- + +AWS Environment: + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html + +- Terraform installed: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli + +Set AWS credentials in your shell: + +.. code-block:: none + + export AWS_ACCESS_KEY_ID="" + export AWS_SECRET_ACCESS_KEY="" + export AWS_SESSION_TOKEN="" + export AWS_DEFAULT_REGION="" # e.g., us-east-1 + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +.. code-block:: none + + aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table + +Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. + +Generate an SSH keypair (or use the included demo key): + +.. code-block:: none + + ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem + chmod 400 keys/vyos_custom_key.pem + +Usage +----- + +Configure variables in `variables.tf`, including instance type, region, and `vyos_ami_id`. + +Terraform Workflow: + +.. code-block:: none + + terraform init + terraform fmt + terraform validate + terraform plan + terraform apply + +On completion, run: + +.. code-block:: none + + terraform output + +This displays the management IP and connectivity test results. + +To clean up: + +.. code-block:: none + + terraform destroy + +Management +---------- + +SSH into VyOS: + +.. code-block:: none + + ssh vyos@ -i keys/vyos_custom_key.pem + + +GitHub Repository +----------------- + +You can clone or download the Terraform project and use them in your environment: + +https://github.com/vyos/vyos-automation/tree/main/Terraform/AWS/ha-instances-with-configs diff --git a/docs/installation/cloud/rst-aws-to-azure.rst b/docs/installation/cloud/rst-aws-to-azure.rst new file mode 100755 index 00000000..81651feb --- /dev/null +++ b/docs/installation/cloud/rst-aws-to-azure.rst @@ -0,0 +1,189 @@ +########## +VyOS Deployment on AWS and Azure for Secure Cloud-to-Cloud Connectivity +########## + +This document provides step-by-step guidance for deploying VyOS routers on both AWS and Azure. +It describes how to establish secure inter-cloud connectivity using IPsec tunnels with BGP, +automated through Terraform. Example workloads (Amazon Linux EC2 on AWS and Ubuntu VM on Azure) +are also deployed for connectivity validation. + +Why Cloud-to-Cloud Connectivity? +-------------------------------- + +Cloud-to-cloud connectivity is needed in modern multi-cloud environments for several reasons: + +- **Inter-Cloud Connectivity** + + Enable secure and reliable communication between workloads in different clouds + (for example, AWS applications connecting to Azure-hosted identity services). + +- **Cloud-to-Cloud Migration** + + During migration projects, workloads may temporarily run in both clouds. + Direct tunnels ensure smooth transition and synchronization. + +- **Testing and Validation** + + Labs and proof-of-concepts often simulate multi-cloud architectures. + A VyOS-based tunnel lets teams test routing, encryption, and failover before production rollout. + +Architecture +------------ + +The architecture consists of VyOS routers deployed in both AWS and Azure, connected via secure IPsec tunnels. +BGP is used for dynamic routing between the clouds, allowing for seamless communication. + +.. figure:: /_static/images/cloud-aws-to-azure.png + :alt: VyOS Cloud-to-Cloud topology diagram + +Terraform Automation +-------------------- + +To streamline and standardize the deployment process, a set of **Terraform projects** has been developed. +These projects automate the provisioning of **VyOS instances** and the required networking resources across **AWS** and **Azure**. + +In addition to deploying VyOS, these projects also provision an **Amazon Linux EC2 instance** on AWS and an **Ubuntu VM** on Azure. +These serve as test endpoints to validate connectivity between the cloud environments. + +Prerequisites +------------- + +AWS Environment +^^^^^^^^^^^^^^^ + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html + +- Terraform installed: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli + +Set AWS credentials in your shell: + +.. code-block:: none + + export AWS_ACCESS_KEY_ID="" + export AWS_SECRET_ACCESS_KEY="" + export AWS_SESSION_TOKEN="" + export AWS_DEFAULT_REGION="" # e.g., us-east-1 + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +.. code-block:: none + + aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table + +Alternatively, set the ``vyos_ami_id`` variable directly in ``variables.tf``. + +Generate an SSH keypair (or use the included demo key): + +.. code-block:: none + + ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem + chmod 400 keys/vyos_custom_key.pem + +Azure Environment +^^^^^^^^^^^^^^^^^ + +- Active Azure subscription: + +.. code-block:: none + + az account set --subscription "" + +- Azure CLI installed: + + https://learn.microsoft.com/en-us/cli/azure/install-azure-cli + +- Logged in with Azure credentials: + +.. code-block:: none + + az version + az login + +- Azure Resource Group (RG) created: + +.. code-block:: none + + az group create --name demoResourceGroup --location westus + az group list + az group show --name demoResourceGroup + +- Terraform installed: + + https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli + +- SSH key generated: + +.. code-block:: none + + ssh-keygen -t rsa -b 4096 -f keys/id_rsa + chmod 400 keys/id_rsa + +Usage +----- + +AWS +^^^ + +All variables needed for customization are defined in ``variables.tf``. +Adjust them according to your requirements, such as EC2 instance type and networking configurations. + +Before deployment, ensure you check ``aws_region``, ``availability_zone``, and update ``vyos_ami_id`` as necessary. + +Azure +^^^^^ + +All variables needed for customization are defined in ``variables.tf``. +Adjust them according to your requirements, such as VM size and networking configurations. + +Before deployment, ensure you check ``azure_region``, ``availability_zone``, and update ``subscription_id`` and ``resource_group_name`` as necessary. + +Terraform Workflow +^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + terraform init + terraform fmt + terraform validate + terraform plan + terraform apply + +On completion, run: + +.. code-block:: none + + terraform output + +This displays the public IP addresses of the VyOS instances. + +To clean up: + +.. code-block:: none + + terraform destroy + +Management +---------- + +SSH into VyOS: + +.. code-block:: none + + ssh vyos@ -i keys/vyos_custom_key.pem + +GitHub Repository +----------------- + +You can clone or download the Terraform projects and use them in your environment: + +https://github.com/vyos/vyos-automation/tree/main/Terraform/Cloud-to-Cloud diff --git a/docs/installation/cloud/rst-azure-ha.rst b/docs/installation/cloud/rst-azure-ha.rst new file mode 100755 index 00000000..e943b550 --- /dev/null +++ b/docs/installation/cloud/rst-azure-ha.rst @@ -0,0 +1,152 @@ +########## +VyOS High Availability (HA) Deployment on Azure +########## + + +This document describes how to deploy VyOS in a High Availability (HA) configuration on Azure using Terraform and Azure Route Server to provide sub-second failover. + +Why Use HA on Azure? +-------------------- + +This module provides a robust, repeatable foundation for building **resilient network architectures** in Azure. By combining VyOS routing features with Terraform and Azure-native services, it enables: + +- Rapid deployment of cloud edge routers. + +- Full control over BGP route advertisement and filtering. + +- Realistic HA and disaster recovery simulations. + +- Seamless integration with hybrid or multi-cloud infrastructure. + +The architecture includes: + +- Two VyOS routers in a Transit VNet, configured with BGP. + +- Azure Route Server for dynamic route distribution. + +- Site-to-Site VPN connections to a simulated on-premises VyOS router. + +- An Ubuntu VM for connectivity and routing validation. + +- A Data VNet for testing and diagnostics. + +Key Features +------------ + +- **High Availability**: Dual VyOS routers for redundancy and failover. + +- **Dynamic Routing**: BGP-based routing via Azure Route Server. + +- **Hybrid Connectivity**: Site-to-Site VPN integration with a simulated on-prem VyOS. + +- **Testing Environment**: Includes Ubuntu VM for verification and diagnostics. + +- **Modular & Flexible**: Easily configurable via variables. + +HA Architecture Diagram +----------------------- + +.. figure:: /_static/images/cloud-azure-ha-architecture.png + :alt: VyOS HA topology diagram + +This deployment architecture simulates a real-world enterprise network scenario for testing and validation purposes. + +Terraform Automation +-------------------- + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on Azure. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. + +- Azure Route Server. + +- A Transit VNet and a Data VNet containing a test Ubuntu VM for connectivity validation. + +Prerequisites +------------- + +Ensure you have: + +- Active Azure subscription: + +.. code-block:: none + + az account set --subscription "" + +- Azure CLI installed: + + https://learn.microsoft.com/en-us/cli/azure/install-azure-cli + +- Logged in with Azure credentials: + +.. code-block:: none + + az version + az login + +- Azure Resource Group (RG) created: + +.. code-block:: none + + az group create --name demoResourceGroup --location westus + az group list + az group show --name demoResourceGroup + +- Terraform installed: + + https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli + +- SSH key generated: + +.. code-block:: none + + ssh-keygen -t rsa -b 4096 -f keys/vyos_custom_key.pem + chmod 400 keys/vyos_custom_key.pem + +Usage +----- + +All variables are defined in ``variables.tf``. Adjust them to match your environment. + +Terraform Workflow: + +.. code-block:: none + + terraform init + terraform fmt + terraform validate + terraform plan + terraform apply + +On completion, run: + +.. code-block:: none + + terraform output + +This displays the management IP and connectivity test results. + +To clean up: + +.. code-block:: none + + terraform destroy + +Management +---------- + +SSH into VyOS: + +.. code-block:: none + + ssh adminuser@ -i keys/vyos_custom_key.pem + + +GitHub Repository +----------------- + +You can clone or download the Terraform project and use them in your environment: + +https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure/azure-ha-deployment-with-configs diff --git a/docs/installation/cloud/rst-azure.rst b/docs/installation/cloud/rst-azure.rst new file mode 100644 index 00000000..563fcb19 --- /dev/null +++ b/docs/installation/cloud/rst-azure.rst @@ -0,0 +1,433 @@ +########## +VyOS Deployment on Azure +########## + + +This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (Virtual Networks, Network Interfaces, Subnets, Security Groups) on Azure via the Azure Portal. + +Prerequisites for Deploying VyOS on Azure +======== + +Azure Account +----------- + +Ensure you have an active Azure subscription. + +Microsoft Entra ID Permissions +----------- + +To manage resources in **Azure Entra ID** (formerly Azure AD), you need appropriate permissions to handle **Virtual Networks**, **Public IP Addresses**, **Subnets**, and **Virtual Machines**. + +**Reference Documentation:** + +https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/manage-roles-portal + +https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal + +https://learn.microsoft.com/en-us/azure/role-based-access-control/overview + +Deployment Steps +======== + +Step 1: Create a Resource Group +----------- + +A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. + +Create resource groups +^^^^^^^^^^^^^^ + +- Go to the Azure Portal https://portal.azure.com/. + +- Sign in with your Azure account credentials. + +- In the portal, search for and select **Resource groups**. + +- Select **Create**. + +.. figure:: /_static/images/cloud-azure-rg-01.png + +- Enter the following values: + +- **Subscription**: Select your Azure subscription. + +- **Resource group**: Enter a new resource group name, e.g., ``VyOSResourceGroup``. + +- **Region**: Select an Azure location, such as Central US. + +- Select **Review + Create** + +- Select **Create**. It takes a few seconds to create a resource group. + +.. figure:: /_static/images/cloud-azure-rg-02.png + + +Step 2: Create a Virtual Network (VNet) and Subnets +----------- + +Sign in to the Azure portal with your Azure account https://portal.azure.com/ + +- In the portal, search for and select **Virtual networks**. + +- On the **Virtual networks** page, select **+ Create**. + +- On the **Basics** tab of **Create virtual network**, enter, or select the following information: + +- **Subscription**: Select your Subscription + +- **Resource Group**: Select e.g., ``VyOSResourceGroup`` + +- **Name**: e.g., ``VyOS-VirtualNetwork`` + +- **Region**: e.g., ``West Europe``. + +.. figure:: /_static/images/cloud-azure-vnet-01.png + +**IP addresses**: + +- Address Space: ``10.1.0.0/16`` + +.. figure:: /_static/images/cloud-azure-vnet-02.png + +**Add two subnets**: + +- Name: e.g., ``VyOS-Private-Subnet`` + + Starting address: e.g., ``10.1.1.0`` + + Size: ``/24`` + +- Name: e.g., ``VyOS-Public-Subnet`` + + Starting address: e.g., ``10.1.11.0`` + + Size: ``/24`` + +.. figure:: /_static/images/cloud-azure-vnet-03.png + +.. figure:: /_static/images/cloud-azure-vnet-04.png + +.. figure:: /_static/images/cloud-azure-vnet-05.png + +- Click **Review + Create** and then **Create**. + + +Step 3: Create and configure Network Security Group (NSG) +----------- + +- In the Azure Portal, search for and select **Network Security Groups**. + +- On the **Network Security Groups** page, select **+ Create**. + +Enter the details: + +- **Subscription**: Select your Subscription + +- **Resource Group**: Select ``VyOSResourceGroup`` + +- **Name**: e.g., ``VyOS-SecurityGroup`` + +- **Region**: e.g., ``West Europe``. + +.. figure:: /_static/images/cloud-azure-sg-01.png + +- Click **Review + Create** and then **Create**. + +**Add inbound rules**: + +- Navigate to the **Network Security Groups** select **VyOS-SecurityGroup** go to **Inbound security rules** under **Settings** + +.. figure:: /_static/images/cloud-azure-sg-02.png + +**Add Rule Example:** + +- **Rule 1**: AllowSSH + + - **Port**: 22 + + - **Protocol**: TCP + + - **Source**: Any + + - **Priority**: 1001 + +**Add Additional Rules**: + +You can add inbound rules based on your specific services, such as: + + - ESP + + - OpenVPN + + - WireGuard, etc. + +.. figure:: /_static/images/cloud-azure-sg-03.png + +**Associate subnets**: + +- Navigate to the **Network Security Groups**, select **Subnets** click **+ Associate** button. Then select your virtual network and the subnet to which you want to associate the NSG. Select **OK**: + +.. figure:: /_static/images/cloud-azure-sg-04.png + + +Step 4: Create Public IP Address +----------- + +- In the Azure Portal, search for and select **Public IP Addresses**. + +- On the **Public IP Addresses** page, select **+ Create**. + +- Provide the following details: + +- **Subscription**: Select your Subscription + +- **Resource Group**: Select ``VyOSResourceGroup`` + +- **Region**: ``West Europe`` + +.. figure:: /_static/images/cloud-azure-pub-ip-01.png + +- **Name**: ``VyOS-Pub-IP`` + +- **IP Version**: ``IPv4`` + +- **SKU**: ``Standard`` + +- **Availability zone**: Select Availability Zone + +.. figure:: /_static/images/cloud-azure-pub-ip-02.png + +- **IP address assignment**: ``Static`` + +- **Idle timeout (minutes)** ``30`` (max) + +.. figure:: /_static/images/cloud-azure-pub-ip-03.png + +- Click **Review + Create**, then **Create**. + + +Step 5: Deploy the VyOS Network Virtual Machine (NVA) +----------- + +- In the Azure Portal, search for and select **Virtual Machines**. + +- On the **Virtual Machines** page, click **+ Create** and select **Azure virtual machine**. + +- Provide the following details: + +- **Subscription**: Select your Subscription + +- **Resource Group**: Select ``VyOSResourceGroup`` + +- **Virtual machine name**: e.g., ``VyOS`` + +- **Region**: e.g., ``West Europe`` + +- **Security type**: ``Standard`` + +- **Image**: ``VyOS`` (On the marketplace search ``VyOS`` and choose the appropriate subscription). + +.. figure:: /_static/images/cloud-azure-vm-01.png + +- **Size**: Select a VM size to support the workload that you want to run. The size that you choose then determines factors such as processing power, memory, and storage capacity. + +.. figure:: /_static/images/cloud-azure-vm-02.png + +- **Password/SSH Key**: Choose whether the administrator account will use username/password or SSH keys for authentication. + +- **Username**: The administrator username for the VM, e.g., ``vyos``. + +- **SSH Key**: You can use your existing SSH key pair or Azure automatically generates it for you and allows you to store it for future use. + +.. figure:: /_static/images/cloud-azure-vm-03.png + +- **Virtual network**: Select ``VyOS-VirtualNetwork``. + +- **Subnet**: Select ``VyOS-Public-Subnet``. + +- **Public IP**: Select public IP address which created before ``VyOS-Pub-IP``. + +.. figure:: /_static/images/cloud-azure-vm-04.png + +- **Configure network security group**: Select existing Security Group ``VyOS-SecurityGroup``. + +.. figure:: /_static/images/cloud-azure-vm-05.png + +- Click **Review + Create**, then **Create**. + +- Click **Download the private key and create resource** this will download private key to your computer and start creating Virtual Machine. + +.. figure:: /_static/images/cloud-azure-vm-06.png + +- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. + +.. figure:: /_static/images/cloud-azure-vm-07.png + + +Step 6: Access the VyOS instance +----------- + +- Access the VyOS instance using **SSH** protocol, **Public IP Address**, **Private Key**: + + .. code-block:: none + + $ ssh vyos@51.124.120.235 -i vyos_key.pem + vyos@VyOS:~$ + +Step 7: Enable IP Forwarding in Network Interface +----------- + +This option allows the virtual machine on this network interface to act as a router and receive traffic addressed to other destinations. + +- On the **Virtual Machines** page, select ``VyOS`` VM, under **Networking** tab select **Network settings**, click network interface. + +.. figure:: /_static/images/cloud-azure-vm-12.png + +- Enable IP forwarding and click the **Apply** button. + +.. figure:: /_static/images/cloud-azure-vm-13.png + +Step 8: Create and attach the second network interface (optional) +------------- + +Now instance has been deployed with one **eth0** ``WAN`` interface and want to add +new one. To add new interface an example **eth1** ``LAN`` you need shutdown the +instance. Attach the interface in the Azure portal and then start the instance. + +.. note:: Azure does not allow you attach interface when the instance in the + **Running** state. + + +Create network interface: +^^^^^^^^^^^^^^ + +- In the Azure Portal, search for and select **Network Interfaces**. + +- On the **Network Interfaces** page, select **+ Create**. + +.. figure:: /_static/images/cloud-azure-nic-01.png + +- **Subscription**: Select your Subscription + +- **Resource Group**: Select ``VyOSResourceGroup`` + +- **Name**: ``VyOS-PRIV-NIC`` + +- **Subnet**: ``VyOS-Private-Subnet`` + +- **Private IP**: ``Dynamic`` + +- Click **Review + Create**, then **Create** + +.. figure:: /_static/images/cloud-azure-nic-02.png + +- Enable **IP Forwarding** + +- Navigate to **Network Interfaces** select ``VyOS-PRIV-NIC`` + +.. figure:: /_static/images/cloud-azure-nic-03.png + +- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. + +.. figure:: /_static/images/cloud-azure-nic-04.png + + +Attach reate network interface: +^^^^^^^^^^^^^^ + +- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button + +.. figure:: /_static/images/cloud-azure-vm-08.png + +- Go to **Networking** select **Network settings** and then select **Attach network interface** + +.. figure:: /_static/images/cloud-azure-vm-09.png + +- Select existing (before created) network interface ``VyOS-PRIV-NIC`` and click the **OK** button. + +.. figure:: /_static/images/cloud-azure-vm-10.png + +- Now you have attached second interface to your instance and you can start Virtual Machine. + +- Go to **Overview** and click the **Start** button. + +.. figure:: /_static/images/cloud-azure-vm-11.png + + +Setp 8: Absorbing Routes +---------------- + +To route traffic from your Virtual Network (VNET) through the LAN interface of your VyOS Network Virtual Appliance (NVA), you need to create and configure a custom route table in Azure. + +- Step-by-Step Instructions: + +- Navigate to **Route Tables** and click **+ Create**. + +Provide the following details: + + - **Subscription**: Select your Subscription + + - **Resource Group**: Select ``VyOSResourceGroup`` + + - **Name**: ``Route-VyOS`` + + - **Region**: e.g., ``West Europe`` + +.. figure:: /_static/images/cloud-azure-route-01.png + +- Click **Review + Create**, then **Create**. + +**Add a Route**: + +- Navigate to **Route Tables** and click the new created route (``Route-VyOS``). + +- Go to **Routes** and click **+ Add** button. + +.. figure:: /_static/images/cloud-azure-route-02.png + +Add following parameters: + +- **Name**: ``Default-Route`` + +- **Destination type**: ``IP Addresses`` + +- **Destination IP addresses/CIDR ranges**: ``0.0.0.0/0`` + +- **Next Hop Type**: ``Virtual Appliance`` + +- **Next Hop IP Address**: ``10.1.11.4`` (The private Network Interface Card IP Address) + +.. figure:: /_static/images/cloud-azure-route-03.png + +- Click the **Add** button. + +**Associate the Route Table with subnet**: + +- Navigate to **Route Tables** and click the new created route (``VyOSResourceGroup``). + +- Go to **Subnets** and click **+ Associate** button. + +.. figure:: /_static/images/cloud-azure-route-04.png + +- **Virtual network**: Select ``VyOS-VirtualNetwork``. + +- **Subnet**: Select ``VyOS-Public-Subnet``. + +.. figure:: /_static/images/cloud-azure-route-05.png + +.. note:: If you want to create a new default route for VMs on the subnet, use **Address Prefix** ``0.0.0.0/0`` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the ``WAN`` interface. + + +Deploy VyOS Instance and Required Resources Automatically (via Terraform) +-------------- + +You can deploy a VyOS instance and its associated resources in **Azure** using Terraform modules available in the GitHub repository. +All necessary parameters will be configured automatically, and you will receive **management and access information** from the outputs. + +You can also edit/change these parameters based on your requirements. + +- Download/Clone the Repository following GitHub repository: + +https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure + + diff --git a/docs/installation/cloud/rst-gcp.rst b/docs/installation/cloud/rst-gcp.rst new file mode 100644 index 00000000..0c23353e --- /dev/null +++ b/docs/installation/cloud/rst-gcp.rst @@ -0,0 +1,277 @@ +##################### +VyOS Deployment on Google Cloud Platform +##################### + +This guide provides step-by-step instructions for deploying a VyOS instance with two NICs and the required resources on Google Cloud Platform (GCP). + +Prerequisites +======== + +Before proceeding, ensure the following: + +- A GCP account with billing enabled. +- Permissions to deploy Marketplace images. +- Access to enable APIs and create resources (e.g., Compute Engine Admin, Network Admin). +- An SSH key pair for VyOS instance access. +- GA Google Cloud Project. + +Deployment Steps +======== + +Step 1: Add SSH Key +------------------- + +1. If you don’t already have SSH keys, generate an SSH key pair of type ``ssh-rsa`` on your local machine: + + Example: + + .. code-block:: none + + ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" + + +.. note:: In the comment ``vyos@mypc``, the username must start with vyos. + This is because the default user in the VyOS image is ``vyos``, and the Google Cloud API uses this value for SSH access. + +2. Open GCP console and navigate to the **Compute Engine** > **Metadata** > **SSH Keys**. Choose + **SSH Keys**. + +.. figure:: /_static/images/cloud-gcp-01.png + + +3. Click **edit** and **Add item**. + +4. Paste your public ssh key and **Save**. + +.. figure:: /_static/images/cloud-gcp-02.png + +For more information, please visit the official Google Cloud documentation: + +https://cloud.google.com/compute/docs/connect/add-ssh-keys + +https://cloud.google.com/compute/docs/connect/create-ssh-keys + + +Step 2: Create a Service Account (If You Don't Have One) +------------------------------- + +1. In the Google Cloud console **IAM & Admin > Service Accounts**. + +2. Select select a project. + +.. figure:: /_static/images/cloud-gcp-proj.png + +3. Click **Create Service Account**: + + - Name: e.g., ``vyos-test`` + + - Service account ID: e.g., ``vyos-test`` + + - Description: e.g., ``VyOS Test Service Account`` + +4. Click **Done**. + +.. figure:: /_static/images/cloud-gcp-svc.png + +For more information, please visit the official Google Cloud documentation: + +https://cloud.google.com/iam/docs/service-accounts-create + +https://cloud.google.com/iam/docs/service-account-overview + + +Step 3: Create VPC Networks and Subnets +------------------------------- + +1. In the Google Cloud console **VPC Network > VPC Networks** https://console.cloud.google.com/networking/networks/list + +2. Select select a project. + +.. figure:: /_static/images/cloud-gcp-proj.png + +3. Click **Create VPC Network**. + + **Public VPC**: + + - Name: e.g., ``vyos-public-vpc`` + + - Subnet creation mode: ``Custom`` + + - Subnet name: e.g., ``vyos-public-subnet`` + + - Region: e.g., ``europe-west1`` + + - IP range: e.g., ``10.0.1.0/24`` + + - Leave all other settings at default, then click **Create**. + +.. figure:: /_static/images/cloud-gcp-vpc-01.png + +.. figure:: /_static/images/cloud-gcp-vpc-02.png + + **Private VPC**: + + - Name: ``vyos-private-vpc`` + + - Subnet creation mode: ``Custom`` + + - Subnet name: ``vyos-private-subnet`` + + - Region: e.g., ``europe-west1`` + + - IP range: ``10.0.11.0/24`` + + - Leave all other settings at default, then click **Create**. + +.. figure:: /_static/images/cloud-gcp-vpc-03.png + +.. figure:: /_static/images/cloud-gcp-vpc-04.png + +4. Add firewall rules to allow specific network traffic from the Internet if needed. By default, all incoming traffic from outside the network is blocked. Typically, a VyOS deployment from the GCP Marketplace configures this automatically, ensuring that SSH access is enabled after deployment. + +.. figure:: /_static/images/cloud-gcp-vpc-05.png + +.. figure:: /_static/images/cloud-gcp-vpc-06.png + +.. figure:: /_static/images/cloud-gcp-vpc-07.png + +For more information, please visit the official Google Cloud documentation: + +https://cloud.google.com/vpc/docs/create-modify-vpc-networks + + +Step 4: Deploy VyOS instance from Marketplace +--------- + +1. Go to the Google Cloud Marketplace page in the Google Cloud console https://console.cloud.google.com/marketplace + +2. Choose the project where you want to deploy the VyOS instance. + +.. figure:: /_static/images/cloud-gcp-proj.png + +3. In the search bar, type ``vyos`` to find the VyOS image in the Marketplace. + +.. figure:: /_static/images/cloud-gcp-market-01.png + +.. figure:: /_static/images/cloud-gcp-market-02.png + +4. On the next page, review details such as support, pricing, and other details. + +.. figure:: /_static/images/cloud-gcp-market-03.png + +5. Click the ``GET STARTED`` button to start deployment process. + +.. figure:: /_static/images/cloud-gcp-market-04.png + +.. figure:: /_static/images/cloud-gcp-market-05.png + +6. General settings. + + - Deployment name: e.g., ``vyos-test-vm`` + + - Select a Service Account: Select the service account created earlier. + + - Image: Select VyOS image for deployment. + + - Zone: e.g., ``europe-west1-b`` + + - Machine type: Choose based on performance and resource needs. + +.. figure:: /_static/images/cloud-gcp-vm-01.png + +.. figure:: /_static/images/cloud-gcp-vm-02.png + +7. Configure the network interfaces. + + **Public Network interface:** + + Edit the first (default) network interface and select following settings: + + - Network: ``vyos-public-vpc`` + + - Subnetwork: ``vyos-public-subnet`` + + - External IP: ``Ephemeral`` + + - Private Network interface: + + **Private Network Interface:** + + Click **ADD A NETWORK INTERFACE** button to create a second (private) interface, and select following settings: + + - Network: ``vyos-private-vpc`` + + - Subnetwork: ``vyos-private-subnet`` + + - External IP: ``None`` + +.. figure:: /_static/images/cloud-gcp-vm-03.png + +8. Deployment automation. + + - You can use ``cloud-init`` ``User Data`` to automatically inject specific configuration commands into the VyOS instance during deployment. + + - Example: + + .. code-block:: none + + #cloud-config + vyos_config_commands: + - set system host-name 'VyOS-for-GCP' + - set system login banner pre-login 'Welcome to the VyOS for on GCP' + - set interfaces ethernet eth0 description 'WAN' + - set interfaces ethernet eth1 description 'LAN' + - set interfaces ethernet eth1 address 'dhcp' + - set interfaces ethernet eth1 dhcp-options no-default-route + +For more information, please visit the documentation: + +https://docs.vyos.io/en/stable/automation/cloud-init.html#module-vyos-userdata + +.. figure:: /_static/images/cloud-gcp-vm-09.png + +9. Click ``Deploy`` button. + +.. figure:: /_static/images/cloud-gcp-vm-06.png + +.. figure:: /_static/images/cloud-gcp-vm-07.png + + +Connect to the VyOS instance +----------- + +To connect to the VyOS instance, use the SSH key that was generated in the first step. + +To retrieve the public IP address, go to the **Google Cloud Console** and navigate to: **Compute Engine** > **VM instances** https://console.cloud.google.com/compute/instances?project=vyos-images + +.. figure:: /_static/images/cloud-gcp-vm-08.png + +Example: + + .. code-block:: none + + ssh vyos@35.233.97.132 -i .ssh/vyos_gcp + + The authenticity of host '35.233.97.132 (35.233.97.132)' can't be established. + ED25519 key fingerprint is SHA256:KCsCnwCGhwX2ba5RcPUAO3ZUSNzS4sXIkujFoScCd0g. + This key is not known by any other names + Are you sure you want to continue connecting (yes/no/[fingerprint])? yes + Warning: Permanently added '35.233.97.132' (ED25519) to the list of known hosts. + Welcome to the VyOS for on GCP + Welcome to VyOS! + + ┌── ┐ + . VyOS 1.4.2 + └ ──┘ sagitta + + * Documentation: https://docs.vyos.io/en/sagitta + * Project news: https://blog.vyos.io + * Bug reports: https://vyos.dev + + You can change this banner using "set system login banner post-login" command. + + VyOS is a free software distribution that includes multiple components, + you can check individual component licenses under /usr/share/doc/*/copyright + vyos@VyOS-for-GCP:~$ + + diff --git a/docs/installation/cloud/rst-index.rst b/docs/installation/cloud/rst-index.rst new file mode 100644 index 00000000..7a17f18d --- /dev/null +++ b/docs/installation/cloud/rst-index.rst @@ -0,0 +1,16 @@ +################################## +Running VyOS in Cloud Environments +################################## + + + +.. toctree:: + :caption: Content + + aws + aws-ha + azure + azure-ha + aws-to-azure + gcp + oracle \ No newline at end of file diff --git a/docs/installation/cloud/rst-oracel.rst b/docs/installation/cloud/rst-oracel.rst new file mode 100644 index 00000000..72c40127 --- /dev/null +++ b/docs/installation/cloud/rst-oracel.rst @@ -0,0 +1,8 @@ +###### +Oracle +###### + + +References +---------- +https://www.oracle.com/cloud/ \ No newline at end of file diff --git a/docs/installation/image.md b/docs/installation/image.md new file mode 100644 index 00000000..7581d065 --- /dev/null +++ b/docs/installation/image.md @@ -0,0 +1,122 @@ +(image-mgmt)= + +# Image Management + +The VyOS image-based installation is implemented by creating a directory for +each image on the storage device selected during the install process. + +The directory structure of the boot device: + +```none +/ +/boot +/boot/grub +/boot/1.2.0-rolling+201810021347 +``` + +The image directory contains the system kernel, a compressed image of the root +filesystem for the OS, and a directory for persistent storage, such as +configuration. On boot, the system will extract the OS image into memory and +mount the appropriate live-rw sub-directories to provide persistent storage +system configuration. + +This process allows for a system to always boot to a known working state, as +the OS image is fixed and non-persistent. It also allows for multiple releases +of VyOS to be installed on the same storage device. The image can be selected +manually at boot if needed, but the system will otherwise boot the image +configured to be the default. + +```{eval-rst} +.. opcmd:: show system image + + List all available system images which can be booted on the current system. + + .. code-block:: none + + vyos@vyos:~$ show system image + The system currently has the following image(s) installed: + + 1: 1.2.0-rolling+201810021347 (default boot) + 2: 1.2.0-rolling+201810021217 + 3: 1.2.0-rolling+201809252218 + +``` + +```{eval-rst} +.. opcmd:: delete system image [image-name] + + Delete no longer needed images from the system. You can specify an optional + image name to delete, the image name can be retrieved via a list of available + images can be shown using the {opcmd}`show system image`. + + .. code-block:: none + + vyos@vyos:~$ delete system image + The following image(s) can be deleted: + + 1: 1.3-rolling-201912181733 (default boot) (running image) + 2: 1.3-rolling-201912180242 + 3: 1.2.2 + 4: 1.2.1 + + Select the image to delete: 2 + + Are you sure you want to delete the + "1.3-rolling-201912180242" image? (Yes/No) [No]: y + Deleting the "1.3-rolling-201912180242" image... + Done +``` + +```{eval-rst} +.. opcmd:: show version + + Show current system image version. + + .. code-block:: none + + vyos@vyos:~$ show version + Version: VyOS 1.3-rolling-201912181733 + Built by: autobuild@vyos.net + Built on: Wed 18 Dec 2019 17:33 UTC + Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c + Build Commit ID: f7ce0d8a692f2d + + Architecture: x86_64 + Boot via: installed image + System type: bare metal + + Hardware vendor: VMware, Inc. + Hardware model: VMware Virtual Platform + Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 + Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 + + Copyright: VyOS maintainers and contributors + + + + +``` + +## System rollback + +If you need to rollback to a previous image, you can easily do so. First +check the available images through the {opcmd}`show system image` +command and then select your image with the following command: + +```{eval-rst} +.. opcmd:: set system image default-boot [image-name] + + Select the default boot image which will be started on the next boot + of the system. +``` + +Then reboot the system. + +:::{note} +VyOS automatically associates the configuration to the image, +so you don't need to worry about that. Each image has a unique copy +of its configuration. +::: + +If you have access to the console, there is a another way to select +your booting image: reboot and use the GRUB menu at startup. diff --git a/docs/installation/image.rst b/docs/installation/image.rst deleted file mode 100644 index 77ca01f9..00000000 --- a/docs/installation/image.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. _image-mgmt: - -################ -Image Management -################ - -The VyOS image-based installation is implemented by creating a directory for -each image on the storage device selected during the install process. - -The directory structure of the boot device: - -.. code-block:: none - - / - /boot - /boot/grub - /boot/1.2.0-rolling+201810021347 - -The image directory contains the system kernel, a compressed image of the root -filesystem for the OS, and a directory for persistent storage, such as -configuration. On boot, the system will extract the OS image into memory and -mount the appropriate live-rw sub-directories to provide persistent storage -system configuration. - -This process allows for a system to always boot to a known working state, as -the OS image is fixed and non-persistent. It also allows for multiple releases -of VyOS to be installed on the same storage device. The image can be selected -manually at boot if needed, but the system will otherwise boot the image -configured to be the default. - -.. opcmd:: show system image - - List all available system images which can be booted on the current system. - - .. code-block:: none - - vyos@vyos:~$ show system image - The system currently has the following image(s) installed: - - 1: 1.2.0-rolling+201810021347 (default boot) - 2: 1.2.0-rolling+201810021217 - 3: 1.2.0-rolling+201809252218 - - -.. opcmd:: delete system image [image-name] - - Delete no longer needed images from the system. You can specify an optional - image name to delete, the image name can be retrieved via a list of available - images can be shown using the :opcmd:`show system image`. - - .. code-block:: none - - vyos@vyos:~$ delete system image - The following image(s) can be deleted: - - 1: 1.3-rolling-201912181733 (default boot) (running image) - 2: 1.3-rolling-201912180242 - 3: 1.2.2 - 4: 1.2.1 - - Select the image to delete: 2 - - Are you sure you want to delete the - "1.3-rolling-201912180242" image? (Yes/No) [No]: y - Deleting the "1.3-rolling-201912180242" image... - Done - -.. opcmd:: show version - - Show current system image version. - - .. code-block:: none - - vyos@vyos:~$ show version - Version: VyOS 1.3-rolling-201912181733 - Built by: autobuild@vyos.net - Built on: Wed 18 Dec 2019 17:33 UTC - Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c - Build Commit ID: f7ce0d8a692f2d - - Architecture: x86_64 - Boot via: installed image - System type: bare metal - - Hardware vendor: VMware, Inc. - Hardware model: VMware Virtual Platform - Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 - Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 - - Copyright: VyOS maintainers and contributors - - - - - -System rollback -=============== - -If you need to rollback to a previous image, you can easily do so. First -check the available images through the :opcmd:`show system image` -command and then select your image with the following command: - -.. opcmd:: set system image default-boot [image-name] - - Select the default boot image which will be started on the next boot - of the system. - -Then reboot the system. - -.. note:: VyOS automatically associates the configuration to the image, - so you don't need to worry about that. Each image has a unique copy - of its configuration. - -If you have access to the console, there is a another way to select -your booting image: reboot and use the GRUB menu at startup. diff --git a/docs/installation/index.md b/docs/installation/index.md new file mode 100644 index 00000000..f9e230fc --- /dev/null +++ b/docs/installation/index.md @@ -0,0 +1,28 @@ +# Installation and Image Management + +:::{note} +This is most likely only relevant for virtual installations: + +When installing VyOS ensure that the MAC address selected for your NICs is +not a locally administered MAC address. Locally administered addresses are +distinguished from universally administered addresses by setting (assigning +the value of 1 to) the second-least-significant bit of the first octet of +the address: + +Example: `02:00:00:00:00:01`, where the second-least-significant bit +(`02` in hex) is set to `1`. +::: + +```{eval-rst} +.. toctree:: + :maxdepth: 2 + :caption: Content + + install + virtual/index + cloud/index + vyos-on-baremetal + update + image + migrate-from-vyatta +``` diff --git a/docs/installation/index.rst b/docs/installation/index.rst deleted file mode 100644 index 97f7d85c..00000000 --- a/docs/installation/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -################################# -Installation and Image Management -################################# - -.. note:: This is most likely only relevant for virtual installations: - - When installing VyOS ensure that the MAC address selected for your NICs is - not a locally administered MAC address. Locally administered addresses are - distinguished from universally administered addresses by setting (assigning - the value of 1 to) the second-least-significant bit of the first octet of - the address: - - Example: ``02:00:00:00:00:01``, where the second-least-significant bit - (``02`` in hex) is set to ``1``. - -.. toctree:: - :maxdepth: 2 - :caption: Content - - install - virtual/index - cloud/index - vyos-on-baremetal - update - image - migrate-from-vyatta diff --git a/docs/installation/install.md b/docs/installation/install.md new file mode 100644 index 00000000..a02b3292 --- /dev/null +++ b/docs/installation/install.md @@ -0,0 +1,396 @@ +(installation)= + +# Installation + +VyOS installation requires a downloaded VyOS .iso file. That file is +a live install image that lets you boot a live VyOS. From the live +system, you can proceed to a permanent installation on a hard drive or +any other type of storage. + +```{eval-rst} +.. table:: Comparison of VyOS image releases + + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | Release Type | Description | Release Cycle | Intended Use | Access to Images | Access to Source | + +==============+===================================================+===================+=======================================+=======================+==================+ + | **Nightly | Automatically built from the current branch. | Every night | Developing VyOS, testing new | Everyone | Everyone | + | (Current)** | Always up to date with cutting edge development | | features, experimenting. | | | + | | but guaranteed to contain bugs. | | | | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | **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 | | | + | | feature freeze. | | high-availability setup. | | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | **Early | Highly stable with no known bugs. Needs to be | Irregularly until | Non-critical production environments, | Everyone | Everyone | + | Production | tested repeatedly under different conditions | LTS comes out | preparing for the LTS release. | | | + | Access** | before it can become the final release. | | | | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | **Long-Term | Guaranteed to be stable and carefully maintained | Every major | Large-scale enterprise networks, | Subscribers, | Everyone | + | Support** | for several years after the release. No features | version | internet service providers, | contributors, | | + | | are introduced but security updates are released | | critical production environments | non-profits, | | + | | in a timely manner. | | that call for minimum downtime. | emergency services, | | + | | | | | academic institutions | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ +``` + +## Hardware requirements + +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. + +## Download + +### Registered Subscribers + +Registered subscribers can log into 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. See this [article] for more information on downloads. + +:::{figure} /_static/images/vyosnew-downloads.png +::: + +### Rolling Release + +Everyone can download bleeding-edge VyOS rolling images from: + + +:::{note} +Rolling releases contain all the latest enhancements and fixes. This +means that there will be new bugs of course. If you think you hit a bug +please follow the guide at {ref}`bug_report`. We depend on your feedback +to improve VyOS! +::: + +The following link contains the list of the most recent VyOS builds for AMD64 +systems from the current branch: + + +### 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. +Minisign is used for verification. + +(minisign-verification)= + +#### Minisign verification + +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. It is portable, lightweight, and +uses the highly secure Ed25519 public-key signature system. + +{vytask}`T2108` switched the validation system to prefer minisign over GPG keys. + +To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run: + +```none +$ minisign -V -P RWTR1ty93Oyontk6caB9WqmiQC4fgeyd/ejgRxCRGd2MQej7nqebHneP -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig +Signature and comment signature verified +Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso +``` + +During an image upgrade VyOS performs the following command: + +```none +$ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig +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 + +:::{note} +A permanent VyOS installation always requires to go first +through a live installation. +::: + +VyOS, as other GNU+Linux distributions, can be tested without installing +it in your hard drive. **With your downloaded VyOS .iso file you can +create a bootable USB drive that will let you boot into a fully +functional VyOS system**. Once you have tested it, you can either decide +to begin a {ref}`permanent_installation` in your hard drive or power +your system off, remove the USB drive, and leave everything as it was. + +If you have a GNU+Linux system, you can create your VyOS bootable USB +stick with with the `dd` command: + +> 1. Open your terminal emulator. +> 2. Find out the device name of your USB drive (you can use the `lsblk` +> command) +> 3. Unmount the USB drive. Replace X in the example below with the +> letter of your device and keep the asterisk (wildcard) to unmount +> all partitions. +> +> ```none +> $ umount /dev/sdX* +> ``` +> +> 4. Write the image (your VyOS .iso file) to the USB drive. +> Note that here you want to use the device name (e.g. /dev/sdb), not +> the partition name (e.g. /dev/sdb1). +> +> > **Warning**: This will destroy all data on the USB drive! +> +> ```none +> # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync +> ``` +> +> 5. Wait until you get the outcome (bytes copied). Be patient, in some +> computers it might take more than one minute. +> 6. Once `dd` has finished, pull the USB drive out and plug it into +> the powered-off computer where you want to install (or test) VyOS. +> 7. Power the computer on, making sure it boots from the USB drive (you +> might need to select booting device or change booting settings). +> 8. Once VyOS is completely loaded, enter the default credentials +> (login: vyos, password: vyos). + +If you find difficulties with this method, prefer to use a GUI program, +or have a different operating system, there are other programs you can +use to create a bootable USB drive, like [balenaEtcher] (for GNU/Linux, +macOS and Windows), [Rufus] (for Windows) and [many others]. You can +follow their instructions to create a bootable USB drive from an .iso +file. + +:::{hint} +The default username and password for the live system is *vyos*. +::: + +(permanent_installation)= + +## Permanent installation + +:::{note} +Before a permanent installation, VyOS requires a +{ref}`live_installation`. +::: + +Unlike general purpose Linux distributions, VyOS uses "image installation" that +mimics the user experience of traditional hardware routers and allows keeping +multiple VyOS versions installed simultaneously. This makes it possible to +switch to a previous version if something breaks or miss-behaves after an image +upgrade. + +Every version is contained in its own squashfs image that is mounted in a union +filesystem together with a directory for mutable data such as configurations, +keys, or custom scripts. + +:::{note} +Older versions (prior to VyOS 1.1) used to support non-image +installation (`install system` command). Support for this has been removed +from VyOS 1.2 and newer releases. Older releases can still be upgraded via +the general `add system image ` upgrade command (consult +{ref}`image-mgmt` for further information). +::: + +In order to proceed with a permanent installation: + +> 1. Log into the VyOS live system (use the default credentials: vyos, +> vyos) +> 2. Run the `install image` command and follow the wizard: + +:::{figure} /_static/images/permanent_install.png +3. After the installation is completed, remove the live USB stick or + CD. +4. Reboot the system. + +```none +vyos@vyos:~$ reboot +Proceed with reboot? (Yes/No) [No] Yes +``` + +You will boot now into a permanent VyOS system. +::: + +## PXE Boot + +VyOS can also be installed through PXE. This is a more complex +installation method that allows deploying VyOS through the network. + +**Requirements** + +- Clients (where VyOS is to be installed) with a PXE-enabled NIC +- {ref}`dhcp-server` +- {ref}`tftp-server` +- Webserver (HTTP) - optional, but we will use it to speed up installation +- VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) +- Files *pxelinux.0* and *ldlinux.c32* [from the Syslinux distribution](https://kernel.org/pub/linux/utils/boot/syslinux/) + +### Configuration + +#### Step 1: DHCP + +Configure a DHCP server to provide the client with: + +- An IP address +- The TFTP server address (DHCP option 66). Sometimes referred as *boot server* +- The *bootfile name* (DHCP option 67), which is *pxelinux.0* + +In this example we configured an existent VyOS as the DHCP server: + +```none +vyos@vyos# show service dhcp-server + shared-network-name mydhcp { + subnet 192.168.1.0/24 { + bootfile-name pxelinux.0 + bootfile-server 192.168.1.50 + default-router 192.168.1.50 + range 0 { + start 192.168.1.70 + stop 192.168.1.100 + } + } + } +``` + +(install_from_tftp)= + +#### Step 2: TFTP + +Configure a TFTP server so that it serves the following: + +- The *pxelinux.0* file from the Syslinux distribution +- The *ldlinux.c32* file from the Syslinux distribution +- The kernel of the VyOS software you want to deploy. That is the + *vmlinuz* file inside the */live* directory of the extracted + contents from the ISO file. +- The initial ramdisk of the VyOS ISO you want to deploy. That is the + *initrd.img* file inside the */live* directory of the extracted + contents from the ISO file. Do not use an empty (0 bytes) initrd.img + file you might find, the correct file may have a longer name. +- A directory named pxelinux.cfg which must contain the configuration + file. We will use the [configuration] file shown below, which we named + [default]. + +In the example we configured our existent VyOS as the TFTP server too: + +```none +vyos@vyos# show service tftp-server + directory /config/tftpboot + listen-address 192.168.1.50 +``` + +Example of the contents of the TFTP server: + +```none +vyos@vyos# ls -hal /config/tftpboot/ +total 29M +drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . +drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. +-r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos +-rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 +-rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 +drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg +-r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz + +vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg +total 12K +drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . +drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. +-rw-r--r-- 1 root root 191 Oct 14 01:10 default +``` + +Example of simple (no menu) configuration file: + +```none +vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default +DEFAULT VyOS123 + +LABEL VyOS123 + KERNEL vmlinuz + APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs +``` + +#### Step 3: HTTP + +We also need to provide the *filesystem.squashfs* file. That is a heavy +file and TFTP is slow, so you could send it through HTTP to speed up the +transfer. That is how it is done in our example, you can find that in +the configuration file above. + +**First** run a web server - you can use a simple one like +[Python's SimpleHTTPServer] and start serving the `filesystem.squashfs` +file. The file can be found inside the `/live` directory of the +extracted contents of the ISO file. + +**Second**, edit the configuration file of the {ref}`install_from_tftp` +so that it shows the correct URL at +`fetch=http:///filesystem.squashfs`. + +:::{note} +Do not change the name of the *filesystem.squashfs* file. If +you are working with different versions, you can create different +directories instead. +::: + +And **third**, restart the TFTP service. If you are using VyOS as your +TFTP Server, you can restart the service with +`sudo service tftpd-hpa restart`. + +:::{note} +Make sure the available directories and files in both TFTP +and HTTP server have the right permissions to be accessed from the +booting clients. +::: + +### Client Boot + +Finally, turn on your PXE-enabled client or clients. They will +automatically get an IP address from the DHCP server and start booting +into VyOS live from the files automatically taken from the TFTP and HTTP +servers. + +Once finished you will be able to proceed with the `install image` +command as in a regular VyOS installation. + +## Known Issues + +This is a list of known issues that can arise during installation. + +### Black screen on install + +GRUB attempts to redirect all output to a serial port for ease of installation +on headless hosts. This appears to cause an hard lockup on some hardware that +lacks a serial port, with the result being a black screen after selecting the +`Live system` option from the installation image. + +The workaround is to type `e` when the boot menu appears and edit the GRUB boot +options. Specifically, remove the: + +`console=ttyS0,115200` + +option, and type CTRL-X to boot. + +Installation can then continue as outlined above. + + + +[article]: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913 +[balenaetcher]: https://www.balena.io/etcher/ +[configuration]: https://wiki.syslinux.org/wiki/index.php?title=Config +[default]: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration +[many others]: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems +[python's simplehttpserver]: https://docs.python.org/2/library/simplehttpserver.html +[rufus]: https://rufus.ie/ +[syslinux]: http://www.syslinux.org/ diff --git a/docs/installation/install.rst b/docs/installation/install.rst deleted file mode 100644 index 664e6bc3..00000000 --- a/docs/installation/install.rst +++ /dev/null @@ -1,417 +0,0 @@ -.. _installation: - -############ -Installation -############ - -VyOS installation requires a downloaded VyOS .iso file. That file is -a live install image that lets you boot a live VyOS. From the live -system, you can proceed to a permanent installation on a hard drive or -any other type of storage. - -.. table:: Comparison of VyOS image releases - - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | Release Type | Description | Release Cycle | Intended Use | Access to Images | Access to Source | - +==============+===================================================+===================+=======================================+=======================+==================+ - | **Nightly | Automatically built from the current branch. | Every night | Developing VyOS, testing new | Everyone | Everyone | - | (Current)** | Always up to date with cutting edge development | | features, experimenting. | | | - | | but guaranteed to contain bugs. | | | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **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 | | | - | | feature freeze. | | high-availability setup. | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **Early | Highly stable with no known bugs. Needs to be | Irregularly until | Non-critical production environments, | Everyone | Everyone | - | Production | tested repeatedly under different conditions | LTS comes out | preparing for the LTS release. | | | - | Access** | before it can become the final release. | | | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **Long-Term | Guaranteed to be stable and carefully maintained | Every major | Large-scale enterprise networks, | Subscribers, | Everyone | - | Support** | for several years after the release. No features | version | internet service providers, | contributors, | | - | | are introduced but security updates are released | | critical production environments | non-profits, | | - | | in a timely manner. | | that call for minimum downtime. | emergency services, | | - | | | | | academic institutions | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - -Hardware requirements -===================== - -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. - -Download -======== - -Registered Subscribers ----------------------- - -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. See this article_ for more information on downloads. - -.. figure:: /_static/images/vyosnew-downloads.png - -Rolling Release ---------------- - -Everyone can download bleeding-edge VyOS rolling images from: -https://downloads.vyos.io/ - -.. note:: Rolling releases contain all the latest enhancements and fixes. This - means that there will be new bugs of course. If you think you hit a bug - please follow the guide at :ref:`bug_report`. We depend on your feedback - to improve VyOS! - -The following link contains the list of the most recent VyOS builds for AMD64 -systems from the current branch: -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. -Minisign is used for verification. - -.. _minisign-verification: - -Minisign verification -^^^^^^^^^^^^^^^^^^^^^ - -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. It is portable, lightweight, and -uses the highly secure Ed25519 public-key signature system. - - -:vytask:`T2108` switched the validation system to prefer minisign over GPG keys. - -To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run: - -.. code-block:: none - - $ minisign -V -P RWTR1ty93Oyontk6caB9WqmiQC4fgeyd/ejgRxCRGd2MQej7nqebHneP -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig - Signature and comment signature verified - Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso - -During an image upgrade VyOS performs the following command: - -.. code-block:: none - - $ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig - 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 -================= - -.. note:: A permanent VyOS installation always requires to go first - through a live installation. - -VyOS, as other GNU+Linux distributions, can be tested without installing -it in your hard drive. **With your downloaded VyOS .iso file you can -create a bootable USB drive that will let you boot into a fully -functional VyOS system**. Once you have tested it, you can either decide -to begin a :ref:`permanent_installation` in your hard drive or power -your system off, remove the USB drive, and leave everything as it was. - - -If you have a GNU+Linux system, you can create your VyOS bootable USB -stick with with the ``dd`` command: - - 1. Open your terminal emulator. - - 2. Find out the device name of your USB drive (you can use the ``lsblk`` - command) - - 3. Unmount the USB drive. Replace X in the example below with the - letter of your device and keep the asterisk (wildcard) to unmount - all partitions. - - .. code-block:: none - - $ umount /dev/sdX* - - 4. Write the image (your VyOS .iso file) to the USB drive. - Note that here you want to use the device name (e.g. /dev/sdb), not - the partition name (e.g. /dev/sdb1). - - **Warning**: This will destroy all data on the USB drive! - - .. code-block:: none - - # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync - - 5. Wait until you get the outcome (bytes copied). Be patient, in some - computers it might take more than one minute. - - 6. Once ``dd`` has finished, pull the USB drive out and plug it into - the powered-off computer where you want to install (or test) VyOS. - - 7. Power the computer on, making sure it boots from the USB drive (you - might need to select booting device or change booting settings). - - 8. Once VyOS is completely loaded, enter the default credentials - (login: vyos, password: vyos). - - -If you find difficulties with this method, prefer to use a GUI program, -or have a different operating system, there are other programs you can -use to create a bootable USB drive, like balenaEtcher_ (for GNU/Linux, -macOS and Windows), Rufus_ (for Windows) and `many others`_. You can -follow their instructions to create a bootable USB drive from an .iso -file. - -.. hint:: The default username and password for the live system is *vyos*. - - -.. _permanent_installation: - -Permanent installation -====================== - -.. note:: Before a permanent installation, VyOS requires a - :ref:`live_installation`. - -Unlike general purpose Linux distributions, VyOS uses "image installation" that -mimics the user experience of traditional hardware routers and allows keeping -multiple VyOS versions installed simultaneously. This makes it possible to -switch to a previous version if something breaks or miss-behaves after an image -upgrade. - -Every version is contained in its own squashfs image that is mounted in a union -filesystem together with a directory for mutable data such as configurations, -keys, or custom scripts. - -.. note:: Older versions (prior to VyOS 1.1) used to support non-image - installation (``install system`` command). Support for this has been removed - from VyOS 1.2 and newer releases. Older releases can still be upgraded via - the general ``add system image `` upgrade command (consult - :ref:`image-mgmt` for further information). - - -In order to proceed with a permanent installation: - - 1. Log into the VyOS live system (use the default credentials: vyos, - vyos) - - 2. Run the ``install image`` command and follow the wizard: - -.. figure:: /_static/images/permanent_install.png - - 3. After the installation is completed, remove the live USB stick or - CD. - - 4. Reboot the system. - - .. code-block:: none - - vyos@vyos:~$ reboot - Proceed with reboot? (Yes/No) [No] Yes - - You will boot now into a permanent VyOS system. - - -PXE Boot -======== - -VyOS can also be installed through PXE. This is a more complex -installation method that allows deploying VyOS through the network. - -**Requirements** - -* Clients (where VyOS is to be installed) with a PXE-enabled NIC -* :ref:`dhcp-server` -* :ref:`tftp-server` -* Webserver (HTTP) - optional, but we will use it to speed up installation -* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) -* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution - `_ - -Configuration -------------- - -Step 1: DHCP -^^^^^^^^^^^^ - -Configure a DHCP server to provide the client with: - -* An IP address -* The TFTP server address (DHCP option 66). Sometimes referred as *boot server* -* The *bootfile name* (DHCP option 67), which is *pxelinux.0* - -In this example we configured an existent VyOS as the DHCP server: - -.. code-block:: none - - vyos@vyos# show service dhcp-server - shared-network-name mydhcp { - subnet 192.168.1.0/24 { - bootfile-name pxelinux.0 - bootfile-server 192.168.1.50 - default-router 192.168.1.50 - range 0 { - start 192.168.1.70 - stop 192.168.1.100 - } - } - } - -.. _install_from_tftp: - -Step 2: TFTP -^^^^^^^^^^^^ - -Configure a TFTP server so that it serves the following: - -* The *pxelinux.0* file from the Syslinux distribution -* The *ldlinux.c32* file from the Syslinux distribution -* The kernel of the VyOS software you want to deploy. That is the - *vmlinuz* file inside the */live* directory of the extracted - contents from the ISO file. -* The initial ramdisk of the VyOS ISO you want to deploy. That is the - *initrd.img* file inside the */live* directory of the extracted - contents from the ISO file. Do not use an empty (0 bytes) initrd.img - file you might find, the correct file may have a longer name. -* A directory named pxelinux.cfg which must contain the configuration - file. We will use the configuration_ file shown below, which we named - default_. - -In the example we configured our existent VyOS as the TFTP server too: - -.. code-block:: none - - vyos@vyos# show service tftp-server - directory /config/tftpboot - listen-address 192.168.1.50 - -Example of the contents of the TFTP server: - -.. code-block:: none - - vyos@vyos# ls -hal /config/tftpboot/ - total 29M - drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . - drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. - -r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos - -rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 - -rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 - drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg - -r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz - - vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg - total 12K - drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . - drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. - -rw-r--r-- 1 root root 191 Oct 14 01:10 default - -Example of simple (no menu) configuration file: - -.. code-block:: none - - vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default - DEFAULT VyOS123 - - LABEL VyOS123 - KERNEL vmlinuz - APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs - -Step 3: HTTP -^^^^^^^^^^^^ - -We also need to provide the *filesystem.squashfs* file. That is a heavy -file and TFTP is slow, so you could send it through HTTP to speed up the -transfer. That is how it is done in our example, you can find that in -the configuration file above. - -**First** run a web server - you can use a simple one like -`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs` -file. The file can be found inside the `/live` directory of the -extracted contents of the ISO file. - -**Second**, edit the configuration file of the :ref:`install_from_tftp` -so that it shows the correct URL at -``fetch=http:///filesystem.squashfs``. - -.. note:: Do not change the name of the *filesystem.squashfs* file. If - you are working with different versions, you can create different - directories instead. - -And **third**, restart the TFTP service. If you are using VyOS as your -TFTP Server, you can restart the service with -``sudo service tftpd-hpa restart``. - -.. note:: Make sure the available directories and files in both TFTP - and HTTP server have the right permissions to be accessed from the - booting clients. - - - -Client Boot ------------ - -Finally, turn on your PXE-enabled client or clients. They will -automatically get an IP address from the DHCP server and start booting -into VyOS live from the files automatically taken from the TFTP and HTTP -servers. - -Once finished you will be able to proceed with the ``install image`` -command as in a regular VyOS installation. - - - -Known Issues -============ - -This is a list of known issues that can arise during installation. - -Black screen on install ------------------------ - -GRUB attempts to redirect all output to a serial port for ease of installation -on headless hosts. This appears to cause an hard lockup on some hardware that -lacks a serial port, with the result being a black screen after selecting the -`Live system` option from the installation image. - -The workaround is to type `e` when the boot menu appears and edit the GRUB boot -options. Specifically, remove the: - -`console=ttyS0,115200` - -option, and type CTRL-X to boot. - -Installation can then continue as outlined above. - - -.. stop_vyoslinter - -.. _SYSLINUX: http://www.syslinux.org/ -.. _balenaEtcher: https://www.balena.io/etcher/ -.. _Rufus: https://rufus.ie/ -.. _many others: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems -.. _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 diff --git a/docs/installation/md-image.md b/docs/installation/md-image.md deleted file mode 100644 index 7581d065..00000000 --- a/docs/installation/md-image.md +++ /dev/null @@ -1,122 +0,0 @@ -(image-mgmt)= - -# Image Management - -The VyOS image-based installation is implemented by creating a directory for -each image on the storage device selected during the install process. - -The directory structure of the boot device: - -```none -/ -/boot -/boot/grub -/boot/1.2.0-rolling+201810021347 -``` - -The image directory contains the system kernel, a compressed image of the root -filesystem for the OS, and a directory for persistent storage, such as -configuration. On boot, the system will extract the OS image into memory and -mount the appropriate live-rw sub-directories to provide persistent storage -system configuration. - -This process allows for a system to always boot to a known working state, as -the OS image is fixed and non-persistent. It also allows for multiple releases -of VyOS to be installed on the same storage device. The image can be selected -manually at boot if needed, but the system will otherwise boot the image -configured to be the default. - -```{eval-rst} -.. opcmd:: show system image - - List all available system images which can be booted on the current system. - - .. code-block:: none - - vyos@vyos:~$ show system image - The system currently has the following image(s) installed: - - 1: 1.2.0-rolling+201810021347 (default boot) - 2: 1.2.0-rolling+201810021217 - 3: 1.2.0-rolling+201809252218 - -``` - -```{eval-rst} -.. opcmd:: delete system image [image-name] - - Delete no longer needed images from the system. You can specify an optional - image name to delete, the image name can be retrieved via a list of available - images can be shown using the {opcmd}`show system image`. - - .. code-block:: none - - vyos@vyos:~$ delete system image - The following image(s) can be deleted: - - 1: 1.3-rolling-201912181733 (default boot) (running image) - 2: 1.3-rolling-201912180242 - 3: 1.2.2 - 4: 1.2.1 - - Select the image to delete: 2 - - Are you sure you want to delete the - "1.3-rolling-201912180242" image? (Yes/No) [No]: y - Deleting the "1.3-rolling-201912180242" image... - Done -``` - -```{eval-rst} -.. opcmd:: show version - - Show current system image version. - - .. code-block:: none - - vyos@vyos:~$ show version - Version: VyOS 1.3-rolling-201912181733 - Built by: autobuild@vyos.net - Built on: Wed 18 Dec 2019 17:33 UTC - Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c - Build Commit ID: f7ce0d8a692f2d - - Architecture: x86_64 - Boot via: installed image - System type: bare metal - - Hardware vendor: VMware, Inc. - Hardware model: VMware Virtual Platform - Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 - Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 - - Copyright: VyOS maintainers and contributors - - - - -``` - -## System rollback - -If you need to rollback to a previous image, you can easily do so. First -check the available images through the {opcmd}`show system image` -command and then select your image with the following command: - -```{eval-rst} -.. opcmd:: set system image default-boot [image-name] - - Select the default boot image which will be started on the next boot - of the system. -``` - -Then reboot the system. - -:::{note} -VyOS automatically associates the configuration to the image, -so you don't need to worry about that. Each image has a unique copy -of its configuration. -::: - -If you have access to the console, there is a another way to select -your booting image: reboot and use the GRUB menu at startup. diff --git a/docs/installation/md-index.md b/docs/installation/md-index.md deleted file mode 100644 index f9e230fc..00000000 --- a/docs/installation/md-index.md +++ /dev/null @@ -1,28 +0,0 @@ -# Installation and Image Management - -:::{note} -This is most likely only relevant for virtual installations: - -When installing VyOS ensure that the MAC address selected for your NICs is -not a locally administered MAC address. Locally administered addresses are -distinguished from universally administered addresses by setting (assigning -the value of 1 to) the second-least-significant bit of the first octet of -the address: - -Example: `02:00:00:00:00:01`, where the second-least-significant bit -(`02` in hex) is set to `1`. -::: - -```{eval-rst} -.. toctree:: - :maxdepth: 2 - :caption: Content - - install - virtual/index - cloud/index - vyos-on-baremetal - update - image - migrate-from-vyatta -``` diff --git a/docs/installation/md-install.md b/docs/installation/md-install.md deleted file mode 100644 index a02b3292..00000000 --- a/docs/installation/md-install.md +++ /dev/null @@ -1,396 +0,0 @@ -(installation)= - -# Installation - -VyOS installation requires a downloaded VyOS .iso file. That file is -a live install image that lets you boot a live VyOS. From the live -system, you can proceed to a permanent installation on a hard drive or -any other type of storage. - -```{eval-rst} -.. table:: Comparison of VyOS image releases - - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | Release Type | Description | Release Cycle | Intended Use | Access to Images | Access to Source | - +==============+===================================================+===================+=======================================+=======================+==================+ - | **Nightly | Automatically built from the current branch. | Every night | Developing VyOS, testing new | Everyone | Everyone | - | (Current)** | Always up to date with cutting edge development | | features, experimenting. | | | - | | but guaranteed to contain bugs. | | | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **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 | | | - | | feature freeze. | | high-availability setup. | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **Early | Highly stable with no known bugs. Needs to be | Irregularly until | Non-critical production environments, | Everyone | Everyone | - | Production | tested repeatedly under different conditions | LTS comes out | preparing for the LTS release. | | | - | Access** | before it can become the final release. | | | | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ - | **Long-Term | Guaranteed to be stable and carefully maintained | Every major | Large-scale enterprise networks, | Subscribers, | Everyone | - | Support** | for several years after the release. No features | version | internet service providers, | contributors, | | - | | are introduced but security updates are released | | critical production environments | non-profits, | | - | | in a timely manner. | | that call for minimum downtime. | emergency services, | | - | | | | | academic institutions | | - +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ -``` - -## Hardware requirements - -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. - -## Download - -### Registered Subscribers - -Registered subscribers can log into 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. See this [article] for more information on downloads. - -:::{figure} /_static/images/vyosnew-downloads.png -::: - -### Rolling Release - -Everyone can download bleeding-edge VyOS rolling images from: - - -:::{note} -Rolling releases contain all the latest enhancements and fixes. This -means that there will be new bugs of course. If you think you hit a bug -please follow the guide at {ref}`bug_report`. We depend on your feedback -to improve VyOS! -::: - -The following link contains the list of the most recent VyOS builds for AMD64 -systems from the current branch: - - -### 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. -Minisign is used for verification. - -(minisign-verification)= - -#### Minisign verification - -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. It is portable, lightweight, and -uses the highly secure Ed25519 public-key signature system. - -{vytask}`T2108` switched the validation system to prefer minisign over GPG keys. - -To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run: - -```none -$ minisign -V -P RWTR1ty93Oyontk6caB9WqmiQC4fgeyd/ejgRxCRGd2MQej7nqebHneP -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig -Signature and comment signature verified -Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso -``` - -During an image upgrade VyOS performs the following command: - -```none -$ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig -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 - -:::{note} -A permanent VyOS installation always requires to go first -through a live installation. -::: - -VyOS, as other GNU+Linux distributions, can be tested without installing -it in your hard drive. **With your downloaded VyOS .iso file you can -create a bootable USB drive that will let you boot into a fully -functional VyOS system**. Once you have tested it, you can either decide -to begin a {ref}`permanent_installation` in your hard drive or power -your system off, remove the USB drive, and leave everything as it was. - -If you have a GNU+Linux system, you can create your VyOS bootable USB -stick with with the `dd` command: - -> 1. Open your terminal emulator. -> 2. Find out the device name of your USB drive (you can use the `lsblk` -> command) -> 3. Unmount the USB drive. Replace X in the example below with the -> letter of your device and keep the asterisk (wildcard) to unmount -> all partitions. -> -> ```none -> $ umount /dev/sdX* -> ``` -> -> 4. Write the image (your VyOS .iso file) to the USB drive. -> Note that here you want to use the device name (e.g. /dev/sdb), not -> the partition name (e.g. /dev/sdb1). -> -> > **Warning**: This will destroy all data on the USB drive! -> -> ```none -> # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync -> ``` -> -> 5. Wait until you get the outcome (bytes copied). Be patient, in some -> computers it might take more than one minute. -> 6. Once `dd` has finished, pull the USB drive out and plug it into -> the powered-off computer where you want to install (or test) VyOS. -> 7. Power the computer on, making sure it boots from the USB drive (you -> might need to select booting device or change booting settings). -> 8. Once VyOS is completely loaded, enter the default credentials -> (login: vyos, password: vyos). - -If you find difficulties with this method, prefer to use a GUI program, -or have a different operating system, there are other programs you can -use to create a bootable USB drive, like [balenaEtcher] (for GNU/Linux, -macOS and Windows), [Rufus] (for Windows) and [many others]. You can -follow their instructions to create a bootable USB drive from an .iso -file. - -:::{hint} -The default username and password for the live system is *vyos*. -::: - -(permanent_installation)= - -## Permanent installation - -:::{note} -Before a permanent installation, VyOS requires a -{ref}`live_installation`. -::: - -Unlike general purpose Linux distributions, VyOS uses "image installation" that -mimics the user experience of traditional hardware routers and allows keeping -multiple VyOS versions installed simultaneously. This makes it possible to -switch to a previous version if something breaks or miss-behaves after an image -upgrade. - -Every version is contained in its own squashfs image that is mounted in a union -filesystem together with a directory for mutable data such as configurations, -keys, or custom scripts. - -:::{note} -Older versions (prior to VyOS 1.1) used to support non-image -installation (`install system` command). Support for this has been removed -from VyOS 1.2 and newer releases. Older releases can still be upgraded via -the general `add system image ` upgrade command (consult -{ref}`image-mgmt` for further information). -::: - -In order to proceed with a permanent installation: - -> 1. Log into the VyOS live system (use the default credentials: vyos, -> vyos) -> 2. Run the `install image` command and follow the wizard: - -:::{figure} /_static/images/permanent_install.png -3. After the installation is completed, remove the live USB stick or - CD. -4. Reboot the system. - -```none -vyos@vyos:~$ reboot -Proceed with reboot? (Yes/No) [No] Yes -``` - -You will boot now into a permanent VyOS system. -::: - -## PXE Boot - -VyOS can also be installed through PXE. This is a more complex -installation method that allows deploying VyOS through the network. - -**Requirements** - -- Clients (where VyOS is to be installed) with a PXE-enabled NIC -- {ref}`dhcp-server` -- {ref}`tftp-server` -- Webserver (HTTP) - optional, but we will use it to speed up installation -- VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) -- Files *pxelinux.0* and *ldlinux.c32* [from the Syslinux distribution](https://kernel.org/pub/linux/utils/boot/syslinux/) - -### Configuration - -#### Step 1: DHCP - -Configure a DHCP server to provide the client with: - -- An IP address -- The TFTP server address (DHCP option 66). Sometimes referred as *boot server* -- The *bootfile name* (DHCP option 67), which is *pxelinux.0* - -In this example we configured an existent VyOS as the DHCP server: - -```none -vyos@vyos# show service dhcp-server - shared-network-name mydhcp { - subnet 192.168.1.0/24 { - bootfile-name pxelinux.0 - bootfile-server 192.168.1.50 - default-router 192.168.1.50 - range 0 { - start 192.168.1.70 - stop 192.168.1.100 - } - } - } -``` - -(install_from_tftp)= - -#### Step 2: TFTP - -Configure a TFTP server so that it serves the following: - -- The *pxelinux.0* file from the Syslinux distribution -- The *ldlinux.c32* file from the Syslinux distribution -- The kernel of the VyOS software you want to deploy. That is the - *vmlinuz* file inside the */live* directory of the extracted - contents from the ISO file. -- The initial ramdisk of the VyOS ISO you want to deploy. That is the - *initrd.img* file inside the */live* directory of the extracted - contents from the ISO file. Do not use an empty (0 bytes) initrd.img - file you might find, the correct file may have a longer name. -- A directory named pxelinux.cfg which must contain the configuration - file. We will use the [configuration] file shown below, which we named - [default]. - -In the example we configured our existent VyOS as the TFTP server too: - -```none -vyos@vyos# show service tftp-server - directory /config/tftpboot - listen-address 192.168.1.50 -``` - -Example of the contents of the TFTP server: - -```none -vyos@vyos# ls -hal /config/tftpboot/ -total 29M -drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . -drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. --r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos --rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 --rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 -drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg --r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz - -vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg -total 12K -drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . -drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. --rw-r--r-- 1 root root 191 Oct 14 01:10 default -``` - -Example of simple (no menu) configuration file: - -```none -vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default -DEFAULT VyOS123 - -LABEL VyOS123 - KERNEL vmlinuz - APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs -``` - -#### Step 3: HTTP - -We also need to provide the *filesystem.squashfs* file. That is a heavy -file and TFTP is slow, so you could send it through HTTP to speed up the -transfer. That is how it is done in our example, you can find that in -the configuration file above. - -**First** run a web server - you can use a simple one like -[Python's SimpleHTTPServer] and start serving the `filesystem.squashfs` -file. The file can be found inside the `/live` directory of the -extracted contents of the ISO file. - -**Second**, edit the configuration file of the {ref}`install_from_tftp` -so that it shows the correct URL at -`fetch=http:///filesystem.squashfs`. - -:::{note} -Do not change the name of the *filesystem.squashfs* file. If -you are working with different versions, you can create different -directories instead. -::: - -And **third**, restart the TFTP service. If you are using VyOS as your -TFTP Server, you can restart the service with -`sudo service tftpd-hpa restart`. - -:::{note} -Make sure the available directories and files in both TFTP -and HTTP server have the right permissions to be accessed from the -booting clients. -::: - -### Client Boot - -Finally, turn on your PXE-enabled client or clients. They will -automatically get an IP address from the DHCP server and start booting -into VyOS live from the files automatically taken from the TFTP and HTTP -servers. - -Once finished you will be able to proceed with the `install image` -command as in a regular VyOS installation. - -## Known Issues - -This is a list of known issues that can arise during installation. - -### Black screen on install - -GRUB attempts to redirect all output to a serial port for ease of installation -on headless hosts. This appears to cause an hard lockup on some hardware that -lacks a serial port, with the result being a black screen after selecting the -`Live system` option from the installation image. - -The workaround is to type `e` when the boot menu appears and edit the GRUB boot -options. Specifically, remove the: - -`console=ttyS0,115200` - -option, and type CTRL-X to boot. - -Installation can then continue as outlined above. - - - -[article]: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913 -[balenaetcher]: https://www.balena.io/etcher/ -[configuration]: https://wiki.syslinux.org/wiki/index.php?title=Config -[default]: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration -[many others]: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems -[python's simplehttpserver]: https://docs.python.org/2/library/simplehttpserver.html -[rufus]: https://rufus.ie/ -[syslinux]: http://www.syslinux.org/ diff --git a/docs/installation/md-update.md b/docs/installation/md-update.md deleted file mode 100644 index e2c16ceb..00000000 --- a/docs/installation/md-update.md +++ /dev/null @@ -1,86 +0,0 @@ -(update_vyos)= - -# Update VyOS - -New system images can be added using the {opcmd}`add system image` -command. The command will extract the chosen image and will prompt you -to use the current system configuration and SSH security keys, allowing -for the new image to boot using the current configuration. - -:::{note} -Only LTS releases are PGP-signed. -::: - -```{eval-rst} -.. opcmd:: add system image [vrf name] - [username user [password pass]] - - Use this command to install a new system image. You can reach the - image from the web (``http://``, ``https://``) or from your local system, - e.g. /tmp/vyos-1.2.3-amd64.iso. - - The `add system image` command also supports installing new versions - of VyOS through an optional given VRF. Also if URL in question requires - authentication, you can specify an optional username and password via - the commandline which will be passed as "Basic-Auth" to the server. -``` - -If there is not enough **free disk space available**, the installation -will be canceled. To delete images use the {opcmd}`delete system image` -command. - -VyOS configuration is associated to each image, and **each image has a -unique copy of its configuration**. This is different than a traditional -network router where the configuration is shared across all images. - -:::{note} -If you have any personal files, like some scripts you created, -and you don't want them to be lost during the upgrade, make sure -those files are stored in `/config` as this directory is always copied -to newer installed images. -::: - -You can access files from a previous installation and copy them to your -current image if they were located in the `/config` directory. This -can be done using the {opcmd}`copy` command. So, for instance, in order -to copy `/config/config.boot` from VyOS 1.2.1 image, you would use the -following command: - -```{code} -copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 -``` - -## Example - -```none -vyos@vyos:~$ add system image https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso -Trying to fetch ISO file from https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed -100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k -ISO download succeeded. -Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 -curl: (22) The requested URL returned error: 404 Not Found - -Unable to fetch digital signature file. -Do you want to continue without signature check? (yes/no) [yes] -Checking MD5 checksums of files on the ISO image...OK. -Done! - -What would you like to name this image? [vyos-1.3-rolling-201912201452]: - -OK. This image will be named: vyos-1.3-rolling-201912201452 -``` - -:::{hint} -The most up-do-date Rolling Release for AMD64 can be accessed using -the following URL: - - -::: - -After reboot you might want to verify the version you are running with -the {opcmd}`show version` command. diff --git a/docs/installation/md-vyos-on-baremetal.md b/docs/installation/md-vyos-on-baremetal.md deleted file mode 100644 index b551a811..00000000 --- a/docs/installation/md-vyos-on-baremetal.md +++ /dev/null @@ -1,626 +0,0 @@ -(vyosonbaremetal)= - -# Running on Bare Metal - -## Supermicro A2SDi (Atom C3000) - -I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. -Running VyOS on an UEFI only device is supported as of VyOS release 1.2. - -### Supermicro Shopping Cart - -- 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) -- 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) -- 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN - with Intel C3000 SoC 1GbE) -- 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) -- 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) -- 1x Supermicro MCP-320-81302-0B (optional FAN tray) - -### Optional (10GE) - -If you want to get additional ethernet ports or even 10GE connectivity -the following optional parts will be required: - -- 1x Supermicro RSC-RR1U-E8 (Riser Card) -- 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) - -Latest VyOS rolling releases boot without any problem on this board. You also -receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no -information about [OpenBMC](https://www.openbmc.org/) so far on this -motherboard). - -### Pictures - -:::{figure} /_static/images/1u_vyos_back.jpg -:alt: CSE-505-203B Back -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front.jpg -:alt: CSE-505-203B Front -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_open_1.jpg -:alt: CSE-505-203B Open 1 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_open_2.jpg -:alt: CSE-505-203B Open 2 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_open_3.jpg -:alt: CSE-505-203B Open 3 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_10ge_open_1.jpg -:alt: CSE-505-203B w/ 10GE Open 1 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_10ge_open_2.jpg -:alt: CSE-505-203B w/ 10GE Open 2 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_10ge_open_3.jpg -:alt: CSE-505-203B w/ 10GE Open 3 -:scale: 25 % -::: - -:::{figure} /_static/images/1u_vyos_front_10ge_open_4.jpg -:alt: CSE-505-203B w/ 10GE Open -:scale: 25 % -::: - -(pc-engines-apu4)= - -## PC Engines APU4 - -As this platform seems to be quite common in terms of noise, cost, power and -performance it makes sense to write a small installation manual. - -This guide was developed using an APU4C4 board with the following specs: - -- AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI - support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. -- 4 GB DDR3-1333 DRAM, with optional ECC support -- About 6 to 10W of 12V DC power depending on CPU load -- 2 miniPCI express (one with SIM socket for 3G modem). -- 4 Gigabit Ethernet channels using Intel i211AT NICs - -The board can be powered via 12V from the front or via a 5V onboard connector. - -(vyos-on-baremetal-apu4-shopping)= - -### APU4 Shopping Cart - -- 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM -- 1x Kingston SUV500MS/120G -- 1x VARIA Group Item 326745 19" dual rack for APU4 - -The 19" enclosure can accommodate up to two APU4 boards - there is a single and -dual front cover. - -#### Extension Modules - -##### WiFi - -Refer to {ref}`wireless-interface` for additional information, below listed -modules have been tested successfully on this Hardware platform: - -- Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. -- Intel Corporation AX200 mini-PCIe WiFi module, only supported in mPCIe slot 1. - (see {ref}`wireless-interface-intel-ax200`) - -##### WWAN - -Refer to {ref}`wwan-interface` for additional information, below listed modules -have been tested successfully on this Hardware platform using VyOS 1.3 -(equuleus): - -- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) -- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) -- Huawei ME909u-521 miniPCIe card (LTE) - -### VyOS 1.4 (sagitta) - -Depending on the VyOS versions you intend to install there is a difference in -the serial port settings ({vytask}`T1327`). - -Create a bootable USB pendrive using e.g. [Rufus] on a Windows machine. - -Connect serial port to a PC through null modem cable (RXD / TXD crossed over). -Set terminal emulator to 115200 8N1. - - -```none -PC Engines apu4 -coreboot build 20171130 -BIOS version v4.6.4 -4080 MB ECC DRAM -SeaBIOS (version rel-1.11.0.1-0-g90da88d) - -Press F10 key now for boot menu: - -Select boot device: - -1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) -2. USB MSC Drive Generic Flash Disk 8.07 -3. Payload [memtest] -4. Payload [setup] -``` - - -Now boot from the `USB MSC Drive Generic Flash Disk 8.07` media by pressing -`2`, the VyOS boot menu will appear, just wait 10 seconds or press `Enter` -to continue. - -```none -lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk -x VyOS - Boot Menu x -tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu -x Live system (amd64-vyos) x -x Live system (amd64-vyos fail-safe mode) x -x Live system (amd64-vyos) - Serial console x -x x -mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj -``` - -The image will be loaded and the last lines you will get will be: - -```none -Loading /live/vmlinuz... ok -Loading /live/initrd.img... -... -Welcome to VyOS - vyos ttyS0 - -vyos login: -``` - -You can now proceed with a regular image installation as described in -{ref}`installation`. - -(vyos-on-baremetal-apu4-pictures)= - -### Pictures - -:::{note} -Both device types operate without any moving parts and emit zero -noise. -::: - -#### Rack Mount - -:::{figure} /_static/images/apu4_rack_1.jpg -:alt: APU4 rack closed -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_rack_2.jpg -:alt: APU4 rack front -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_rack_3.jpg -:alt: 'APU4 rack module #1' -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_rack_4.jpg -:alt: 'APU4 rack module #2' -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_rack_5.jpg -:alt: 'APU4 rack module #3 with PSU' -:scale: 25 % -::: - -##### VyOS custom print - -:::{figure} /_static/images/apu4_rack_vyos_print.jpg -:alt: APU4 custom VyOS powder coat -:scale: 25 % -::: - -#### Desktop / Bench Top - -:::{figure} /_static/images/apu4_desk_1.jpg -:alt: APU4 desktop closed -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_desk_2.jpg -:alt: APU4 desktop closed -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_desk_3.jpg -:alt: APU4 desktop back -:scale: 25 % -::: - -:::{figure} /_static/images/apu4_desk_4.jpg -:alt: APU4 desktop back -:scale: 25 % -::: - -## Qotom Q355G4 - -The install on this Q355G4 box is pretty much plug and play. The port numbering -the OS does might differ from the labels on the outside, but the UEFI firmware -has a port blink test built in with MAC addresses so you can very quickly -identify which is which. MAC labels are on the inside as well, and this test -can be done from VyOS or plain Linux too. Default settings in the UEFI will -make it boot, but depending on your installation wishes (i.e. storage type, -boot type, console type) you might want to adjust them. This Qotom company -seems to be the real OEM/ODM for many other relabelling companies like -Protectli. - -### Hardware - -There are a number of other options, but they all seem to be close to Intel -reference designs, with added features like more serial ports, more network -interfaces and the likes. Because they don't deviate too much from standard -designs all the hardware is well-supported by mainline. It accepts one LPDDR3 -SO-DIMM, but chances are that if you need more than that, you'll also want -something even beefier than an i5. There are options for antenna holes, and SIM -slots, so you could in theory add an LTE/Cell modem (not tested so far). - -The chassis is a U-shaped alu extrusion with removable I/O plates and removable -bottom plate. Cooling is completely passive with a heatsink on the SoC with -internal and external fins, a flat interface surface, thermal pad on top of -that, which then directly attaches to the chassis, which has fins as well. It -comes with mounting hardware and rubber feet, so you could place it like a -desktop model or mount it on a VESA mount, or even wall mount it with the -provided mounting plate. The closing plate doubles as internal 2.5" mounting -place for an HDD or SSD, and comes supplied with a small SATA cable and SATA -power cable. - -Power supply is a 12VDC barrel jack, and included switching power supply, which -is why SATA power regulation is on-board. Internally it has a NUC-board-style -on-board 12V input header as well, the molex locking style. - -There are WDT options and auto-boot on power enable, which is great for remote -setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled -in enforcement mode, which is good but also means no coreboot option), yet has -most options available to configure (so it's not locked out like most firmwares -are). - -An external RS232 serial port is available, internally a GPIO header as well. -It does have Realtek based audio on board for some reason, but you can disable -that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS -mode and HDMI BIOS mode depends on what is connected at startup; it goes into -serial mode if you disconnect HDMI and plug in serial, in all other cases it's -HDMI mode. - -## Partaker i5 - -:::{figure} ../_static/images/600px-Partaker-i5.jpg -::: - -I believe this is actually the same hardware as the Protectli. I purchased it -in June 2018. It came pre-loaded with pfSense. - -[Manufacturer product page](http://www.inctel.com.cn/product/detail/338.html). - -### Installation - -- Write VyOS ISO to USB drive of some sort -- Plug in VGA, power, USB keyboard, and USB drive -- Press "SW" button on the front (this is the power button; I don't know what - "SW" is supposed to mean). -- Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, - but with a few tries you should be able to get into the BIOS. -- Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 - (EHCI) to Enabled. Without doing this, the USB drive won't boot. -- Boot to the VyOS installer and install as usual. - -Warning the interface labels on my device are backwards; the left-most "LAN4" -port is eth0 and the right-most "LAN1" port is eth3. - -## Acrosser AND-J190N1 - -:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg -::: - -:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg -::: - -This microbox network appliance was build to create OpenVPN bridges. It can -saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN - -You may have to add your own RAM and HDD/SSD. There is no VGA connector. But -Acrosser provides a DB25 adapter for the VGA header on the motherboard (not -used). - -### BIOS Settings: - -First thing you want to do is getting a more user friendly console to configure -BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. - -For practical issues change speed from 115200 to 9600. 9600 is the default -speed at which both linux kernel and VyOS will reconfigure the serial port -when loading. - -Connect to serial (115200bps). Power on the appliance and press Del in the -console when requested to enter BIOS settings. - -Advanced > Serial Port Console Redirection > Console Redirection Settings: - -- Terminal Type : VT100+ -- Bits per second : 9600 - -Save, reboot and change serial speed to 9600 on your client. - -Some options have to be changed for VyOS to boot correctly. With XHCI enabled -the installer can’t access the USB key. Enable EHCI instead. - -Reboot into BIOS, Chipset > South Bridge > USB Configuration: - -- Disable XHCI -- Enable USB 2.0 (EHCI) Support - -Perform Image installation using `install image` CLI command. - -(gowin-gw-fn-1ur1-10g)= - -## Gowin GW-FN-1UR1-10G - -A platform utilizing an Intel Alder Lake-N100 CPU with 6M cache, TDP 6W. -Onboard LPDDR5 16GB RAM and 128GB eMMC (can be used for image installation). - -The appliance comes with 2 * 2.5GbE Intel I226-V and 3 * 1GbE Intel I210 -where one supports IEEE802.3at PoE+ (Typical 30W). - -In addition there is a Mellanox ConnectX-3 2\* 10GbE SFP+ NIC available. - -**NOTE:** This is the entry level platform. Other derivates exists with -i3-N305 CPU and 2x 25GbE! - -### Gowin Shopping Cart - -- 1x Gowin GW-FN-1UR1-10G -- 2x 128GB M.2 NVMe SSDs - -### Optional (WiFi + WWAN) - -- 1x MediaTek 7921E M.2 NGFF WIFI module (not tested as this currently leads to - a Kernel crash) -- 1x HP LT4120 Snapdragon X5 LTE WWAN module - -### Pictures - -:::{figure} ../_static/images/gowin-01.png -::: - -:::{figure} ../_static/images/gowin-02.png -::: - -:::{figure} ../_static/images/gowin-03.png -::: - -:::{figure} ../_static/images/gowin-04.png -::: - -### Cooling - -The device itself is passivly cooled, whereas the power supply has an active fan. -Even if the main processor is powered off, the power supply fan is operating and -the entire chassis draws 7.5W. During operation the chassis drew arround 38W. - -### BIOS Settings - -No settings needed to be altered, everything worked out of the box! - -### Installation - -The system provides a regular RS232 console port using 115200,8n1 setting which -is sufficient to install VyOS from a USB pendrive. - -### First Boot - -Please note that there is a weirdness on the network interface mapping. -The interface \<-> MAC mapping is going upwards but the NICs are placed -somehow swapped on the mainboard/MACs programmed in a swapped order. - -See interface description for more detailed mapping. - -```none -vyos@vyos:~$ show interfaces -Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down -Interface IP Address MAC VRF MTU S/L Description ------------ -------------- ----------------- ------- ----- ----- ------------- -eth0 - 00:f0:cb:00:00:99 default 1500 u/D Intel I226-V - Front eth2 -eth1 - 00:f0:cb:00:00:9a default 1500 u/D Intel I226-V - Front eth1 -eth2 - 00:f0:cb:00:00:9b default 1500 u/D Intel I210 - Front eth4 -eth3 - 00:f0:cb:00:00:9c default 1500 u/D Intel I210 - Front eth3 -eth4 - 00:f0:cb:00:00:9d default 1500 u/D Intel I210 - Front POE -eth5 - 00:02:c9:00:00:30 default 1500 u/D Mellanox ConnectX-3 - SFP2 -eth6 - 00:02:c9:00:00:31 default 1500 u/D Mellanox ConnectX-3 - SFP1 -lo 127.0.0.1/8 00:00:00:00:00:00 default 65536 u/u - ::1/128 -wwan0 - d2:39:76:8e:05:12 default 1500 A/D -``` - -#### VyOS 1.4 (sagitta) - -Connect serial port to a PC through a USB \<-> RJ45 console cable. Set terminal -emulator to 115200 8N1. You can also perform the installation using VGA or HDMI -ports. - -In this example I choose to install VyOS as RAID-1 on both NVMe drives. However, -a previous installation on the 128GB eMMC storage worked without any issues, -too. - -```none -Welcome to VyOS - vyos ttyS0 - -vyos login: -``` - -Perform Image installation using `install image` CLI command. This installation -uses two 128GB NVMe disks setup as RAID1. - -```none -Welcome to VyOS! - - ┌── ┐ - . VyOS 1.4.0 - └ ──┘ sagitta - -* Support portal: https://support.vyos.io -* Documentation: https://docs.vyos.io/en/sagitta -* Project news: https://blog.vyos.io -* Bug reports: https://vyos.dev - -You can change this banner using "set system login banner post-login" command. - -VyOS is a free software distribution that includes multiple components, -you can check individual component licenses under /usr/share/doc/*/copyright -Use of this pre-built image is governed by the EULA you can find in -/usr/share/vyos/EULA - -vyos@vyos:~$ install image - -Welcome to VyOS installation! -This command will install VyOS to your permanent storage. -Would you like to continue? [y/N] y - -What would you like to name this image? (Default: 1.4.0) - -Please enter a password for the "vyos" user: -Please confirm password for the "vyos" user: - -What console should be used by default? (K: KVM, S: Serial)? (Default: S) - -Probing disks -4 disk(s) found -Would you like to configure RAID-1 mirroring? [Y/n] y - -The following disks were found: - /dev/sda (14.4 GB) - /dev/mmcblk0 (116.5 GB) -Would you like to configure RAID-1 mirroring on them? [Y/n] n - -Would you like to choose two disks for RAID-1 mirroring? [Y/n] y -Disks available: - 1: /dev/sda (14.4 GB) - 2: /dev/mmcblk0 (116.5 GB) - 3: /dev/nvme1n1 (119.2 GB) - 4: /dev/nvme0n1 (119.2 GB) -Select first disk: 3 - -Remaining disks: - 1: /dev/sda (14.4 GB) - 2: /dev/mmcblk0 (116.5 GB) - 3: /dev/nvme0n1 (119.2 GB) -Select second disk: 3 - -Installation will delete all data on both drives. Continue? [y/N] y - -Searching for data from previous installations -No previous installation found -Creating partitions on /dev/nvme1n1 -Creating partition table... -Creating partitions on /dev/nvme0n1 -Creating partition table... -Creating RAID array -Updating initramfs -Creating filesystem on RAID array -The following config files are available for boot: - 1: /opt/vyatta/etc/config/config.boot - 2: /opt/vyatta/etc/config.boot.default - -Which file would you like as boot config? (Default: 1) -Creating temporary directories -Mounting new partitions -Creating a configuration file -Copying system image files -Installing GRUB configuration files -Installing GRUB to the drives -Cleaning up -Unmounting target filesystems -Removing temporary files -The image installed successfully; please reboot now. -``` - -### Hardware - -```none -vyos@vyos:~$ lspci -00:00.0 Host bridge: Intel Corporation Device 461c -00:02.0 VGA compatible controller: Intel Corporation Alder Lake-N [UHD Graphics] -00:0a.0 Signal processing controller: Intel Corporation Platform Monitoring Technology (rev 01) -00:0d.0 USB controller: Intel Corporation Device 464e -00:14.0 USB controller: Intel Corporation Device 54ed -00:14.2 RAM memory: Intel Corporation Device 54ef -00:15.0 Serial bus controller: Intel Corporation Device 54e8 -00:16.0 Communication controller: Intel Corporation Device 54e0 -00:1a.0 SD Host controller: Intel Corporation Device 54c4 -00:1c.0 PCI bridge: Intel Corporation Device 54b8 -00:1c.2 PCI bridge: Intel Corporation Device 54ba -00:1c.3 PCI bridge: Intel Corporation Device 54bb -00:1c.6 PCI bridge: Intel Corporation Device 54be -00:1d.0 PCI bridge: Intel Corporation Device 54b0 -00:1f.0 ISA bridge: Intel Corporation Device 5481 -00:1f.4 SMBus: Intel Corporation Device 54a3 -00:1f.5 Serial bus controller: Intel Corporation Device 54a4 -01:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -02:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -02:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -02:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -02:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -03:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) -04:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) -05:00.0 Network controller: MEDIATEK Corp. MT7922 802.11ax PCI Express Wireless Network Adapter -06:00.0 SATA controller: ASMedia Technology Inc. Device 0622 (rev 01) -07:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -08:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -08:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -08:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -08:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) -09:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) -0a:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) -0b:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) -0d:00.0 Non-Volatile memory controller: Device 1ed0:2283 -0f:00.0 Non-Volatile memory controller: Device 1ed0:2283 -11:00.0 Ethernet controller: Mellanox Technologies MT27500 Family [ConnectX-3] -``` - -```none -vyos@vyos:~$ lsusb -Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub -Bus 003 Device 005: ID 0e8d:c616 MediaTek Inc. Wireless_Device -Bus 003 Device 003: ID 413c:2113 Dell Computer Corp. KB216 Wired Keyboard -Bus 003 Device 004: ID 03f0:9d1d HP, Inc HP lt4120 Snapdragon X5 LTE -Bus 003 Device 002: ID 05e3:0610 Genesys Logic, Inc. Hub -Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub -Bus 002 Device 002: ID 05e3:0620 Genesys Logic, Inc. GL3523 Hub -Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub -Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub -``` - -#### WWAN - -The LTE module can be enabled as simple as this config snippet: - -```none -interfaces { - wwan wwan0 { - address "dhcp" - apn "YOUR-APN-GOES-HERE" - } -} -``` - -For more information please refer to chapter: {ref}`wwan-interface` - -[rufus]: https://rufus.ie/ diff --git a/docs/installation/rst-image.rst b/docs/installation/rst-image.rst new file mode 100644 index 00000000..77ca01f9 --- /dev/null +++ b/docs/installation/rst-image.rst @@ -0,0 +1,115 @@ +.. _image-mgmt: + +################ +Image Management +################ + +The VyOS image-based installation is implemented by creating a directory for +each image on the storage device selected during the install process. + +The directory structure of the boot device: + +.. code-block:: none + + / + /boot + /boot/grub + /boot/1.2.0-rolling+201810021347 + +The image directory contains the system kernel, a compressed image of the root +filesystem for the OS, and a directory for persistent storage, such as +configuration. On boot, the system will extract the OS image into memory and +mount the appropriate live-rw sub-directories to provide persistent storage +system configuration. + +This process allows for a system to always boot to a known working state, as +the OS image is fixed and non-persistent. It also allows for multiple releases +of VyOS to be installed on the same storage device. The image can be selected +manually at boot if needed, but the system will otherwise boot the image +configured to be the default. + +.. opcmd:: show system image + + List all available system images which can be booted on the current system. + + .. code-block:: none + + vyos@vyos:~$ show system image + The system currently has the following image(s) installed: + + 1: 1.2.0-rolling+201810021347 (default boot) + 2: 1.2.0-rolling+201810021217 + 3: 1.2.0-rolling+201809252218 + + +.. opcmd:: delete system image [image-name] + + Delete no longer needed images from the system. You can specify an optional + image name to delete, the image name can be retrieved via a list of available + images can be shown using the :opcmd:`show system image`. + + .. code-block:: none + + vyos@vyos:~$ delete system image + The following image(s) can be deleted: + + 1: 1.3-rolling-201912181733 (default boot) (running image) + 2: 1.3-rolling-201912180242 + 3: 1.2.2 + 4: 1.2.1 + + Select the image to delete: 2 + + Are you sure you want to delete the + "1.3-rolling-201912180242" image? (Yes/No) [No]: y + Deleting the "1.3-rolling-201912180242" image... + Done + +.. opcmd:: show version + + Show current system image version. + + .. code-block:: none + + vyos@vyos:~$ show version + Version: VyOS 1.3-rolling-201912181733 + Built by: autobuild@vyos.net + Built on: Wed 18 Dec 2019 17:33 UTC + Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c + Build Commit ID: f7ce0d8a692f2d + + Architecture: x86_64 + Boot via: installed image + System type: bare metal + + Hardware vendor: VMware, Inc. + Hardware model: VMware Virtual Platform + Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 + Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 + + Copyright: VyOS maintainers and contributors + + + + + +System rollback +=============== + +If you need to rollback to a previous image, you can easily do so. First +check the available images through the :opcmd:`show system image` +command and then select your image with the following command: + +.. opcmd:: set system image default-boot [image-name] + + Select the default boot image which will be started on the next boot + of the system. + +Then reboot the system. + +.. note:: VyOS automatically associates the configuration to the image, + so you don't need to worry about that. Each image has a unique copy + of its configuration. + +If you have access to the console, there is a another way to select +your booting image: reboot and use the GRUB menu at startup. diff --git a/docs/installation/rst-index.rst b/docs/installation/rst-index.rst new file mode 100644 index 00000000..97f7d85c --- /dev/null +++ b/docs/installation/rst-index.rst @@ -0,0 +1,26 @@ +################################# +Installation and Image Management +################################# + +.. note:: This is most likely only relevant for virtual installations: + + When installing VyOS ensure that the MAC address selected for your NICs is + not a locally administered MAC address. Locally administered addresses are + distinguished from universally administered addresses by setting (assigning + the value of 1 to) the second-least-significant bit of the first octet of + the address: + + Example: ``02:00:00:00:00:01``, where the second-least-significant bit + (``02`` in hex) is set to ``1``. + +.. toctree:: + :maxdepth: 2 + :caption: Content + + install + virtual/index + cloud/index + vyos-on-baremetal + update + image + migrate-from-vyatta diff --git a/docs/installation/rst-install.rst b/docs/installation/rst-install.rst new file mode 100644 index 00000000..664e6bc3 --- /dev/null +++ b/docs/installation/rst-install.rst @@ -0,0 +1,417 @@ +.. _installation: + +############ +Installation +############ + +VyOS installation requires a downloaded VyOS .iso file. That file is +a live install image that lets you boot a live VyOS. From the live +system, you can proceed to a permanent installation on a hard drive or +any other type of storage. + +.. table:: Comparison of VyOS image releases + + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | Release Type | Description | Release Cycle | Intended Use | Access to Images | Access to Source | + +==============+===================================================+===================+=======================================+=======================+==================+ + | **Nightly | Automatically built from the current branch. | Every night | Developing VyOS, testing new | Everyone | Everyone | + | (Current)** | Always up to date with cutting edge development | | features, experimenting. | | | + | | but guaranteed to contain bugs. | | | | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | **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 | | | + | | feature freeze. | | high-availability setup. | | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | **Early | Highly stable with no known bugs. Needs to be | Irregularly until | Non-critical production environments, | Everyone | Everyone | + | Production | tested repeatedly under different conditions | LTS comes out | preparing for the LTS release. | | | + | Access** | before it can become the final release. | | | | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + | **Long-Term | Guaranteed to be stable and carefully maintained | Every major | Large-scale enterprise networks, | Subscribers, | Everyone | + | Support** | for several years after the release. No features | version | internet service providers, | contributors, | | + | | are introduced but security updates are released | | critical production environments | non-profits, | | + | | in a timely manner. | | that call for minimum downtime. | emergency services, | | + | | | | | academic institutions | | + +--------------+---------------------------------------------------+-------------------+---------------------------------------+-----------------------+------------------+ + +Hardware requirements +===================== + +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. + +Download +======== + +Registered Subscribers +---------------------- + +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. See this article_ for more information on downloads. + +.. figure:: /_static/images/vyosnew-downloads.png + +Rolling Release +--------------- + +Everyone can download bleeding-edge VyOS rolling images from: +https://downloads.vyos.io/ + +.. note:: Rolling releases contain all the latest enhancements and fixes. This + means that there will be new bugs of course. If you think you hit a bug + please follow the guide at :ref:`bug_report`. We depend on your feedback + to improve VyOS! + +The following link contains the list of the most recent VyOS builds for AMD64 +systems from the current branch: +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. +Minisign is used for verification. + +.. _minisign-verification: + +Minisign verification +^^^^^^^^^^^^^^^^^^^^^ + +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. It is portable, lightweight, and +uses the highly secure Ed25519 public-key signature system. + + +:vytask:`T2108` switched the validation system to prefer minisign over GPG keys. + +To verify a VyOS image starting off with VyOS 1.3.0-rc6 you can run: + +.. code-block:: none + + $ minisign -V -P RWTR1ty93Oyontk6caB9WqmiQC4fgeyd/ejgRxCRGd2MQej7nqebHneP -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig + Signature and comment signature verified + Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso + +During an image upgrade VyOS performs the following command: + +.. code-block:: none + + $ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig + 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 +================= + +.. note:: A permanent VyOS installation always requires to go first + through a live installation. + +VyOS, as other GNU+Linux distributions, can be tested without installing +it in your hard drive. **With your downloaded VyOS .iso file you can +create a bootable USB drive that will let you boot into a fully +functional VyOS system**. Once you have tested it, you can either decide +to begin a :ref:`permanent_installation` in your hard drive or power +your system off, remove the USB drive, and leave everything as it was. + + +If you have a GNU+Linux system, you can create your VyOS bootable USB +stick with with the ``dd`` command: + + 1. Open your terminal emulator. + + 2. Find out the device name of your USB drive (you can use the ``lsblk`` + command) + + 3. Unmount the USB drive. Replace X in the example below with the + letter of your device and keep the asterisk (wildcard) to unmount + all partitions. + + .. code-block:: none + + $ umount /dev/sdX* + + 4. Write the image (your VyOS .iso file) to the USB drive. + Note that here you want to use the device name (e.g. /dev/sdb), not + the partition name (e.g. /dev/sdb1). + + **Warning**: This will destroy all data on the USB drive! + + .. code-block:: none + + # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync + + 5. Wait until you get the outcome (bytes copied). Be patient, in some + computers it might take more than one minute. + + 6. Once ``dd`` has finished, pull the USB drive out and plug it into + the powered-off computer where you want to install (or test) VyOS. + + 7. Power the computer on, making sure it boots from the USB drive (you + might need to select booting device or change booting settings). + + 8. Once VyOS is completely loaded, enter the default credentials + (login: vyos, password: vyos). + + +If you find difficulties with this method, prefer to use a GUI program, +or have a different operating system, there are other programs you can +use to create a bootable USB drive, like balenaEtcher_ (for GNU/Linux, +macOS and Windows), Rufus_ (for Windows) and `many others`_. You can +follow their instructions to create a bootable USB drive from an .iso +file. + +.. hint:: The default username and password for the live system is *vyos*. + + +.. _permanent_installation: + +Permanent installation +====================== + +.. note:: Before a permanent installation, VyOS requires a + :ref:`live_installation`. + +Unlike general purpose Linux distributions, VyOS uses "image installation" that +mimics the user experience of traditional hardware routers and allows keeping +multiple VyOS versions installed simultaneously. This makes it possible to +switch to a previous version if something breaks or miss-behaves after an image +upgrade. + +Every version is contained in its own squashfs image that is mounted in a union +filesystem together with a directory for mutable data such as configurations, +keys, or custom scripts. + +.. note:: Older versions (prior to VyOS 1.1) used to support non-image + installation (``install system`` command). Support for this has been removed + from VyOS 1.2 and newer releases. Older releases can still be upgraded via + the general ``add system image `` upgrade command (consult + :ref:`image-mgmt` for further information). + + +In order to proceed with a permanent installation: + + 1. Log into the VyOS live system (use the default credentials: vyos, + vyos) + + 2. Run the ``install image`` command and follow the wizard: + +.. figure:: /_static/images/permanent_install.png + + 3. After the installation is completed, remove the live USB stick or + CD. + + 4. Reboot the system. + + .. code-block:: none + + vyos@vyos:~$ reboot + Proceed with reboot? (Yes/No) [No] Yes + + You will boot now into a permanent VyOS system. + + +PXE Boot +======== + +VyOS can also be installed through PXE. This is a more complex +installation method that allows deploying VyOS through the network. + +**Requirements** + +* Clients (where VyOS is to be installed) with a PXE-enabled NIC +* :ref:`dhcp-server` +* :ref:`tftp-server` +* Webserver (HTTP) - optional, but we will use it to speed up installation +* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) +* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution + `_ + +Configuration +------------- + +Step 1: DHCP +^^^^^^^^^^^^ + +Configure a DHCP server to provide the client with: + +* An IP address +* The TFTP server address (DHCP option 66). Sometimes referred as *boot server* +* The *bootfile name* (DHCP option 67), which is *pxelinux.0* + +In this example we configured an existent VyOS as the DHCP server: + +.. code-block:: none + + vyos@vyos# show service dhcp-server + shared-network-name mydhcp { + subnet 192.168.1.0/24 { + bootfile-name pxelinux.0 + bootfile-server 192.168.1.50 + default-router 192.168.1.50 + range 0 { + start 192.168.1.70 + stop 192.168.1.100 + } + } + } + +.. _install_from_tftp: + +Step 2: TFTP +^^^^^^^^^^^^ + +Configure a TFTP server so that it serves the following: + +* The *pxelinux.0* file from the Syslinux distribution +* The *ldlinux.c32* file from the Syslinux distribution +* The kernel of the VyOS software you want to deploy. That is the + *vmlinuz* file inside the */live* directory of the extracted + contents from the ISO file. +* The initial ramdisk of the VyOS ISO you want to deploy. That is the + *initrd.img* file inside the */live* directory of the extracted + contents from the ISO file. Do not use an empty (0 bytes) initrd.img + file you might find, the correct file may have a longer name. +* A directory named pxelinux.cfg which must contain the configuration + file. We will use the configuration_ file shown below, which we named + default_. + +In the example we configured our existent VyOS as the TFTP server too: + +.. code-block:: none + + vyos@vyos# show service tftp-server + directory /config/tftpboot + listen-address 192.168.1.50 + +Example of the contents of the TFTP server: + +.. code-block:: none + + vyos@vyos# ls -hal /config/tftpboot/ + total 29M + drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . + drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. + -r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos + -rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 + -rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 + drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg + -r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz + + vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg + total 12K + drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . + drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. + -rw-r--r-- 1 root root 191 Oct 14 01:10 default + +Example of simple (no menu) configuration file: + +.. code-block:: none + + vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default + DEFAULT VyOS123 + + LABEL VyOS123 + KERNEL vmlinuz + APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs + +Step 3: HTTP +^^^^^^^^^^^^ + +We also need to provide the *filesystem.squashfs* file. That is a heavy +file and TFTP is slow, so you could send it through HTTP to speed up the +transfer. That is how it is done in our example, you can find that in +the configuration file above. + +**First** run a web server - you can use a simple one like +`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs` +file. The file can be found inside the `/live` directory of the +extracted contents of the ISO file. + +**Second**, edit the configuration file of the :ref:`install_from_tftp` +so that it shows the correct URL at +``fetch=http:///filesystem.squashfs``. + +.. note:: Do not change the name of the *filesystem.squashfs* file. If + you are working with different versions, you can create different + directories instead. + +And **third**, restart the TFTP service. If you are using VyOS as your +TFTP Server, you can restart the service with +``sudo service tftpd-hpa restart``. + +.. note:: Make sure the available directories and files in both TFTP + and HTTP server have the right permissions to be accessed from the + booting clients. + + + +Client Boot +----------- + +Finally, turn on your PXE-enabled client or clients. They will +automatically get an IP address from the DHCP server and start booting +into VyOS live from the files automatically taken from the TFTP and HTTP +servers. + +Once finished you will be able to proceed with the ``install image`` +command as in a regular VyOS installation. + + + +Known Issues +============ + +This is a list of known issues that can arise during installation. + +Black screen on install +----------------------- + +GRUB attempts to redirect all output to a serial port for ease of installation +on headless hosts. This appears to cause an hard lockup on some hardware that +lacks a serial port, with the result being a black screen after selecting the +`Live system` option from the installation image. + +The workaround is to type `e` when the boot menu appears and edit the GRUB boot +options. Specifically, remove the: + +`console=ttyS0,115200` + +option, and type CTRL-X to boot. + +Installation can then continue as outlined above. + + +.. stop_vyoslinter + +.. _SYSLINUX: http://www.syslinux.org/ +.. _balenaEtcher: https://www.balena.io/etcher/ +.. _Rufus: https://rufus.ie/ +.. _many others: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems +.. _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 diff --git a/docs/installation/rst-update.rst b/docs/installation/rst-update.rst new file mode 100644 index 00000000..5f75f9db --- /dev/null +++ b/docs/installation/rst-update.rst @@ -0,0 +1,82 @@ +.. _update_vyos: + +Update VyOS +=========== + +New system images can be added using the :opcmd:`add system image` +command. The command will extract the chosen image and will prompt you +to use the current system configuration and SSH security keys, allowing +for the new image to boot using the current configuration. + +.. note:: Only LTS releases are PGP-signed. + +.. opcmd:: add system image [vrf name] + [username user [password pass]] + + Use this command to install a new system image. You can reach the + image from the web (``http://``, ``https://``) or from your local system, + e.g. /tmp/vyos-1.2.3-amd64.iso. + + The `add system image` command also supports installing new versions + of VyOS through an optional given VRF. Also if URL in question requires + authentication, you can specify an optional username and password via + the commandline which will be passed as "Basic-Auth" to the server. + +If there is not enough **free disk space available**, the installation +will be canceled. To delete images use the :opcmd:`delete system image` +command. + +VyOS configuration is associated to each image, and **each image has a +unique copy of its configuration**. This is different than a traditional +network router where the configuration is shared across all images. + +.. note:: If you have any personal files, like some scripts you created, + and you don't want them to be lost during the upgrade, make sure + those files are stored in ``/config`` as this directory is always copied + to newer installed images. + +You can access files from a previous installation and copy them to your +current image if they were located in the ``/config`` directory. This +can be done using the :opcmd:`copy` command. So, for instance, in order +to copy ``/config/config.boot`` from VyOS 1.2.1 image, you would use the +following command: + +.. code:: + + copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 + + +Example +""""""" + +.. code-block:: none + + vyos@vyos:~$ add system image https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso + Trying to fetch ISO file from https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k + ISO download succeeded. + Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 + curl: (22) The requested URL returned error: 404 Not Found + + Unable to fetch digital signature file. + Do you want to continue without signature check? (yes/no) [yes] + Checking MD5 checksums of files on the ISO image...OK. + Done! + + What would you like to name this image? [vyos-1.3-rolling-201912201452]: + + OK. This image will be named: vyos-1.3-rolling-201912201452 + + +.. hint:: The most up-do-date Rolling Release for AMD64 can be accessed using + the following URL: + + https://vyos.net/get/nightly-builds/ + +After reboot you might want to verify the version you are running with +the :opcmd:`show version` command. diff --git a/docs/installation/rst-vyos-on-baremetal.rst b/docs/installation/rst-vyos-on-baremetal.rst new file mode 100644 index 00000000..783fdf85 --- /dev/null +++ b/docs/installation/rst-vyos-on-baremetal.rst @@ -0,0 +1,632 @@ +.. _vyosonbaremetal: + +##################### +Running on Bare Metal +##################### + +Supermicro A2SDi (Atom C3000) +============================= + +I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. +Running VyOS on an UEFI only device is supported as of VyOS release 1.2. + +Supermicro Shopping Cart +------------------------ + +* 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) +* 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) +* 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN + with Intel C3000 SoC 1GbE) +* 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) +* 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) +* 1x Supermicro MCP-320-81302-0B (optional FAN tray) + +Optional (10GE) +--------------- +If you want to get additional ethernet ports or even 10GE connectivity +the following optional parts will be required: + +* 1x Supermicro RSC-RR1U-E8 (Riser Card) +* 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) + +Latest VyOS rolling releases boot without any problem on this board. You also +receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no +information about `OpenBMC `_ so far on this +motherboard). + +Pictures +-------- + +.. figure:: /_static/images/1u_vyos_back.jpg + :scale: 25 % + :alt: CSE-505-203B Back + +.. figure:: /_static/images/1u_vyos_front.jpg + :scale: 25 % + :alt: CSE-505-203B Front + +.. figure:: /_static/images/1u_vyos_front_open_1.jpg + :scale: 25 % + :alt: CSE-505-203B Open 1 + +.. figure:: /_static/images/1u_vyos_front_open_2.jpg + :scale: 25 % + :alt: CSE-505-203B Open 2 + +.. figure:: /_static/images/1u_vyos_front_open_3.jpg + :scale: 25 % + :alt: CSE-505-203B Open 3 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_1.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 1 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_2.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 2 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_3.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 3 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_4.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open + + +.. _pc-engines-apu4: + +PC Engines APU4 +================ + +As this platform seems to be quite common in terms of noise, cost, power and +performance it makes sense to write a small installation manual. + +This guide was developed using an APU4C4 board with the following specs: + +* AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI + support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. +* 4 GB DDR3-1333 DRAM, with optional ECC support +* About 6 to 10W of 12V DC power depending on CPU load +* 2 miniPCI express (one with SIM socket for 3G modem). +* 4 Gigabit Ethernet channels using Intel i211AT NICs + +The board can be powered via 12V from the front or via a 5V onboard connector. + +.. _vyos-on-baremetal:apu4_shopping: + +APU4 Shopping Cart +------------------ + +* 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM +* 1x Kingston SUV500MS/120G +* 1x VARIA Group Item 326745 19" dual rack for APU4 + +The 19" enclosure can accommodate up to two APU4 boards - there is a single and +dual front cover. + +Extension Modules +^^^^^^^^^^^^^^^^^ + +WiFi +"""" + +Refer to :ref:`wireless-interface` for additional information, below listed +modules have been tested successfully on this Hardware platform: + +* Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. +* Intel Corporation AX200 mini-PCIe WiFi module, only supported in mPCIe slot 1. + (see :ref:`wireless-interface-intel-ax200`) + +WWAN +"""" + +Refer to :ref:`wwan-interface` for additional information, below listed modules +have been tested successfully on this Hardware platform using VyOS 1.3 +(equuleus): + +* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +* Huawei ME909u-521 miniPCIe card (LTE) + +VyOS 1.4 (sagitta) +--------------- + +Depending on the VyOS versions you intend to install there is a difference in +the serial port settings (:vytask:`T1327`). + +Create a bootable USB pendrive using e.g. Rufus_ on a Windows machine. + +Connect serial port to a PC through null modem cable (RXD / TXD crossed over). +Set terminal emulator to 115200 8N1. + +.. stop_vyoslinter +.. code-block:: none + + PC Engines apu4 + coreboot build 20171130 + BIOS version v4.6.4 + 4080 MB ECC DRAM + SeaBIOS (version rel-1.11.0.1-0-g90da88d) + + Press F10 key now for boot menu: + + Select boot device: + + 1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) + 2. USB MSC Drive Generic Flash Disk 8.07 + 3. Payload [memtest] + 4. Payload [setup] + +.. start_vyoslinter + +Now boot from the ``USB MSC Drive Generic Flash Disk 8.07`` media by pressing +``2``, the VyOS boot menu will appear, just wait 10 seconds or press ``Enter`` +to continue. + +.. code-block:: none + + lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk + x VyOS - Boot Menu x + tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu + x Live system (amd64-vyos) x + x Live system (amd64-vyos fail-safe mode) x + x Live system (amd64-vyos) - Serial console x + x x + mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj + +The image will be loaded and the last lines you will get will be: + +.. code-block:: none + + Loading /live/vmlinuz... ok + Loading /live/initrd.img... + ... + Welcome to VyOS - vyos ttyS0 + + vyos login: + +You can now proceed with a regular image installation as described in +:ref:`installation`. + +.. _vyos-on-baremetal:apu4_pictures: + +Pictures +-------- + +.. note:: Both device types operate without any moving parts and emit zero + noise. + +Rack Mount +^^^^^^^^^^ + +.. figure:: /_static/images/apu4_rack_1.jpg + :scale: 25 % + :alt: APU4 rack closed + +.. figure:: /_static/images/apu4_rack_2.jpg + :scale: 25 % + :alt: APU4 rack front + +.. figure:: /_static/images/apu4_rack_3.jpg + :scale: 25 % + :alt: APU4 rack module #1 + +.. figure:: /_static/images/apu4_rack_4.jpg + :scale: 25 % + :alt: APU4 rack module #2 + +.. figure:: /_static/images/apu4_rack_5.jpg + :scale: 25 % + :alt: APU4 rack module #3 with PSU + +VyOS custom print +""""""""""""""""" + +.. figure:: /_static/images/apu4_rack_vyos_print.jpg + :scale: 25 % + :alt: APU4 custom VyOS powder coat + +Desktop / Bench Top +^^^^^^^^^^^^^^^^^^^ + +.. figure:: /_static/images/apu4_desk_1.jpg + :scale: 25 % + :alt: APU4 desktop closed + +.. figure:: /_static/images/apu4_desk_2.jpg + :scale: 25 % + :alt: APU4 desktop closed + +.. figure:: /_static/images/apu4_desk_3.jpg + :scale: 25 % + :alt: APU4 desktop back + +.. figure:: /_static/images/apu4_desk_4.jpg + :scale: 25 % + :alt: APU4 desktop back + +.. _Rufus: https://rufus.ie/ + +Qotom Q355G4 +============ + +The install on this Q355G4 box is pretty much plug and play. The port numbering +the OS does might differ from the labels on the outside, but the UEFI firmware +has a port blink test built in with MAC addresses so you can very quickly +identify which is which. MAC labels are on the inside as well, and this test +can be done from VyOS or plain Linux too. Default settings in the UEFI will +make it boot, but depending on your installation wishes (i.e. storage type, +boot type, console type) you might want to adjust them. This Qotom company +seems to be the real OEM/ODM for many other relabelling companies like +Protectli. + +Hardware +-------- + +There are a number of other options, but they all seem to be close to Intel +reference designs, with added features like more serial ports, more network +interfaces and the likes. Because they don't deviate too much from standard +designs all the hardware is well-supported by mainline. It accepts one LPDDR3 +SO-DIMM, but chances are that if you need more than that, you'll also want +something even beefier than an i5. There are options for antenna holes, and SIM +slots, so you could in theory add an LTE/Cell modem (not tested so far). + +The chassis is a U-shaped alu extrusion with removable I/O plates and removable +bottom plate. Cooling is completely passive with a heatsink on the SoC with +internal and external fins, a flat interface surface, thermal pad on top of +that, which then directly attaches to the chassis, which has fins as well. It +comes with mounting hardware and rubber feet, so you could place it like a +desktop model or mount it on a VESA mount, or even wall mount it with the +provided mounting plate. The closing plate doubles as internal 2.5" mounting +place for an HDD or SSD, and comes supplied with a small SATA cable and SATA +power cable. + +Power supply is a 12VDC barrel jack, and included switching power supply, which +is why SATA power regulation is on-board. Internally it has a NUC-board-style +on-board 12V input header as well, the molex locking style. + +There are WDT options and auto-boot on power enable, which is great for remote +setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled +in enforcement mode, which is good but also means no coreboot option), yet has +most options available to configure (so it's not locked out like most firmwares +are). + +An external RS232 serial port is available, internally a GPIO header as well. +It does have Realtek based audio on board for some reason, but you can disable +that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS +mode and HDMI BIOS mode depends on what is connected at startup; it goes into +serial mode if you disconnect HDMI and plug in serial, in all other cases it's +HDMI mode. + +Partaker i5 +=========== + +.. figure:: ../_static/images/600px-Partaker-i5.jpg + +I believe this is actually the same hardware as the Protectli. I purchased it +in June 2018. It came pre-loaded with pfSense. + +`Manufacturer product page `_. + +Installation +------------ + +* Write VyOS ISO to USB drive of some sort +* Plug in VGA, power, USB keyboard, and USB drive +* Press "SW" button on the front (this is the power button; I don't know what + "SW" is supposed to mean). +* Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, + but with a few tries you should be able to get into the BIOS. +* Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 + (EHCI) to Enabled. Without doing this, the USB drive won't boot. +* Boot to the VyOS installer and install as usual. + +Warning the interface labels on my device are backwards; the left-most "LAN4" +port is eth0 and the right-most "LAN1" port is eth3. + +Acrosser AND-J190N1 +=================== + +.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg + +.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg + +This microbox network appliance was build to create OpenVPN bridges. It can +saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN + +You may have to add your own RAM and HDD/SSD. There is no VGA connector. But +Acrosser provides a DB25 adapter for the VGA header on the motherboard (not +used). + +BIOS Settings: +-------------- + +First thing you want to do is getting a more user friendly console to configure +BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. + +For practical issues change speed from 115200 to 9600. 9600 is the default +speed at which both linux kernel and VyOS will reconfigure the serial port +when loading. + +Connect to serial (115200bps). Power on the appliance and press Del in the +console when requested to enter BIOS settings. + +Advanced > Serial Port Console Redirection > Console Redirection Settings: + +* Terminal Type : VT100+ +* Bits per second : 9600 + +Save, reboot and change serial speed to 9600 on your client. + +Some options have to be changed for VyOS to boot correctly. With XHCI enabled +the installer can’t access the USB key. Enable EHCI instead. + +Reboot into BIOS, Chipset > South Bridge > USB Configuration: + +* Disable XHCI +* Enable USB 2.0 (EHCI) Support + +Perform Image installation using `install image` CLI command. + +.. _gowin_gw-fn-1ur1-10g: + +Gowin GW-FN-1UR1-10G +==================== + +A platform utilizing an Intel Alder Lake-N100 CPU with 6M cache, TDP 6W. +Onboard LPDDR5 16GB RAM and 128GB eMMC (can be used for image installation). + +The appliance comes with 2 * 2.5GbE Intel I226-V and 3 * 1GbE Intel I210 +where one supports IEEE802.3at PoE+ (Typical 30W). + +In addition there is a Mellanox ConnectX-3 2* 10GbE SFP+ NIC available. + +**NOTE:** This is the entry level platform. Other derivates exists with +i3-N305 CPU and 2x 25GbE! + +Gowin Shopping Cart +------------------- + +* 1x Gowin GW-FN-1UR1-10G +* 2x 128GB M.2 NVMe SSDs + +Optional (WiFi + WWAN) +---------------------- + +* 1x MediaTek 7921E M.2 NGFF WIFI module (not tested as this currently leads to + a Kernel crash) +* 1x HP LT4120 Snapdragon X5 LTE WWAN module + +Pictures +-------- + +.. figure:: ../_static/images/gowin-01.png + +.. figure:: ../_static/images/gowin-02.png + +.. figure:: ../_static/images/gowin-03.png + +.. figure:: ../_static/images/gowin-04.png + +Cooling +------- + +The device itself is passivly cooled, whereas the power supply has an active fan. +Even if the main processor is powered off, the power supply fan is operating and +the entire chassis draws 7.5W. During operation the chassis drew arround 38W. + +BIOS Settings +------------- + +No settings needed to be altered, everything worked out of the box! + +Installation +------------ + +The system provides a regular RS232 console port using 115200,8n1 setting which +is sufficient to install VyOS from a USB pendrive. + +First Boot +---------- + +Please note that there is a weirdness on the network interface mapping. +The interface <-> MAC mapping is going upwards but the NICs are placed +somehow swapped on the mainboard/MACs programmed in a swapped order. + +See interface description for more detailed mapping. + +.. code-block:: none + + vyos@vyos:~$ show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address MAC VRF MTU S/L Description + ----------- -------------- ----------------- ------- ----- ----- ------------- + eth0 - 00:f0:cb:00:00:99 default 1500 u/D Intel I226-V - Front eth2 + eth1 - 00:f0:cb:00:00:9a default 1500 u/D Intel I226-V - Front eth1 + eth2 - 00:f0:cb:00:00:9b default 1500 u/D Intel I210 - Front eth4 + eth3 - 00:f0:cb:00:00:9c default 1500 u/D Intel I210 - Front eth3 + eth4 - 00:f0:cb:00:00:9d default 1500 u/D Intel I210 - Front POE + eth5 - 00:02:c9:00:00:30 default 1500 u/D Mellanox ConnectX-3 - SFP2 + eth6 - 00:02:c9:00:00:31 default 1500 u/D Mellanox ConnectX-3 - SFP1 + lo 127.0.0.1/8 00:00:00:00:00:00 default 65536 u/u + ::1/128 + wwan0 - d2:39:76:8e:05:12 default 1500 A/D + +VyOS 1.4 (sagitta) +^^^^^^^^^^^^^^^^^^ + +Connect serial port to a PC through a USB <-> RJ45 console cable. Set terminal +emulator to 115200 8N1. You can also perform the installation using VGA or HDMI +ports. + +In this example I choose to install VyOS as RAID-1 on both NVMe drives. However, +a previous installation on the 128GB eMMC storage worked without any issues, +too. + +.. code-block:: none + + Welcome to VyOS - vyos ttyS0 + + vyos login: + +Perform Image installation using `install image` CLI command. This installation +uses two 128GB NVMe disks setup as RAID1. + +.. code-block:: none + + Welcome to VyOS! + + ┌── ┐ + . VyOS 1.4.0 + └ ──┘ sagitta + + * Support portal: https://support.vyos.io + * Documentation: https://docs.vyos.io/en/sagitta + * Project news: https://blog.vyos.io + * Bug reports: https://vyos.dev + + You can change this banner using "set system login banner post-login" command. + + VyOS is a free software distribution that includes multiple components, + you can check individual component licenses under /usr/share/doc/*/copyright + Use of this pre-built image is governed by the EULA you can find in + /usr/share/vyos/EULA + + vyos@vyos:~$ install image + + Welcome to VyOS installation! + This command will install VyOS to your permanent storage. + Would you like to continue? [y/N] y + + What would you like to name this image? (Default: 1.4.0) + + Please enter a password for the "vyos" user: + Please confirm password for the "vyos" user: + + What console should be used by default? (K: KVM, S: Serial)? (Default: S) + + Probing disks + 4 disk(s) found + Would you like to configure RAID-1 mirroring? [Y/n] y + + The following disks were found: + /dev/sda (14.4 GB) + /dev/mmcblk0 (116.5 GB) + Would you like to configure RAID-1 mirroring on them? [Y/n] n + + Would you like to choose two disks for RAID-1 mirroring? [Y/n] y + Disks available: + 1: /dev/sda (14.4 GB) + 2: /dev/mmcblk0 (116.5 GB) + 3: /dev/nvme1n1 (119.2 GB) + 4: /dev/nvme0n1 (119.2 GB) + Select first disk: 3 + + Remaining disks: + 1: /dev/sda (14.4 GB) + 2: /dev/mmcblk0 (116.5 GB) + 3: /dev/nvme0n1 (119.2 GB) + Select second disk: 3 + + Installation will delete all data on both drives. Continue? [y/N] y + + Searching for data from previous installations + No previous installation found + Creating partitions on /dev/nvme1n1 + Creating partition table... + Creating partitions on /dev/nvme0n1 + Creating partition table... + Creating RAID array + Updating initramfs + Creating filesystem on RAID array + The following config files are available for boot: + 1: /opt/vyatta/etc/config/config.boot + 2: /opt/vyatta/etc/config.boot.default + + Which file would you like as boot config? (Default: 1) + Creating temporary directories + Mounting new partitions + Creating a configuration file + Copying system image files + Installing GRUB configuration files + Installing GRUB to the drives + Cleaning up + Unmounting target filesystems + Removing temporary files + The image installed successfully; please reboot now. + +Hardware +-------- + +.. code-block:: none + + vyos@vyos:~$ lspci + 00:00.0 Host bridge: Intel Corporation Device 461c + 00:02.0 VGA compatible controller: Intel Corporation Alder Lake-N [UHD Graphics] + 00:0a.0 Signal processing controller: Intel Corporation Platform Monitoring Technology (rev 01) + 00:0d.0 USB controller: Intel Corporation Device 464e + 00:14.0 USB controller: Intel Corporation Device 54ed + 00:14.2 RAM memory: Intel Corporation Device 54ef + 00:15.0 Serial bus controller: Intel Corporation Device 54e8 + 00:16.0 Communication controller: Intel Corporation Device 54e0 + 00:1a.0 SD Host controller: Intel Corporation Device 54c4 + 00:1c.0 PCI bridge: Intel Corporation Device 54b8 + 00:1c.2 PCI bridge: Intel Corporation Device 54ba + 00:1c.3 PCI bridge: Intel Corporation Device 54bb + 00:1c.6 PCI bridge: Intel Corporation Device 54be + 00:1d.0 PCI bridge: Intel Corporation Device 54b0 + 00:1f.0 ISA bridge: Intel Corporation Device 5481 + 00:1f.4 SMBus: Intel Corporation Device 54a3 + 00:1f.5 Serial bus controller: Intel Corporation Device 54a4 + 01:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) + 02:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) + 02:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) + 02:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) + 02:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) + 03:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) + 04:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) + 05:00.0 Network controller: MEDIATEK Corp. MT7922 802.11ax PCI Express Wireless Network Adapter + 06:00.0 SATA controller: ASMedia Technology Inc. Device 0622 (rev 01) + 07:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) + 08:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) + 08:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) + 08:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) + 08:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) + 09:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) + 0a:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) + 0b:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) + 0d:00.0 Non-Volatile memory controller: Device 1ed0:2283 + 0f:00.0 Non-Volatile memory controller: Device 1ed0:2283 + 11:00.0 Ethernet controller: Mellanox Technologies MT27500 Family [ConnectX-3] + +.. code-block:: none + + vyos@vyos:~$ lsusb + Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub + Bus 003 Device 005: ID 0e8d:c616 MediaTek Inc. Wireless_Device + Bus 003 Device 003: ID 413c:2113 Dell Computer Corp. KB216 Wired Keyboard + Bus 003 Device 004: ID 03f0:9d1d HP, Inc HP lt4120 Snapdragon X5 LTE + Bus 003 Device 002: ID 05e3:0610 Genesys Logic, Inc. Hub + Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub + Bus 002 Device 002: ID 05e3:0620 Genesys Logic, Inc. GL3523 Hub + Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub + Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub + +WWAN +^^^^ + +The LTE module can be enabled as simple as this config snippet: + +.. code-block:: none + + interfaces { + wwan wwan0 { + address "dhcp" + apn "YOUR-APN-GOES-HERE" + } + } + +For more information please refer to chapter: :ref:`wwan-interface` diff --git a/docs/installation/update.md b/docs/installation/update.md new file mode 100644 index 00000000..e2c16ceb --- /dev/null +++ b/docs/installation/update.md @@ -0,0 +1,86 @@ +(update_vyos)= + +# Update VyOS + +New system images can be added using the {opcmd}`add system image` +command. The command will extract the chosen image and will prompt you +to use the current system configuration and SSH security keys, allowing +for the new image to boot using the current configuration. + +:::{note} +Only LTS releases are PGP-signed. +::: + +```{eval-rst} +.. opcmd:: add system image [vrf name] + [username user [password pass]] + + Use this command to install a new system image. You can reach the + image from the web (``http://``, ``https://``) or from your local system, + e.g. /tmp/vyos-1.2.3-amd64.iso. + + The `add system image` command also supports installing new versions + of VyOS through an optional given VRF. Also if URL in question requires + authentication, you can specify an optional username and password via + the commandline which will be passed as "Basic-Auth" to the server. +``` + +If there is not enough **free disk space available**, the installation +will be canceled. To delete images use the {opcmd}`delete system image` +command. + +VyOS configuration is associated to each image, and **each image has a +unique copy of its configuration**. This is different than a traditional +network router where the configuration is shared across all images. + +:::{note} +If you have any personal files, like some scripts you created, +and you don't want them to be lost during the upgrade, make sure +those files are stored in `/config` as this directory is always copied +to newer installed images. +::: + +You can access files from a previous installation and copy them to your +current image if they were located in the `/config` directory. This +can be done using the {opcmd}`copy` command. So, for instance, in order +to copy `/config/config.boot` from VyOS 1.2.1 image, you would use the +following command: + +```{code} +copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 +``` + +## Example + +```none +vyos@vyos:~$ add system image https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso +Trying to fetch ISO file from https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k +ISO download succeeded. +Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 +curl: (22) The requested URL returned error: 404 Not Found + +Unable to fetch digital signature file. +Do you want to continue without signature check? (yes/no) [yes] +Checking MD5 checksums of files on the ISO image...OK. +Done! + +What would you like to name this image? [vyos-1.3-rolling-201912201452]: + +OK. This image will be named: vyos-1.3-rolling-201912201452 +``` + +:::{hint} +The most up-do-date Rolling Release for AMD64 can be accessed using +the following URL: + + +::: + +After reboot you might want to verify the version you are running with +the {opcmd}`show version` command. diff --git a/docs/installation/update.rst b/docs/installation/update.rst deleted file mode 100644 index 5f75f9db..00000000 --- a/docs/installation/update.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _update_vyos: - -Update VyOS -=========== - -New system images can be added using the :opcmd:`add system image` -command. The command will extract the chosen image and will prompt you -to use the current system configuration and SSH security keys, allowing -for the new image to boot using the current configuration. - -.. note:: Only LTS releases are PGP-signed. - -.. opcmd:: add system image [vrf name] - [username user [password pass]] - - Use this command to install a new system image. You can reach the - image from the web (``http://``, ``https://``) or from your local system, - e.g. /tmp/vyos-1.2.3-amd64.iso. - - The `add system image` command also supports installing new versions - of VyOS through an optional given VRF. Also if URL in question requires - authentication, you can specify an optional username and password via - the commandline which will be passed as "Basic-Auth" to the server. - -If there is not enough **free disk space available**, the installation -will be canceled. To delete images use the :opcmd:`delete system image` -command. - -VyOS configuration is associated to each image, and **each image has a -unique copy of its configuration**. This is different than a traditional -network router where the configuration is shared across all images. - -.. note:: If you have any personal files, like some scripts you created, - and you don't want them to be lost during the upgrade, make sure - those files are stored in ``/config`` as this directory is always copied - to newer installed images. - -You can access files from a previous installation and copy them to your -current image if they were located in the ``/config`` directory. This -can be done using the :opcmd:`copy` command. So, for instance, in order -to copy ``/config/config.boot`` from VyOS 1.2.1 image, you would use the -following command: - -.. code:: - - copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 - - -Example -""""""" - -.. code-block:: none - - vyos@vyos:~$ add system image https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso - Trying to fetch ISO file from https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 - curl: (22) The requested URL returned error: 404 Not Found - - Unable to fetch digital signature file. - Do you want to continue without signature check? (yes/no) [yes] - Checking MD5 checksums of files on the ISO image...OK. - Done! - - What would you like to name this image? [vyos-1.3-rolling-201912201452]: - - OK. This image will be named: vyos-1.3-rolling-201912201452 - - -.. hint:: The most up-do-date Rolling Release for AMD64 can be accessed using - the following URL: - - https://vyos.net/get/nightly-builds/ - -After reboot you might want to verify the version you are running with -the :opcmd:`show version` command. diff --git a/docs/installation/virtual/docker.md b/docs/installation/virtual/docker.md new file mode 100644 index 00000000..10da8d41 --- /dev/null +++ b/docs/installation/virtual/docker.md @@ -0,0 +1,67 @@ +(docker)= + +# Running in Docker Container + +Docker is an open-source project for deploying applications as standardized +units called containers. Deploying VyOS in a container provides a simple and +lightweight mechanism for both testing and packet routing for container +workloads. + +## IPv6 Support for docker + +VyOS requires an IPv6-enabled docker network. Currently linux distributions +do not enable docker IPv6 support by default. You can enable IPv6 support in +two ways. + +### Method 1: Create a docker network with IPv6 support + +Here is a example using the macvlan driver. + +```none +docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet +``` + +### Method 2: Add IPv6 support to the docker daemon + +Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and to specify +the `fixed-cidr-v6` to your desired IPv6 subnet. + +```none +{ + "ipv6": true, + "fixed-cidr-v6": "2001:db8::/64" +} +``` + +Reload the docker configuration. + +```none +$ sudo systemctl reload docker +``` + +## Deploy container from ISO + +Download the ISO on which you want to base the container. In this example, +the name of the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you +created a custom IPv6-enabled network, the `docker run` command below +will require that this network be included as the `--net` parameter to +`docker run`. + +```none +$ mkdir vyos && cd vyos +$ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso +$ mkdir rootfs +$ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs +$ sudo apt-get install -y squashfs-tools +$ mkdir unsquashfs +$ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs +$ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249 +$ sudo umount rootfs +$ cd .. +$ sudo rm -rf vyos +$ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \ +> vyos:1.4-rolling-202111281249 /sbin/init +$ docker exec -ti vyos su - vyos +``` + +You can execute `docker stop vyos` when you are finished with the container. diff --git a/docs/installation/virtual/docker.rst b/docs/installation/virtual/docker.rst deleted file mode 100644 index 0abb4f26..00000000 --- a/docs/installation/virtual/docker.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. _docker: - -*************************** -Running in Docker Container -*************************** - -Docker is an open-source project for deploying applications as standardized -units called containers. Deploying VyOS in a container provides a simple and -lightweight mechanism for both testing and packet routing for container -workloads. - -IPv6 Support for docker -======================= - -VyOS requires an IPv6-enabled docker network. Currently linux distributions -do not enable docker IPv6 support by default. You can enable IPv6 support in -two ways. - -Method 1: Create a docker network with IPv6 support ---------------------------------------------------- - -Here is a example using the macvlan driver. - -.. code-block:: none - - docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet - -Method 2: Add IPv6 support to the docker daemon ------------------------------------------------ - -Edit /etc/docker/daemon.json to set the ``ipv6`` key to ``true`` and to specify -the ``fixed-cidr-v6`` to your desired IPv6 subnet. - -.. code-block:: none - - { - "ipv6": true, - "fixed-cidr-v6": "2001:db8::/64" - } - -Reload the docker configuration. - -.. code-block:: none - - $ sudo systemctl reload docker - - -Deploy container from ISO -========================= - -Download the ISO on which you want to base the container. In this example, -the name of the ISO is ``vyos-1.4-rolling-202308240020-amd64.iso``. If you -created a custom IPv6-enabled network, the ``docker run`` command below -will require that this network be included as the ``--net`` parameter to -``docker run``. - -.. code-block:: none - - $ mkdir vyos && cd vyos - $ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso - $ mkdir rootfs - $ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs - $ sudo apt-get install -y squashfs-tools - $ mkdir unsquashfs - $ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs - $ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249 - $ sudo umount rootfs - $ cd .. - $ sudo rm -rf vyos - $ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \ - > vyos:1.4-rolling-202111281249 /sbin/init - $ docker exec -ti vyos su - vyos - -You can execute ``docker stop vyos`` when you are finished with the container. diff --git a/docs/installation/virtual/eve-ng.md b/docs/installation/virtual/eve-ng.md new file mode 100644 index 00000000..3e32e61f --- /dev/null +++ b/docs/installation/virtual/eve-ng.md @@ -0,0 +1,5 @@ +# EVE-NG + +## References + + diff --git a/docs/installation/virtual/eve-ng.rst b/docs/installation/virtual/eve-ng.rst deleted file mode 100644 index d5134838..00000000 --- a/docs/installation/virtual/eve-ng.rst +++ /dev/null @@ -1,8 +0,0 @@ -###### -EVE-NG -###### - -References -========== - -https://www.eve-ng.net/ \ No newline at end of file diff --git a/docs/installation/virtual/gns3.md b/docs/installation/virtual/gns3.md new file mode 100644 index 00000000..d903c9a4 --- /dev/null +++ b/docs/installation/virtual/gns3.md @@ -0,0 +1,187 @@ +(vyos-on-gns3)= + +# Running on GNS3 + +Sometimes you may want to test VyOS in a lab environment. +[GNS3](http://www.gns3.com) is a network emulation software you +might use for it. + +This guide will provide the necessary steps for installing +and setting up VyOS on GNS3. + +## Requirements + +The following items are required: + +- A VyOS installation image (.iso file). You + can find how to get it on the {ref}`installation` page +- A working GNS3 installation. For further information see the + [GNS3 documentation](https://docs.gns3.com/). + +(vm-setup)= + +## VM setup + +First, a virtual machine (VM) for the VyOS installation must be created +in GNS3. + +Go to the GNS3 **File** menu, click **New template** and choose select +**Manually create a new Template**. + +:::{figure} /_static/images/gns3-01.png +::: + +Select **Quemu VMs** and then click on the `New` button. + +:::{figure} /_static/images/gns3-02.png +::: + +Write a name for your VM, for instance "VyOS", and click `Next`. + +:::{figure} /_static/images/gns3-03.png +::: + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click `Next`. + +:::{figure} /_static/images/gns3-04.png +::: + +Select **telnet** as your console type and click `Next`. + +:::{figure} /_static/images/gns3-05.png +::: + +Select **New image** for the base disk image of your VM and click +`Create`. + +:::{figure} /_static/images/gns3-06.png +::: + +Use the defaults in the **Binary and format** window and click +`Next`. + +:::{figure} /_static/images/gns3-07.png +::: + +Use the defaults in the **Qcow2 options** window and click `Next`. + +:::{figure} /_static/images/gns3-08.png +::: + +Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu +image creator**. + +:::{figure} /_static/images/gns3-09.png +::: + +Click `Finish` to end the **New QEMU VM template** wizard. + +:::{figure} /_static/images/gns3-10.png +::: + +Now the VM settings have to be edited. + +Being again at the **Preferences** window, having **Qemu VMs** +selected and having our new VM selected, click the `Edit` button. + +:::{figure} /_static/images/gns3-11.png +::: + +In the **General settings** tab of your **QEMU VM template +configuration**, do the following: + +- Click on the `Browse...` button to choose the **Symbol** you want to + have representing your VM. +- In **Category** select in which group you want to find your VM. +- Set the **Boot priority** to **CD/DVD-ROM**. + +:::{figure} /_static/images/gns3-12.png +::: + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +:::{figure} /_static/images/gns3-13.png +::: + +At the **CD/DVD** tab click on `Browse...` and locate the VyOS image +you want to install. + +:::{figure} /_static/images/gns3-14.png +::: + +:::{note} +You probably will want to accept to copy the .iso file to your +default image directory when you are asked. +::: + +In the **Network** tab, set **0** as the number of adapters, set the +**Name format** to **eth\{0}** and the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +:::{figure} /_static/images/gns3-15.png +::: + +In the **Advanced** tab, unmark the checkbox **Use as a linked base +VM** and click `OK`, which will save and close the **QEMU VM template +configuration** window. + +:::{figure} /_static/images/gns3-16.png +::: + +At the general **Preferences** window, click `OK` to save and close. + +:::{figure} /_static/images/gns3-17.png +::: + +(vyos-installation)= + +## VyOS installation + +- Create a new project. +- Drag the newly created VyOS VM into it. +- Start the VM. +- Open a console. + The console should show the system booting. It will ask for the login + credentials, you are at the VyOS live system. +- {ref}`Install VyOS ` + as normal (that is, using the `install image` command). +- After a successful installation, shutdown the VM with the `poweroff` + command. +- **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +(vyos-vm-configuration)= + +## VyOS VM configuration + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +:::{figure} /_static/images/gns3-20.png +::: + +**CD/DVD** tab: Unmount the installation image file by clearing the +**Image** entry field. + +:::{figure} /_static/images/gns3-21.png +::: + +Set the number of required network adapters, for example **4**. + +:::{figure} /_static/images/gns3-215.png +::: + +**Advanced** settings tab: Mark the checkbox **Use as a linked +base VM** and click `OK` to save the changes. + +:::{figure} /_static/images/gns3-22.png +::: + +The VyOS VM is now ready to be deployed. diff --git a/docs/installation/virtual/gns3.rst b/docs/installation/virtual/gns3.rst deleted file mode 100644 index f95bd9c9..00000000 --- a/docs/installation/virtual/gns3.rst +++ /dev/null @@ -1,175 +0,0 @@ -.. _vyos-on-gns3: - -############### -Running on GNS3 -############### - -Sometimes you may want to test VyOS in a lab environment. -`GNS3 `__ is a network emulation software you -might use for it. - -This guide will provide the necessary steps for installing -and setting up VyOS on GNS3. - -Requirements ------------- - -The following items are required: - -* A VyOS installation image (.iso file). You - can find how to get it on the :ref:`installation` page - -* A working GNS3 installation. For further information see the - `GNS3 documentation `__. - -.. _vm_setup: - -VM setup --------- - -First, a virtual machine (VM) for the VyOS installation must be created -in GNS3. - -Go to the GNS3 **File** menu, click **New template** and choose select -**Manually create a new Template**. - -.. figure:: /_static/images/gns3-01.png - -Select **Quemu VMs** and then click on the ``New`` button. - -.. figure:: /_static/images/gns3-02.png - -Write a name for your VM, for instance "VyOS", and click ``Next``. - -.. figure:: /_static/images/gns3-03.png - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click ``Next``. - -.. figure:: /_static/images/gns3-04.png - -Select **telnet** as your console type and click ``Next``. - -.. figure:: /_static/images/gns3-05.png - -Select **New image** for the base disk image of your VM and click -``Create``. - -.. figure:: /_static/images/gns3-06.png - -Use the defaults in the **Binary and format** window and click -``Next``. - -.. figure:: /_static/images/gns3-07.png - -Use the defaults in the **Qcow2 options** window and click ``Next``. - -.. figure:: /_static/images/gns3-08.png - -Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu -image creator**. - -.. figure:: /_static/images/gns3-09.png - -Click ``Finish`` to end the **New QEMU VM template** wizard. - -.. figure:: /_static/images/gns3-10.png - -Now the VM settings have to be edited. - -Being again at the **Preferences** window, having **Qemu VMs** -selected and having our new VM selected, click the ``Edit`` button. - -.. figure:: /_static/images/gns3-11.png - -In the **General settings** tab of your **QEMU VM template -configuration**, do the following: - -* Click on the ``Browse...`` button to choose the **Symbol** you want to - have representing your VM. -* In **Category** select in which group you want to find your VM. -* Set the **Boot priority** to **CD/DVD-ROM**. - -.. figure:: /_static/images/gns3-12.png - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -.. figure:: /_static/images/gns3-13.png - -At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image -you want to install. - -.. figure:: /_static/images/gns3-14.png - -.. note:: You probably will want to accept to copy the .iso file to your - default image directory when you are asked. - -In the **Network** tab, set **0** as the number of adapters, set the -**Name format** to **eth{0}** and the **Type** to **Paravirtualized -Network I/O (virtio-net-pci)**. - -.. figure:: /_static/images/gns3-15.png - -In the **Advanced** tab, unmark the checkbox **Use as a linked base -VM** and click ``OK``, which will save and close the **QEMU VM template -configuration** window. - -.. figure:: /_static/images/gns3-16.png - -At the general **Preferences** window, click ``OK`` to save and close. - -.. figure:: /_static/images/gns3-17.png - - -.. _vyos_installation: - -VyOS installation ------------------ - -* Create a new project. -* Drag the newly created VyOS VM into it. -* Start the VM. -* Open a console. - The console should show the system booting. It will ask for the login - credentials, you are at the VyOS live system. -* :ref:`Install VyOS ` - as normal (that is, using the ``install image`` command). - -* After a successful installation, shutdown the VM with the ``poweroff`` - command. - -* **Delete the VM** from the GNS3 project. - -The *VyOS-hda.qcow2* file now contains a working VyOS image and can be -used as a template. But it still needs some fixes before we can deploy -VyOS in our labs. - -.. _vyos_vm_configuration: - -VyOS VM configuration ---------------------- - -To turn the template into a working VyOS machine, further steps are -necessary as outlined below: - -**General settings** tab: Set the boot priority to **HDD** - -.. figure:: /_static/images/gns3-20.png - -**CD/DVD** tab: Unmount the installation image file by clearing the -**Image** entry field. - -.. figure:: /_static/images/gns3-21.png - -Set the number of required network adapters, for example **4**. - -.. figure:: /_static/images/gns3-215.png - -**Advanced** settings tab: Mark the checkbox **Use as a linked -base VM** and click ``OK`` to save the changes. - -.. figure:: /_static/images/gns3-22.png - -The VyOS VM is now ready to be deployed. - diff --git a/docs/installation/virtual/index.md b/docs/installation/virtual/index.md new file mode 100644 index 00000000..12ac179e --- /dev/null +++ b/docs/installation/virtual/index.md @@ -0,0 +1,13 @@ +# Running VyOS in Virtual Environments + +```{eval-rst} +.. toctree:: + :caption: Content + + libvirt + proxmox + vmware + gns3 + eve-ng + docker +``` diff --git a/docs/installation/virtual/index.rst b/docs/installation/virtual/index.rst deleted file mode 100644 index 8b088598..00000000 --- a/docs/installation/virtual/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -#################################### -Running VyOS in Virtual Environments -#################################### - -.. toctree:: - :caption: Content - - libvirt - proxmox - vmware - gns3 - eve-ng - docker diff --git a/docs/installation/virtual/libvirt.md b/docs/installation/virtual/libvirt.md new file mode 100644 index 00000000..5acefd43 --- /dev/null +++ b/docs/installation/virtual/libvirt.md @@ -0,0 +1,171 @@ +(libvirt)= + +# Running on Libvirt Qemu/KVM + +Libvirt is an open-source API, daemon and management tool for managing platform +virtualization. There are several ways to deploy VyOS on libvirt kvm. +Use Virt-manager and native CLI. In an example we will be use use 4 gigabytes +of memory, 2 cores CPU and default network virbr0. + +## CLI + +### Deploy from ISO + +Create VM name `vyos_r1`. You must specify the path to the `ISO` image, +the disk `qcow2` will be created automatically. The `default` network is +the virtual network (type Virtio) created by the hypervisor with NAT. + +```none +$ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom /var/lib/libvirt/images/vyos.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ + --noautoconsole +``` + +Connect to VM with command `virsh console vyos_r1` + +```none +$ virsh console vyos_r1 + +Connected to domain vyos_r1 +Escape character is ^] + +vyos login: vyos +Password: + +vyos@vyos:~$ install image +``` + +After installation - exit from the console using the key combination +`Ctrl + ]` and reboot the system. + +### Deploy from qcow2 + +The convenience of using {abbr}`KVM (Kernel-based Virtual Machine)` +images is that they don't need to be installed. +Download predefined VyOS.qcow2 image for `KVM` + +```none +curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 +``` + +Create VM with `import` qcow2 disk option. + +```none +$ virt-install -n vyos_r2 \ + --ram 4096 \ + --vcpus 2 \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole +``` + +Connect to VM with command `virsh console vyos_r2` + +```none +$ virsh console vyos_r2 + +Connected to domain vyos_r2 +Escape character is ^] + +vyos login: vyos +Password: + +vyos@vyos:~$ +``` + +The system is fully operational. + +## Virt-manager + +The virt-manager application is a desktop user interface for managing virtual +machines through libvirt. On the linux open +{abbr}`VMM (Virtual Machine Manager)`. + +(libvirt-virt-manager-iso)= + +### Deploy from ISO + +1. Open {abbr}`VMM (Virtual Machine Manager)` and Create a new + {abbr}`VM (Virtual Machine)` +2. Choose `Local install media` (ISO) + +:::{figure} /_static/images/virt-libvirt-01.png +::: + +3. Choose path to iso vyos.iso. Operating System can be any Debian based. + +:::{figure} /_static/images/virt-libvirt-02.png +::: + +4. Choose Memory and CPU + +:::{figure} /_static/images/virt-libvirt-03.png +::: + +5. Disk size + +:::{figure} /_static/images/virt-libvirt-04.png +::: + +6. Name of VM and network selection + +:::{figure} /_static/images/virt-libvirt-05.png +::: + +7. Then you will be taken to the console. + +:::{figure} /_static/images/virt-libvirt-06.png +::: + +(libvirt-virt-manager-qcow2)= + +### Deploy from qcow2 + +Download predefined VyOS.qcow2 image for `KVM` + +```none +curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 +``` + +1. Open {abbr}`VMM (Virtual Machine Manager)` and Create a new + {abbr}`VM (Virtual Machine)` +2. Choose `Import existing disk` image + +:::{figure} /_static/images/virt-libvirt-qc-01.png +::: + +3. Choose the path to the image `vyos_kvm.qcow2` that was previously + downloaded . Operation System can be any Debian based. + +:::{figure} /_static/images/virt-libvirt-qc-02.png +::: + +4. Choose Memory and CPU + +:::{figure} /_static/images/virt-libvirt-03.png +::: + +5. Name of VM and network selection + +:::{figure} /_static/images/virt-libvirt-05.png +::: + +6. Then you will be taken to the console. + +:::{figure} /_static/images/virt-libvirt-qc-03.png +::: diff --git a/docs/installation/virtual/libvirt.rst b/docs/installation/virtual/libvirt.rst deleted file mode 100644 index 09d2cfed..00000000 --- a/docs/installation/virtual/libvirt.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. _libvirt: - -*************************** -Running on Libvirt Qemu/KVM -*************************** - -Libvirt is an open-source API, daemon and management tool for managing platform -virtualization. There are several ways to deploy VyOS on libvirt kvm. -Use Virt-manager and native CLI. In an example we will be use use 4 gigabytes -of memory, 2 cores CPU and default network virbr0. - -CLI -=== - -Deploy from ISO ---------------- - -Create VM name ``vyos_r1``. You must specify the path to the ``ISO`` image, -the disk ``qcow2`` will be created automatically. The ``default`` network is -the virtual network (type Virtio) created by the hypervisor with NAT. - -.. code-block:: none - - $ virt-install -n vyos_r1 \ - --ram 4096 \ - --vcpus 2 \ - --cdrom /var/lib/libvirt/images/vyos.iso \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ - --noautoconsole - -Connect to VM with command ``virsh console vyos_r1`` - -.. code-block:: none - - $ virsh console vyos_r1 - - Connected to domain vyos_r1 - Escape character is ^] - - vyos login: vyos - Password: - - vyos@vyos:~$ install image - -After installation - exit from the console using the key combination -``Ctrl + ]`` and reboot the system. - -Deploy from qcow2 ------------------ -The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` -images is that they don't need to be installed. -Download predefined VyOS.qcow2 image for ``KVM`` - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - -Create VM with ``import`` qcow2 disk option. - -.. code-block:: none - - $ virt-install -n vyos_r2 \ - --ram 4096 \ - --vcpus 2 \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ - --import \ - --noautoconsole - -Connect to VM with command ``virsh console vyos_r2`` - -.. code-block:: none - - $ virsh console vyos_r2 - - Connected to domain vyos_r2 - Escape character is ^] - - vyos login: vyos - Password: - - vyos@vyos:~$ - -The system is fully operational. - -Virt-manager -============ -The virt-manager application is a desktop user interface for managing virtual -machines through libvirt. On the linux open -:abbr:`VMM (Virtual Machine Manager)`. - -.. _libvirt:virt-manager_iso: - -Deploy from ISO ---------------- - -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new - :abbr:`VM (Virtual Machine)` - -2. Choose ``Local install media`` (ISO) - -.. figure:: /_static/images/virt-libvirt-01.png - -3. Choose path to iso vyos.iso. Operating System can be any Debian based. - -.. figure:: /_static/images/virt-libvirt-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Disk size - -.. figure:: /_static/images/virt-libvirt-04.png - -6. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -7. Then you will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-06.png - -.. _libvirt:virt-manager_qcow2: - -Deploy from qcow2 ------------------ - -Download predefined VyOS.qcow2 image for ``KVM`` - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - - -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new - :abbr:`VM (Virtual Machine)` - -2. Choose ``Import existing disk`` image - -.. figure:: /_static/images/virt-libvirt-qc-01.png - -3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously - downloaded . Operation System can be any Debian based. - -.. figure:: /_static/images/virt-libvirt-qc-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -6. Then you will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-qc-03.png - - - diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md deleted file mode 100644 index 10da8d41..00000000 --- a/docs/installation/virtual/md-docker.md +++ /dev/null @@ -1,67 +0,0 @@ -(docker)= - -# Running in Docker Container - -Docker is an open-source project for deploying applications as standardized -units called containers. Deploying VyOS in a container provides a simple and -lightweight mechanism for both testing and packet routing for container -workloads. - -## IPv6 Support for docker - -VyOS requires an IPv6-enabled docker network. Currently linux distributions -do not enable docker IPv6 support by default. You can enable IPv6 support in -two ways. - -### Method 1: Create a docker network with IPv6 support - -Here is a example using the macvlan driver. - -```none -docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet -``` - -### Method 2: Add IPv6 support to the docker daemon - -Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and to specify -the `fixed-cidr-v6` to your desired IPv6 subnet. - -```none -{ - "ipv6": true, - "fixed-cidr-v6": "2001:db8::/64" -} -``` - -Reload the docker configuration. - -```none -$ sudo systemctl reload docker -``` - -## Deploy container from ISO - -Download the ISO on which you want to base the container. In this example, -the name of the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you -created a custom IPv6-enabled network, the `docker run` command below -will require that this network be included as the `--net` parameter to -`docker run`. - -```none -$ mkdir vyos && cd vyos -$ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso -$ mkdir rootfs -$ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs -$ sudo apt-get install -y squashfs-tools -$ mkdir unsquashfs -$ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs -$ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249 -$ sudo umount rootfs -$ cd .. -$ sudo rm -rf vyos -$ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \ -> vyos:1.4-rolling-202111281249 /sbin/init -$ docker exec -ti vyos su - vyos -``` - -You can execute `docker stop vyos` when you are finished with the container. diff --git a/docs/installation/virtual/md-eve-ng.md b/docs/installation/virtual/md-eve-ng.md deleted file mode 100644 index 3e32e61f..00000000 --- a/docs/installation/virtual/md-eve-ng.md +++ /dev/null @@ -1,5 +0,0 @@ -# EVE-NG - -## References - - diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md deleted file mode 100644 index d903c9a4..00000000 --- a/docs/installation/virtual/md-gns3.md +++ /dev/null @@ -1,187 +0,0 @@ -(vyos-on-gns3)= - -# Running on GNS3 - -Sometimes you may want to test VyOS in a lab environment. -[GNS3](http://www.gns3.com) is a network emulation software you -might use for it. - -This guide will provide the necessary steps for installing -and setting up VyOS on GNS3. - -## Requirements - -The following items are required: - -- A VyOS installation image (.iso file). You - can find how to get it on the {ref}`installation` page -- A working GNS3 installation. For further information see the - [GNS3 documentation](https://docs.gns3.com/). - -(vm-setup)= - -## VM setup - -First, a virtual machine (VM) for the VyOS installation must be created -in GNS3. - -Go to the GNS3 **File** menu, click **New template** and choose select -**Manually create a new Template**. - -:::{figure} /_static/images/gns3-01.png -::: - -Select **Quemu VMs** and then click on the `New` button. - -:::{figure} /_static/images/gns3-02.png -::: - -Write a name for your VM, for instance "VyOS", and click `Next`. - -:::{figure} /_static/images/gns3-03.png -::: - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click `Next`. - -:::{figure} /_static/images/gns3-04.png -::: - -Select **telnet** as your console type and click `Next`. - -:::{figure} /_static/images/gns3-05.png -::: - -Select **New image** for the base disk image of your VM and click -`Create`. - -:::{figure} /_static/images/gns3-06.png -::: - -Use the defaults in the **Binary and format** window and click -`Next`. - -:::{figure} /_static/images/gns3-07.png -::: - -Use the defaults in the **Qcow2 options** window and click `Next`. - -:::{figure} /_static/images/gns3-08.png -::: - -Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu -image creator**. - -:::{figure} /_static/images/gns3-09.png -::: - -Click `Finish` to end the **New QEMU VM template** wizard. - -:::{figure} /_static/images/gns3-10.png -::: - -Now the VM settings have to be edited. - -Being again at the **Preferences** window, having **Qemu VMs** -selected and having our new VM selected, click the `Edit` button. - -:::{figure} /_static/images/gns3-11.png -::: - -In the **General settings** tab of your **QEMU VM template -configuration**, do the following: - -- Click on the `Browse...` button to choose the **Symbol** you want to - have representing your VM. -- In **Category** select in which group you want to find your VM. -- Set the **Boot priority** to **CD/DVD-ROM**. - -:::{figure} /_static/images/gns3-12.png -::: - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -:::{figure} /_static/images/gns3-13.png -::: - -At the **CD/DVD** tab click on `Browse...` and locate the VyOS image -you want to install. - -:::{figure} /_static/images/gns3-14.png -::: - -:::{note} -You probably will want to accept to copy the .iso file to your -default image directory when you are asked. -::: - -In the **Network** tab, set **0** as the number of adapters, set the -**Name format** to **eth\{0}** and the **Type** to **Paravirtualized -Network I/O (virtio-net-pci)**. - -:::{figure} /_static/images/gns3-15.png -::: - -In the **Advanced** tab, unmark the checkbox **Use as a linked base -VM** and click `OK`, which will save and close the **QEMU VM template -configuration** window. - -:::{figure} /_static/images/gns3-16.png -::: - -At the general **Preferences** window, click `OK` to save and close. - -:::{figure} /_static/images/gns3-17.png -::: - -(vyos-installation)= - -## VyOS installation - -- Create a new project. -- Drag the newly created VyOS VM into it. -- Start the VM. -- Open a console. - The console should show the system booting. It will ask for the login - credentials, you are at the VyOS live system. -- {ref}`Install VyOS ` - as normal (that is, using the `install image` command). -- After a successful installation, shutdown the VM with the `poweroff` - command. -- **Delete the VM** from the GNS3 project. - -The *VyOS-hda.qcow2* file now contains a working VyOS image and can be -used as a template. But it still needs some fixes before we can deploy -VyOS in our labs. - -(vyos-vm-configuration)= - -## VyOS VM configuration - -To turn the template into a working VyOS machine, further steps are -necessary as outlined below: - -**General settings** tab: Set the boot priority to **HDD** - -:::{figure} /_static/images/gns3-20.png -::: - -**CD/DVD** tab: Unmount the installation image file by clearing the -**Image** entry field. - -:::{figure} /_static/images/gns3-21.png -::: - -Set the number of required network adapters, for example **4**. - -:::{figure} /_static/images/gns3-215.png -::: - -**Advanced** settings tab: Mark the checkbox **Use as a linked -base VM** and click `OK` to save the changes. - -:::{figure} /_static/images/gns3-22.png -::: - -The VyOS VM is now ready to be deployed. diff --git a/docs/installation/virtual/md-index.md b/docs/installation/virtual/md-index.md deleted file mode 100644 index 12ac179e..00000000 --- a/docs/installation/virtual/md-index.md +++ /dev/null @@ -1,13 +0,0 @@ -# Running VyOS in Virtual Environments - -```{eval-rst} -.. toctree:: - :caption: Content - - libvirt - proxmox - vmware - gns3 - eve-ng - docker -``` diff --git a/docs/installation/virtual/md-libvirt.md b/docs/installation/virtual/md-libvirt.md deleted file mode 100644 index 5acefd43..00000000 --- a/docs/installation/virtual/md-libvirt.md +++ /dev/null @@ -1,171 +0,0 @@ -(libvirt)= - -# Running on Libvirt Qemu/KVM - -Libvirt is an open-source API, daemon and management tool for managing platform -virtualization. There are several ways to deploy VyOS on libvirt kvm. -Use Virt-manager and native CLI. In an example we will be use use 4 gigabytes -of memory, 2 cores CPU and default network virbr0. - -## CLI - -### Deploy from ISO - -Create VM name `vyos_r1`. You must specify the path to the `ISO` image, -the disk `qcow2` will be created automatically. The `default` network is -the virtual network (type Virtio) created by the hypervisor with NAT. - -```none -$ virt-install -n vyos_r1 \ - --ram 4096 \ - --vcpus 2 \ - --cdrom /var/lib/libvirt/images/vyos.iso \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ - --noautoconsole -``` - -Connect to VM with command `virsh console vyos_r1` - -```none -$ virsh console vyos_r1 - -Connected to domain vyos_r1 -Escape character is ^] - -vyos login: vyos -Password: - -vyos@vyos:~$ install image -``` - -After installation - exit from the console using the key combination -`Ctrl + ]` and reboot the system. - -### Deploy from qcow2 - -The convenience of using {abbr}`KVM (Kernel-based Virtual Machine)` -images is that they don't need to be installed. -Download predefined VyOS.qcow2 image for `KVM` - -```none -curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 -``` - -Create VM with `import` qcow2 disk option. - -```none -$ virt-install -n vyos_r2 \ - --ram 4096 \ - --vcpus 2 \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ - --import \ - --noautoconsole -``` - -Connect to VM with command `virsh console vyos_r2` - -```none -$ virsh console vyos_r2 - -Connected to domain vyos_r2 -Escape character is ^] - -vyos login: vyos -Password: - -vyos@vyos:~$ -``` - -The system is fully operational. - -## Virt-manager - -The virt-manager application is a desktop user interface for managing virtual -machines through libvirt. On the linux open -{abbr}`VMM (Virtual Machine Manager)`. - -(libvirt-virt-manager-iso)= - -### Deploy from ISO - -1. Open {abbr}`VMM (Virtual Machine Manager)` and Create a new - {abbr}`VM (Virtual Machine)` -2. Choose `Local install media` (ISO) - -:::{figure} /_static/images/virt-libvirt-01.png -::: - -3. Choose path to iso vyos.iso. Operating System can be any Debian based. - -:::{figure} /_static/images/virt-libvirt-02.png -::: - -4. Choose Memory and CPU - -:::{figure} /_static/images/virt-libvirt-03.png -::: - -5. Disk size - -:::{figure} /_static/images/virt-libvirt-04.png -::: - -6. Name of VM and network selection - -:::{figure} /_static/images/virt-libvirt-05.png -::: - -7. Then you will be taken to the console. - -:::{figure} /_static/images/virt-libvirt-06.png -::: - -(libvirt-virt-manager-qcow2)= - -### Deploy from qcow2 - -Download predefined VyOS.qcow2 image for `KVM` - -```none -curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 -``` - -1. Open {abbr}`VMM (Virtual Machine Manager)` and Create a new - {abbr}`VM (Virtual Machine)` -2. Choose `Import existing disk` image - -:::{figure} /_static/images/virt-libvirt-qc-01.png -::: - -3. Choose the path to the image `vyos_kvm.qcow2` that was previously - downloaded . Operation System can be any Debian based. - -:::{figure} /_static/images/virt-libvirt-qc-02.png -::: - -4. Choose Memory and CPU - -:::{figure} /_static/images/virt-libvirt-03.png -::: - -5. Name of VM and network selection - -:::{figure} /_static/images/virt-libvirt-05.png -::: - -6. Then you will be taken to the console. - -:::{figure} /_static/images/virt-libvirt-qc-03.png -::: diff --git a/docs/installation/virtual/md-proxmox.md b/docs/installation/virtual/md-proxmox.md deleted file mode 100644 index cad22137..00000000 --- a/docs/installation/virtual/md-proxmox.md +++ /dev/null @@ -1,45 +0,0 @@ -(proxmox)= - -# Running on Proxmox - -Proxmox is an open-source platform for virtualization. Please visit - to see how to get a qcow2 image that can be imported -into Proxmox. - -## Deploy VyOS from CLI with qcow2 image - -1. Copy the qcow2 image to a temporary directory on the Proxmox server. -2. The commands below assume that virtual machine ID 200 is unused and that the user wants the disk stored in a storage pool called `local-lvm`. - -```none -$ qm create 200 --name vyos2 --memory 2048 --net0 virtio,bridge=vmbr0 -$ qm importdisk 200 /path/to/image/vyos-1.2.8-proxmox-2G.qcow2 local-lvm -$ qm set 200 --virtio0 local-lvm:vm-200-disk-0 -$ qm set 200 --boot order=virtio0 -``` - -3. Optionally, the user can attach a CDROM with an ISO as a cloud-init data source. The below command assumes the ISO has been uploaded to the `local` storage pool with the name `seed.iso`. - -```none -$ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso -``` - -4. Start the virtual machine in the proxmox GUI or CLI using `qm start 200`. - -## Deploy VyOS from CLI with rolling release ISO - -1. Download the rolling release iso from . 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 . -2. Prepare VM for installation from ISO media. The commands below assume that your iso is available in a storage pool 'local', that you want it to have a VM ID '200' and want to create a new disk on storage pool 'local-lvm' of size 15GB. - -```none -qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15 -``` - -3. Start the VM using the command `qm start 200` or using the start button located in the proxmox GUI. -4. Using the proxmox webGUI, open the virtual console for your newly created vm. Login username/password is `vyos/vyos`. -5. Once booted into the live system, type `install image` into the command line and follow the prompts to install VyOS to the virtual drive. -6. After installation has completed, remove the installation iso using the GUI or `qm set 200 --ide2 none`. -7. Reboot the virtual machine using the GUI or `qm reboot 200`. - -Visit for more information about the download -and installation of this hypervisor. diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md deleted file mode 100644 index 0338067c..00000000 --- a/docs/installation/virtual/md-vmware.md +++ /dev/null @@ -1,39 +0,0 @@ -(vyosonvmware)= - -# Running on VMware ESXi - -## ESXi 5.5 or later - -.ova files are available for supporting users, and a VyOS can also be stood up -using a generic Linux instance, and attaching the bootable ISO file and -installing from the ISO using the normal process around `install image`. - -:::{NOTE} -There have been previous documented issues with GRE/IPSEC tunneling -using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been -advised. -::: - -### Memory Contention Considerations - -When the underlying ESXi host is approaching ~92% memory utilisation it will -start the balloon process in a 'soft' state to start reclaiming memory from -guest operating systems. This causes an artificial pressure using the vmmemctl -driver on memory usage on the virtual guest. As VyOS by default does not have -a swap file, this vmmemctl pressure is unable to force processes to move in -memory data to the paging file, and blindly consumes memory forcing the -virtual guest into a low memory state with no way to escape. The balloon -can expand to 65% of guest allocated memory, so a VyOS guest running >35% of -memory usage, can encounter an out of memory situation, and trigger the kernel -oom_kill process. At this point a weighted lottery favouring memory hungry -processes will be run with the unlucky winner being terminated by the kernel. - -It is advised that VyOS routers are configured in a resource group with -adequate memory reservations so that ballooning is not inflicted on -virtual VyOS guests. - -### References - - - - diff --git a/docs/installation/virtual/proxmox.md b/docs/installation/virtual/proxmox.md new file mode 100644 index 00000000..cad22137 --- /dev/null +++ b/docs/installation/virtual/proxmox.md @@ -0,0 +1,45 @@ +(proxmox)= + +# Running on Proxmox + +Proxmox is an open-source platform for virtualization. Please visit + to see how to get a qcow2 image that can be imported +into Proxmox. + +## Deploy VyOS from CLI with qcow2 image + +1. Copy the qcow2 image to a temporary directory on the Proxmox server. +2. The commands below assume that virtual machine ID 200 is unused and that the user wants the disk stored in a storage pool called `local-lvm`. + +```none +$ qm create 200 --name vyos2 --memory 2048 --net0 virtio,bridge=vmbr0 +$ qm importdisk 200 /path/to/image/vyos-1.2.8-proxmox-2G.qcow2 local-lvm +$ qm set 200 --virtio0 local-lvm:vm-200-disk-0 +$ qm set 200 --boot order=virtio0 +``` + +3. Optionally, the user can attach a CDROM with an ISO as a cloud-init data source. The below command assumes the ISO has been uploaded to the `local` storage pool with the name `seed.iso`. + +```none +$ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso +``` + +4. Start the virtual machine in the proxmox GUI or CLI using `qm start 200`. + +## Deploy VyOS from CLI with rolling release ISO + +1. Download the rolling release iso from . 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 . +2. Prepare VM for installation from ISO media. The commands below assume that your iso is available in a storage pool 'local', that you want it to have a VM ID '200' and want to create a new disk on storage pool 'local-lvm' of size 15GB. + +```none +qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15 +``` + +3. Start the VM using the command `qm start 200` or using the start button located in the proxmox GUI. +4. Using the proxmox webGUI, open the virtual console for your newly created vm. Login username/password is `vyos/vyos`. +5. Once booted into the live system, type `install image` into the command line and follow the prompts to install VyOS to the virtual drive. +6. After installation has completed, remove the installation iso using the GUI or `qm set 200 --ide2 none`. +7. Reboot the virtual machine using the GUI or `qm reboot 200`. + +Visit for more information about the download +and installation of this hypervisor. diff --git a/docs/installation/virtual/proxmox.rst b/docs/installation/virtual/proxmox.rst deleted file mode 100644 index e44aa65a..00000000 --- a/docs/installation/virtual/proxmox.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _proxmox: - -****************** -Running on Proxmox -****************** - -Proxmox is an open-source platform for virtualization. Please visit -https://vyos.io to see how to get a qcow2 image that can be imported -into Proxmox. - -Deploy VyOS from CLI with qcow2 image -===================================== - -1. Copy the qcow2 image to a temporary directory on the Proxmox server. -2. The commands below assume that virtual machine ID 200 is unused and that the user wants the disk stored in a storage pool called `local-lvm`. - -.. code-block:: none - - $ qm create 200 --name vyos2 --memory 2048 --net0 virtio,bridge=vmbr0 - $ qm importdisk 200 /path/to/image/vyos-1.2.8-proxmox-2G.qcow2 local-lvm - $ qm set 200 --virtio0 local-lvm:vm-200-disk-0 - $ qm set 200 --boot order=virtio0 - -3. Optionally, the user can attach a CDROM with an ISO as a cloud-init data source. The below command assumes the ISO has been uploaded to the `local` storage pool with the name `seed.iso`. - -.. code-block:: none - - $ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso - -4. Start the virtual machine in the proxmox GUI or CLI using ``qm start 200``. - - - -Deploy VyOS from CLI with rolling release ISO -============================================= - -1. Download the rolling release iso from https://vyos.net/get/nightly-builds/. 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 https://github.com/vyos/vyos-build. -2. Prepare VM for installation from ISO media. The commands below assume that your iso is available in a storage pool 'local', that you want it to have a VM ID '200' and want to create a new disk on storage pool 'local-lvm' of size 15GB. - -.. code-block:: none - - qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15 - -3. Start the VM using the command ``qm start 200`` or using the start button located in the proxmox GUI. -4. Using the proxmox webGUI, open the virtual console for your newly created vm. Login username/password is ``vyos/vyos``. -5. Once booted into the live system, type ``install image`` into the command line and follow the prompts to install VyOS to the virtual drive. -6. After installation has completed, remove the installation iso using the GUI or ``qm set 200 --ide2 none``. -7. Reboot the virtual machine using the GUI or ``qm reboot 200``. - - - - - -Visit https://www.proxmox.com/en/ for more information about the download -and installation of this hypervisor. - diff --git a/docs/installation/virtual/rst-docker.rst b/docs/installation/virtual/rst-docker.rst new file mode 100644 index 00000000..0abb4f26 --- /dev/null +++ b/docs/installation/virtual/rst-docker.rst @@ -0,0 +1,74 @@ +.. _docker: + +*************************** +Running in Docker Container +*************************** + +Docker is an open-source project for deploying applications as standardized +units called containers. Deploying VyOS in a container provides a simple and +lightweight mechanism for both testing and packet routing for container +workloads. + +IPv6 Support for docker +======================= + +VyOS requires an IPv6-enabled docker network. Currently linux distributions +do not enable docker IPv6 support by default. You can enable IPv6 support in +two ways. + +Method 1: Create a docker network with IPv6 support +--------------------------------------------------- + +Here is a example using the macvlan driver. + +.. code-block:: none + + docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet + +Method 2: Add IPv6 support to the docker daemon +----------------------------------------------- + +Edit /etc/docker/daemon.json to set the ``ipv6`` key to ``true`` and to specify +the ``fixed-cidr-v6`` to your desired IPv6 subnet. + +.. code-block:: none + + { + "ipv6": true, + "fixed-cidr-v6": "2001:db8::/64" + } + +Reload the docker configuration. + +.. code-block:: none + + $ sudo systemctl reload docker + + +Deploy container from ISO +========================= + +Download the ISO on which you want to base the container. In this example, +the name of the ISO is ``vyos-1.4-rolling-202308240020-amd64.iso``. If you +created a custom IPv6-enabled network, the ``docker run`` command below +will require that this network be included as the ``--net`` parameter to +``docker run``. + +.. code-block:: none + + $ mkdir vyos && cd vyos + $ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso + $ mkdir rootfs + $ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs + $ sudo apt-get install -y squashfs-tools + $ mkdir unsquashfs + $ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs + $ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249 + $ sudo umount rootfs + $ cd .. + $ sudo rm -rf vyos + $ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \ + > vyos:1.4-rolling-202111281249 /sbin/init + $ docker exec -ti vyos su - vyos + +You can execute ``docker stop vyos`` when you are finished with the container. diff --git a/docs/installation/virtual/rst-eve-ng.rst b/docs/installation/virtual/rst-eve-ng.rst new file mode 100644 index 00000000..d5134838 --- /dev/null +++ b/docs/installation/virtual/rst-eve-ng.rst @@ -0,0 +1,8 @@ +###### +EVE-NG +###### + +References +========== + +https://www.eve-ng.net/ \ No newline at end of file diff --git a/docs/installation/virtual/rst-gns3.rst b/docs/installation/virtual/rst-gns3.rst new file mode 100644 index 00000000..f95bd9c9 --- /dev/null +++ b/docs/installation/virtual/rst-gns3.rst @@ -0,0 +1,175 @@ +.. _vyos-on-gns3: + +############### +Running on GNS3 +############### + +Sometimes you may want to test VyOS in a lab environment. +`GNS3 `__ is a network emulation software you +might use for it. + +This guide will provide the necessary steps for installing +and setting up VyOS on GNS3. + +Requirements +------------ + +The following items are required: + +* A VyOS installation image (.iso file). You + can find how to get it on the :ref:`installation` page + +* A working GNS3 installation. For further information see the + `GNS3 documentation `__. + +.. _vm_setup: + +VM setup +-------- + +First, a virtual machine (VM) for the VyOS installation must be created +in GNS3. + +Go to the GNS3 **File** menu, click **New template** and choose select +**Manually create a new Template**. + +.. figure:: /_static/images/gns3-01.png + +Select **Quemu VMs** and then click on the ``New`` button. + +.. figure:: /_static/images/gns3-02.png + +Write a name for your VM, for instance "VyOS", and click ``Next``. + +.. figure:: /_static/images/gns3-03.png + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click ``Next``. + +.. figure:: /_static/images/gns3-04.png + +Select **telnet** as your console type and click ``Next``. + +.. figure:: /_static/images/gns3-05.png + +Select **New image** for the base disk image of your VM and click +``Create``. + +.. figure:: /_static/images/gns3-06.png + +Use the defaults in the **Binary and format** window and click +``Next``. + +.. figure:: /_static/images/gns3-07.png + +Use the defaults in the **Qcow2 options** window and click ``Next``. + +.. figure:: /_static/images/gns3-08.png + +Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu +image creator**. + +.. figure:: /_static/images/gns3-09.png + +Click ``Finish`` to end the **New QEMU VM template** wizard. + +.. figure:: /_static/images/gns3-10.png + +Now the VM settings have to be edited. + +Being again at the **Preferences** window, having **Qemu VMs** +selected and having our new VM selected, click the ``Edit`` button. + +.. figure:: /_static/images/gns3-11.png + +In the **General settings** tab of your **QEMU VM template +configuration**, do the following: + +* Click on the ``Browse...`` button to choose the **Symbol** you want to + have representing your VM. +* In **Category** select in which group you want to find your VM. +* Set the **Boot priority** to **CD/DVD-ROM**. + +.. figure:: /_static/images/gns3-12.png + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +.. figure:: /_static/images/gns3-13.png + +At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image +you want to install. + +.. figure:: /_static/images/gns3-14.png + +.. note:: You probably will want to accept to copy the .iso file to your + default image directory when you are asked. + +In the **Network** tab, set **0** as the number of adapters, set the +**Name format** to **eth{0}** and the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +.. figure:: /_static/images/gns3-15.png + +In the **Advanced** tab, unmark the checkbox **Use as a linked base +VM** and click ``OK``, which will save and close the **QEMU VM template +configuration** window. + +.. figure:: /_static/images/gns3-16.png + +At the general **Preferences** window, click ``OK`` to save and close. + +.. figure:: /_static/images/gns3-17.png + + +.. _vyos_installation: + +VyOS installation +----------------- + +* Create a new project. +* Drag the newly created VyOS VM into it. +* Start the VM. +* Open a console. + The console should show the system booting. It will ask for the login + credentials, you are at the VyOS live system. +* :ref:`Install VyOS ` + as normal (that is, using the ``install image`` command). + +* After a successful installation, shutdown the VM with the ``poweroff`` + command. + +* **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +.. _vyos_vm_configuration: + +VyOS VM configuration +--------------------- + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +.. figure:: /_static/images/gns3-20.png + +**CD/DVD** tab: Unmount the installation image file by clearing the +**Image** entry field. + +.. figure:: /_static/images/gns3-21.png + +Set the number of required network adapters, for example **4**. + +.. figure:: /_static/images/gns3-215.png + +**Advanced** settings tab: Mark the checkbox **Use as a linked +base VM** and click ``OK`` to save the changes. + +.. figure:: /_static/images/gns3-22.png + +The VyOS VM is now ready to be deployed. + diff --git a/docs/installation/virtual/rst-index.rst b/docs/installation/virtual/rst-index.rst new file mode 100644 index 00000000..8b088598 --- /dev/null +++ b/docs/installation/virtual/rst-index.rst @@ -0,0 +1,13 @@ +#################################### +Running VyOS in Virtual Environments +#################################### + +.. toctree:: + :caption: Content + + libvirt + proxmox + vmware + gns3 + eve-ng + docker diff --git a/docs/installation/virtual/rst-libvirt.rst b/docs/installation/virtual/rst-libvirt.rst new file mode 100644 index 00000000..09d2cfed --- /dev/null +++ b/docs/installation/virtual/rst-libvirt.rst @@ -0,0 +1,172 @@ +.. _libvirt: + +*************************** +Running on Libvirt Qemu/KVM +*************************** + +Libvirt is an open-source API, daemon and management tool for managing platform +virtualization. There are several ways to deploy VyOS on libvirt kvm. +Use Virt-manager and native CLI. In an example we will be use use 4 gigabytes +of memory, 2 cores CPU and default network virbr0. + +CLI +=== + +Deploy from ISO +--------------- + +Create VM name ``vyos_r1``. You must specify the path to the ``ISO`` image, +the disk ``qcow2`` will be created automatically. The ``default`` network is +the virtual network (type Virtio) created by the hypervisor with NAT. + +.. code-block:: none + + $ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom /var/lib/libvirt/images/vyos.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ + --noautoconsole + +Connect to VM with command ``virsh console vyos_r1`` + +.. code-block:: none + + $ virsh console vyos_r1 + + Connected to domain vyos_r1 + Escape character is ^] + + vyos login: vyos + Password: + + vyos@vyos:~$ install image + +After installation - exit from the console using the key combination +``Ctrl + ]`` and reboot the system. + +Deploy from qcow2 +----------------- +The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` +images is that they don't need to be installed. +Download predefined VyOS.qcow2 image for ``KVM`` + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + +Create VM with ``import`` qcow2 disk option. + +.. code-block:: none + + $ virt-install -n vyos_r2 \ + --ram 4096 \ + --vcpus 2 \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole + +Connect to VM with command ``virsh console vyos_r2`` + +.. code-block:: none + + $ virsh console vyos_r2 + + Connected to domain vyos_r2 + Escape character is ^] + + vyos login: vyos + Password: + + vyos@vyos:~$ + +The system is fully operational. + +Virt-manager +============ +The virt-manager application is a desktop user interface for managing virtual +machines through libvirt. On the linux open +:abbr:`VMM (Virtual Machine Manager)`. + +.. _libvirt:virt-manager_iso: + +Deploy from ISO +--------------- + +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new + :abbr:`VM (Virtual Machine)` + +2. Choose ``Local install media`` (ISO) + +.. figure:: /_static/images/virt-libvirt-01.png + +3. Choose path to iso vyos.iso. Operating System can be any Debian based. + +.. figure:: /_static/images/virt-libvirt-02.png + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.png + +5. Disk size + +.. figure:: /_static/images/virt-libvirt-04.png + +6. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.png + +7. Then you will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-06.png + +.. _libvirt:virt-manager_qcow2: + +Deploy from qcow2 +----------------- + +Download predefined VyOS.qcow2 image for ``KVM`` + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + + +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new + :abbr:`VM (Virtual Machine)` + +2. Choose ``Import existing disk`` image + +.. figure:: /_static/images/virt-libvirt-qc-01.png + +3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously + downloaded . Operation System can be any Debian based. + +.. figure:: /_static/images/virt-libvirt-qc-02.png + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.png + +5. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.png + +6. Then you will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-qc-03.png + + + diff --git a/docs/installation/virtual/rst-proxmox.rst b/docs/installation/virtual/rst-proxmox.rst new file mode 100644 index 00000000..e44aa65a --- /dev/null +++ b/docs/installation/virtual/rst-proxmox.rst @@ -0,0 +1,56 @@ +.. _proxmox: + +****************** +Running on Proxmox +****************** + +Proxmox is an open-source platform for virtualization. Please visit +https://vyos.io to see how to get a qcow2 image that can be imported +into Proxmox. + +Deploy VyOS from CLI with qcow2 image +===================================== + +1. Copy the qcow2 image to a temporary directory on the Proxmox server. +2. The commands below assume that virtual machine ID 200 is unused and that the user wants the disk stored in a storage pool called `local-lvm`. + +.. code-block:: none + + $ qm create 200 --name vyos2 --memory 2048 --net0 virtio,bridge=vmbr0 + $ qm importdisk 200 /path/to/image/vyos-1.2.8-proxmox-2G.qcow2 local-lvm + $ qm set 200 --virtio0 local-lvm:vm-200-disk-0 + $ qm set 200 --boot order=virtio0 + +3. Optionally, the user can attach a CDROM with an ISO as a cloud-init data source. The below command assumes the ISO has been uploaded to the `local` storage pool with the name `seed.iso`. + +.. code-block:: none + + $ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso + +4. Start the virtual machine in the proxmox GUI or CLI using ``qm start 200``. + + + +Deploy VyOS from CLI with rolling release ISO +============================================= + +1. Download the rolling release iso from https://vyos.net/get/nightly-builds/. 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 https://github.com/vyos/vyos-build. +2. Prepare VM for installation from ISO media. The commands below assume that your iso is available in a storage pool 'local', that you want it to have a VM ID '200' and want to create a new disk on storage pool 'local-lvm' of size 15GB. + +.. code-block:: none + + qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15 + +3. Start the VM using the command ``qm start 200`` or using the start button located in the proxmox GUI. +4. Using the proxmox webGUI, open the virtual console for your newly created vm. Login username/password is ``vyos/vyos``. +5. Once booted into the live system, type ``install image`` into the command line and follow the prompts to install VyOS to the virtual drive. +6. After installation has completed, remove the installation iso using the GUI or ``qm set 200 --ide2 none``. +7. Reboot the virtual machine using the GUI or ``qm reboot 200``. + + + + + +Visit https://www.proxmox.com/en/ for more information about the download +and installation of this hypervisor. + diff --git a/docs/installation/virtual/rst-vmware.rst b/docs/installation/virtual/rst-vmware.rst new file mode 100644 index 00000000..a522dc78 --- /dev/null +++ b/docs/installation/virtual/rst-vmware.rst @@ -0,0 +1,46 @@ +.. _vyosonvmware: + +Running on VMware ESXi +###################### + +ESXi 5.5 or later +***************** + +.ova files are available for supporting users, and a VyOS can also be stood up +using a generic Linux instance, and attaching the bootable ISO file and +installing from the ISO using the normal process around `install image`. + +.. NOTE:: There have been previous documented issues with GRE/IPSEC tunneling + using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been + advised. + +Memory Contention Considerations +-------------------------------- +When the underlying ESXi host is approaching ~92% memory utilisation it will +start the balloon process in a 'soft' state to start reclaiming memory from +guest operating systems. This causes an artificial pressure using the vmmemctl +driver on memory usage on the virtual guest. As VyOS by default does not have +a swap file, this vmmemctl pressure is unable to force processes to move in +memory data to the paging file, and blindly consumes memory forcing the +virtual guest into a low memory state with no way to escape. The balloon +can expand to 65% of guest allocated memory, so a VyOS guest running >35% of +memory usage, can encounter an out of memory situation, and trigger the kernel +oom_kill process. At this point a weighted lottery favouring memory hungry +processes will be run with the unlucky winner being terminated by the kernel. + +It is advised that VyOS routers are configured in a resource group with +adequate memory reservations so that ballooning is not inflicted on +virtual VyOS guests. + + + + + +References +---------- + +.. stop_vyoslinter + +https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html + +.. start_vyoslinter \ No newline at end of file diff --git a/docs/installation/virtual/vmware.md b/docs/installation/virtual/vmware.md new file mode 100644 index 00000000..0338067c --- /dev/null +++ b/docs/installation/virtual/vmware.md @@ -0,0 +1,39 @@ +(vyosonvmware)= + +# Running on VMware ESXi + +## ESXi 5.5 or later + +.ova files are available for supporting users, and a VyOS can also be stood up +using a generic Linux instance, and attaching the bootable ISO file and +installing from the ISO using the normal process around `install image`. + +:::{NOTE} +There have been previous documented issues with GRE/IPSEC tunneling +using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been +advised. +::: + +### Memory Contention Considerations + +When the underlying ESXi host is approaching ~92% memory utilisation it will +start the balloon process in a 'soft' state to start reclaiming memory from +guest operating systems. This causes an artificial pressure using the vmmemctl +driver on memory usage on the virtual guest. As VyOS by default does not have +a swap file, this vmmemctl pressure is unable to force processes to move in +memory data to the paging file, and blindly consumes memory forcing the +virtual guest into a low memory state with no way to escape. The balloon +can expand to 65% of guest allocated memory, so a VyOS guest running >35% of +memory usage, can encounter an out of memory situation, and trigger the kernel +oom_kill process. At this point a weighted lottery favouring memory hungry +processes will be run with the unlucky winner being terminated by the kernel. + +It is advised that VyOS routers are configured in a resource group with +adequate memory reservations so that ballooning is not inflicted on +virtual VyOS guests. + +### References + + + + diff --git a/docs/installation/virtual/vmware.rst b/docs/installation/virtual/vmware.rst deleted file mode 100644 index a522dc78..00000000 --- a/docs/installation/virtual/vmware.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _vyosonvmware: - -Running on VMware ESXi -###################### - -ESXi 5.5 or later -***************** - -.ova files are available for supporting users, and a VyOS can also be stood up -using a generic Linux instance, and attaching the bootable ISO file and -installing from the ISO using the normal process around `install image`. - -.. NOTE:: There have been previous documented issues with GRE/IPSEC tunneling - using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been - advised. - -Memory Contention Considerations --------------------------------- -When the underlying ESXi host is approaching ~92% memory utilisation it will -start the balloon process in a 'soft' state to start reclaiming memory from -guest operating systems. This causes an artificial pressure using the vmmemctl -driver on memory usage on the virtual guest. As VyOS by default does not have -a swap file, this vmmemctl pressure is unable to force processes to move in -memory data to the paging file, and blindly consumes memory forcing the -virtual guest into a low memory state with no way to escape. The balloon -can expand to 65% of guest allocated memory, so a VyOS guest running >35% of -memory usage, can encounter an out of memory situation, and trigger the kernel -oom_kill process. At this point a weighted lottery favouring memory hungry -processes will be run with the unlucky winner being terminated by the kernel. - -It is advised that VyOS routers are configured in a resource group with -adequate memory reservations so that ballooning is not inflicted on -virtual VyOS guests. - - - - - -References ----------- - -.. stop_vyoslinter - -https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html - -.. start_vyoslinter \ No newline at end of file diff --git a/docs/installation/vyos-on-baremetal.md b/docs/installation/vyos-on-baremetal.md new file mode 100644 index 00000000..b551a811 --- /dev/null +++ b/docs/installation/vyos-on-baremetal.md @@ -0,0 +1,626 @@ +(vyosonbaremetal)= + +# Running on Bare Metal + +## Supermicro A2SDi (Atom C3000) + +I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. +Running VyOS on an UEFI only device is supported as of VyOS release 1.2. + +### Supermicro Shopping Cart + +- 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) +- 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) +- 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN + with Intel C3000 SoC 1GbE) +- 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) +- 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) +- 1x Supermicro MCP-320-81302-0B (optional FAN tray) + +### Optional (10GE) + +If you want to get additional ethernet ports or even 10GE connectivity +the following optional parts will be required: + +- 1x Supermicro RSC-RR1U-E8 (Riser Card) +- 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) + +Latest VyOS rolling releases boot without any problem on this board. You also +receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no +information about [OpenBMC](https://www.openbmc.org/) so far on this +motherboard). + +### Pictures + +:::{figure} /_static/images/1u_vyos_back.jpg +:alt: CSE-505-203B Back +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front.jpg +:alt: CSE-505-203B Front +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_open_1.jpg +:alt: CSE-505-203B Open 1 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_open_2.jpg +:alt: CSE-505-203B Open 2 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_open_3.jpg +:alt: CSE-505-203B Open 3 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_1.jpg +:alt: CSE-505-203B w/ 10GE Open 1 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_2.jpg +:alt: CSE-505-203B w/ 10GE Open 2 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_3.jpg +:alt: CSE-505-203B w/ 10GE Open 3 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_4.jpg +:alt: CSE-505-203B w/ 10GE Open +:scale: 25 % +::: + +(pc-engines-apu4)= + +## PC Engines APU4 + +As this platform seems to be quite common in terms of noise, cost, power and +performance it makes sense to write a small installation manual. + +This guide was developed using an APU4C4 board with the following specs: + +- AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI + support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. +- 4 GB DDR3-1333 DRAM, with optional ECC support +- About 6 to 10W of 12V DC power depending on CPU load +- 2 miniPCI express (one with SIM socket for 3G modem). +- 4 Gigabit Ethernet channels using Intel i211AT NICs + +The board can be powered via 12V from the front or via a 5V onboard connector. + +(vyos-on-baremetal-apu4-shopping)= + +### APU4 Shopping Cart + +- 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM +- 1x Kingston SUV500MS/120G +- 1x VARIA Group Item 326745 19" dual rack for APU4 + +The 19" enclosure can accommodate up to two APU4 boards - there is a single and +dual front cover. + +#### Extension Modules + +##### WiFi + +Refer to {ref}`wireless-interface` for additional information, below listed +modules have been tested successfully on this Hardware platform: + +- Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. +- Intel Corporation AX200 mini-PCIe WiFi module, only supported in mPCIe slot 1. + (see {ref}`wireless-interface-intel-ax200`) + +##### WWAN + +Refer to {ref}`wwan-interface` for additional information, below listed modules +have been tested successfully on this Hardware platform using VyOS 1.3 +(equuleus): + +- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +- Huawei ME909u-521 miniPCIe card (LTE) + +### VyOS 1.4 (sagitta) + +Depending on the VyOS versions you intend to install there is a difference in +the serial port settings ({vytask}`T1327`). + +Create a bootable USB pendrive using e.g. [Rufus] on a Windows machine. + +Connect serial port to a PC through null modem cable (RXD / TXD crossed over). +Set terminal emulator to 115200 8N1. + + +```none +PC Engines apu4 +coreboot build 20171130 +BIOS version v4.6.4 +4080 MB ECC DRAM +SeaBIOS (version rel-1.11.0.1-0-g90da88d) + +Press F10 key now for boot menu: + +Select boot device: + +1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) +2. USB MSC Drive Generic Flash Disk 8.07 +3. Payload [memtest] +4. Payload [setup] +``` + + +Now boot from the `USB MSC Drive Generic Flash Disk 8.07` media by pressing +`2`, the VyOS boot menu will appear, just wait 10 seconds or press `Enter` +to continue. + +```none +lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk +x VyOS - Boot Menu x +tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu +x Live system (amd64-vyos) x +x Live system (amd64-vyos fail-safe mode) x +x Live system (amd64-vyos) - Serial console x +x x +mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj +``` + +The image will be loaded and the last lines you will get will be: + +```none +Loading /live/vmlinuz... ok +Loading /live/initrd.img... +... +Welcome to VyOS - vyos ttyS0 + +vyos login: +``` + +You can now proceed with a regular image installation as described in +{ref}`installation`. + +(vyos-on-baremetal-apu4-pictures)= + +### Pictures + +:::{note} +Both device types operate without any moving parts and emit zero +noise. +::: + +#### Rack Mount + +:::{figure} /_static/images/apu4_rack_1.jpg +:alt: APU4 rack closed +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_2.jpg +:alt: APU4 rack front +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_3.jpg +:alt: 'APU4 rack module #1' +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_4.jpg +:alt: 'APU4 rack module #2' +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_5.jpg +:alt: 'APU4 rack module #3 with PSU' +:scale: 25 % +::: + +##### VyOS custom print + +:::{figure} /_static/images/apu4_rack_vyos_print.jpg +:alt: APU4 custom VyOS powder coat +:scale: 25 % +::: + +#### Desktop / Bench Top + +:::{figure} /_static/images/apu4_desk_1.jpg +:alt: APU4 desktop closed +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_desk_2.jpg +:alt: APU4 desktop closed +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_desk_3.jpg +:alt: APU4 desktop back +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_desk_4.jpg +:alt: APU4 desktop back +:scale: 25 % +::: + +## Qotom Q355G4 + +The install on this Q355G4 box is pretty much plug and play. The port numbering +the OS does might differ from the labels on the outside, but the UEFI firmware +has a port blink test built in with MAC addresses so you can very quickly +identify which is which. MAC labels are on the inside as well, and this test +can be done from VyOS or plain Linux too. Default settings in the UEFI will +make it boot, but depending on your installation wishes (i.e. storage type, +boot type, console type) you might want to adjust them. This Qotom company +seems to be the real OEM/ODM for many other relabelling companies like +Protectli. + +### Hardware + +There are a number of other options, but they all seem to be close to Intel +reference designs, with added features like more serial ports, more network +interfaces and the likes. Because they don't deviate too much from standard +designs all the hardware is well-supported by mainline. It accepts one LPDDR3 +SO-DIMM, but chances are that if you need more than that, you'll also want +something even beefier than an i5. There are options for antenna holes, and SIM +slots, so you could in theory add an LTE/Cell modem (not tested so far). + +The chassis is a U-shaped alu extrusion with removable I/O plates and removable +bottom plate. Cooling is completely passive with a heatsink on the SoC with +internal and external fins, a flat interface surface, thermal pad on top of +that, which then directly attaches to the chassis, which has fins as well. It +comes with mounting hardware and rubber feet, so you could place it like a +desktop model or mount it on a VESA mount, or even wall mount it with the +provided mounting plate. The closing plate doubles as internal 2.5" mounting +place for an HDD or SSD, and comes supplied with a small SATA cable and SATA +power cable. + +Power supply is a 12VDC barrel jack, and included switching power supply, which +is why SATA power regulation is on-board. Internally it has a NUC-board-style +on-board 12V input header as well, the molex locking style. + +There are WDT options and auto-boot on power enable, which is great for remote +setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled +in enforcement mode, which is good but also means no coreboot option), yet has +most options available to configure (so it's not locked out like most firmwares +are). + +An external RS232 serial port is available, internally a GPIO header as well. +It does have Realtek based audio on board for some reason, but you can disable +that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS +mode and HDMI BIOS mode depends on what is connected at startup; it goes into +serial mode if you disconnect HDMI and plug in serial, in all other cases it's +HDMI mode. + +## Partaker i5 + +:::{figure} ../_static/images/600px-Partaker-i5.jpg +::: + +I believe this is actually the same hardware as the Protectli. I purchased it +in June 2018. It came pre-loaded with pfSense. + +[Manufacturer product page](http://www.inctel.com.cn/product/detail/338.html). + +### Installation + +- Write VyOS ISO to USB drive of some sort +- Plug in VGA, power, USB keyboard, and USB drive +- Press "SW" button on the front (this is the power button; I don't know what + "SW" is supposed to mean). +- Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, + but with a few tries you should be able to get into the BIOS. +- Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 + (EHCI) to Enabled. Without doing this, the USB drive won't boot. +- Boot to the VyOS installer and install as usual. + +Warning the interface labels on my device are backwards; the left-most "LAN4" +port is eth0 and the right-most "LAN1" port is eth3. + +## Acrosser AND-J190N1 + +:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg +::: + +:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg +::: + +This microbox network appliance was build to create OpenVPN bridges. It can +saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN + +You may have to add your own RAM and HDD/SSD. There is no VGA connector. But +Acrosser provides a DB25 adapter for the VGA header on the motherboard (not +used). + +### BIOS Settings: + +First thing you want to do is getting a more user friendly console to configure +BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. + +For practical issues change speed from 115200 to 9600. 9600 is the default +speed at which both linux kernel and VyOS will reconfigure the serial port +when loading. + +Connect to serial (115200bps). Power on the appliance and press Del in the +console when requested to enter BIOS settings. + +Advanced > Serial Port Console Redirection > Console Redirection Settings: + +- Terminal Type : VT100+ +- Bits per second : 9600 + +Save, reboot and change serial speed to 9600 on your client. + +Some options have to be changed for VyOS to boot correctly. With XHCI enabled +the installer can’t access the USB key. Enable EHCI instead. + +Reboot into BIOS, Chipset > South Bridge > USB Configuration: + +- Disable XHCI +- Enable USB 2.0 (EHCI) Support + +Perform Image installation using `install image` CLI command. + +(gowin-gw-fn-1ur1-10g)= + +## Gowin GW-FN-1UR1-10G + +A platform utilizing an Intel Alder Lake-N100 CPU with 6M cache, TDP 6W. +Onboard LPDDR5 16GB RAM and 128GB eMMC (can be used for image installation). + +The appliance comes with 2 * 2.5GbE Intel I226-V and 3 * 1GbE Intel I210 +where one supports IEEE802.3at PoE+ (Typical 30W). + +In addition there is a Mellanox ConnectX-3 2\* 10GbE SFP+ NIC available. + +**NOTE:** This is the entry level platform. Other derivates exists with +i3-N305 CPU and 2x 25GbE! + +### Gowin Shopping Cart + +- 1x Gowin GW-FN-1UR1-10G +- 2x 128GB M.2 NVMe SSDs + +### Optional (WiFi + WWAN) + +- 1x MediaTek 7921E M.2 NGFF WIFI module (not tested as this currently leads to + a Kernel crash) +- 1x HP LT4120 Snapdragon X5 LTE WWAN module + +### Pictures + +:::{figure} ../_static/images/gowin-01.png +::: + +:::{figure} ../_static/images/gowin-02.png +::: + +:::{figure} ../_static/images/gowin-03.png +::: + +:::{figure} ../_static/images/gowin-04.png +::: + +### Cooling + +The device itself is passivly cooled, whereas the power supply has an active fan. +Even if the main processor is powered off, the power supply fan is operating and +the entire chassis draws 7.5W. During operation the chassis drew arround 38W. + +### BIOS Settings + +No settings needed to be altered, everything worked out of the box! + +### Installation + +The system provides a regular RS232 console port using 115200,8n1 setting which +is sufficient to install VyOS from a USB pendrive. + +### First Boot + +Please note that there is a weirdness on the network interface mapping. +The interface \<-> MAC mapping is going upwards but the NICs are placed +somehow swapped on the mainboard/MACs programmed in a swapped order. + +See interface description for more detailed mapping. + +```none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address MAC VRF MTU S/L Description +----------- -------------- ----------------- ------- ----- ----- ------------- +eth0 - 00:f0:cb:00:00:99 default 1500 u/D Intel I226-V - Front eth2 +eth1 - 00:f0:cb:00:00:9a default 1500 u/D Intel I226-V - Front eth1 +eth2 - 00:f0:cb:00:00:9b default 1500 u/D Intel I210 - Front eth4 +eth3 - 00:f0:cb:00:00:9c default 1500 u/D Intel I210 - Front eth3 +eth4 - 00:f0:cb:00:00:9d default 1500 u/D Intel I210 - Front POE +eth5 - 00:02:c9:00:00:30 default 1500 u/D Mellanox ConnectX-3 - SFP2 +eth6 - 00:02:c9:00:00:31 default 1500 u/D Mellanox ConnectX-3 - SFP1 +lo 127.0.0.1/8 00:00:00:00:00:00 default 65536 u/u + ::1/128 +wwan0 - d2:39:76:8e:05:12 default 1500 A/D +``` + +#### VyOS 1.4 (sagitta) + +Connect serial port to a PC through a USB \<-> RJ45 console cable. Set terminal +emulator to 115200 8N1. You can also perform the installation using VGA or HDMI +ports. + +In this example I choose to install VyOS as RAID-1 on both NVMe drives. However, +a previous installation on the 128GB eMMC storage worked without any issues, +too. + +```none +Welcome to VyOS - vyos ttyS0 + +vyos login: +``` + +Perform Image installation using `install image` CLI command. This installation +uses two 128GB NVMe disks setup as RAID1. + +```none +Welcome to VyOS! + + ┌── ┐ + . VyOS 1.4.0 + └ ──┘ sagitta + +* Support portal: https://support.vyos.io +* Documentation: https://docs.vyos.io/en/sagitta +* Project news: https://blog.vyos.io +* Bug reports: https://vyos.dev + +You can change this banner using "set system login banner post-login" command. + +VyOS is a free software distribution that includes multiple components, +you can check individual component licenses under /usr/share/doc/*/copyright +Use of this pre-built image is governed by the EULA you can find in +/usr/share/vyos/EULA + +vyos@vyos:~$ install image + +Welcome to VyOS installation! +This command will install VyOS to your permanent storage. +Would you like to continue? [y/N] y + +What would you like to name this image? (Default: 1.4.0) + +Please enter a password for the "vyos" user: +Please confirm password for the "vyos" user: + +What console should be used by default? (K: KVM, S: Serial)? (Default: S) + +Probing disks +4 disk(s) found +Would you like to configure RAID-1 mirroring? [Y/n] y + +The following disks were found: + /dev/sda (14.4 GB) + /dev/mmcblk0 (116.5 GB) +Would you like to configure RAID-1 mirroring on them? [Y/n] n + +Would you like to choose two disks for RAID-1 mirroring? [Y/n] y +Disks available: + 1: /dev/sda (14.4 GB) + 2: /dev/mmcblk0 (116.5 GB) + 3: /dev/nvme1n1 (119.2 GB) + 4: /dev/nvme0n1 (119.2 GB) +Select first disk: 3 + +Remaining disks: + 1: /dev/sda (14.4 GB) + 2: /dev/mmcblk0 (116.5 GB) + 3: /dev/nvme0n1 (119.2 GB) +Select second disk: 3 + +Installation will delete all data on both drives. Continue? [y/N] y + +Searching for data from previous installations +No previous installation found +Creating partitions on /dev/nvme1n1 +Creating partition table... +Creating partitions on /dev/nvme0n1 +Creating partition table... +Creating RAID array +Updating initramfs +Creating filesystem on RAID array +The following config files are available for boot: + 1: /opt/vyatta/etc/config/config.boot + 2: /opt/vyatta/etc/config.boot.default + +Which file would you like as boot config? (Default: 1) +Creating temporary directories +Mounting new partitions +Creating a configuration file +Copying system image files +Installing GRUB configuration files +Installing GRUB to the drives +Cleaning up +Unmounting target filesystems +Removing temporary files +The image installed successfully; please reboot now. +``` + +### Hardware + +```none +vyos@vyos:~$ lspci +00:00.0 Host bridge: Intel Corporation Device 461c +00:02.0 VGA compatible controller: Intel Corporation Alder Lake-N [UHD Graphics] +00:0a.0 Signal processing controller: Intel Corporation Platform Monitoring Technology (rev 01) +00:0d.0 USB controller: Intel Corporation Device 464e +00:14.0 USB controller: Intel Corporation Device 54ed +00:14.2 RAM memory: Intel Corporation Device 54ef +00:15.0 Serial bus controller: Intel Corporation Device 54e8 +00:16.0 Communication controller: Intel Corporation Device 54e0 +00:1a.0 SD Host controller: Intel Corporation Device 54c4 +00:1c.0 PCI bridge: Intel Corporation Device 54b8 +00:1c.2 PCI bridge: Intel Corporation Device 54ba +00:1c.3 PCI bridge: Intel Corporation Device 54bb +00:1c.6 PCI bridge: Intel Corporation Device 54be +00:1d.0 PCI bridge: Intel Corporation Device 54b0 +00:1f.0 ISA bridge: Intel Corporation Device 5481 +00:1f.4 SMBus: Intel Corporation Device 54a3 +00:1f.5 Serial bus controller: Intel Corporation Device 54a4 +01:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +03:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) +04:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) +05:00.0 Network controller: MEDIATEK Corp. MT7922 802.11ax PCI Express Wireless Network Adapter +06:00.0 SATA controller: ASMedia Technology Inc. Device 0622 (rev 01) +07:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +09:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0a:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0b:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0d:00.0 Non-Volatile memory controller: Device 1ed0:2283 +0f:00.0 Non-Volatile memory controller: Device 1ed0:2283 +11:00.0 Ethernet controller: Mellanox Technologies MT27500 Family [ConnectX-3] +``` + +```none +vyos@vyos:~$ lsusb +Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub +Bus 003 Device 005: ID 0e8d:c616 MediaTek Inc. Wireless_Device +Bus 003 Device 003: ID 413c:2113 Dell Computer Corp. KB216 Wired Keyboard +Bus 003 Device 004: ID 03f0:9d1d HP, Inc HP lt4120 Snapdragon X5 LTE +Bus 003 Device 002: ID 05e3:0610 Genesys Logic, Inc. Hub +Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub +Bus 002 Device 002: ID 05e3:0620 Genesys Logic, Inc. GL3523 Hub +Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub +Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub +``` + +#### WWAN + +The LTE module can be enabled as simple as this config snippet: + +```none +interfaces { + wwan wwan0 { + address "dhcp" + apn "YOUR-APN-GOES-HERE" + } +} +``` + +For more information please refer to chapter: {ref}`wwan-interface` + +[rufus]: https://rufus.ie/ diff --git a/docs/installation/vyos-on-baremetal.rst b/docs/installation/vyos-on-baremetal.rst deleted file mode 100644 index 783fdf85..00000000 --- a/docs/installation/vyos-on-baremetal.rst +++ /dev/null @@ -1,632 +0,0 @@ -.. _vyosonbaremetal: - -##################### -Running on Bare Metal -##################### - -Supermicro A2SDi (Atom C3000) -============================= - -I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. -Running VyOS on an UEFI only device is supported as of VyOS release 1.2. - -Supermicro Shopping Cart ------------------------- - -* 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) -* 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) -* 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN - with Intel C3000 SoC 1GbE) -* 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) -* 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) -* 1x Supermicro MCP-320-81302-0B (optional FAN tray) - -Optional (10GE) ---------------- -If you want to get additional ethernet ports or even 10GE connectivity -the following optional parts will be required: - -* 1x Supermicro RSC-RR1U-E8 (Riser Card) -* 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) - -Latest VyOS rolling releases boot without any problem on this board. You also -receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no -information about `OpenBMC `_ so far on this -motherboard). - -Pictures --------- - -.. figure:: /_static/images/1u_vyos_back.jpg - :scale: 25 % - :alt: CSE-505-203B Back - -.. figure:: /_static/images/1u_vyos_front.jpg - :scale: 25 % - :alt: CSE-505-203B Front - -.. figure:: /_static/images/1u_vyos_front_open_1.jpg - :scale: 25 % - :alt: CSE-505-203B Open 1 - -.. figure:: /_static/images/1u_vyos_front_open_2.jpg - :scale: 25 % - :alt: CSE-505-203B Open 2 - -.. figure:: /_static/images/1u_vyos_front_open_3.jpg - :scale: 25 % - :alt: CSE-505-203B Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_1.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 1 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_2.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 2 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_3.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_4.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open - - -.. _pc-engines-apu4: - -PC Engines APU4 -================ - -As this platform seems to be quite common in terms of noise, cost, power and -performance it makes sense to write a small installation manual. - -This guide was developed using an APU4C4 board with the following specs: - -* AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI - support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. -* 4 GB DDR3-1333 DRAM, with optional ECC support -* About 6 to 10W of 12V DC power depending on CPU load -* 2 miniPCI express (one with SIM socket for 3G modem). -* 4 Gigabit Ethernet channels using Intel i211AT NICs - -The board can be powered via 12V from the front or via a 5V onboard connector. - -.. _vyos-on-baremetal:apu4_shopping: - -APU4 Shopping Cart ------------------- - -* 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM -* 1x Kingston SUV500MS/120G -* 1x VARIA Group Item 326745 19" dual rack for APU4 - -The 19" enclosure can accommodate up to two APU4 boards - there is a single and -dual front cover. - -Extension Modules -^^^^^^^^^^^^^^^^^ - -WiFi -"""" - -Refer to :ref:`wireless-interface` for additional information, below listed -modules have been tested successfully on this Hardware platform: - -* Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. -* Intel Corporation AX200 mini-PCIe WiFi module, only supported in mPCIe slot 1. - (see :ref:`wireless-interface-intel-ax200`) - -WWAN -"""" - -Refer to :ref:`wwan-interface` for additional information, below listed modules -have been tested successfully on this Hardware platform using VyOS 1.3 -(equuleus): - -* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) -* Huawei ME909u-521 miniPCIe card (LTE) - -VyOS 1.4 (sagitta) ---------------- - -Depending on the VyOS versions you intend to install there is a difference in -the serial port settings (:vytask:`T1327`). - -Create a bootable USB pendrive using e.g. Rufus_ on a Windows machine. - -Connect serial port to a PC through null modem cable (RXD / TXD crossed over). -Set terminal emulator to 115200 8N1. - -.. stop_vyoslinter -.. code-block:: none - - PC Engines apu4 - coreboot build 20171130 - BIOS version v4.6.4 - 4080 MB ECC DRAM - SeaBIOS (version rel-1.11.0.1-0-g90da88d) - - Press F10 key now for boot menu: - - Select boot device: - - 1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) - 2. USB MSC Drive Generic Flash Disk 8.07 - 3. Payload [memtest] - 4. Payload [setup] - -.. start_vyoslinter - -Now boot from the ``USB MSC Drive Generic Flash Disk 8.07`` media by pressing -``2``, the VyOS boot menu will appear, just wait 10 seconds or press ``Enter`` -to continue. - -.. code-block:: none - - lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk - x VyOS - Boot Menu x - tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu - x Live system (amd64-vyos) x - x Live system (amd64-vyos fail-safe mode) x - x Live system (amd64-vyos) - Serial console x - x x - mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj - -The image will be loaded and the last lines you will get will be: - -.. code-block:: none - - Loading /live/vmlinuz... ok - Loading /live/initrd.img... - ... - Welcome to VyOS - vyos ttyS0 - - vyos login: - -You can now proceed with a regular image installation as described in -:ref:`installation`. - -.. _vyos-on-baremetal:apu4_pictures: - -Pictures --------- - -.. note:: Both device types operate without any moving parts and emit zero - noise. - -Rack Mount -^^^^^^^^^^ - -.. figure:: /_static/images/apu4_rack_1.jpg - :scale: 25 % - :alt: APU4 rack closed - -.. figure:: /_static/images/apu4_rack_2.jpg - :scale: 25 % - :alt: APU4 rack front - -.. figure:: /_static/images/apu4_rack_3.jpg - :scale: 25 % - :alt: APU4 rack module #1 - -.. figure:: /_static/images/apu4_rack_4.jpg - :scale: 25 % - :alt: APU4 rack module #2 - -.. figure:: /_static/images/apu4_rack_5.jpg - :scale: 25 % - :alt: APU4 rack module #3 with PSU - -VyOS custom print -""""""""""""""""" - -.. figure:: /_static/images/apu4_rack_vyos_print.jpg - :scale: 25 % - :alt: APU4 custom VyOS powder coat - -Desktop / Bench Top -^^^^^^^^^^^^^^^^^^^ - -.. figure:: /_static/images/apu4_desk_1.jpg - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_2.jpg - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_3.jpg - :scale: 25 % - :alt: APU4 desktop back - -.. figure:: /_static/images/apu4_desk_4.jpg - :scale: 25 % - :alt: APU4 desktop back - -.. _Rufus: https://rufus.ie/ - -Qotom Q355G4 -============ - -The install on this Q355G4 box is pretty much plug and play. The port numbering -the OS does might differ from the labels on the outside, but the UEFI firmware -has a port blink test built in with MAC addresses so you can very quickly -identify which is which. MAC labels are on the inside as well, and this test -can be done from VyOS or plain Linux too. Default settings in the UEFI will -make it boot, but depending on your installation wishes (i.e. storage type, -boot type, console type) you might want to adjust them. This Qotom company -seems to be the real OEM/ODM for many other relabelling companies like -Protectli. - -Hardware --------- - -There are a number of other options, but they all seem to be close to Intel -reference designs, with added features like more serial ports, more network -interfaces and the likes. Because they don't deviate too much from standard -designs all the hardware is well-supported by mainline. It accepts one LPDDR3 -SO-DIMM, but chances are that if you need more than that, you'll also want -something even beefier than an i5. There are options for antenna holes, and SIM -slots, so you could in theory add an LTE/Cell modem (not tested so far). - -The chassis is a U-shaped alu extrusion with removable I/O plates and removable -bottom plate. Cooling is completely passive with a heatsink on the SoC with -internal and external fins, a flat interface surface, thermal pad on top of -that, which then directly attaches to the chassis, which has fins as well. It -comes with mounting hardware and rubber feet, so you could place it like a -desktop model or mount it on a VESA mount, or even wall mount it with the -provided mounting plate. The closing plate doubles as internal 2.5" mounting -place for an HDD or SSD, and comes supplied with a small SATA cable and SATA -power cable. - -Power supply is a 12VDC barrel jack, and included switching power supply, which -is why SATA power regulation is on-board. Internally it has a NUC-board-style -on-board 12V input header as well, the molex locking style. - -There are WDT options and auto-boot on power enable, which is great for remote -setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled -in enforcement mode, which is good but also means no coreboot option), yet has -most options available to configure (so it's not locked out like most firmwares -are). - -An external RS232 serial port is available, internally a GPIO header as well. -It does have Realtek based audio on board for some reason, but you can disable -that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS -mode and HDMI BIOS mode depends on what is connected at startup; it goes into -serial mode if you disconnect HDMI and plug in serial, in all other cases it's -HDMI mode. - -Partaker i5 -=========== - -.. figure:: ../_static/images/600px-Partaker-i5.jpg - -I believe this is actually the same hardware as the Protectli. I purchased it -in June 2018. It came pre-loaded with pfSense. - -`Manufacturer product page `_. - -Installation ------------- - -* Write VyOS ISO to USB drive of some sort -* Plug in VGA, power, USB keyboard, and USB drive -* Press "SW" button on the front (this is the power button; I don't know what - "SW" is supposed to mean). -* Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, - but with a few tries you should be able to get into the BIOS. -* Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 - (EHCI) to Enabled. Without doing this, the USB drive won't boot. -* Boot to the VyOS installer and install as usual. - -Warning the interface labels on my device are backwards; the left-most "LAN4" -port is eth0 and the right-most "LAN1" port is eth3. - -Acrosser AND-J190N1 -=================== - -.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg - -.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg - -This microbox network appliance was build to create OpenVPN bridges. It can -saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN - -You may have to add your own RAM and HDD/SSD. There is no VGA connector. But -Acrosser provides a DB25 adapter for the VGA header on the motherboard (not -used). - -BIOS Settings: --------------- - -First thing you want to do is getting a more user friendly console to configure -BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. - -For practical issues change speed from 115200 to 9600. 9600 is the default -speed at which both linux kernel and VyOS will reconfigure the serial port -when loading. - -Connect to serial (115200bps). Power on the appliance and press Del in the -console when requested to enter BIOS settings. - -Advanced > Serial Port Console Redirection > Console Redirection Settings: - -* Terminal Type : VT100+ -* Bits per second : 9600 - -Save, reboot and change serial speed to 9600 on your client. - -Some options have to be changed for VyOS to boot correctly. With XHCI enabled -the installer can’t access the USB key. Enable EHCI instead. - -Reboot into BIOS, Chipset > South Bridge > USB Configuration: - -* Disable XHCI -* Enable USB 2.0 (EHCI) Support - -Perform Image installation using `install image` CLI command. - -.. _gowin_gw-fn-1ur1-10g: - -Gowin GW-FN-1UR1-10G -==================== - -A platform utilizing an Intel Alder Lake-N100 CPU with 6M cache, TDP 6W. -Onboard LPDDR5 16GB RAM and 128GB eMMC (can be used for image installation). - -The appliance comes with 2 * 2.5GbE Intel I226-V and 3 * 1GbE Intel I210 -where one supports IEEE802.3at PoE+ (Typical 30W). - -In addition there is a Mellanox ConnectX-3 2* 10GbE SFP+ NIC available. - -**NOTE:** This is the entry level platform. Other derivates exists with -i3-N305 CPU and 2x 25GbE! - -Gowin Shopping Cart -------------------- - -* 1x Gowin GW-FN-1UR1-10G -* 2x 128GB M.2 NVMe SSDs - -Optional (WiFi + WWAN) ----------------------- - -* 1x MediaTek 7921E M.2 NGFF WIFI module (not tested as this currently leads to - a Kernel crash) -* 1x HP LT4120 Snapdragon X5 LTE WWAN module - -Pictures --------- - -.. figure:: ../_static/images/gowin-01.png - -.. figure:: ../_static/images/gowin-02.png - -.. figure:: ../_static/images/gowin-03.png - -.. figure:: ../_static/images/gowin-04.png - -Cooling -------- - -The device itself is passivly cooled, whereas the power supply has an active fan. -Even if the main processor is powered off, the power supply fan is operating and -the entire chassis draws 7.5W. During operation the chassis drew arround 38W. - -BIOS Settings -------------- - -No settings needed to be altered, everything worked out of the box! - -Installation ------------- - -The system provides a regular RS232 console port using 115200,8n1 setting which -is sufficient to install VyOS from a USB pendrive. - -First Boot ----------- - -Please note that there is a weirdness on the network interface mapping. -The interface <-> MAC mapping is going upwards but the NICs are placed -somehow swapped on the mainboard/MACs programmed in a swapped order. - -See interface description for more detailed mapping. - -.. code-block:: none - - vyos@vyos:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address MAC VRF MTU S/L Description - ----------- -------------- ----------------- ------- ----- ----- ------------- - eth0 - 00:f0:cb:00:00:99 default 1500 u/D Intel I226-V - Front eth2 - eth1 - 00:f0:cb:00:00:9a default 1500 u/D Intel I226-V - Front eth1 - eth2 - 00:f0:cb:00:00:9b default 1500 u/D Intel I210 - Front eth4 - eth3 - 00:f0:cb:00:00:9c default 1500 u/D Intel I210 - Front eth3 - eth4 - 00:f0:cb:00:00:9d default 1500 u/D Intel I210 - Front POE - eth5 - 00:02:c9:00:00:30 default 1500 u/D Mellanox ConnectX-3 - SFP2 - eth6 - 00:02:c9:00:00:31 default 1500 u/D Mellanox ConnectX-3 - SFP1 - lo 127.0.0.1/8 00:00:00:00:00:00 default 65536 u/u - ::1/128 - wwan0 - d2:39:76:8e:05:12 default 1500 A/D - -VyOS 1.4 (sagitta) -^^^^^^^^^^^^^^^^^^ - -Connect serial port to a PC through a USB <-> RJ45 console cable. Set terminal -emulator to 115200 8N1. You can also perform the installation using VGA or HDMI -ports. - -In this example I choose to install VyOS as RAID-1 on both NVMe drives. However, -a previous installation on the 128GB eMMC storage worked without any issues, -too. - -.. code-block:: none - - Welcome to VyOS - vyos ttyS0 - - vyos login: - -Perform Image installation using `install image` CLI command. This installation -uses two 128GB NVMe disks setup as RAID1. - -.. code-block:: none - - Welcome to VyOS! - - ┌── ┐ - . VyOS 1.4.0 - └ ──┘ sagitta - - * Support portal: https://support.vyos.io - * Documentation: https://docs.vyos.io/en/sagitta - * Project news: https://blog.vyos.io - * Bug reports: https://vyos.dev - - You can change this banner using "set system login banner post-login" command. - - VyOS is a free software distribution that includes multiple components, - you can check individual component licenses under /usr/share/doc/*/copyright - Use of this pre-built image is governed by the EULA you can find in - /usr/share/vyos/EULA - - vyos@vyos:~$ install image - - Welcome to VyOS installation! - This command will install VyOS to your permanent storage. - Would you like to continue? [y/N] y - - What would you like to name this image? (Default: 1.4.0) - - Please enter a password for the "vyos" user: - Please confirm password for the "vyos" user: - - What console should be used by default? (K: KVM, S: Serial)? (Default: S) - - Probing disks - 4 disk(s) found - Would you like to configure RAID-1 mirroring? [Y/n] y - - The following disks were found: - /dev/sda (14.4 GB) - /dev/mmcblk0 (116.5 GB) - Would you like to configure RAID-1 mirroring on them? [Y/n] n - - Would you like to choose two disks for RAID-1 mirroring? [Y/n] y - Disks available: - 1: /dev/sda (14.4 GB) - 2: /dev/mmcblk0 (116.5 GB) - 3: /dev/nvme1n1 (119.2 GB) - 4: /dev/nvme0n1 (119.2 GB) - Select first disk: 3 - - Remaining disks: - 1: /dev/sda (14.4 GB) - 2: /dev/mmcblk0 (116.5 GB) - 3: /dev/nvme0n1 (119.2 GB) - Select second disk: 3 - - Installation will delete all data on both drives. Continue? [y/N] y - - Searching for data from previous installations - No previous installation found - Creating partitions on /dev/nvme1n1 - Creating partition table... - Creating partitions on /dev/nvme0n1 - Creating partition table... - Creating RAID array - Updating initramfs - Creating filesystem on RAID array - The following config files are available for boot: - 1: /opt/vyatta/etc/config/config.boot - 2: /opt/vyatta/etc/config.boot.default - - Which file would you like as boot config? (Default: 1) - Creating temporary directories - Mounting new partitions - Creating a configuration file - Copying system image files - Installing GRUB configuration files - Installing GRUB to the drives - Cleaning up - Unmounting target filesystems - Removing temporary files - The image installed successfully; please reboot now. - -Hardware --------- - -.. code-block:: none - - vyos@vyos:~$ lspci - 00:00.0 Host bridge: Intel Corporation Device 461c - 00:02.0 VGA compatible controller: Intel Corporation Alder Lake-N [UHD Graphics] - 00:0a.0 Signal processing controller: Intel Corporation Platform Monitoring Technology (rev 01) - 00:0d.0 USB controller: Intel Corporation Device 464e - 00:14.0 USB controller: Intel Corporation Device 54ed - 00:14.2 RAM memory: Intel Corporation Device 54ef - 00:15.0 Serial bus controller: Intel Corporation Device 54e8 - 00:16.0 Communication controller: Intel Corporation Device 54e0 - 00:1a.0 SD Host controller: Intel Corporation Device 54c4 - 00:1c.0 PCI bridge: Intel Corporation Device 54b8 - 00:1c.2 PCI bridge: Intel Corporation Device 54ba - 00:1c.3 PCI bridge: Intel Corporation Device 54bb - 00:1c.6 PCI bridge: Intel Corporation Device 54be - 00:1d.0 PCI bridge: Intel Corporation Device 54b0 - 00:1f.0 ISA bridge: Intel Corporation Device 5481 - 00:1f.4 SMBus: Intel Corporation Device 54a3 - 00:1f.5 Serial bus controller: Intel Corporation Device 54a4 - 01:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) - 02:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) - 02:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) - 02:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) - 02:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) - 03:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) - 04:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) - 05:00.0 Network controller: MEDIATEK Corp. MT7922 802.11ax PCI Express Wireless Network Adapter - 06:00.0 SATA controller: ASMedia Technology Inc. Device 0622 (rev 01) - 07:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) - 08:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) - 08:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) - 08:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) - 08:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) - 09:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) - 0a:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) - 0b:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) - 0d:00.0 Non-Volatile memory controller: Device 1ed0:2283 - 0f:00.0 Non-Volatile memory controller: Device 1ed0:2283 - 11:00.0 Ethernet controller: Mellanox Technologies MT27500 Family [ConnectX-3] - -.. code-block:: none - - vyos@vyos:~$ lsusb - Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub - Bus 003 Device 005: ID 0e8d:c616 MediaTek Inc. Wireless_Device - Bus 003 Device 003: ID 413c:2113 Dell Computer Corp. KB216 Wired Keyboard - Bus 003 Device 004: ID 03f0:9d1d HP, Inc HP lt4120 Snapdragon X5 LTE - Bus 003 Device 002: ID 05e3:0610 Genesys Logic, Inc. Hub - Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub - Bus 002 Device 002: ID 05e3:0620 Genesys Logic, Inc. GL3523 Hub - Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub - Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub - -WWAN -^^^^ - -The LTE module can be enabled as simple as this config snippet: - -.. code-block:: none - - interfaces { - wwan wwan0 { - address "dhcp" - apn "YOUR-APN-GOES-HERE" - } - } - -For more information please refer to chapter: :ref:`wwan-interface` -- cgit v1.2.3