diff options
Diffstat (limited to 'docs/installation')
| -rw-r--r-- | docs/installation/cloud/md-aws-ha.md | 132 | ||||
| -rw-r--r-- | docs/installation/cloud/md-aws-to-azure.md | 177 | ||||
| -rw-r--r-- | docs/installation/cloud/md-aws.md | 722 | ||||
| -rw-r--r-- | docs/installation/cloud/md-azure-ha.md | 130 | ||||
| -rw-r--r-- | docs/installation/cloud/md-azure.md | 449 | ||||
| -rw-r--r-- | docs/installation/cloud/md-gcp.md | 298 | ||||
| -rw-r--r-- | docs/installation/cloud/md-index.md | 13 | ||||
| -rw-r--r-- | docs/installation/cloud/md-oracel.md | 5 | ||||
| -rw-r--r-- | docs/installation/md-image.md | 131 | ||||
| -rw-r--r-- | docs/installation/md-index.md | 34 | ||||
| -rw-r--r-- | docs/installation/md-install.md | 504 | ||||
| -rw-r--r-- | docs/installation/md-update.md | 110 | ||||
| -rw-r--r-- | docs/installation/md-vyos-on-baremetal.md | 609 | ||||
| -rw-r--r-- | docs/installation/virtual/md-docker.md | 65 | ||||
| -rw-r--r-- | docs/installation/virtual/md-eve-ng.md | 5 | ||||
| -rw-r--r-- | docs/installation/virtual/md-gns3.md | 208 | ||||
| -rw-r--r-- | docs/installation/virtual/md-index.md | 12 | ||||
| -rw-r--r-- | docs/installation/virtual/md-libvirt.md | 176 | ||||
| -rw-r--r-- | docs/installation/virtual/md-proxmox.md | 43 | ||||
| -rw-r--r-- | docs/installation/virtual/md-vmware.md | 35 |
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> |