feat: import MyST swap mechanism + content for sagitta (replaces #1886)

Replaces the broken #1886 with a fresh, properly-converted MyST set for
the sagitta (1.4.x) docs, mirroring what landed for circinus via #1897.

This PR:

- Re-imports 210 md-*.md files for sagitta. Source: ran the pipelines
  rst-to-myst converter (chrisjsewell/rst-to-myst v0.4.0, with pandoc
  fallback) on sagittas RST. Post-processed via the pipelines
  postprocess stage (10 ordered fixes for blanks, admonitions, label
  hyphens, pandoc artifacts, structural blanks, linter markers).
  Compared to the broken #1886 content (which was left over from an
  earlier stage-1-only run): zero raw `<div class=>` remnants.

- For 23 stems where sagittas RST is byte-identical with currents RST
  (mostly stable policy/protocol pages and the 404 page), reuses currents
  already-validated md-*.md content rather than re-converting.

- Drops cli and installation/cloud/aws from sagittas swap set: their
  RST has SEVERE/4 "Title level inconsistent" errors that crash
  rst-to-myst; they need an independent RST-source fix and are kept as
  RST-only for now.

- Adds the per-page swap mechanism: scripts/swap_sources.py,
  scripts/import_myst.py, the matching tests under tests/, _swap.txt
  with 210 stems, _ext/vyos.py MyST renderer fallback, Makefile
  swap-wrapped targets, .readthedocs.yml swap pre/post hooks.

- Adds 187 .webp images and removes 235 superseded .jpg/.png/.jpeg
  static assets; flips html_logo to vyos-logo.webp.

- Adds the MyST swap-related blocks to docs/conf.py only:
  myst_enable_extensions, myst_fence_as_directive, md-*.md exclude
  patterns, _swap_exclude.txt reader, _prefer_webp and _copy_md_sources
  setup hooks. github_version fallback set to 'sagitta' to match the
  branch (parallel to currents 'current' and circinuss 'circinus').

Deliberately excluded (per user direction):

- llms.txt and sphinx-llms-txt / sphinx-sitemap config: these will
  land separately for sagitta via #1870 plus a new sagitta-specific
  llms.txt template PR. The conf.py here does not pull those extensions
  in, so the build does not depend on the new pip packages.

Verification before pushing:

- 210 md-*.md = 210 _swap.txt stems = 210 RST siblings on sagitta (1:1:1).
- 0 files contain raw `<div class=` (the breakage that took down /en/1.5/).
- conf.py copyright/version/release preserve sagittas values
  (2024 / 1.4 / "1.4.x (sagitta)") - not currents.
- html_title from currents conf.py removed - PR #1880 is the right place
  for sagittas branch-localized title.

Supersedes / closes on merge:

- #1886 (broken converter output, would break /en/1.4/ if merged).

Generated by robots https://vyos.io

19 files changed, 2880 insertions, 0 deletions

