Add incremental RST-to-MyST swap mechanism (sagitta) (#1868)

* feat(swap-sagitta): add incremental RST-to-MyST swap mechanism

Backport of the swap mechanism from feat/incremental-myst-swap onto
the sagitta release branch. Built directly on top of origin/sagitta,
so the underlying RST tree is sagitta's (not current's).

Mechanism:
- scripts/import_myst.py — import md from myst/* with md- prefix
- scripts/swap_sources.py — rename md-{name}.md → {name}.md before
  Sphinx builds, restore after; writes _build/_swap_state.json and
  _build/_swap_exclude.txt
- docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build →
  trap restore; explicit `swap` and `restore` targets too
- docs/conf.py — MyST extensions enabled; swap exclude_patterns
  loader; _prefer_webp builder hook so html prefers webp over png

Content:
- 202 md-prefixed pages from origin/myst/sagitta (md-{name}.md
  alongside each {name}.rst counterpart)
- 1 plain MyST-only page from myst/sagitta where no .rst exists
  (already at canonical name on sagitta: docs/copyright.md)
- 240 .webp images from myst/sagitta (added alongside the existing
  PNG/JPG so RST builds keep their assets)
- docs/_swap.txt populated with all 202 stems → MyST is served by
  default, revert a page by removing its stem from _swap.txt

🤖 Generated by [robots](https://vyos.io)

* feat(conf): copy .md sources into HTML output for plain-text serving

Adds a build-finished hook that mirrors every .md file from the Sphinx
source tree into the HTML output directory verbatim, making unrendered
MyST sources accessible alongside HTML renders at the same URL path.

🤖 Generated by [robots](https://vyos.io)

* docs: address review feedback (backport from PR #1857)

Fix conversion artifacts, typos, and technical inaccuracies applicable
to the sagitta branch: curly quotes, typos (deamonless, cammans,
amdifferent, trough), incorrect firewall command paths, missing closing
brace in zone-policy, peer name inconsistencies, hardcoded passwords
replaced with vault references, and md-*.md exclusion in conf.py.

🤖 Generated by [robots](https://vyos.io)

* docs: port .readthedocs.yml jobs, _ext/vyos.py fallback and swap-script tests from PR #1857

Parity backport from PR #1857 (current) — three pieces were missing on
sagitta.

- .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run
  scripts/swap_sources.py --swap before the Sphinx build and --restore
  after. Without this, the swap mechanism ships but never runs on RTD
  builds for this branch — the swap is a silent no-op.
- docs/_ext/vyos.py: CmdInclude.run() now falls back to nested_parse()
  when self.state._renderer is not present. Required for cfgcmd /
  opcmd / cmdincludemd directives to render correctly when included
  from MyST pages (the swap mechanism's whole point). Sagitta-only
  delta on _ext/vyos.py (the path = str(path) line on 224) is
  intentionally untouched.
- tests/test_import_myst.py, tests/test_swap_sources.py: tests for the
  swap scripts. The scripts on this branch are byte-identical to
  current's, so the same tests apply. Travels with the branch so CI
  catches per-branch regressions if the scripts ever drift.

🤖 Generated by [robots](https://vyos.io)

* fix(conf): skip md-*.md staging files in _copy_md_sources

Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/919695a7-688d-41b9-89f0-540684625dbc

Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>

20 files changed, 3858 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..8cdfda44
--- /dev/null
+++ b/docs/installation/cloud/md-aws-ha.md
@@ -0,0 +1,132 @@
+\##########
+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>
+<img src="/_static/images/cloud-aws-ha-architecture.webp" alt="VyOS HA topology diagram" />
+</figure>
+
+# 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 <span class="title-ref">main.tf</span>, <span class="title-ref">network.tf</span>, <span class="title-ref">transit_gateway.tf</span>, <span class="title-ref">variables.tf</span>, and <span class="title-ref">outputs.tf</span> 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 <span class="title-ref">vyos_ami_id</span> variable directly in <span class="title-ref">variables.tf</span>.
+
+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 <span class="title-ref">variables.tf</span>, including instance type, region, and <span class="title-ref">vyos_ami_id</span>.
+
+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..87effb97
--- /dev/null
+++ b/docs/installation/cloud/md-aws-to-azure.md
@@ -0,0 +1,177 @@
+\##########
+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>
+<img src="/_static/images/cloud-aws-to-azure.webp" alt="VyOS Cloud-to-Cloud topology diagram" />
+</figure>
+
+# 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-aws.md b/docs/installation/cloud/md-aws.md
new file mode 100644
index 00000000..523fd280
--- /dev/null
+++ b/docs/installation/cloud/md-aws.md
@@ -0,0 +1,722 @@
+\##########
+VyOS Deployment on AWS
+\##########
+
+This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (VPC, ENIs, Subnets, Security Groups) on AWS.
+
+Prerequisites
+========
+
+1\. AWS Account
+-----------
+Ensure you have an AWS account with administrative access.
+
+2\. IAM Permissions
+-----------
+
+To deploy VyOS and related resources, the user must have the following permissions:
+
+- `ec2:` for managing EC2, ENIs, and EIPs.
+- `vpc:` for creating VPCs, subnets, and route tables.
+- `iam:` for attaching roles.
+
+3\. SSH Key Pair
+-----------
+
+You can use Amazon EC2 to create your key pairs, or you can use a third-party tool to create your key pairs and then import them to Amazon EC2.
+Amazon EC2 supports:
+
+- `2048-bit SSH-2 RSA keys` for Linux and Windows instances.
+- `ED25519 keys` for Linux instances (not supported for Windows).
+
+When you create a key pair using Amazon EC2:
+
+- The `public key` is stored in Amazon EC2.
+- You store the `private key` securely on your local machine.
+
+Steps to Create a Key Pair Using Amazon EC2
+^^^^^^^^^^^^^^
+
+- Open the Amazon EC2 console <https://console.aws.amazon.com/ec2/>.
+- In the navigation pane, under `Network & Security`, choose `Key Pairs`.
+
+<figure>
+<img src="/_static/images/cloud-aws-keypair-01.webp" />
+</figure>
+
+- Choose `Create key pair` and select `AWS region` at the top right corner of the windows where you plan to deploy the VyOS instance.
+
+<figure>
+<img src="/_static/images/cloud-aws-keypair-02.webp" />
+</figure>
+
+\- Configure Key Pair:
+""""""""""
+
+> - **Name**: Enter a descriptive name for the key pair, e.g., `vyos-keypair`.
+>
+> > <div class="note">
+> >
+> > <div class="title">
+> >
+> > Note
+> >
+> > </div>
+> >
+> > The key name can include up to 255 ASCII characters. It cannot include leading or trailing spaces.
+> >
+> > </div>
+>
+> - **Select Key Pair Type**:
+>   - For **Linux instances**: Choose either **RSA** or **ED25519**.
+>
+>   - For **Windows instances**: Choose **RSA**.
+>
+>     <div class="note">
+>
+>     <div class="title">
+>
+>     Note
+>
+>     </div>
+>
+>     ED25519 keys are not supported for Windows instances.
+>
+>     </div>
+> - **Private Key File Format**:
+>   - **PEM**: Choose this format if using OpenSSH or other SSH clients (e.g., on Linux/macOS).
+>   - **PPK**: Choose this format if using PuTTY on Windows.
+
+- **Optional**: Add tags to the key pair. Choose **Add tag** and provide the **key** and **value** for each tag.
+
+- Choose **Create key pair**.
+
+- The private key file will automatically download to your browser.  
+  - The file name will match the name you provided (e.g., <span class="title-ref">vyos-keypair.pem</span>), with the extension determined by the format you chose.
+
+<figure>
+<img src="/_static/images/cloud-aws-keypair-03.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-aws-keypair-04.webp" alt="Important Notes" />
+<figcaption aria-hidden="true"><strong>Important Notes</strong></figcaption>
+</figure>
+
+- **Save the private key file securely**:  
+  This is your **only chance** to download the private key. If you lose it, you cannot connect to your instance.
+
+- If you are using SSH on a **macOS or Linux computer**, set the correct permissions for the private key file:
+
+``` none
+chmod 400 vyos-keypair.pem
+```
+
+If permissions are not set to **400**, you will encounter an **"Unprotected private key file"** error when attempting to connect to the instance.
+
+> **Example Usage for SSH**
+
+``` none
+ssh -i vyos-keypair.pem vyos@<Public/Elastic IP>
+```
+
+For more information, please visit the official AWS documentation:
+
+<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html#having-ec2-create-your-key-pair>
+
+4\. VyOS Subscription
+-----------
+- Go to the AWS Marketplace <https://aws.amazon.com/marketplace> and search for **VyOS**.
+- Subscribe to the VyOS AMI.
+
+For more information, please visit:
+
+<https://aws.amazon.com/marketplace/seller-profile?id=7636d180-1710-48bc-acd6-d323c4a0429f>
+
+Create required resources
+========
+
+Certain resources need to be created in the AWS infrastructure before creating a VyOS instance, such as a VPC, Subnets, Elastic IPs, Route Tables, Security Groups, and others.
+
+Step 1: Create Virtual Private Cloud (VPC) and Subnets
+-----------
+
+1\. Create a VPC
+^^^^^^^^^^^^^^
+
+To create a VPC for your AWS environment:
+
+- Go to the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>.
+- In the navigation pane, choose **Your VPCs**.
+- Choose **Create VPC**.
+
+<figure>
+<img src="/_static/images/cloud-aws-vpc-01.webp" />
+</figure>
+
+- **Configure VPC Settings**:  
+  - **Name tag - optional**: Enter a descriptive name for your VPC, e.g., `VyOS-VPC`.
+  - **IPv4 CIDR Block**: Enter `10.0.0.0/16`.
+
+- Choose **Create VPC**.
+
+<figure>
+<img src="/_static/images/cloud-aws-vpc-02.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-aws-vpc-03.webp" />
+</figure>
+
+For more information, please visit the AWS documentation:
+
+<https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html>
+
+2\. Create Subnets
+^^^^^^^^^^^^^^
+
+Subnets allow you to divide your VPC into smaller IP spaces. Follow these steps to create subnets for both **public** and **private** networks:
+
+- Go to the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>.
+- In the navigation pane, choose **Subnets**.
+- Choose **Create Subnet**.
+
+<figure>
+<img src="/_static/images/cloud-aws-subnet-01.webp" />
+</figure>
+
+\- Configure Subnet Settings:
+""""""""""
+
+> - **Public Subnet**:
+>   - **VPC**: Select `VyOS-VPC`.
+>   - **Name Tag**: `VyOS-Public-Subnet`.
+>   - **IPv4 CIDR Block**: `10.0.1.0/24`.
+>   - **Availability Zone**: Select an AZ, e.g., `us-east-1a`.
+> - **Private Subnet**:
+>   - **VPC**: Select `VyOS-VPC`.
+>   - **Name Tag**: `VyOS-Private-Subnet`.
+>   - **IPv4 CIDR Block**: `10.0.2.0/24`.
+>   - **Availability Zone**: Select an AZ, e.g., `us-east-1a`.
+
+- Choose **Create Subnet**.
+
+<figure>
+<img src="/_static/images/cloud-aws-subnet-02.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-aws-subnet-03.webp" />
+</figure>
+
+For additional information, please visit the AWS documentation:
+
+<https://docs.aws.amazon.com/vpc/latest/userguide/create-subnets.html>
+
+For additional details about IP addressing for your VPC and subnets, refer to the AWS documentation:
+
+<https://docs.aws.amazon.com/vpc/latest/userguide/vpc-ip-addressing.html>
+
+Step 2: Create and Configure Security Groups
+-----------
+
+1\. Create Public Security Group
+^^^^^^^^^^^^^^
+
+The **Public Security Group** is used for **outbound connectivity**. All external resources, systems, or networks will connect via this security group.
+
+- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>.
+- In the navigation pane, choose **Security Groups**.
+- Choose **Create Security Group**.
+
+<figure>
+<img src="/_static/images/cloud-aws-sg-01.webp" />
+</figure>
+
+- **Configure the Security Group**:
+
+  > - **Name**: `VyOS-Public-SG`.
+  > - **Description**: "Public security group for outbound connectivity"
+  > - **VPC**: Select the VPC in which your VyOS instance resides.
+
+\- Inbound Rules:
+""""""""""
+
+> - **SSH**: Port `22`, Source `0.0.0.0/0` (Restrict to your IP for security).
+> - **ICMP**: Allow for ping testing purposes.
+> - **IPSec**: Allow port `500` (UDP) for ISAKMP (Phase 1 negotiation).
+> - **NAT Traversal**: Allow port `4500` (UDP) for NAT-T support in IPsec.
+> - **WireGuard**: Allow port `51820` (UDP).
+> - **OpenVPN**: Allow port `1194` (UDP or TCP).
+
+<figure>
+<img src="/_static/images/cloud-aws-sg-02.webp" />
+</figure>
+
+- (Optional) Add tags to identify the security group:  
+  - **Key**: <span class="title-ref">Name</span>, **Value**: <span class="title-ref">VyOS-Public-SG</span>.
+
+- Choose **Create Security Group**.
+
+<figure>
+<img src="/_static/images/cloud-aws-sg-03.webp" />
+</figure>
+
+2\. Create Private Security Group
+^^^^^^^^^^^^^^
+
+The **Private Security Group** is used for **internal connectivity** from internal or VPC-based resources.
+
+- Open the **Amazon EC2 Console**.
+- In the navigation pane, choose **Security Groups**.
+- Choose **Create Security Group**.
+
+\- Configure the Security Group:
+""""""""""
+
+> - **Name**: `VyOS-Private-SG`.
+> - **Description**: "Private security group for internal connectivity"
+> - **VPC**: Select the VPC in which your VyOS instance resides.
+
+\- Inbound Rules:
+""""""""""
+
+> - Allow **All Traffic** (`0.0.0.0/0`) for internal connectivity between resources, VPCs, and other trusted networks.
+
+<figure>
+<img src="/_static/images/cloud-aws-sg-04.webp" />
+</figure>
+
+- (Optional) Add tags to identify the security group:  
+  - **Key**: `Name`, **Value**: `VyOS-Private-SG`.
+
+- Choose **Create Security Group**.
+
+<figure>
+<img src="/_static/images/cloud-aws-sg-05.webp" />
+</figure>
+
+For detailed instructions on creating a security group, refer to the official AWS documentation:
+
+<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-security-group.html>
+
+For more information, refer to the official AWS documentation:
+
+<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html>
+
+Step 3: Create ENIs (Elastic Network Interfaces)
+-----------
+
+Network Interfaces (ENIs) are essential for connecting instances to subnets and managing network traffic. Follow the steps below to create **Public** and **Private** ENIs.
+
+- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>.
+- In the navigation pane, choose **Network Interfaces**.
+- Choose **Create Network Interface**.
+- **Configure Network Interface Settings**:
+
+# Public ENI
+
+> - **Name**: `VyOS-Public-ENI`.
+> - **Description**: "Network Interface for Public Subnet."
+> - **Subnet**: Select the `VyOS-Public-Subnet` you created earlier.
+> - **Private IPv4 Address**: Choose **Auto-assign** to let AWS pick an IP address from the subnet.
+> - **Security Group**: Select the `VyOS-Public-SG`.
+>
+> \- (Optional) Add tags to identify the ENIs:  
+> **Key**: `Name`, **Value**: `VyOS-Public-ENI`.
+>
+> - Choose **Create Network Interface**.
+>
+> <figure>
+> <img src="/_static/images/cloud-aws-eni-01.webp" />
+> </figure>
+
+Private ENI
+""""""""""
+- **Name**: `VyOS-Private-ENI`.
+
+> - **Description**: "Network Interface for Private Subnet."
+> - **Subnet**: Select the `VyOS-Private-Subnet` you created earlier.
+> - **Private IPv4 Address**: Choose **Auto-assign** to let AWS pick an IP address from the subnet.
+> - **Security Group**: Select the `VyOS-Private-SG`.
+>
+> \- (Optional) Add tags to identify the ENIs:  
+> **Key**: `Name`, **Value**: `VyOS-Private-ENI`.
+>
+> - Choose **Create Network Interface**.
+>
+> <figure>
+> <img src="/_static/images/cloud-aws-eni-02.webp" />
+> </figure>
+
+Step 4: Configure Internet Gateway
+-----------
+
+An **Internet Gateway** allows communication between your VPC and the internet. Follow the steps below to create and attach an Internet Gateway to your VPC.
+
+1\. Create an Internet Gateway
+^^^^^^^^^^^^^^
+
+- Open the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>.
+
+- In the navigation pane, choose **Internet Gateways**.
+
+- Choose **Create Internet Gateway**.
+
+- **Configure Internet Gateway**:  
+  - (Optional) **Name**: Enter a descriptive name, e.g., `VyOS-IGW`.
+
+- (Optional) Add a tag to identify the Internet Gateway:  
+  - **Key**: `Name`, **Value**: `VyOS-IGW`.
+
+- Choose **Create Internet Gateway**.
+
+<figure>
+<img src="/_static/images/cloud-aws-igw-01.webp" />
+</figure>
+
+2\. Attach the Internet Gateway to Your VPC
+^^^^^^^^^^^^^^
+
+To enable your VPC to access the internet, attach the Internet Gateway to your VPC:
+
+- After creating the Internet Gateway, select it from the **Internet Gateways** list.
+
+- Choose **Actions \> Attach to VPC**.
+
+- Select the VPC where you want to attach the Internet Gateway:  
+  - Choose <span class="title-ref">VyOS-VPC</span> (the VPC you created earlier).
+
+- Choose **Attach Internet Gateway**.
+
+<figure>
+<img src="/_static/images/cloud-aws-igw-02.webp" />
+</figure>
+
+For more details, refer to the official AWS documentation:
+
+<https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html>.
+
+Step 5: Configure Route Tables
+-----------
+
+Route tables define the paths for network traffic within your VPC. In this step, we will configure **Public** and **Private** route tables to control traffic flow for their respective subnets.
+
+1\. Create and Configure the Public Route Table
+^^^^^^^^^^^^^^
+
+- **Go to the Route Tables Section:**  
+  - Open the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>.
+  - In the left navigation pane, choose **Route Tables**.
+
+- **Create a New Route Table:**
+
+  > - In the **Route Tables** section, choose **Create Route Table**.
+  > - Configure the route table:
+  >   - **Name**: `Public RT`.
+  >   - **VPC**: Select the `VyOS-VPC`.
+  >   - Click **Create Route Table**.
+  >
+  > <figure>
+  > <img src="/_static/images/cloud-aws-route-01.webp" />
+  > </figure>
+
+- **Add a Route to the Internet Gateway:**
+
+  > - Go to the **Routes** tab and click **Edit Routes**.
+  > - Click **Add Route** and enter:
+  >   - **Destination**: `0.0.0.0/0` (Default route to all IPs).
+  >   - **Target**: Select the **Internet Gateway** (`VyOS-IGW`) you created earlier.
+  >   - Click **Save Routes**.
+  >
+  > <figure>
+  > <img src="/_static/images/cloud-aws-route-02.webp" />
+  > </figure>
+
+- **Associate the Public Subnet:**
+
+  > - Go to the **Subnet Associations** tab and click **Edit Subnet Associations**.
+  > - Select the **Public Subnet** (`VyOS-Public-Subnet`).
+  > - Click **Save associations**.
+  >
+  > <figure>
+  > <img src="/_static/images/cloud-aws-route-03.webp" />
+  > </figure>
+
+Step 6: Allocate and Attach Elastic IP (EIP)
+-----------
+
+An **Elastic IP (EIP)** is a static, public IPv4 address designed for dynamic cloud computing. Elastic IP addresses can help maintain consistent connectivity to instances, even if they are stopped, rebooted, or replaced.
+
+- Elastic IP addresses are **public IPv4 addresses** and are reachable from the internet.
+- They can be quickly remapped to different instances or network interfaces within your AWS account to mask failures.
+
+For more details, refer to the official AWS documentation:
+
+<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html>.
+
+Steps to Allocate and Attach Elastic IP
+^^^^^^^^^^^^^^
+
+1\. Allocate Elastic IP
+""""""""""
+
+- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>.
+
+- In the navigation pane, choose **Elastic IPs**.
+
+- Choose **Allocate Elastic IP address**.
+
+- **Elastic IP address settings**:  
+  - For **Public IPv4 address pool**, select **Amazon's pool of IPv4 addresses**.
+
+- (Optional) Add a tag:  
+  - **Key**: `Name`, **Value**: `VyOS-EIP`.
+
+- Choose **Allocate**.
+
+<figure>
+<img src="/_static/images/cloud-aws-eip-01.webp" />
+</figure>
+
+2\. Attach Elastic IP to Public ENI
+""""""""""
+
+- Go to **EC2 \> Elastic IPs**.
+
+- Select the **Elastic IP** you just allocated.
+
+- Choose **Actions \> Associate Elastic IP address**.
+
+- **Configure Association**:
+
+  > - **Resource type**: Choose **Network Interface**.
+  > - **Network Interface**: Select the **VyOS-Public-ENI** created earlier.
+  > - **Private IPv4 Address**: Ensure it is correctly selected.
+
+- (Optional) Select **Allow the Elastic IP address to be reassociated** if the EIP is already associated with another resource.
+
+- Choose **Associate**.
+
+<figure>
+<img src="/_static/images/cloud-aws-eip-02.webp" />
+</figure>
+
+**Why Use Elastic IP?**
+
+- **Consistency**: The EIP remains static, even if the instance stops or is replaced.
+- **Failover**: If an instance fails, you can remap the EIP to a new instance to restore services quickly.
+- **DNS Integration**: You can point your domain to the Elastic IP for consistent public access.
+
+For additional details, refer to the AWS documentation:
+
+<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-eips.html>
+
+Launch VyOS Instance
+========
+
+Follow the detailed instructions below to launch a VyOS instance in your AWS environment with two ENIs (Public and Private).
+
+- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>.
+
+- In the EC2 dashboard, choose **Launch Instance**.
+
+- **Configure Instance Details**:
+
+  > - **Name and Tags**:
+  >
+  >   - Under **Name and tags**, enter a descriptive name for your instance, e.g., `VyOS-Instance`.
+  >
+  >   <figure>
+  >   <img src="/_static/images/cloud-aws-vyos-01.webp" />
+  >   </figure>
+  >
+  > - **Application and OS Images (AMI)**:
+  >
+  >   - Choose **Browse more AMIs**.
+  >   - Go to the **AWS Marketplace** tab and search for **VyOS**.
+  >   - Choose the VyOS AMI that matches your requirements and click **Select**.
+  >
+  >   <figure>
+  >   <img src="/_static/images/cloud-aws-vyos-02.webp" />
+  >   </figure>
+  >
+  >   <figure>
+  >   <img src="/_static/images/cloud-aws-vyos-03.webp" />
+  >   </figure>
+  >
+  > - **Instance Type**:
+  >
+  >   - Select the instance type that fits your workload. For example:
+  >     - `c5n.large` (or larger recommended for VyOS).
+  >
+  >   > <figure>
+  >   > <img src="/_static/images/cloud-aws-vyos-04.webp" />
+  >   > </figure>
+  >
+  > - **Key pair (login)**:
+  >
+  >   - For **Key pair name**, select the key pair you created earlier (`vyos-keypair`).
+  >   - If you do not have a key pair, create a new one and download the private key file.
+  >
+  >   <figure>
+  >   <img src="/_static/images/cloud-aws-vyos-05.webp" />
+  >   </figure>
+  >
+  > - **Network Settings**:
+  >
+  >   - **VPC**: Select `VyOS-VPC`.
+  >   - **Subnet**: Select the **Public Subnet** (`VyOS-Public-Subnet`).
+  >   - **Auto-assign Public IP**: **Disable**.
+  >   - **Firewall (security groups)**: Select the **Select existing security group**.
+  >   - **Common security groups**: Live empty (Do not select any security groups).
+  >
+  >   <figure>
+  >   <img src="/_static/images/cloud-aws-vyos-09.webp" />
+  >   </figure>
+  >
+  > - **Advanced network configuration**
+  >
+  >   > - **Network interface 1** select `VyOS-Public-ENI`
+  >   >
+  >   > <figure>
+  >   > <img src="/_static/images/cloud-aws-vyos-07.webp" />
+  >   > </figure>
+  >   >
+  >   > - Click to the **Add network interface** button
+  >   > - **Network interface 2** select `VyOS-Private-ENI`
+  >   >
+  >   > <figure>
+  >   > <img src="/_static/images/cloud-aws-vyos-08.webp" />
+  >   > </figure>
+  >   >
+  >   > - In **Subnet** deselect subnet
+  >   >
+  >   > <figure>
+  >   > <img src="/_static/images/cloud-aws-vyos-10.webp" />
+  >   > </figure>
+
+- Review the instance configuration in the **Summary** panel and choose **Launch Instance**.
+
+- Wait until the instance status changes to **Running**.
+
+<figure>
+<img src="/_static/images/cloud-aws-vyos-11.webp" />
+</figure>
+
+Connect to the VyOS instance
+-----------
+
+> You can only connect to the VyOS instance via **SSH** protocol. Use the default username **vyos**, **Elastic IP** and **SSH Key Pair** to connect to the VyOS instance via SSH:
+>
+> ``` none
+> ssh -i vyos-keypair.pem vyos@35.152.131.62
+> ```
+
+Deployment of VyOS Instance and Required Resources via CloudFormation Template
+========
+
+These CloudFormation templates automate the deployment of a VyOS instance on AWS, configuring essential components such as:
+
+- VPC
+- Public and private subnets
+- Internet Gateway
+- Route Tables
+- Elastic IPs
+- Security Groups
+
+You can download or clone these templates from the GitHub repository and use them in your environment:
+
+<https://github.com/vyos/vyos-automation/tree/main/CloudFormation>
+
+Deployment of VyOS Instance and Required Resources via Terraform
+========
+
+These Terraform projects automate the deployment of a VyOS instance on AWS, configuring essential components such as:
+
+- VPC
+- Public and private subnets
+- Internet Gateway
+- Route Tables
+- Elastic IPs
+- Security Groups
+
+You can download or clone these templates from the GitHub repository and use them in your environment:
+
+<https://github.com/vyos/vyos-automation/tree/main/Terraform/AWS/>
+
+## Amazon CloudWatch Agent Usage
+
+To use Amazon CloudWatch Agent, configure it within the Amazon SSM Parameter Store. If you don't have a configuration yet, do `configuration_creation`.
+
+1.  Create an `IAM (Identity and Access Management)` role for the `EC2 (Elastic Compute Cloud)` instance to access CloudWatch service, and name it CloudWatchAgentServerRole. The role should contain two default policies: CloudWatchAgentServerPolicy and AmazonSSMManagedInstanceCore.
+2.  Attach the created role to your VyOS `EC2 (Elastic Compute Cloud)` instance.
+3.  Ensure that amazon-cloudwatch-agent package is installed.
+
+> ``` none
+> $ sudo apt list --installed | grep amazon-cloudwatch-agent
+> ```
+>
+> <div class="note">
+>
+> <div class="title">
+>
+> Note
+>
+> </div>
+>
+> The amazon-cloudwatch-agent package is normally included in VyOS 1.3.3+ and 1.4+
+>
+> </div>
+
+3.  Retrieve an existing CloudWatch Agent configuration from the `SSM (Systems Manager)` Parameter Store.
+
+> ``` none
+> $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c ssm:<your-configuration-name>
+> ```
+>
+> This step also enables systemd service and runs it.
+>
+> <div class="note">
+>
+> <div class="title">
+>
+> Note
+>
+> </div>
+>
+> The VyOS platform-specific scripts feature is under development. Thus, this step should be repeated manually after changing system image (`/installation/update`)
+>
+> </div>
+
+### CloudWatch SSM Configuration creation
+
+Creating the Amazon Cloudwatch Agent Configuration in Amazon `SSM (Systems Manager)` Parameter Store.
+
+1.  Create an `IAM (Identity and Access Management)` role for your `EC2 (Elastic Compute Cloud)` instance to access the CloudWatch service. Name it CloudWatchAgentAdminRole. The role should contain at two default policies: CloudWatchAgentAdminPolicy and AmazonSSMManagedInstanceCore.
+
+> <div class="note">
+>
+> <div class="title">
+>
+> Note
+>
+> </div>
+>
+> CloudWatchAgentServerRole is too permissive and should be used for single configuration creation and deployment. That's why after completion of step \#3 highly recommended to replace instance CloudWatchAgentAdminRole role with CloudWatchAgentServerRole.
+>
+> </div>
+
+2.  Run Cloudwatch configuration wizard.
+
+> ``` none
+> $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard
+> ```
+
+3.  When prompted, answer "yes" to the question "Do you want to store the config in the SSM parameter store?".
+
+## References
+
+- <https://console.aws.amazon.com/>
+- <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-iam-roles-for-cloudwatch-agent.html>
+- <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance-fleet.html>
diff --git a/docs/installation/cloud/md-azure-ha.md b/docs/installation/cloud/md-azure-ha.md
new file mode 100644
index 00000000..4a77565d
--- /dev/null
+++ b/docs/installation/cloud/md-azure-ha.md
@@ -0,0 +1,130 @@
+\##########
+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>
+<img src="/_static/images/cloud-azure-ha-architecture.webp" alt="VyOS HA topology diagram" />
+</figure>
+
+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..8489a532
--- /dev/null
+++ b/docs/installation/cloud/md-azure.md
@@ -0,0 +1,449 @@
+\##########
+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>
+<img src="/_static/images/cloud-azure-rg-01.webp" />
+</figure>
+
+- 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>
+<img src="/_static/images/cloud-azure-rg-02.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-azure-vnet-01.webp" />
+</figure>
+
+**IP addresses**:
+
+- Address Space: `10.1.0.0/16`
+
+<figure>
+<img src="/_static/images/cloud-azure-vnet-02.webp" />
+</figure>
+
+**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>
+<img src="/_static/images/cloud-azure-vnet-03.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-azure-vnet-04.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-azure-vnet-05.webp" />
+</figure>
+
+- 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>
+<img src="/_static/images/cloud-azure-sg-01.webp" />
+</figure>
+
+- 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>
+<img src="/_static/images/cloud-azure-sg-02.webp" />
+</figure>
+
+**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>
+<img src="/_static/images/cloud-azure-sg-03.webp" />
+</figure>
+
+**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>
+<img src="/_static/images/cloud-azure-sg-04.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-azure-pub-ip-01.webp" />
+</figure>
+
+- **Name**: `VyOS-Pub-IP`
+- **IP Version**: `IPv4`
+- **SKU**: `Standard`
+- **Availability zone**: Select Availability Zone
+
+<figure>
+<img src="/_static/images/cloud-azure-pub-ip-02.webp" />
+</figure>
+
+- **IP address assignment**: `Static`
+- **Idle timeout (minutes)** `30` (max)
+
+<figure>
+<img src="/_static/images/cloud-azure-pub-ip-03.webp" />
+</figure>
+
+- 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>
+<img src="/_static/images/cloud-azure-vm-01.webp" />
+</figure>
+
+- **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>
+<img src="/_static/images/cloud-azure-vm-02.webp" />
+</figure>
+
+- **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>
+<img src="/_static/images/cloud-azure-vm-03.webp" />
+</figure>
+
+- **Virtual network**: Select `VyOS-VirtualNetwork`.
+- **Subnet**: Select `VyOS-Public-Subnet`.
+- **Public IP**: Select public IP address which created before `VyOS-Pub-IP`.
+
+<figure>
+<img src="/_static/images/cloud-azure-vm-04.webp" />
+</figure>
+
+- **Configure network security group**: Select existing Security Group `VyOS-SecurityGroup`.
+
+<figure>
+<img src="/_static/images/cloud-azure-vm-05.webp" />
+</figure>
+
+- 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>
+<img src="/_static/images/cloud-azure-vm-06.webp" />
+</figure>
+
+- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**.
+
+<figure>
+<img src="/_static/images/cloud-azure-vm-07.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-azure-vm-12.webp" />
+</figure>
+
+- Enable IP forwarding and click the **Apply** button.
+
+<figure>
+<img src="/_static/images/cloud-azure-vm-13.webp" />
+</figure>
+
+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.
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+Azure does not allow you attach interface when the instance in the
+**Running** state.
+
+</div>
+
+Create network interface:
+^^^^^^^^^^^^^^
+
+- In the Azure Portal, search for and select **Network Interfaces**.
+- On the **Network Interfaces** page, select **+ Create**.
+
+<figure>
+<img src="/_static/images/cloud-azure-nic-01.webp" />
+</figure>
+
+- **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>
+<img src="/_static/images/cloud-azure-nic-02.webp" />
+</figure>
+
+- Enable **IP Forwarding**
+- Navigate to **Network Interfaces** select `VyOS-PRIV-NIC`
+
+<figure>
+<img src="/_static/images/cloud-azure-nic-03.webp" />
+</figure>
+
+- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**.
+
+<figure>
+<img src="/_static/images/cloud-azure-nic-04.webp" />
+</figure>
+
+Attach reate network interface:
+^^^^^^^^^^^^^^
+
+- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button
+
+<figure>
+<img src="/_static/images/cloud-azure-vm-08.webp" />
+</figure>
+
+- Go to **Networking** select **Network settings** and then select **Attach network interface**
+
+<figure>
+<img src="/_static/images/cloud-azure-vm-09.webp" />
+</figure>
+
+- Select existing (before created) network interface `VyOS-PRIV-NIC` and click the **OK** button.
+
+<figure>
+<img src="/_static/images/cloud-azure-vm-10.webp" />
+</figure>
+
+- Now you have attached second interface to your instance and you can start Virtual Machine.
+- Go to **Overview** and click the **Start** button.
+
+<figure>
+<img src="/_static/images/cloud-azure-vm-11.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-azure-route-01.webp" />
+</figure>
+
+- 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>
+<img src="/_static/images/cloud-azure-route-02.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-azure-route-03.webp" />
+</figure>
+
+- 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>
+<img src="/_static/images/cloud-azure-route-04.webp" />
+</figure>
+
+- **Virtual network**: Select `VyOS-VirtualNetwork`.
+- **Subnet**: Select `VyOS-Public-Subnet`.
+
+<figure>
+<img src="/_static/images/cloud-azure-route-05.webp" />
+</figure>
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+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.
+
+</div>
+
+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..b30d6494
--- /dev/null
+++ b/docs/installation/cloud/md-gcp.md
@@ -0,0 +1,298 @@
+\#####################
+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"
+> ```
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+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.
+
+</div>
+
+2.  Open GCP console and navigate to the **Compute Engine** \> **Metadata** \> **SSH Keys**. Choose
+    **SSH Keys**.
+
+<figure>
+<img src="/_static/images/cloud-gcp-01.webp" />
+</figure>
+
+3.  Click **edit** and **Add item**.
+4.  Paste your public ssh key and **Save**.
+
+<figure>
+<img src="/_static/images/cloud-gcp-02.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-gcp-proj.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-gcp-svc.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-gcp-proj.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-gcp-vpc-01.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-gcp-vpc-02.webp" alt="Private VPC:" />
+<figcaption><strong>Private VPC</strong>:
+<ul>
+<li>Name: <code>vyos-private-vpc</code></li>
+<li>Subnet creation mode: <code>Custom</code></li>
+<li>Subnet name: <code>vyos-private-subnet</code></li>
+<li>Region: e.g., <code>europe-west1</code></li>
+<li>IP range: <code>10.0.11.0/24</code></li>
+<li>Leave all other settings at default, then click <strong>Create</strong>.</li>
+</ul></figcaption>
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-gcp-vpc-03.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-gcp-vpc-04.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-gcp-vpc-05.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-gcp-vpc-06.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-gcp-vpc-07.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-gcp-proj.webp" />
+</figure>
+
+3.  In the search bar, type `vyos` to find the VyOS image in the Marketplace.
+
+<figure>
+<img src="/_static/images/cloud-gcp-market-01.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-gcp-market-02.webp" />
+</figure>
+
+4.  On the next page, review details such as support, pricing, and other details.
+
+<figure>
+<img src="/_static/images/cloud-gcp-market-03.webp" />
+</figure>
+
+5.  Click the `GET STARTED` button to start deployment process.
+
+<figure>
+<img src="/_static/images/cloud-gcp-market-04.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-gcp-market-05.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-gcp-vm-01.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-gcp-vm-02.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-gcp-vm-03.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-gcp-vm-09.webp" />
+</figure>
+
+9.  Click `Deploy` button.
+
+<figure>
+<img src="/_static/images/cloud-gcp-vm-06.webp" />
+</figure>
+
+<figure>
+<img src="/_static/images/cloud-gcp-vm-07.webp" />
+</figure>
+
+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>
+<img src="/_static/images/cloud-gcp-vm-08.webp" />
+</figure>
+
+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..1c1e1ed6
--- /dev/null
+++ b/docs/installation/cloud/md-index.md
@@ -0,0 +1,13 @@
+# Running VyOS in Cloud Environments
+
+<div class="toctree" caption="Content">
+
+aws
+aws-ha
+azure
+azure-ha
+aws-to-azure
+gcp
+oracle
+
+</div>
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..fb57d73f
--- /dev/null
+++ b/docs/installation/md-image.md
@@ -0,0 +1,131 @@
+# 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.
+
+<div class="opcmd">
+
+show system image
+
+List all available system images which can be booted on the current system.
+
+``` 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
+```
+
+</div>
+
+<div class="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 `show system image`.
+
+``` 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
+```
+
+</div>
+
+<div class="opcmd">
+
+show version
+
+Show current system image version.
+
+``` 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
+```
+
+</div>
+
+## System rollback
+
+If you need to rollback to a previous image, you can easily do so. First
+check the available images through the `show system image`
+command and then select your image with the following command:
+
+<div class="opcmd">
+
+set system image default-boot \[image-name\]
+
+Select the default boot image which will be started on the next boot
+of the system.
+
+</div>
+
+Then reboot the system.
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+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.
+
+</div>
+
+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..2e8e93c9
--- /dev/null
+++ b/docs/installation/md-index.md
@@ -0,0 +1,34 @@
+# Installation and Image Management
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+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`.
+
+</div>
+
+<div class="toctree" maxdepth="2" caption="Content">
+
+install
+virtual/index
+cloud/index
+vyos-on-baremetal
+update
+image
+migrate-from-vyatta
+
+</div>
diff --git a/docs/installation/md-install.md b/docs/installation/md-install.md
new file mode 100644
index 00000000..947d71d7
--- /dev/null
+++ b/docs/installation/md-install.md
@@ -0,0 +1,504 @@
+# Installation
+
+VyOS installation requires a downloaded VyOS .iso file. That file is
+a live install image that lets you boot a live VyOS. From the live
+system, you can proceed to a permanent installation on a hard drive or
+any other type of storage.
+
+<table style="width:98%;">
+<caption>Comparison of VyOS image releases</caption>
+<colgroup>
+<col style="width: 8%" />
+<col style="width: 29%" />
+<col style="width: 11%" />
+<col style="width: 22%" />
+<col style="width: 13%" />
+<col style="width: 10%" />
+</colgroup>
+<thead>
+<tr>
+<th>Release Type</th>
+<th>Description</th>
+<th>Release Cycle</th>
+<th>Intended Use</th>
+<th>Access to Images</th>
+<th>Access to Source</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>Nightly
+(Current)</strong></td>
+<td>Automatically built from the current branch.
+Always up to date with cutting edge development
+but guaranteed to contain bugs.</td>
+<td>Every night</td>
+<td>Developing VyOS, testing new
+features, experimenting.</td>
+<td>Everyone</td>
+<td>Everyone</td>
+</tr>
+<tr>
+<td><strong>Stream</strong></td>
+<td>VyOS Stream serves as a technology preview and
+a quality gate for the upcoming LTS release.
+Allows everyone to try new features and check
+if they work well or need improvements</td>
+<td>Every quarter</td>
+<td>Non-critical production environments,
+preparing for the LTS release.</td>
+<td>Everyone</td>
+<td>Everyone</td>
+</tr>
+<tr>
+<td><strong>Release
+Candidate</strong></td>
+<td>Rather stable. All development focuses on testing
+and hunting down remaining bugs following the
+feature freeze.</td>
+<td>Irregularly until
+EPA comes out</td>
+<td>Labs, small offices and non-critical
+production systems backed by a
+high-availability setup.</td>
+<td>Everyone</td>
+<td>Everyone</td>
+</tr>
+<tr>
+<td><strong>Early
+Production
+Access</strong></td>
+<td>Highly stable with no known bugs. Needs to be
+tested repeatedly under different conditions
+before it can become the final release.</td>
+<td>Irregularly until
+LTS comes out</td>
+<td>Non-critical production environments,
+preparing for the LTS release.</td>
+<td>Everyone</td>
+<td>Everyone</td>
+</tr>
+<tr>
+<td><strong>Long-Term
+Support</strong></td>
+<td>Guaranteed to be stable and carefully maintained
+for several years after the release. No features
+are introduced but security updates are released
+in a timely manner.</td>
+<td>Every major
+version</td>
+<td>Large-scale enterprise networks,
+internet service providers,
+critical production environments
+that call for minimum downtime.</td>
+<td>Subscribers,
+contributors,
+non-profits,
+emergency services,
+academic institutions</td>
+<td>Everyone</td>
+</tr>
+</tbody>
+</table>
+
+## 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](https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913) for more information on downloads.
+
+<figure>
+<img src="/_static/images/vyosnew-downloads.webp" />
+</figure>
+
+### Rolling Release
+
+Everyone can download bleeding-edge VyOS rolling images from:
+<https://downloads.vyos.io/>
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+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 `bug_report`. We depend on your feedback
+to improve VyOS!
+
+</div>
+
+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
+
+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.
+
+`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
+```
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+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(`T7301`).
+
+</div>
+
+## Live installation
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+A permanent VyOS installation always requires to go first
+through a live installation.
+
+</div>
+
+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 `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](https://www.balena.io/etcher/) (for GNU/Linux,
+macOS and Windows), [Rufus](https://rufus.ie/) (for Windows) and [many others](https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems). You can
+follow their instructions to create a bootable USB drive from an .iso
+file.
+
+<div class="hint">
+
+<div class="title">
+
+Hint
+
+</div>
+
+The default username and password for the live system is *vyos*.
+
+</div>
+
+## Permanent installation
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+Before a permanent installation, VyOS requires a
+`live_installation`.
+
+</div>
+
+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.
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+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
+`image-mgmt` for further information).
+
+</div>
+
+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>
+<img src="/_static/images/permanent_install.webp" alt="3. After the installation is completed, remove the live USB stick or CD." />
+<figcaption>3. After the installation is completed, remove the live USB stick or
+CD.
+<ol start="4" type="1">
+<li>Reboot the system.</li>
+</ol>
+<pre class="none"><code>vyos@vyos:~$ reboot
+Proceed with reboot? (Yes/No) [No] Yes</code></pre>
+<p>You will boot now into a permanent VyOS system.</p></figcaption>
+</figure>
+
+## 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
+- `dhcp-server`
+- `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
+         }
+     }
+ }
+```
+
+#### 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](https://wiki.syslinux.org/wiki/index.php?title=Config) file shown below, which we named
+  [default](https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration).
+
+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](https://docs.python.org/2/library/simplehttpserver.html) and start serving the <span class="title-ref">filesystem.squashfs</span>
+file. The file can be found inside the <span class="title-ref">/live</span> directory of the
+extracted contents of the ISO file.
+
+**Second**, edit the configuration file of the `install_from_tftp`
+so that it shows the correct URL at
+`fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs`.
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+Do not change the name of the *filesystem.squashfs* file. If
+you are working with different versions, you can create different
+directories instead.
+
+</div>
+
+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`.
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+Make sure the available directories and files in both TFTP
+and HTTP server have the right permissions to be accessed from the
+booting clients.
+
+</div>
+
+### 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
+<span class="title-ref">Live system</span> option from the installation image.
+
+The workaround is to type <span class="title-ref">e</span> when the boot menu appears and edit the GRUB boot
+options. Specifically, remove the:
+
+<span class="title-ref">console=ttyS0,115200</span>
+
+option, and type CTRL-X to boot.
+
+Installation can then continue as outlined above.
diff --git a/docs/installation/md-update.md b/docs/installation/md-update.md
new file mode 100644
index 00000000..cff79228
--- /dev/null
+++ b/docs/installation/md-update.md
@@ -0,0 +1,110 @@
+# Update VyOS
+
+New system images can be added using the `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.
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+Only LTS releases are PGP-signed.
+
+</div>
+
+<div class="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 <span class="title-ref">add system image</span> 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.
+
+</div>
+
+If there is not enough **free disk space available**, the installation
+will be canceled. To delete images use the `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.
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+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.
+
+</div>
+
+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 `copy` command. So, for instance, in order
+to copy `/config/config.boot` from VyOS 1.2.1 image, you would use the
+following command:
+
+``` 
+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
+```
+
+<div class="hint">
+
+<div class="title">
+
+Hint
+
+</div>
+
+The most up-do-date Rolling Release for AMD64 can be accessed using
+the following URL:
+
+<https://vyos.net/get/nightly-builds/>
+
+</div>
+
+After reboot you might want to verify the version you are running with
+the `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..aaf2c78d
--- /dev/null
+++ b/docs/installation/md-vyos-on-baremetal.md
@@ -0,0 +1,609 @@
+# 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>
+<img src="/_static/images/1u_vyos_back.webp" alt="CSE-505-203B Back" />
+</figure>
+
+<figure>
+<img src="/_static/images/1u_vyos_front.webp" alt="CSE-505-203B Front" />
+</figure>
+
+<figure>
+<img src="/_static/images/1u_vyos_front_open_1.webp" alt="CSE-505-203B Open 1" />
+</figure>
+
+<figure>
+<img src="/_static/images/1u_vyos_front_open_2.webp" alt="CSE-505-203B Open 2" />
+</figure>
+
+<figure>
+<img src="/_static/images/1u_vyos_front_open_3.webp" alt="CSE-505-203B Open 3" />
+</figure>
+
+<figure>
+<img src="/_static/images/1u_vyos_front_10ge_open_1.webp" alt="CSE-505-203B w/ 10GE Open 1" />
+</figure>
+
+<figure>
+<img src="/_static/images/1u_vyos_front_10ge_open_2.webp" alt="CSE-505-203B w/ 10GE Open 2" />
+</figure>
+
+<figure>
+<img src="/_static/images/1u_vyos_front_10ge_open_3.webp" alt="CSE-505-203B w/ 10GE Open 3" />
+</figure>
+
+<figure>
+<img src="/_static/images/1u_vyos_front_10ge_open_4.webp" alt="CSE-505-203B w/ 10GE Open" />
+</figure>
+
+## 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.
+
+### 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 `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 `wireless-interface-intel-ax200`)
+
+##### WWAN
+
+Refer to `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 (`T1327`).
+
+Create a bootable USB pendrive using e.g. [Rufus](https://rufus.ie/) 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
+`installation`.
+
+### Pictures
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+Both device types operate without any moving parts and emit zero
+noise.
+
+</div>
+
+#### Rack Mount
+
+<figure>
+<img src="/_static/images/apu4_rack_1.webp" alt="APU4 rack closed" />
+</figure>
+
+<figure>
+<img src="/_static/images/apu4_rack_2.webp" alt="APU4 rack front" />
+</figure>
+
+<figure>
+<img src="/_static/images/apu4_rack_3.webp" alt="APU4 rack module #1" />
+</figure>
+
+<figure>
+<img src="/_static/images/apu4_rack_4.webp" alt="APU4 rack module #2" />
+</figure>
+
+<figure>
+<img src="/_static/images/apu4_rack_5.webp" alt="APU4 rack module #3 with PSU" />
+</figure>
+
+##### VyOS custom print
+
+<figure>
+<img src="/_static/images/apu4_rack_vyos_print.webp" alt="APU4 custom VyOS powder coat" />
+</figure>
+
+#### Desktop / Bench Top
+
+<figure>
+<img src="/_static/images/apu4_desk_1.webp" alt="APU4 desktop closed" />
+</figure>
+
+<figure>
+<img src="/_static/images/apu4_desk_2.webp" alt="APU4 desktop closed" />
+</figure>
+
+<figure>
+<img src="/_static/images/apu4_desk_3.webp" alt="APU4 desktop back" />
+</figure>
+
+<figure>
+<img src="/_static/images/apu4_desk_4.webp" alt="APU4 desktop back" />
+</figure>
+
+## 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>
+<img src="../_static/images/600px-Partaker-i5.webp" />
+</figure>
+
+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>
+<img src="../_static/images/480px-Acrosser_ANDJ190N1_Front.webp" />
+</figure>
+
+<figure>
+<img src="../_static/images/480px-Acrosser_ANDJ190N1_Back.webp" />
+</figure>
+
+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 <span class="title-ref">install image</span> CLI command.
+
+## 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>
+<img src="../_static/images/gowin-01.webp" />
+</figure>
+
+<figure>
+<img src="../_static/images/gowin-02.webp" />
+</figure>
+
+<figure>
+<img src="../_static/images/gowin-03.webp" />
+</figure>
+
+<figure>
+<img src="../_static/images/gowin-04.webp" />
+</figure>
+
+### 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 <span class="title-ref">install image</span> 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: `wwan-interface`
diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md
new file mode 100644
index 00000000..964b9f64
--- /dev/null
+++ b/docs/installation/virtual/md-docker.md
@@ -0,0 +1,65 @@
+# 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..b1bb2a1d
--- /dev/null
+++ b/docs/installation/virtual/md-gns3.md
@@ -0,0 +1,208 @@
+# 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 `installation` page
+- A working GNS3 installation. For further information see the
+  [GNS3 documentation](https://docs.gns3.com/).
+
+## 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>
+<img src="/_static/images/gns3-01.webp" />
+</figure>
+
+Select **Quemu VMs** and then click on the `New` button.
+
+<figure>
+<img src="/_static/images/gns3-02.webp" />
+</figure>
+
+Write a name for your VM, for instance "VyOS", and click `Next`.
+
+<figure>
+<img src="/_static/images/gns3-03.webp" />
+</figure>
+
+Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM
+and click `Next`.
+
+<figure>
+<img src="/_static/images/gns3-04.webp" />
+</figure>
+
+Select **telnet** as your console type and click `Next`.
+
+<figure>
+<img src="/_static/images/gns3-05.webp" />
+</figure>
+
+Select **New image** for the base disk image of your VM and click
+`Create`.
+
+<figure>
+<img src="/_static/images/gns3-06.webp" />
+</figure>
+
+Use the defaults in the **Binary and format** window and click
+`Next`.
+
+<figure>
+<img src="/_static/images/gns3-07.webp" />
+</figure>
+
+Use the defaults in the **Qcow2 options** window and click `Next`.
+
+<figure>
+<img src="/_static/images/gns3-08.webp" />
+</figure>
+
+Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu
+image creator**.
+
+<figure>
+<img src="/_static/images/gns3-09.webp" />
+</figure>
+
+Click `Finish` to end the **New QEMU VM template** wizard.
+
+<figure>
+<img src="/_static/images/gns3-10.webp" />
+</figure>
+
+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>
+<img src="/_static/images/gns3-11.webp" />
+</figure>
+
+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>
+<img src="/_static/images/gns3-12.webp" />
+</figure>
+
+At the **HDD** tab, change the Disk interface to **sata** to speed up
+the boot process.
+
+<figure>
+<img src="/_static/images/gns3-13.webp" />
+</figure>
+
+At the **CD/DVD** tab click on `Browse...` and locate the VyOS image
+you want to install.
+
+<figure>
+<img src="/_static/images/gns3-14.webp" />
+</figure>
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+You probably will want to accept to copy the .iso file to your
+default image directory when you are asked.
+
+</div>
+
+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>
+<img src="/_static/images/gns3-15.webp" />
+</figure>
+
+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>
+<img src="/_static/images/gns3-16.webp" />
+</figure>
+
+At the general **Preferences** window, click `OK` to save and close.
+
+<figure>
+<img src="/_static/images/gns3-17.webp" />
+</figure>
+
+## 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.
+- `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
+
+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>
+<img src="/_static/images/gns3-20.webp" />
+</figure>
+
+**CD/DVD** tab: Unmount the installation image file by clearing the
+**Image** entry field.
+
+<figure>
+<img src="/_static/images/gns3-21.webp" />
+</figure>
+
+Set the number of required network adapters, for example **4**.
+
+<figure>
+<img src="/_static/images/gns3-215.webp" />
+</figure>
+
+**Advanced** settings tab: Mark the checkbox **Use as a linked
+base VM** and click `OK` to save the changes.
+
+<figure>
+<img src="/_static/images/gns3-22.webp" />
+</figure>
+
+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..7ed572e4
--- /dev/null
+++ b/docs/installation/virtual/md-index.md
@@ -0,0 +1,12 @@
+# Running VyOS in Virtual Environments
+
+<div class="toctree" caption="Content">
+
+libvirt
+proxmox
+vmware
+gns3
+eve-ng
+docker
+
+</div>
diff --git a/docs/installation/virtual/md-libvirt.md b/docs/installation/virtual/md-libvirt.md
new file mode 100644
index 00000000..04a05ad0
--- /dev/null
+++ b/docs/installation/virtual/md-libvirt.md
@@ -0,0 +1,176 @@
+# 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 `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
+`VMM (Virtual Machine Manager)`.
+
+### Deploy from ISO
+
+1.  Open `VMM (Virtual Machine Manager)` and Create a new
+    `VM (Virtual Machine)`
+2.  Choose `Local install media` (ISO)
+
+<figure>
+<img src="/_static/images/virt-libvirt-01.webp" />
+</figure>
+
+3.  Choose path to iso vyos.iso. Operating System can be any Debian based.
+
+<figure>
+<img src="/_static/images/virt-libvirt-02.webp" />
+</figure>
+
+4.  Choose Memory and CPU
+
+<figure>
+<img src="/_static/images/virt-libvirt-03.webp" />
+</figure>
+
+5.  Disk size
+
+<figure>
+<img src="/_static/images/virt-libvirt-04.webp" />
+</figure>
+
+6.  Name of VM and network selection
+
+<figure>
+<img src="/_static/images/virt-libvirt-05.webp" />
+</figure>
+
+7.  Then you will be taken to the console.
+
+<figure>
+<img src="/_static/images/virt-libvirt-06.webp" />
+</figure>
+
+### 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 `VMM (Virtual Machine Manager)` and Create a new
+    `VM (Virtual Machine)`
+2.  Choose `Import existing disk` image
+
+<figure>
+<img src="/_static/images/virt-libvirt-qc-01.webp" />
+</figure>
+
+3.  Choose the path to the image `vyos_kvm.qcow2` that was previously
+    downloaded . Operation System can be any Debian based.
+
+<figure>
+<img src="/_static/images/virt-libvirt-qc-02.webp" />
+</figure>
+
+4.  Choose Memory and CPU
+
+<figure>
+<img src="/_static/images/virt-libvirt-03.webp" />
+</figure>
+
+5.  Name of VM and network selection
+
+<figure>
+<img src="/_static/images/virt-libvirt-05.webp" />
+</figure>
+
+6.  Then you will be taken to the console.
+
+<figure>
+<img src="/_static/images/virt-libvirt-qc-03.webp" />
+</figure>
diff --git a/docs/installation/virtual/md-proxmox.md b/docs/installation/virtual/md-proxmox.md
new file mode 100644
index 00000000..da4bd03b
--- /dev/null
+++ b/docs/installation/virtual/md-proxmox.md
@@ -0,0 +1,43 @@
+# 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 <span class="title-ref">local-lvm</span>.
+
+``` 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 <span class="title-ref">local</span> storage pool with the name <span class="title-ref">seed.iso</span>.
+
+``` 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 `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..6d693455
--- /dev/null
+++ b/docs/installation/virtual/md-vmware.md
@@ -0,0 +1,35 @@
+# 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 <span class="title-ref">install image</span>.
+
+:::{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>