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

Backport of the swap mechanism from feat/incremental-myst-swap onto
the circinus release branch. Built directly on top of origin/circinus,
so the underlying RST tree is circinus'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 (all from origin/myst/circinus):
- 253 md-prefixed pages alongside each {name}.rst counterpart
- 1 plain MyST-only page kept at canonical name (docs/copyright.md,
  no .rst counterpart)
- 182 .webp images added (circinus release previously had only
  PNG/JPG; this PR brings webp into circinus alongside the originals)
- docs/_swap.txt populated with all 253 stems → MyST is served by
  default; revert a page by removing its stem from _swap.txt

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

5 files changed, 355 insertions, 0 deletions

diff --git a/docs/installation/cloud/md-aws.md b/docs/installation/cloud/md-aws.md
new file mode 100644
index 00000000..9692b5a6
--- /dev/null
+++ b/docs/installation/cloud/md-aws.md
@@ -0,0 +1,174 @@
+---
+lastproofread: '2026-02-06'
+---
+
+# Amazon AWS
+
+## Deploy VM
+
+Deploy VyOS on Amazon {abbr}`AWS (Amazon Web Services)`.
+
+1. Click **Instances** and then click **Launch Instance**.
+
+:::{figure} /_static/images/cloud-aws-01.webp
+:::
+
+2. Search for "VyOS" in the Marketplace.
+
+:::{figure} /_static/images/cloud-aws-02.webp
+:::
+
+3. Choose the instance type. The recommended minimum is `m3.medium`.
+
+:::{figure} /_static/images/cloud-aws-03.webp
+:::
+
+4. Configure the instance for your requirements. Select the number of
+   instances, network, and subnet.
+
+:::{figure} /_static/images/cloud-aws-04.webp
+:::
+
+5. Configure additional storage. You can remove the additional storage
+   `/dev/sdb`. The root device will be `/dev/xvda`. You can skip this step.
+
+:::{figure} /_static/images/cloud-aws-05.webp
+:::
+
+6. Configure the security group. We recommend configuring SSH access
+   only from specific sources, or you can permit any IP address (the default).
+
+:::{figure} /_static/images/cloud-aws-06.webp
+:::
+
+7. Select the SSH key pair and click **Launch Instances**.
+
+:::{figure} /_static/images/cloud-aws-07.webp
+:::
+
+8. Note your public IP address.
+
+:::{figure} /_static/images/cloud-aws-08.webp
+:::
+
+9. Connect to the instance using your SSH key.
+
+```none
+ssh -i ~/.ssh/amazon.pem vyos@203.0.113.3
+vyos@ip-192-0-2-10:~$
+```
+
+## Amazon CloudWatch Agent Usage
+
+To use the Amazon CloudWatch agent, configure it in the Amazon Systems Manager
+Parameter Store. For instructions on creating a configuration, see
+{ref}`configuration_creation`.
+
+1. Create an {abbr}`IAM (Identity and Access Management)` role for the
+   {abbr}`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 {abbr}`EC2 (Elastic Compute Cloud)`
+   instance.
+3. Ensure the amazon-cloudwatch-agent package is installed.
+
+```none
+$ sudo apt list --installed | grep amazon-cloudwatch-agent
+```
+
+>
+> :::{note}
+> The amazon-cloudwatch-agent package is normally included in
+> VyOS 1.3.3+ and 1.4+
+> :::
+
+4. Retrieve an existing CloudWatch Agent configuration from the
+   {abbr}`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.
+>
+> :::{note}
+> The VyOS platform-specific scripts feature is under development.
+> Thus, this step should be repeated manually after changing system image
+> ({doc}`/installation/update`)
+> :::
+
+(configuration_creation)=
+
+### CloudWatch SSM Configuration creation
+
+Creating the Amazon Cloudwatch Agent Configuration in Amazon
+{abbr}`SSM (Systems Manager)` Parameter Store.
+
+1. Create an {abbr}`IAM (Identity and Access Management)` role for your
+   {abbr}`EC2 (Elastic Compute Cloud)` instance to access the CloudWatch
+   service. Name it `CloudWatchAgentAdminRole`. The role must contain at
+   least two policies: `CloudWatchAgentAdminPolicy` and
+   `AmazonSSMManagedInstanceCore`.
+
+> :::{note}
+> CloudWatchAgentServerRole is too permissive and should be used only
+> for
+> creating and deploying a single configuration. After step 3, we recommend
+> replacing the `CloudWatchAgentAdminRole` with the
+> `CloudWatchAgentServerRole`.
+> :::
+
+2. Run the CloudWatch configuration wizard.
+
+```none
+$ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard
+```
+
+3. When prompted, enter "yes" to the question "Do you want to store the
+   config in the SSM parameter store?".
+
+## AWS Gateway Load Balancer
+
+VyOS supports the AWS Gateway Load Balancer (GWLB) tunnel handler (`gwlbtun`),
+which enables VyOS to act as an inspection or processing target for GWLB. GWLB
+uses Geneve encapsulation with custom metadata to deliver traffic to VyOS for
+packet filtering, shaping, deep packet inspection, NAT, or other traffic
+manipulation functions. The tunnel handler automatically creates Linux tunnel
+interfaces (`gwi-*` for ingress and `gwo-*` for egress) per endpoint,
+allowing you to use standard Linux utilities like iptables, tc, and netfilter
+to implement your inspection or processing logic. This enables VyOS to serve as
+a centralized appliance for traffic inspection in your AWS infrastructure,
+supporting both single-endpoint (1-arm) and multi-endpoint (2-arm) deployment
+modes.
+
+
+For more information about integrating with AWS Gateway Load Balancer, see
+the following article from AWS:
+[How to integrate Linux instances with AWS Gateway Load Balancer](https://aws.amazon.com/blogs/networking-and-content-delivery/how-to-integrate-linux-instances-with-aws-gateway-load-balancer/).
+
+
+### Configuration Example
+
+Configure the AWS GWLB service with the following commands:
+
+```none
+set service aws glb script on-create '/config/scripts/glb-create.sh'
+set service aws glb script on-destroy '/config/scripts/glb-destroy.sh'
+set service aws glb status format 'simple'
+set service aws glb status port '8282'
+set service aws glb threads tunnel '4'
+set service aws glb threads tunnel-affinity '1-2'
+set service aws glb threads udp '4'
+set service aws glb threads udp-affinity '0-3'
+```
+
+
+## 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>
+- <https://aws.amazon.com/blogs/networking-and-content-delivery/how-to-integrate-linux-instances-with-aws-gateway-load-balancer/>
+
diff --git a/docs/installation/cloud/md-azure.md b/docs/installation/cloud/md-azure.md
new file mode 100644
index 00000000..a865912e
--- /dev/null
+++ b/docs/installation/cloud/md-azure.md
@@ -0,0 +1,88 @@
+---
+lastproofread: '2026-02-09'
+---
+
+# Azure
+
+## Deploy VM
+
+Deploy VyOS on Azure.
+
+1. Go to Azure services and click **Add new Virtual machine**.
+2. Choose a VM name, resource group, and region, then click **Browse all public
+   and private images**.
+
+:::{figure} /_static/images/cloud-azure-01.webp
+:::
+
+3. Search for "VyOS" in the marketplace and choose the appropriate
+   subscription.
+
+:::{figure} /_static/images/cloud-azure-02.webp
+:::
+
+4. Generate new SSH key pair or use existing.
+
+:::{figure} /_static/images/cloud-azure-03.webp
+:::
+
+5. Configure the network, subnet, and public IP. Or use the defaults.
+
+:::{figure} /_static/images/cloud-azure-04.webp
+:::
+
+6. Click **Review + create**. Your deployment completes in a few seconds.
+
+:::{figure} /_static/images/cloud-azure-05.webp
+:::
+
+7. Select your new VM and note your public IP address.
+
+:::{figure} /_static/images/cloud-azure-06.webp
+:::
+
+8. Connect to the instance with your SSH key.
+
+```none
+ssh -i ~/.ssh/vyos_azure vyos@203.0.113.3
+vyos@vyos-doc-r1:~$
+```
+
+## Add interface
+
+If your instance was deployed with one **eth0** (`WAN`) interface and you
+want to add another, you must shut down the instance. To add a new interface,
+such as **eth1** (`LAN`), attach it in the Azure portal and then restart the
+instance.
+
+:::{note}
+Azure doesn't allow you to attach an interface while the instance is
+running.
+:::
+
+## Absorbing Routes
+
+If you're using the VM as a router, you can use a route table to absorb some or
+all traffic from your virtual network (VNET) with your LAN interface.
+
+1. Create a route table and navigate to **Configuration**.
+2. Add one or more routes for the networks you want to route through the VyOS
+   VM. For **Next hop type**, select **Virtual Appliance** and set the **Next
+   Hop Address** to the VyOS `LAN` interface.
+
+:::{note}
+To create a default route for VMs on the subnet, use
+**Address Prefix** `0.0.0.0/0`. For a typical edge device configuration,
+configure masquerade NAT on the `WAN` interface.
+:::
+
+## Serial Console
+
+VyOS includes serial console support by default. However, if you replace the
+`config.boot` file and reboot, ensure this configuration is present:
+
+`set system console device ttyS0 speed '9600'`
+
+## References
+
+<https://azure.microsoft.com>
diff --git a/docs/installation/cloud/md-gcp.md b/docs/installation/cloud/md-gcp.md
new file mode 100644
index 00000000..1df20864
--- /dev/null
+++ b/docs/installation/cloud/md-gcp.md
@@ -0,0 +1,60 @@
+---
+lastproofread: '2026-02-09'
+---
+
+# Google Cloud Platform
+
+## Deploy VM
+
+To deploy VyOS on Google Cloud Platform (GCP):
+
+1. Generate an SSH key pair of type **ssh-rsa** on the host that will connect
+   to VyOS.
+
+   Example:
+
+   ```none
+   ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc"
+   ```
+
+:::{note}
+The SSH key comment must begin with `vyos@` because that's the
+default VyOS user. GCP uses this value to set the username on the instance.
+:::
+
+2. Open the GCP Console and navigate to **Metadata**. Select **SSH Keys** and
+   click **Edit**.
+
+:::{figure} /_static/images/cloud-gcp-01.webp
+Click **Add item**, paste your public SSH key, and click **Save**.
+:::
+
+:::{figure} /_static/images/cloud-gcp-02.webp
+:::
+
+3. Search for "VyOS" in the Marketplace.
+4. Configure the deployment name, zone, and machine type, then click **Deploy**.
+
+:::{figure} /_static/images/cloud-gcp-03.webp
+:::
+
+5. After a few seconds, select your **instance**.
+
+:::{figure} /_static/images/cloud-gcp-04.webp
+:::
+
+6. Note your external IP address.
+
+:::{figure} /_static/images/cloud-gcp-05.webp
+:::
+
+7. Connect to the instance using the SSH key you generated in step 1.
+
+```none
+ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3
+vyos@vyos-r1-vm:~$
+```
+
+## References
+
+<https://console.cloud.google.com/>
diff --git a/docs/installation/cloud/md-index.md b/docs/installation/cloud/md-index.md
new file mode 100644
index 00000000..cf7d447d
--- /dev/null
+++ b/docs/installation/cloud/md-index.md
@@ -0,0 +1,10 @@
+# Cloud Environments
+
+```{toctree}
+:caption: Content
+
+aws
+azure
+gcp
+oracle
+```
diff --git a/docs/installation/cloud/md-oracle.md b/docs/installation/cloud/md-oracle.md
new file mode 100644
index 00000000..ee49057b
--- /dev/null
+++ b/docs/installation/cloud/md-oracle.md
@@ -0,0 +1,23 @@
+lastproofread  
+2026-02-09
+
+# Oracle
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+This page is a stub and needs expansion.
+Contributions welcome via the
+VyOS [documentation repository](https://github.com/vyos/vyos-documentation).
+
+</div>
+
+## References
+
+<https://www.oracle.com/cloud/>
+<https://docs.oracle.com/en/cloud/paas/developer-cloud-classic/csdcc/deploy-application.html>