diff --git a/docs/installation/cloud/md-aws-ha.md b/docs/installation/cloud/md-aws-ha.md
new file mode 100644
index 00000000..f32e2ab5
--- /dev/null
+++ b/docs/installation/cloud/md-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: <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:
+
+```none
+export AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>"
+export AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>"
+export AWS_SESSION_TOKEN="<AWS_SESSION_TOKEN>"
+export AWS_DEFAULT_REGION="<AWS_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@<vyos_public_ip> -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/md-aws-to-azure.md b/docs/installation/cloud/md-aws-to-azure.md
new file mode 100644
index 00000000..246df5f3
--- /dev/null
+++ b/docs/installation/cloud/md-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: <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:
+
+```none
+export AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>"
+export AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>"
+export AWS_SESSION_TOKEN="<AWS_SESSION_TOKEN>"
+export AWS_DEFAULT_REGION="<AWS_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 "<subscription ID or name>"
+```
+
+- Azure CLI installed:
+
+  <https://learn.microsoft.com/en-us/cli/azure/install-azure-cli>
+
+- 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:
+
+  <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli>
+
+- 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@<vyos_public_ip> -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/md-azure-ha.md b/docs/installation/cloud/md-azure-ha.md
new file mode 100644
index 00000000..fa94c222
--- /dev/null
+++ b/docs/installation/cloud/md-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 "<subscription ID or name>"
+```
+
+- Azure CLI installed:
+
+  <https://learn.microsoft.com/en-us/cli/azure/install-azure-cli>
+
+- 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:
+
+  <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli>
+
+- 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@<vyos_public_ip> -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/md-azure.md b/docs/installation/cloud/md-azure.md
new file mode 100644
index 00000000..aa577aa1
--- /dev/null
+++ b/docs/installation/cloud/md-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:**
+
+<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**:
+
+  ```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/md-gcp.md b/docs/installation/cloud/md-gcp.md
new file mode 100644
index 00000000..7144f083
--- /dev/null
+++ b/docs/installation/cloud/md-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:
+
+<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:
+
+> ```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:
+
+> ```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
new file mode 100644
index 00000000..f64883fc
--- /dev/null
+++ b/docs/installation/cloud/md-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/md-oracel.md b/docs/installation/cloud/md-oracel.md
new file mode 100644
index 00000000..9ed07ff9
--- /dev/null
+++ b/docs/installation/cloud/md-oracel.md
@@ -0,0 +1,5 @@
+# Oracle
+
+## References
+
+<https://www.oracle.com/cloud/>
diff --git a/docs/installation/md-image.md b/docs/installation/md-image.md
new file mode 100644
index 00000000..7581d065
--- /dev/null
+++ b/docs/installation/md-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/md-index.md b/docs/installation/md-index.md
new file mode 100644
index 00000000..f9e230fc
--- /dev/null
+++ b/docs/installation/md-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/md-install.md b/docs/installation/md-install.md
new file mode 100644
index 00000000..a02b3292
--- /dev/null
+++ b/docs/installation/md-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 <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:
+
+```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 <image_path>` 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://<address_of_your_HTTP_server>/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
new file mode 100644
index 00000000..e2c16ceb
--- /dev/null
+++ b/docs/installation/md-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 <url | path> [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:
+
+<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/md-vyos-on-baremetal.md b/docs/installation/md-vyos-on-baremetal.md
new file mode 100644
index 00000000..b551a811
--- /dev/null
+++ b/docs/installation/md-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/virtual/md-docker.md b/docs/installation/virtual/md-docker.md
new file mode 100644
index 00000000..10da8d41
--- /dev/null
+++ b/docs/installation/virtual/md-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/md-eve-ng.md b/docs/installation/virtual/md-eve-ng.md
new file mode 100644
index 00000000..3e32e61f
--- /dev/null
+++ b/docs/installation/virtual/md-eve-ng.md
@@ -0,0 +1,5 @@
+# EVE-NG
+
+## References
+
+<https://www.eve-ng.net/>
diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md
new file mode 100644
index 00000000..d903c9a4
--- /dev/null
+++ b/docs/installation/virtual/md-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 <installation>`
+  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
new file mode 100644
index 00000000..12ac179e
--- /dev/null
+++ b/docs/installation/virtual/md-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/md-libvirt.md b/docs/installation/virtual/md-libvirt.md
new file mode 100644
index 00000000..5acefd43
--- /dev/null
+++ b/docs/installation/virtual/md-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/md-proxmox.md b/docs/installation/virtual/md-proxmox.md
new file mode 100644
index 00000000..cad22137
--- /dev/null
+++ b/docs/installation/virtual/md-proxmox.md
@@ -0,0 +1,45 @@
+(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`.
+
+```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 <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.
+
+```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/md-vmware.md b/docs/installation/virtual/md-vmware.md
new file mode 100644
index 00000000..0338067c
--- /dev/null
+++ b/docs/installation/virtual/md-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
+
+
+<https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html>
+