Skip to content

Knowledge Base#

How to Import a RedHat / RHEL / CentOS based VM

Overview

Key Points

  • Redhat/CentOS installs drivers only for the detected hardware during installation.
  • Imported VMs may fail to boot due to missing drivers for new hardware.
  • You can resolve these boot issues by adjusting hardware configuration and regenerating the initramfs.

This guide explains how to import Redhat/CentOS based virtual machines from other hypervisors into VergeOS. It addresses potential problems like VMs not booting or lacking network connectivity after migration.

Prerequisites

  • Access to VergeOS and the VergeOS UI.
  • Familiarity with the hypervisor environment and VM configuration.
  • Imported VM files must be present in the VergeOS environment.

Steps

1. Update VM Hardware Configuration

  1. Change all hard drives to virtio-scsi:

    • In the VergeOS UI, navigate to the VM's settings.
    • For each hard drive, change the interface to virtio-scsi for optimal performance and compatibility.
  2. Change all NICs to virtio:

    • Ensure that all network interface cards (NICs) are set to virtio for enhanced networking support.
  3. Adjust Boot Order:

    • Make sure that the OS disk is listed as ID 0 in the boot order.

2. Boot into Rescue Mode

  1. Start the VM:

    • Power on the VM, and during boot, hold the Left Shift key to access the GRUB boot menu.
  2. Select Rescue Mode:

    • In the GRUB menu, select the rescue mode to boot into a minimal recovery environment.

3. Rebuild Initramfs

  1. Log into the Terminal:

    • Once in rescue mode, access the terminal via the VM console.
  2. Regenerate Initramfs:

    • Run the following command to regenerate the initramfs with the necessary drivers:
      sudo dracut -f --regenerate-all --add-drivers "virtio_blk virtio_net"
      
    • This command adds drivers for virtio_blk (block device) and virtio_net (network device) to the initramfs, allowing the VM to boot with the correct drivers for VergeOS.

4. Reboot and Verify

  1. Reboot the VM:

    • After regenerating the initramfs, reboot the VM by running:
      reboot
      
  2. Verify Boot and Network Connectivity:

    • Confirm that the VM boots successfully and that network connectivity is functional via the virtio NIC.

Troubleshooting

Common Issues

  • VM is not booting:
  • Solution: Double-check the boot order in the VM settings. The OS disk must be set as ID 0.
  • No network connectivity:
  • Solution: Ensure that NICs are set to virtio and that the initramfs was rebuilt with the appropriate network drivers.

Additional Resources

Feedback

Need Help?

If you have any questions or encounter issues while importing a VM, please reach out to our support team for assistance.


Document Information

  • Last Updated: 2024-09-09
  • VergeOS Version: 4.12.6

API Guide

Overview

The VergeOS API allows developers to interact with the VergeOS system programmatically. It provides access to system operations such as creating virtual machines, managing resources, and interacting with billing and catalog repositories. The API uses standard REST-like conventions and supports multiple authentication methods. This guide provides an overview of the VergeOS API, endpoint documentation, example requests, and error handling.

This document outlines the usage of the API. Detailed information for the API can be found within the VergeOS UI as a Swagger documentation page, which is dynamically generated and shows a complete listing of available API tables and operations.

Swagger Interface

To access the Swagger documentation in the VergeOS UI:

  1. Login to the VergeOS system with valid credentials.
  2. From the Main Dashboard, click System in the left menu.
  3. In the System Dashboard, find the API Documentation link at the bottom left and click it.
  4. The Swagger documentation page will open. This page provides detailed examples for each API operation, including the ability to test the API directly.

Swagger Documentation Example

  1. Select an individual table and choose one of the available GET/POST/DELETE/PUT options to view and test API actions.

Swagger Documentation Example

  1. Specify the parameters and click the Execute Button to run the API command. This will return the response, which includes the response body, header, and a curl example.

Swagger Documentation Example

API Basics

HTTP Methods

The VergeOS API uses standard HTTP methods like GET, POST, PUT, and DELETE for resource manipulation.

GET Parameters

  • fields: Specify which fields to return in the result set.
  • filter: Filter the result set based on certain criteria.
  • sort: Sort the results by a specified field.
  • limit: Limit the number of returned results.

Authentication

All API requests must be made over HTTPS and require authentication using basic access authentication or a session token.

Additional Notes

  • Rate Limits: The API supports a maximum of 1000 requests per hour per API key.
  • Data Formats: All responses are returned in JSON format.
  • Pagination: Endpoints that return large sets of data support pagination using offset and limit query parameters.

Authentication

VergeOS supports two methods of authentication:

  1. Basic HTTP Authentication
    The API is available only through SSL.

  2. Token-based Authentication
    Developers must request a token from the API by posting to the /sys/tokens endpoint. The token is then passed in subsequent API requests in the x-yottabyte-token header.

Example Authentication Request

To obtain a token:

curl --header "X-JSON-Non-Compact: 1" --basic --data-ascii '{"login": "USERNAME", "password": "PASSWORD"}' --insecure --request "POST" --header 'Content-Type: application/json' 'https://your-verge-instance.com/api/sys/tokens'

Example response:

{
   "location":"\\/sys\\/tokens\\/3a334563456378845634563b7b82d2efcadce9",
   "dbpath":"tokens\\/3a334563456378845634563b7b82d2efcadce9",
   "$row":1,
   "$key":"3a334563456378845634563b7b82d2efcadce9"
}

Use the token from the "$key" field in all subsequent requests:

x-yottabyte-token: 3a334563456378845634563b7b82d2efcadce9

To log out, send a DELETE request to the /sys/tokens/{token} endpoint.

Example Logout Request

DELETE /sys/tokens/3a334563456378845634563b7b82d2efcadce9

Example Virtual Machines

The VMs section of the VergeOS API allows users to manage virtual machines programmatically. It includes endpoints to list, create, modify, and delete VMs.

Retrieve a List of Virtual Machines

Endpoint:
GET /v4/vms?fields=most

Description:
Retrieves a list of all VMs in the system with details such as CPU cores, RAM, machine type, and configuration details.

Example Request:

curl -X 'GET' \
  'https://your-verge-instance.com/api/v4/vms?fields=most' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-token>'

Example Response:

[
  {
    "$key": 1,
    "name": "CentOS 7 (Latest) 1.0-7",
    "machine": 7,
    "cpu_cores": 2,
    "cpu_type": "Cascadelake-Server",
    "ram": 2048,
    "os_family": "linux",
    "is_snapshot": true,
    "boot_order": "cd",
    "rtc_base": "utc",
    "console": "vnc",
    "uefi": false,
    "secure_boot": false,
    "serial_port": true,
    "uuid": "d3914756-4ec5-9dfe-5c45-b28af2fd3d73",
    "created": 1724435418,
    "modified": 1724435418
  }
]

Overview of the Data Returned:

  • $key: The unique identifier for the VM.
  • name: The name of the virtual machine.
  • machine: Machine ID associated with the VM.
  • cpu_cores: Number of CPU cores allocated to the VM.
  • ram: Amount of RAM allocated (in MB).
  • os_family: Operating system type.
  • uuid: Universally unique identifier (UUID) for the VM.
  • created: The creation timestamp.
  • modified: The last modified timestamp.

Create a New Virtual Machine

Endpoint:
POST /v4/vms

Description:
Creates a new virtual machine with specific configuration details, such as CPU cores, RAM, machine type, boot order, etc.

Example Request:

curl -X 'POST' \
  'https://your-verge-instance.com/api/v4/vms' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "rest",
    "description": "test",
    "machine_type": "pc-q35-9.0",
    "allow_hotplug": true,
    "cpu_cores": 1,
    "cpu_type": "Broadwell",
    "ram": 1024,
    "os_family": "linux",
    "boot_order": "cd",
    "uefi": false,
    "note": "test vm"
  }'

Example Response:

{
  "location": "/v4/vms/36",
  "dbpath": "vms/36",
  "$row": 36,
  "$key": "36"
}

Overview of the Data Returned:

  • location: The location of the newly created VM resource.
  • dbpath: Database path of the new VM.
  • $row: Row ID of the VM.
  • $key: Unique key for the VM.

Example Virtual Networks (Vnets)

The Vnets section of the VergeOS API allows users to manage virtual networks (Vnets) programmatically. It includes endpoints to retrieve, create, and manage network resources, including internal and external networks, and allows advanced options like rate limiting.

Retrieve Vnet Details

Endpoint:
GET /v4/vnets?fields=most

Description:
Retrieves a list of all Vnets in the system with details such as network type, MTU, DHCP settings, and DNS configuration.

Example Request:

curl -X 'GET' \
  'https://your-verge-instance.com/api/v4/vnets?fields=most' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-token>'

Example Response:

[
  {
    "$key": 6,
    "name": "Internal Test 1",
    "advanced_options": {
      "dnsmasq": [
        "--dhcp-boot=netboot.xyz.kpxe,,192.168.10.20",
        "--dhcp-match=set:efi-x86,option:client-arch,6",
        "--dhcp-boot=tag:efi-x86,netboot.xyz.efi,,192.168.10.20",
        "--dhcp-match=set:efi-x86_64,option:client-arch,7",
        "--dhcp-boot=tag:efi-x86_64,netboot.xyz.efi,,192.168.10.20",
        "--dhcp-match=set:efi-x86_64,option:client-arch,9",
        "--dhcp-boot=tag:efi-x86_64,netboot.xyz.efi,,192.168.10.20"
      ]
    },
    "type": "internal",
    "layer2_type": "vxlan",
    "network": "192.168.100.0/24",
    "mtu": 9000,
    "dhcp_enabled": true,
    "dhcp_start": "192.168.100.100",
    "dhcp_stop": "192.168.100.200",
    "rate_limit": 0,
    "rate_limit_type": "mbytes/second",
    "gateway": ""
  }
]

Overview of the Data Returned:

  • $key: The unique identifier for the Vnet.
  • name: Name of the virtual network.
  • advanced_options: Advanced options to be passed to services running inside the network, in this example netboot flags for dnsmasq
  • type: Network type (e.g., "internal").
  • layer2_type: The type of Layer 2 networking, such as VXLAN.
  • network: Network CIDR block.
  • mtu: Maximum Transmission Unit (MTU) size.
  • dhcp_enabled: Indicates whether DHCP is enabled for this network.
  • dhcp_start: Starting IP address for the DHCP pool.
  • dhcp_stop: Ending IP address for the DHCP pool.
  • rate_limit: Rate limit for the network (in mbytes/second).
  • gateway: The default gateway for the network.

Create an Internal Network with Rate Limiting

Endpoint:
POST /v4/vnets

Description:
Creates a new internal virtual network with rate limiting and DHCP settings.

Example Request:

curl -X 'POST' \
  'https://your-verge-instance.com/api/v4/vnets' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"int1",
    "description":"workloads",
    "type":"internal",
    "mtu":"9000",
    "network":"192.168.80.0/24",
    "gateway":"192.168.80.1",
    "dnslist":"1.1.1.1",
    "dhcp_enabled": true,
    "rate_limit": 100,
    "rate_limit_burst": 500,
    "dhcp_start":"192.168.80.100",
    "dhcp_stop":"192.168.80.200"
  }'

Example Response:

{
  "location": "/v4/vnets/8",
  "dbpath": "vnets/8",
  "$row": 8,
  "$key": "8"
}

Overview of the Data Returned: - location: The location of the newly created Vnet resource. - dbpath: Database path of the new Vnet. - \(row**: Row ID of the Vnet. - **\)key: Unique key for the Vnet.


Here's the Resources section formatted for the API guide:

Resources

Below is an example URL used to query a list of machines.

Example: https://user1:xxxxxx@server1.verge.io/api/v4/machines?fields=all

https:// user : password @ server /api /v4/machines ? filter=&fields=all&sort=&limit=
User name User Password Server host name or IP Resource location (URI) These options are described below

GET Options

Fields
  • Specify which fields to return in the result set (may also be a view if there is one defined for the table schema).
  • all returns every field.
  • most returns most fields except for argument fields and rows.
  • summary returns fields marked as 'summary' in their schema.
  • Example: fields=name,email,enabled,groups[all] as all_groups,collapse(groups[name]) as first_groups_name

Field functions: - collapse - datetime - upper - lower - count - diskspace - display - hex - sha1 - sum - avg - min - max

Filter
  • Filter result sets by specified criteria.
  • Similar to OData.
  • Example: filter=enabled eq true and size gt 1048576.
  • Example: filter=cputype eq 'qemu' or cputype eq 'kvm'.
Operator Description
eq Equal
ne Not equal
gt Greater than
ge Greater than or equal
lt Less than
le Less than or equal
bw Begins with
ew Ends with
and Logical and
or Logical or
cs Contains string (case sensitive)
ct Contains text (case insensitive)
rx Regex match
Sort
  • Sort results by the specified field.
  • Example: sort=+name.
  • Example: sort=-id.
Limit
  • limit (integer) limits the result set to a specified number of entries. A value of 0 means unlimited.
  • Example: limit=1.

Generic HTTP Response Codes

  • 400 - Bad Request: The request was invalid.
  • 401 - Failed Login / Login Required: Authentication failed or is required.
  • 403 - Permission Denied: You lack the required permissions.
  • 404 - Resource Not Found: The requested row or API does not exist.
  • 405 - Not Permitted: The operation is not allowed.
  • 409 - Row Exists: The resource already exists.
  • 422 - Failed Validation / Invalid Parameter: Validation failed.
  • 500 - Internal Server Error: An unhandled error occurred.
POST-Specific
  • 201 - Created: A new row/resource was successfully created.
Websocket-Specific (Used for VNC/SPICE)
  • 101 - Switching Protocols: The protocol was successfully switched.
PUT/GET/DELETE
  • 200 - Success: The operation completed successfully.

Schema Table Definitions

Field Types
  • bool
  • text
  • string
  • num
  • uint8
  • uint16
  • uint32
  • uint64
  • int8
  • int16
  • int32
  • int64
  • enabled
  • created
  • created_ms
  • created_us
  • modified
  • modified_ms
  • modified_us
  • filename
  • filesize
  • fileused
  • fileallocated
  • filemodified
  • json
  • row
  • rows
Schema Owner / Parent Field
  • Owner Field: If the owner field is null, normal permissions apply. If the owner field has a value, permissions are replaced by a permission check to the owner.
  • Parent Field: The permission check is applied to the row itself, and if permissions fail, permissions are also checked on the parent row.

Full Table Schema

To retrieve a table’s schema, append $table to the URI:

/api/v4/machines/$table (replace "machines" with the table name).

You will be prompted for your credentials; this requires VergeOS admin credentials. The output will be in JSON format. Firefox displays this in a readable format by default, but other browsers may require exporting the JSON to an external program for better readability.


Example Errors

Example Error (HTTP Code 422)
{
  "err": "Validation error on field: 'dhcp_start' - 'fails validation test'"
}

VergeOS uses standard HTTP status codes to indicate the result of an API request.

  • 400 Bad Request: The request is invalid or cannot be processed.
  • 401 Unauthorized: The API key is missing or invalid.
  • 403 Forbidden: The API key lacks the required permissions.
  • 404 Not Found: The resource does not exist.
  • 500 Internal Server Error: A server error occurred.

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Terraform VergeIO Provider

The Terraform VergeIO Provider enables the integration and automation of VergeOS infrastructure with Terraform. It allows users to define, manage, and scale VergeOS resources as part of Infrastructure as Code (IaC) workflows.

For the latest provider documentation and examples, please refer to the following:


Example Usage

For more detailed usage examples, check the docs folder in the GitHub repository.

Example Configuration

provider "vergeio" {
  host     = "https://some_url_or_ip"
  username = "my_user"
  password = "my_password"
  insecure = false  # Use true if using self-signed SSL certificates
}

resource "vergeio_vm" "new_vm" {
  name        = "NEW VM"
  description = "NEW TF VM"
  enabled     = true
  os_family   = "linux"
  cpu_cores   = 4
  machine_type = "q35"
  ram         = 8192
}

Initializing and Applying

To apply the configuration:

terraform init && terraform apply

Configuration Reference

host (Required): URL or IP address for the VergeOS system or tenant.
username (Required): Username for the VergeOS system or tenant.
password (Required): Password for the provided username.
insecure (Optional): Set to true for systems using self-signed SSL certificates.

Resources

The following VergeOS resources can be managed via Terraform:

vergeio_drive
vergeio_member
vergeio_network
vergeio_nic
vergeio_user
vergeio_vm

Data Sources

The following data sources are available for querying VergeOS resources:

vergeio_clusters
vergeio_groups
vergeio_mediasources
vergeio_networks
vergeio_nodes
vergeio_version
vergeio_vms

Testing a Sample Configuration

To test your configuration, create a main.tf file in your Terraform workspace:

terraform {
  required_providers {
    vergeio = {
      source = "vergeio/cloud/vergeio"
    }
  }
}

provider "vergeio" {
  host     = "https://someURLorIP"
  username = "username"
  password = "password"
}

resource "vergeio_vm" "new_vm" {
  name        = "NEW VM"
  description = "NEW TF VM"
  enabled     = true
  os_family   = "linux"
  cpu_cores   = 4
  machine_type = "q35"
  ram         = 8192
}

Then, run the following command:

terraform init && terraform apply

Document Information

  • Last Updated: 2024-09-03
  • VergeOS Version: 4.12.6

Updating a VergeOS System with Airgap License

Overview

Key Points

  • This guide details the process of manually updating a VergeOS system using an air-gap license.
  • The update is performed using an ISO file, ensuring that systems without internet access can be kept up-to-date.
  • Ensure you have a valid air-gap license and the latest ISO file before starting.

This guide provides a step-by-step process to manually update your air-gapped VergeOS system using an ISO file.

Prerequisites

  • Access to the VergeOS Cloud Dashboard.
  • The latest VergeOS update ISO file.
  • A valid air-gap license.
  • A recent backup of your VergeOS system.

Steps

  1. Download the Update ISO - Visit the VergeOS updates page at https://updates.verge.io/download. - Download the latest VergeOS release ISO file.

!!! tip "Pro Tip" Ensure that the ISO file corresponds to your current VergeOS version to avoid compatibility issues.

  1. Upload the ISO to VergeOS - Log in to your VergeOS Cloud Dashboard. - Navigate to Media Images in the left-hand menu. - Upload the downloaded ISO file to the Media Images section.

!!! note The upload process may take a few minutes depending on your network speed.

  1. Configure Update Settings - Go to System > Updates > Edit Settings. - In the Update Source dropdown menu, select -- Update ISO --. - Choose the ISO file you just uploaded from the Media Images. - Click Submit to save the settings.

  2. Perform the Update - Return to the Updates section and click Check For Updates. - Once the update is detected, click Download. - After the download completes, click Install. - Follow the prompts to Reboot the system to apply the updates.

!!! warning "Important" Do not interrupt the update process. Ensure that the system remains powered on and connected during the update.

Troubleshooting

Common Issues

  • Issue: Update not detected after uploading the ISO.
  • Solution: Ensure the ISO was uploaded correctly and reselect it in the Update Source settings.

  • Issue: Errors during the update process.

  • Solution: Check system logs for detailed error messages and verify that your air-gap license is valid.

  • Issue: System fails to reboot after the update.

  • Solution: Contact Verge support for assistance.

Additional Resources

Feedback

Need Help?

If you encounter any issues during the update process or have any questions, please reach out to our support team.


Document Information

  • Last Updated: 2024-08-19
  • VergeOS Version: 4.12.6

Requesting an Airgap License for VergeOS

Overview

Key Points

  • VergeOS requires a valid license for operation
  • Airgapped environments need a special airgap license
  • The process involves generating a license request file and emailing it to Verge

This guide walks you through the process of requesting an airgap license for VergeOS systems in environments without outbound Internet access.

Prerequisites

  • Access to the VergeOS Cloud Dashboard
  • A working email client on a machine that can send external emails
  • Understanding of your system's airgapped status

Steps

  1. Navigate to System Settings - From the Cloud Dashboard, click System on the left menu - Click Settings on the left menu

  2. Initiate License Request - In the License section, click the Request License button

  3. Generate License Request File - A popup window titled "Request Generated" will appear - This window displays information about the license request file

  4. Download Request File - Click the Download Request File button - Save the license request file to your local machine

  5. Prepare Email to Verge - Click the Email license@Verge.io button - This opens your default email client with a pre-addressed email

  6. Send License Request - Attach the downloaded license request file to the email - Provide additional information in the email body (e.g., company name, purpose of license) - Send the email to Verge's licensing team

What Happens Next

  1. Verge processes your request and generates an airgap license file
  2. You receive a reply email with the airgap license file attached
  3. Upload the received license file to your VergeOS system (covered in a separate guide)

Processing Time

If you haven't received a response within 2 business days, please follow up with Verge's support team.

Important Considerations

  • Ensure the system requesting the license is the one you intend to license
  • Keep the license request file secure
  • For multiple systems, repeat this process for each system individually

Troubleshooting

Common Issues

  • Problem: Unable to generate license request file
  • Solution: Verify your access permissions in the VergeOS Cloud Dashboard

  • Problem: Email client doesn't open automatically

  • Solution: Manually compose an email to license@Verge.io and attach the downloaded request file

Additional Resources

  • [Understanding VergeOS Licensing]
  • [Uploading an Airgap License to VergeOS]
  • [VergeOS System Requirements]

Feedback

Need Help?

If you encounter any issues while requesting an airgap license or have questions about this process, please don't hesitate to contact our support team.


Document Information

  • Last Updated: 2024-09-09T15:41:14.296Z
  • VergeOS Version: 4.12.6

How to Achieve Network Micro-Segmentation on VergeOS

Network micro-segmentation is a security approach that divides a network into isolated segments, each with its own security controls. This article explains how to implement micro-segmentation using VergeOS's powerful networking features.

Key Features for Micro-Segmentation

VergeOS provides several features that enable effective network micro-segmentation:

  1. Internal Networks: Create multiple isolated virtual networks.
  2. Network Rules: Implement granular firewall rules.
  3. IPSec and WireGuard VPNs: Establish encrypted tunnels between networks.
  4. Tenant Isolation: Separate virtual data centers for strong multi-tenancy.
  5. Network Aliases: Group IP addresses/networks for easier policy management.
  6. Port Mirroring: Monitor traffic for security analysis.

Implementing Micro-Segmentation

Follow these steps to achieve network micro-segmentation on VergeOS:

1. Design Your Network Topology

  • Create separate internal networks for different applications or workloads.
  • Each internal network provides a default-secure environment.

Example:

- Web Application Network
- Database Network
- Management Network
- Development Network

2. Configure Network Rules

Use network rules to control traffic between internal networks and VMs:

  1. Navigate to the network dashboard.
  2. Select "Rules" from the left menu.
  3. Click "New" to create a rule.
  4. Set the action (e.g., Accept, Drop), protocol, and direction.
  5. Define source and destination networks/IPs.
  6. Apply the rule.

Example rule: Allow web servers to access the database on a specific port:

Action: Accept
Protocol: TCP
Direction: Outgoing
Source: Web Application Network
Destination: Database Network
Destination Port: 3306

3. Utilize Network Aliases

Group IP addresses or networks for easier policy management:

  1. Go to the network dashboard.
  2. Select "Aliases" from the left menu.
  3. Click "New" to create an alias.
  4. Name the alias and add IP addresses or networks.
  5. Use the alias in network rules.

Example:

Alias Name: Web Servers
IP Addresses: 192.168.1.10, 192.168.1.11, 192.168.1.12

4. Implement VPN Tunnels

For sensitive traffic between networks, use IPSec or WireGuard VPNs:

  1. Navigate to the VPN configuration section.
  2. Choose IPSec or WireGuard.
  3. Configure the VPN settings (e.g., encryption, authentication).
  4. Apply the VPN to the desired networks.

5. Leverage Tenant Isolation

For multi-tenant environments:

  • Create separate tenants for different departments or customers.
  • Each tenant has its own set of isolated internal networks.

6. Monitor and Adjust

Use port mirroring to monitor traffic:

  1. Go to the network dashboard.
  2. Enable port mirroring for the networks you want to monitor.
  3. Analyze the traffic and adjust network rules as needed.

Best Practices

  • Follow the principle of least privilege: only allow necessary traffic.
  • Regularly review and update network rules.
  • Use descriptive names for networks, rules, and aliases.
  • Document your network topology and segmentation strategy.

By utilizing these features and following these steps, you can create a highly segmented network architecture on VergeOS, implementing zero trust principles and reducing the potential attack surface.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

API Helper Script

The yb-api helper script provides an easy way for developers to interact with the VergeOS API. It simplifies making API calls, such as retrieving virtual machines, updating configurations, and managing resources. This guide will outline the key commands and usage of the yb-api script.

Prerequisites

  • Access to a VergeOS system.
  • Access to the cluster via SSH or direct connection.
  • wget and curl must be installed on the system for certain operations.

Running the Helper Script

To get help or view the available options, run:

yb-api --help

Connect to the node and execute this command to begin using the API helper.

yb-api Example

Example Commands

Below are examples of how to use yb-api for various VM management tasks.

Get a List of Virtual Machines (excluding snapshots)

Retrieve a list of VMs and filter out snapshots.

yb-api --get --user=admin --server=10.0.0.100 \
--fields='name,$key,ram,machine#status#status as machine_status' \
--filter='is_snapshot eq false' /v4/vms

Simple Dump of All VMs

This command retrieves a list of all VMs. The --server, --user, --filter, and --fields flags are optional in this case.

yb-api --get /v4/vms

Get Detailed VM Information

Retrieve most of the fields, including drive and NIC information, for a specific VM (VM 1 in this case).

yb-api --get --user=admin --server=10.0.0.100 \
--fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1

Rename a Virtual Machine

Change the name of an existing virtual machine (VM 1) to "NEWNAME".

yb-api --put='{"name":"NEWNAME"}' --user=admin --server=10.0.0.100 /v4/vms/1

Delete a Virtual Machine

Delete a specific VM (VM 1), using its $key.

yb-api --delete --user=admin --server=10.0.0.100 \
--fields='name,$key,ram' /v4/vms/1

Create a New Virtual Machine

Create a new VM with specific configurations (name, CPU cores, RAM, etc.).

yb-api --post='{"name":"NEWVM","enabled":true,"description":"test vm",\
"os_family":"linux","cpu_cores":4,"ram":"8192"}' --user=admin \
--server=10.0.0.100 /v4/vms

Get the VM Database Table Schema

Retrieve the schema for the VMs database table.

yb-api --get --user=admin --server=10.0.0.100 '/v4/vms/$table'

Clone a Virtual Machine

Clone an existing VM (VM 1) and give it a new name.

yb-api --get --user=admin --server=10.0.0.100 '/v4/vm_actions' \
--post='{"vm":1, "action": "clone", "params": {"name": "NEW VM NAME"}}'

Power On a Virtual Machine

Power on an existing VM (VM 1).

yb-api --get --user=admin --server=10.0.0.100 '/v4/vm_actions' \
--post='{"vm":1, "action": "poweron"}'

Notes About yb-api

  • The yb-api script relies on wget, which may not be installed by default on macOS. Make sure to install it if necessary.
  • curl is used for the upload function in certain API calls, such as posting data to create new VMs.

By using the yb-api helper script, developers can simplify interaction with the VergeOS API and manage virtual machines more efficiently. Let us know if you need assistance with further commands or options.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Max RAM per machine setting explained

The Max RAM per machine setting determines the maximum amount of RAM that a virtual machine can utilize on a particular cluster. This setting helps prevent a single VM from consuming excessive resources and affecting the cluster's overall performance.

At the time of installation, the default maximum RAM setting is 64GB. To run a virtual machine requiring more than 64GB, this setting must be adjusted. Fortunately, changes can be made at runtime, so a node reboot is not required to apply the updated setting.

If a VM attempts to use more RAM than allowed by the cluster, an error message, "Machine exceeds the max amount of RAM allowed on this cluster", will be logged. To resolve this, adjust the setting to accommodate the workload. vm_max_ram_exceeded.png

Adjusting the Max RAM per machine setting

Follow these steps to adjust the setting:

  1. From the Main Dashboard, navigate to System and then Clusters in the left-hand menu, or select the Clusters count box in the top row.
  2. In the Cluster list view, select the cluster where the virtual machine is set to run.
  3. Select Edit in the left-hand menu.
  4. Adjust the Max RAM per machine setting to accommodate the virtual machine's requirements. max_ram_per_machine.png
  5. Submit the changes by clicking Submit at the bottom of the page.
  6. Start the virtual machine to confirm the changes.

By increasing the Max RAM per machine setting, larger VMs can be successfully launched on the cluster.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Configuring Proxy

Using a Proxy grants the ability to use 1 IP address for multiple Tenant environments by mapping FQDN hostnames. This bypasses the need to have 1 IP address per tenant and helps to preserve ipv4 addresses.

Enabling Proxy

  1. From the external network used to access tenant environments: - Select Edit in the left menu. - Enable Proxy. - In most cases, the Proxy Listen Address field can be left blank. This will default to 0.0.0.0, meaning it will listen on all addresses.

For VergeOS verions 4.12.6 and older

'Bind DNS' will need to be temporarily enabled if it is not already in use on the network. This will expose the IP Alias selection in the UI (step 2).

  • Submit the settings but DO NOT RESTART THE NETWORK OR APPLY RULES YET!
  1. From the same external network: - Select IP Addresses in the left menu. - Edit or create an IP Address, setting the Type to IP Alias. - Submit. - Set the external network DNS back to the original setting (Prior to Version 4.12.4). - Select Rules. - Create a new rule that looks like the following image:

proxy_accept_rule.png

  • Restart the network and apply the rules.
  • Test the rule by opening a browser tab and navigating to the URL using the IP Alias address assigned in the previous step. If it works properly, the UI login page will open on the IP Alias address.

Creating a New Tenant with Proxy

  1. Create an A Record for the new tenant in your domain registrar to point to the assigned IP Alias.
  2. Create a new tenant: - Enter all desired settings, leaving the URL blank.
  3. In the UI Management tab of the tenant creation page, select Create a new FQDN.
  4. In the Proxy Tenant Config page: - Select the network the proxy service is running on. - Select the tenant name. - Enter the FQDN of the tenant (the A Record created in step 1). - Submit.
  5. Select Skip at the bottom of the UI Management page to avoid assigning an IP directly to the tenant.

A tenant cannot have a UI IP address AND a proxied FQDN.

  1. In the new tenant dashboard, select Apply Proxy in the highlighted warning.

apply_proxy.png

  1. Start the tenant and navigate to its URL in a browser tab to log in.

Editing an Existing Tenant to use Proxy

  1. Create an A Record for the tenant in your domain registrar to point to the assigned IP Alias (if one does not already exist).
  2. From the tenant dashboard, select Edit in the left menu: - In the UI Address field, select None.
  3. Navigate to the network running the proxy service: - Select Proxy in the left menu.
  4. From the Proxy Dashboard: - Select View Tenants. - Select New.
  5. In the Proxy Tenant Config page: - Select the network the proxy service is running on. - Select the tenant name. - Enter the FQDN of the tenant (the A Record created in step 1).
  6. Navigate to the tenant dashboard and select Apply Proxy in the highlighted warning.

apply_proxy.png

  1. Select the tenant network (highlighted) from the tenant dashboard.

tenant_apply_rules.png

  1. Select Apply Rules in the highlighted warning.

tenant_rules_highlighted.png

  1. Test access to the tenant by navigating to its URL in a browser tab.

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Importing Windows Server with UEFI into VergeOS

This guide covers how to migrate a Windows Server VM with UEFI enabled from VMware into VergeOS. The process was tested with Windows Server 2019 and 2022, but it may also work for earlier versions of Windows.

VMware tools were removed before the migration. This was tested on Windows Server 2019 and 2022. It may also work on previous versions of Windows.

Steps to Import the Windows Server VM

  1. Import the VM from the VMware service. Follow the steps from this guide to import the VM into VergeOS.

  2. Set the primary disk interface to SATA for compatibility during initial boot.

  3. Change the primary disk's Boot Order to 0 in VergeOS.

  4. Power On the VM to boot into Windows.

  5. Install the virtio-win-guest-tools.exe if it's not already installed. This package includes Virtio drivers necessary for disk and network performance.

  6. Once the installation is complete, Power Off the VM.

  7. Delete the EFI drive, as it is no longer needed after the migration. You can remove it from the VM's disk settings.

  8. Change the primary disk interface from SATA to Virtio-SCSI for optimal performance.

  9. Remove the media file (ISO) from the CD drive in the VM settings.

  10. Change the NIC driver to Virtio to ensure the VM uses a high-performance network driver.

  11. Enable the QEMU Guest Agent on the VM edit screen to allow VergeOS to gather information about the VM.

  12. Power On the VM again and ensure everything is working correctly.

  13. Verify that the guest agent is reporting back to VergeOS by checking the VM dashboard.

Monitoring the Guest Agent

The guest agent status can be viewed on the VM's dashboard. If it doesn't report back, ensure the guest agent service is running inside the VM.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Generating System Diagnostics

How to Generate System Diagnostics

VergeOS support may request that a system administrator generate a system diagnostics file for detailed logs from the platform. The diagnostic file will include detailed logs from all nodes in a system and package it into a single compressed file which can easily be then uploaded to support automatically or downloaded to be sent via email or a 3rd party file-sharing service.

Here are the steps to create and download a System Diagnostics file. 1. Log in to the parent/root environment. The diagnostics file needs to be generated at the Parent environment, rather than a Tenant. 1. From the Main dashboard, in the left navigation menu, click System 1. On the System dashboard, in the left navigation menu, click System Diagnostics 1. From the System Diagnostics, in the left navigation menu, click Build

  1. Once inside the New System Diagnostic Report, complete the Name, Description, and check the "Send diagnostic information to VergeOS support, then click Submit at the bottom. This will generate a compressed file of system logs.
  2. Wait while the compressed log file is built. The status column will show the status as 'Building" then on to 'Sending to Support'.
  3. When it is finished, the status will change to 'Sent to Support'.
  4. When sending completes, you can also download the file to your local computer.

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Virtual Wire Setup and Use

A virtual wire provides a tenant the ability to access a VLAN outside the VergeOS environment without going through routing steps.

Prerequisite Steps

  1. Add the desired VLAN(s) to the appropriate switch ports so they are accessible to the nodes running the VergeOS environment.
  2. Determine whether the tenant will need access to a single VLAN or multiple VLANs. This will determine the virtual wire configuration.

Warning

VLANs 1 & 100-102 cannot be used in a virtual wire capacity. These VLANs are reserved for internal traffic. They can, however, be remapped to another VLAN for tenant consumption.

Info

If a tenant requires access to more than 1 or 2 VLANs, it is recommended to configure the virtual wire in Trunk Mode.

Creating a 1:1 Virtual Wire

  1. Ensure the VLAN(s) have been created in the VergeOS UI. If not, follow the steps to create VLAN(s) here.
  2. From the Main Dashboard, select Networks in the left menu to open the Networks Dashboard.
  3. Select Virtual Wires in the left menu to view all virtual wires in the environment.
  4. Select New to create a new virtual wire.
  5. Enter the following settings: virtual-wire-create-settings.png

Info

  • The Network dropdown will list all networks inside the environment. Choose the network with the corresponding VLAN to pass into the tenant.
  • The Destination Wire dropdown will automatically select Empty List if no unconnected virtual wires are detected.
  • Leave the PVID field set to 1.
  1. Submit your changes and return to the virtual wires list view.
  2. Select New to create the second half of the virtual wire.
  3. Enter the following settings: virtual-wire-create-settings-tenant.png

Info

  • In the Network dropdown, select the tenant network that the VLAN will be passed to, typically named tenant_'$TENANTNAME'.
  • The Destination Wire dropdown will automatically select the other half of the virtual wire created earlier.
  • Change the PVID field to the actual VLAN ID of the network being attached.
  1. Submit your changes.
  2. Navigate to the Networks Dashboard, select Networks, and apply the rules for the networks connected by the virtual wires.

Creating a Trunk Mode Virtual Wire

Warning

To use Trunk Mode Virtual Wires, the corresponding "Physical Network" (tied to node NICs) must be set to bridge mode.

Warning

If the external network is in a VLAN and the physical NIC that the external network references is in bridge mode, trunking a virtual wire from the bridge will not work.

Setting a Physical Network to Bridge Mode

  1. Navigate to Networks in the left menu to access the Networks Dashboard.
  2. Select Networks again to view all networks in the environment.
  3. Double-click the Physical Network (NIC) that the VLANs are trunked to on the physical switch. !!! info A "Physical Network" typically has "Switch" appended and represents a physical NIC on a node.
  4. Select Edit to enter the network configuration page.
  5. In the configuration page, enable Physical Bridged to activate Bridge Mode. network-bridge-mode.png

The "On Power Loss" setting can remain as Last State or Power On.

  1. Submit your changes.
  2. Reboot the necessary nodes for Bridge Mode to become active.

Configuring a Trunk Mode Virtual Wire

  1. Ensure the "Physical Network" is set to Bridged Mode and is powered on.
  2. From the Main Dashboard, select Networks and then Virtual Wires.
  3. Select New to create the first half of the virtual wire.
  4. Enter the following settings: vw-trunk-host.png

Info

  • Select the corresponding Physical Network in the Network dropdown.
  • Set the PVID field to 0.
  • Enter the allowed VLANs in the Allowed VLAN List, comma-delimited and with ranges as necessary.
  1. Submit your configuration.
  2. Select New to create the second half of the virtual wire.
  3. Enter the following settings: vw-trunk-tenant.png

Info

  • Select the tenant network in the Network dropdown.
  • Set the PVID field to 0.
  • Enter the allowed VLANs in the Allowed VLAN List.
  1. Submit your changes.
  2. Apply the rules for the connected networks as described above.

Adding VLANs Inside the Tenant

  1. Navigate to the tenant UI and log in.
  2. From the Main Dashboard, navigate to Networks, then select New External.
  3. Enter the following settings: virtual-wire-network-in-tenant.png

For the interface network, select Physical.

  1. Submit your configuration.
  2. Attach workloads to the network for Layer 2 access to networks outside of Verge.io.

Troubleshooting Steps

Traffic is not reaching the virtual machine

  • Confirm firewall rules related to the virtual wire have been applied.
  • Verify the destination tenant network and VLAN network are in the "Running" state and reside on the same physical node.
  • Ensure VLANs are trunked to the correct physical node ports.

Document Information

  • Last Updated: 2024-09-03
  • VergeOS Version: 4.12.6

How to Configure a VM Export Volume

In VergeOS, you can create a volume specifically for exporting selected virtual machines (VMs). This export volume can then be used with third-party backup software to back up the VMs. The volume contains VM snapshots from the most recent export.

Steps to Configure a VM Export Volume

1. Preparing the VMs for Export

  1. Edit the VMs you want to export:
    • Navigate to the VM settings and enable the option for Allow Export.

2. Setting Up the NAS Service

To host the VM export volume, you will need to create and configure a NAS service:

  1. Navigate to NAS > NAS Services.
  2. Click New.
  3. Provide Name, Hostname, TimeZone, and Networking for the NAS service.
  4. Click Submit to initialize the NAS service.

3. Starting the NAS Service

Once the NAS service is created:

  1. Select the NAS service from the list.
  2. Click Power On to bring the NAS online and prepare it to host the export volume.

4. Creating a NAS User

You’ll need to create a user to access the NAS:

  1. Navigate to NAS > NAS Services > The NAS Service you created.
  2. Click NAS Users > New.
  3. Provide a username and password.

5. Creating a New Volume for VM Export

  1. Navigate to NAS > Volumes > New
  2. Provide a Name for the volume and choose VergeOS VM Export as the filesystem type.
  3. Select the appropriate NAS service to host the export volume.
  4. Make sure Quiesced is checked.
  5. Adjust the number of exports to store.
  6. Click Submit.

6. Starting the VM Export

  1. Under Export VMs, select Start to initiate the VM export process.
  2. Confirm by clicking Yes at the prompt.

Setting up a CIFS Share for the Exported Data

To access the exported VM snapshots, set up a CIFS share on the NAS volume:

  1. Create a CIFS Share: - Navigate to NAS > CIFS Shares > New. - Select the export volume you created earlier as the target volume. - Provide a Share Name and assign the NAS user you created in step 4 to access the share.

  2. Access the Share: - Browse to \\IPorDNSnameoftheNAS\CIFSShareYouCreated. - Use the NAS user credentials when prompted.

!!! note "For Windows Users" You may need to edit the Group Policy (GPO) or modify the Windows Registry to connect using the Guest account if Guest mode is enabled.

Automating the VM Export

You can schedule regular exports by setting up an automated event:

  1. Navigate to the VM Export Volume.
  2. Select Events > New.
  3. Select *Scheduled as the Task Triggered by.
  4. Provide a Name for the task.
  5. Select VM Exports for section.
  6. Ensure VM Exports as the volume you created previously.
  7. Configure the event to trigger the export at your desired intervals.
  8. Click Submit

By following these steps, you'll have a properly configured VM export volume that can be used with third-party backup solutions, along with automated export scheduling.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

How to import Physical/Virtual Machines into VergeOS

The VergeOS Clone Utility (VergeOS-clone.iso) can be used to import external physical or virtual machines into VergeOS as virtual machines. This process is optimized for PtoV (physical-to-virtual) and non-VMware VtoV (virtual-to-virtual) migrations using efficient block transfer.

For VMware environments, use the VMware connector instead of the VergeOS Clone Utility.

Prerequisites

VergeOS System (Destination)

  • Network URL accessible from the source VMs.
  • VergeOS credentials with VM creation permissions.
  • Sufficient available vSAN storage for VM drives.

VergeOS vSAN global deduplication reduces the space requirement by handling zero blocks.

  • Adequate RAM/CPU to run the imported VMs.

Source Machine (Physical or Virtual)

  • Network connection accessible to the VergeOS system.
  • USB/CD-ROM for the VergeOS Clone ISO.
  • At least 1 GB of RAM to boot and run the ISO.

Selecting Sync Method

  • HTTPS Upload: Default method requiring minimal configuration.
  • vSAN-direct Sync: Optimized for LAN connections (requires additional network setup, not recommended for WAN).

vSAN-direct sync is only allowed to the host system, not directly to tenants.

Obtaining the VergeOS Clone Utility

  1. From the Main Dashboard, click Backup/DR on the left menu.
  2. Click Add Clone ISO in the Clone ISO section.
  3. Select the desired public download option for the ISO file.
  4. After the build process completes, download the ISO via the provided link or from the VergeOS UI.

You can make a bootable USB using the Creating Bootable Installation Media guide, substituting the Clone ISO.

Using the VergeOS Clone Utility

  1. Boot the source machine using the VergeOS Clone ISO.
  2. Select Launch Clone Utility.
  3. Choose the NIC to connect to the VergeOS system.
  4. Select DHCP or configure a Static IP.

If using static IP: - Use the arrow keys to navigate between fields. - Press Enter to edit a field and configure the IP, subnet, gateway, and DNS.

  1. Enter the VergeOS system URL and credentials.

Ensure the user has permissions to create VMs.

  1. Confirm the VergeOS connection and proceed.

Clone Utility Configuration

  1. Enter the name for the VM to be created on VergeOS.
  2. Select the disks to be cloned.
  3. Adjust any Advanced Settings:
    • Send Threads: Default = 4. Adjust for high-latency or high-speed connections.
    • MAC addresses: Choose whether to clone existing MAC addresses or generate new ones.

Setting threads too high may degrade performance.

  1. Begin the clone process by selecting Start Clone.

Resuming a Clone

If a clone import fails or is interrupted, boot the source machine from the VergeOS Clone ISO again and resume by selecting the previously used VM name.

Rebuilding the Clone ISO

  1. To rebuild the Clone ISO after updates, go to Backup/DR on the Main Dashboard.
  2. Click Edit Clone ISO and check Force Rebuild.
  3. The rebuild may take a few minutes.

To automate rebuilds after system updates, schedule a task under System > Tasks/Events.

Direct vSAN Network Configuration

The Direct vSAN transfer method can be used for faster cloning over a local network. It is not recommended for WAN connections.

Direct vSAN can only be used to transfer to a root system (not directly to a tenant).

Network Rules Setup

Three networking rules must be created:

Core Network Rule - 14201 PAT Rule

  1. Name: vSAN PAT
  2. Action: Translate
  3. Protocol: TCP
  4. Direction: Incoming
  5. Source: Any / None (default)
  6. Destination Type: Custom
    Custom Filter: ui
    Destination Ports: 14201
  7. Target Type: IP/Custom
    Target IP: ui

UI is a VergeOS keyword that must be entered in lowercase.

Core Network SNAT Rule

  1. Name: vSAN SNAT for Clone Utility
  2. Action: Translate
  3. Protocol: TCP
  4. Direction: Outgoing
  5. Source: Any / None (default)
  6. Destination Type: My Network Address
    Destination Ports: 14201
  7. Target Type: My Router IP

External Network Rule - 14201 PAT Rule

  1. Name: vsan PAT
  2. Action: Translate
  3. Protocol: TCP
  4. Direction: Incoming
  5. Source: Source IP/IP range of the incoming clone transfer
  6. Destination Type: My Router IP
    Destination Ports: 14201
  7. Target Type: IP/Custom
    Target IP: ui

Once the rules are created, click Apply Rules to finalize the configuration.

Troubleshooting Common Issues

Failed DHCP

If DHCP cannot be found:

  • Verify there is an active DHCP service.
  • Ensure network connectivity is available through the selected NIC.

Login Failed

  • Check the username, password, and URL format (no "https://").
  • Verify static IP settings and DNS configuration if using static addressing.

OpenSSL Errors

These errors indicate network problems. Check for MTU mismatches or other network issues.

Permission Denied

Ensure the VergeOS user has the necessary permissions to create VMs.

If the initial clone fails due to permissions, you can resume the process or delete the VM and restart the clone.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Wireguard - Setup Remote Access VPN

How to Setup a Wireguard Remote Access VPN

Here are instructions on how to set up a Remote Access VPN using the built-in Wireguard capabilities of VergeOS. More information can be found in the Help section of the VergeOS User Interface.

Create the Wireguard Setup on Your Internal Network

You can use an existing Internal Network or create a new Internal Network.

  1. In the Verge OS UI, navigate to Networks -> Internals and view or double-click on the Internal Network that you want to use.
  2. In the left menu, click on Wireguard (VPN).
  3. Click on Add New Interface. wireguardvpn-img1.png

  4. Enter the following information:

    • Enter a unique Name for this interface.
    • Enter a Description (optional).
    • Check Enabled.
    • Enter the IP Address to be used for this Wireguard Internal Network. This must be separate from your existing Internal network IP scheme. For example, if your Internal Network is using 192.168.0.1/24, you must choose a different unique IP scheme like 192.168.255.1/24.
    • Enter the Listen Port to be used when connecting to the VPN (Default: 51820). This is the port that you will use on your External network to send VPN traffic into your Internal Network.
    • Enter a Private Key or leave it blank to auto-generate a key.
    • Enter an Endpoint IP or leave it blank, and the system will attempt to auto-detect the IP. We highly recommend you enter the IP manually to ensure the correct config. This IP is the external IP of your environment, usually the same IP as your UI. You can find your External IP by going to Networks -> Externals and viewing your External network. In the Network Router section, it should be the IP address as shown below: wireguardvpn-img3-fixed.png
  5. Click Submit to add the new interface.

  6. After adding the interface, it will take you to the dashboard where you will see your new interface. wireguardvpn-img2.png

  7. Click Apply Rules on the left menu bar to apply the firewall rules. The rules automatically created will accept inbound UDP traffic on port 51820 to both the Router IP and the DMZ IP of the Internal Network. wireguardvpn-img-intrules.png

External Network PAT Rule

In order for the internal network to be connected, we need an external PAT (Port Address Translation) rule to translate the port (default 51820) to the internal network.

2023-09-06_11_56_18-training___rules.png

Add External PAT Rule
  1. From the External network Dashboard, click Rules on the left menu.
  2. Click New on the left menu.
  3. Enter a Name that will be helpful to future administration.
  4. Optionally, a Description can be entered to record additional administrative information.
  5. In the Action dropdown, select Translate.
  6. In the Protocol dropdown, select UDP.
  7. In the Direction dropdown, select Incoming.

Source:

  1. In the Type dropdown, select Any/None. Optionally, you can source-lock the VPN traffic here if needed.

Destination:

  1. In the Type dropdown, select My Router IP. If you are inside a Tenant, change this to My IP Addresses and choose the IP of the Tenant UI. This should be the same as the Endpoint IP used above. If using a different IP than the UI IP, create an SNAT rule on the External network.

  2. In the Destination Ports/Ranges field, enter the Port (Default Port: 51820).

Target:

  1. In the Type dropdown, select Other Network DMZ IP.
  2. In the Target Network dropdown, select the Target Network.
  3. Leave the Target Ports/Ranges field blank.

  4. Click Submit and Apply Rules on the left menu to put the new rule into effect.

SNAT Rule (if not using UI IP)

If you are adding Wireguard and are not using the IP address of the UI, we recommend creating an SNAT rule on the External network.

  1. From the External network Dashboard, click Rules on the left menu.
  2. Click New on the left menu.
  3. Enter a Name that will be helpful to future administration.
  4. Optionally, enter a Description for additional information.
  5. In the Action dropdown, select Translate.
  6. In the Protocol dropdown, select UDP.
  7. In the Direction dropdown, select Outgoing.

Source:

  1. In the Type dropdown, select Other Network DMZ IP.
  2. In the Network dropdown, select the Internal Network that Wireguard is on.
  3. Leave the Source Ports/Ranges field blank.

Destination:

  1. In the Type dropdown, select Any / None.
  2. Leave the Destination Ports/Ranges field blank.

Target:

  1. In the Type dropdown, select My IP Addresses.
  2. In the IP Address dropdown, select the IP address you want to use.

  3. Click Submit and Apply Rules to enable the SNAT rule.

This SNAT rule forces any outgoing traffic from the DMZ IP of the internal network to use the correct IP. By default, it goes out the UI IP, causing flapping issues.

Adding a Remote User Peer

You will set up a Peer for each user connecting to the VPN.

  1. From the Wireguard Interface screen, click Add new peer. wireguardvpn-img4.png

  2. Assign a Name to the peer, such as the remote user's name.

  3. Optionally, enter a Description.
  4. Check the Auto-Generate Peer Configuration checkbox.
  5. Enter the Endpoint for the Peer (the external-facing IP address, hostname, or URL).
  6. For Allowed IPs, enter the /32 IP for this peer.
  7. In the Configure Firewall dropdown, select Remote User.
  8. Click Submit to save the peer entry. wireguardvpn-img6.png
Download the Configuration File:
  1. Click the Download Config button on the peer record and download the file.

download-link.png configuration-file.png

Install WireGuard Software on Client:

WireGuard client software can be downloaded from: https://wireguard.com/install.

  1. Install WireGuard on the client machine.
  2. Click Add Tunnel.
  3. Navigate to and select the generated configuration file.
  4. Click the Activate button to open the tunnel. tunnel-active.png

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.11

Importing VMs from Media Images

Importing via Media Images allows you to import a single VM at a time by uploading VM data files (such as VMX, VMDK, OVF, VHD/X) to VergeOS and then selecting them for import.

Importing a VM (Configuration and Disks) from Media Images

Hyper-V VMs

Hyper-V VMs should be exported to OVA/OVF or VMware formats before upload, or you can use the Create VM Shell, Import VM Disks method described below to create the VM first, and then import disks.

  1. Upload the configuration and disk image files to the vSAN. For instructions, see Managing Media Images.
  2. From the Main Dashboard, click Machines on the left menu.
  3. Click New VM on the left menu.
  4. From the options list, select --Import from Media Images--. The files uploaded to the vSAN will appear on the right under Selections Available. Click to select the VM configuration file (e.g., *.vmx, *.ovf). VM Import
  5. Click Next at the bottom of the screen. Import Job
  6. The VM Name will default to the name of the configuration file unless you specify a custom name.
  7. By default, the Preserve MAC Address option is selected. If you wish to assign a new MAC address to the VM, deselect this option.
  8. Select the Preferred Tier, or leave it at the default. This specifies the storage tier for the VM's disks. See Preferred Tier Usage for more details.
  9. Click Submit to create the VM. The new VM's dashboard will be presented.

Create VM Shell, Import VM Disks

If you cannot import the entire configuration, you can create a VM shell (a disk-less VM) and then import individual disk files.

  1. Upload the disk image files to the vSAN. See Managing Media Images for details.
  2. Create a new Custom VM with appropriate hardware specifications. See the Creating VMs section in the VergeOS help guide.
  3. Add a new drive to the VM, ensuring to select Import Disk in the Media field. Import Disk
  4. Choose the correct Interface (IDE, SATA, virtio-scsi, virtio-legacy, etc.). Using SATA often helps with driver compatibility in guest OSs.
  5. Select the Media File from the list of uploaded files (*.vhd, *.vhdx, *.qcow, raw, etc.).
  6. Repeat for additional drives if necessary.
  7. Start the VM and verify that it boots correctly.

Supported File Types

The following file types are supported for VM imports using media images: - IMG (Raw Disk Image) - RAW (Binary Disk Image) - QCOW (Legacy QEMU) - QCOW2 (QEMU, Xen) - VDI (VirtualBox) - VHD/VPC (Legacy Hyper-V) - VHDX (Hyper-V) - OVA (VMware, VirtualBox) - OVF (VMware, VirtualBox) - VMDK (VMware) - VMX (VMware)

Troubleshooting Issues

Failure to Boot into the OS

This is often a driver issue. You may encounter a Windows Inaccessible Boot Device error or similar.

Steps to resolve:

  1. Change the drive interface from virtio-scsi to IDE or SATA. This often resolves driver issues.
  2. Once the guest OS boots, install the virtio drivers by attaching them via a virtual CD-ROM or downloading them from virtio-win.
  3. Shut down the VM.
  4. Switch the drive interface back to virtio-scsi.
  5. Start the VM again.

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

How to Create an IPsec VPN Tunnel in VergeOS

In VergeOS, the DMZ Network handles basic routing between networks: - Every router has a NIC and an IP address in the DMZ to route traffic between networks inside VergeOS. - Each vNet represents its own VXLAN or VLAN.

These instructions focus on setting up the IPsec Tunnel to connect to a VergeOS Internal Network. If you are connecting to an External Network or have special use cases, network rules must be adjusted accordingly.

Steps to Create an IPsec VPN Tunnel

Step 1: Reserve a Static IP Address

Reserve a static IP on the Internal (LAN) network that the VPN connection will use.

  • In this example, the IP address 192.168.0.254 is set to static on the internal network named Internal.

    Reserve Static IP

    • Type: Set to Static.
    • IP Address: Select an available IP address from the system. If there are no available IPs, add a new IP.

Step 2: Create the VPN Connection

  1. Navigate to Main Dashboard > Networks.
  2. Click New VPN on the left menu.

Configure the settings as required by the connection:

  • Layer 2: Set the network layer configuration.
  • Interface Network: Select the network that will be bridged to the VPN connection.
  • IP Address Type: Set to Static.
  • Network Router IP: Enter the IP address reserved in Step 1.

    Create VPN Connection

Step 3: Edit IPsec Configuration

  1. From the VPN Dashboard, click on Edit IPsec to modify or add connection-specific details.

    Edit IPsec

Step 4: Create the IPsec Tunnel

  1. Click on IPsec Tunnels to start creating the tunnel between VergeOS and the remote site.
    • Remote Gateway: Configure according to the connection requirements.
    • Phase 1 Proposal (Authentication): Set the authentication method and Pre-Shared Key.

    Phase 1 Setup

Step 5: Configure Phase 2

After completing Phase 1, you will be prompted to configure Phase 2.

  • Mode: Set to Tunnel.
  • Local Network and Remote Network: Configure as required.
  • Phase 2 Proposal: Enter the details as needed for the connection.

    Phase 2 Setup

This will automatically create rules for the VPN network.

Reviewing and Configuring VPN Network Rules

Step 6: Review VPN Network Rules

Verify the rules that were automatically created during VPN setup.

  • Allow IKE: Accept incoming UDP traffic on port 500 to My Router IP.
  • Allow IPsec NAT-Traversal: Accept incoming UDP traffic on port 4500 to My Router IP.
  • Allow ESP: Accept incoming ESP protocol traffic to My Router IP.
  • Allow AH: Accept incoming AH protocol traffic to My Router IP.

    Review Rules

Step 7: Assign a Virtual IP to the VPN Network

Assign a new virtual IP to the VPN network from the External network (Public side of the VPN tunnel).

Assign Virtual IP

This automatically creates an outgoing route rule on the VPN network with that virtual IP address. Ensure the rule is applied.

Step 8: Create VPN Network Rules

  1. Create a Default Route rule for the new VPN network to define the default outbound path for traffic inside this network.

    Create Default Route

  2. Create an sNAT Rule on the new VPN network to mask external traffic.

    Create sNAT Rule

  3. Create a General sNAT Rule as a catchall for traffic from this network.

    General sNAT Rule

  4. Create a Translate Rule to allow traffic from the VPN tunnel to access this network.

    Translate Rule

  5. Create Accept Rules:

    • One rule to allow incoming traffic from the remote network.
    • Another rule to accept traffic within the VPN network.

    Create Accept Rules

Step 9: Create Internal Network Rules

  1. Create a Route Rule on the Internal network to send traffic properly through the VPN tunnel.

    Internal Route Rule

  2. Create an Accept Rule on the Internal network to allow traffic from the remote network.

    Internal Accept Rule

Connecting to IPsec

  1. Open the VPN network's Dashboard (Networks > VPNs > select VPN).
  2. Scroll down to the IPsec Connections section.
  3. Click the plug icon to connect.

    Connect IPsec

  4. Watch for the IPsec status to show connected.

If the connection fails, proceed to the troubleshooting steps below.

Troubleshooting Guide

Checking Logs and Status

  1. Go to Diagnostics on the left menu.
  2. Change the Query to Logs and click Send.
  3. Review the latest logs for errors, such as retransmission attempts.

    Check Logs

Common Connection Issues

If you see many retransmit messages, this could indicate connection issues, often caused by incorrect network rules or firewall setups.

  • Test connectivity with Ping.
  • Change the Host to the Remote Gateway IP and check for packet failures.

If pinging the Remote Gateway fails, verify that your connection is not blocked and that the correct route is in place.

Other Diagnostics

  1. Ping 8.8.8.8 to test for internet connectivity. If this fails, check the Default Route rule.
  2. Run "What's My IP" to verify the VPN's WAN connection.
  3. Use TCP Connection Test to check the IKE port (port 500) on the Remote Gateway.
  4. Run a Trace Route to the Remote Gateway to confirm correct traffic routing.
  5. Use IPsec diagnostics with Status All to view the current state of the IPsec Tunnel or Show Config to review the configuration.
  6. Review Logs in Diagnostics, increasing the line count if necessary.

By following these steps and rules, you can successfully set up an IPsec VPN tunnel in VergeOS, troubleshoot common issues, and ensure that traffic flows properly between networks.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

How to Resize a Virtual Disk Drive

Note

Drives can only be increased in size; they cannot be reduced. Verify whether your guest OS supports resizing without a power cycle, particularly for Virtio-SCSI drives.

To resize a virtual disk drive within a VM, follow these steps:

  1. From the VM Dashboard, click Drives in the left menu.
  2. Select the drive to be modified.
  3. Click Edit in the left menu.
  4. Modify the drive size as desired.
  5. Click Submit.

Important Notes

Note

If the VM configuration allows hot-plugging, the disk interface is set to Virtio-SCSI, and the guest Operating System (OS) supports it, the drive size can typically be increased without power cycling the VM.

Warning

Drives cannot be reduced in size. While partitions may be resized inside the guest OS, the disk drive itself cannot be shrunk.

Warning

Modifications to drive size will most likely require corresponding changes within the guest Operating System to utilize the newly added space.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Network Blocks

Network Blocks Overview

Network blocks in VergeOS are a powerful way to assign multiple IP addresses to tenants or networks for workloads. This method is preferred over virtual wires since VergeOS focuses on Layer 3 connectivity, avoiding the common issues associated with Layer 2 connections (like virtual wires). Network blocks also allow the direct assignment of public IP addresses to VMs inside an internal network or a tenant.

Creating a Network Block

  1. In the VergeOS UI, navigate to the External Network where the network block will originate.
  2. In the left menu, select Network Blocks, then click New.
  3. Enter the network block information in CIDR notation (e.g., a.b.c.d/n).
  4. To assign the block to a tenant at creation, set the Owner Type to Tenant, then select the tenant from the Owner drop-down. new-network-block.png
  5. Submit your work to create the block.
  6. To apply the automatically created rules, select the External breadcrumb in the header to return to the network dashboard. Then, select Apply Rules from the left menu or click the notification pop-up. net-block-rules.png

Creating a Network from a Network Block

  1. Log in to the tenant's URL with the necessary credentials.
  2. Navigate to Networks, then go to the External Network Dashboard.
  3. In the left menu, select Network Blocks.
  4. Select the network block assigned to the tenant.
  5. Click New Network in the left menu. new-net-from-block.png
  6. Give the new network a name. The rest of the details will be pre-filled based on the CIDR information.
  7. Modify any details in the form if necessary, then submit to create the network.
  8. After creation, the system will redirect you to the new network's dashboard. The necessary routes and accept rules will be set up automatically, but note that inbound traffic will be dropped by default. Add appropriate firewall rules to allow inbound access.
  9. Power on the network using the option in the left menu.
  10. Assign any desired virtual machines to the network and test connectivity.

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Changing Resolution on a UEFI VM

In a UEFI-based virtual machine (VM), the screen resolution is controlled by the OVMF (Open Virtual Machine Firmware) Platform Configuration. By default, only the resolution configured in the platform settings is available to the VM. If you need to change the display resolution, follow the steps outlined below.

Steps to Change the Screen Resolution

  1. Reboot the VM while connected to the console (through the VergeOS UI or any console manager you're using).

  2. As the VM starts, press ESC to enter the UEFI Settings menu.

  3. Once in the UEFI menu, navigate to Device Manager.

  4. In Device Manager, select OVMF Platform Configuration.

  5. Choose your desired Preferred Resolution from the list of available options.

  6. Save the configuration changes and reboot the VM for the new resolution to take effect.

Notes and Considerations

  • The resolution options available depend on the firmware and the display capabilities of the guest operating system.
  • If you are still experiencing resolution issues, ensure that your guest OS has the necessary display drivers installed.
  • UEFI settings may vary slightly depending on the VM and configuration, so some steps may look a little different in certain environments.

By following these steps, you can successfully adjust the screen resolution for your UEFI-based VM.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

API Tables Description

The following is a brief description of each of the API tables. To find out more details, add /#swagger to the end of your VergeUI's URL (or navigate to System->API Documentation). Swagger provides detailed information about each table and allows you to test each method with a Get/Post/Put/Delete action. For more instructions on how to integrate with the API, refer to the API Documentation page.

API Tables

auth_source_states

Provides a list of auth source states.

auth_sources

Authorization sources table for managing authorization sources like OpenID or AzureAD.

billing

Used to get billing information for the current environment. This is stored as billing data with a from->to date.

billing_actions

Used to send billing actions. The main action is "generate," which creates a new bill.

  • Fields:
  • action : See action list below.

  • Actions:

  • generate : Generate bill

  • Example:

URL: '/v4/billing_actions'
POST(JSON): {"action": "generate"}

catalog_logs

Logs specific to Catalogs.

catalog_repositories

Catalog repositories and sublists for catalogs, logs, permissions, etc.

catalog_repository_actions

Used to send Catalog Repository Actions.

  • Fields:
  • repository : Row ID for the repository you want to refresh.
  • action : Default action is refresh. See action list below.

  • Actions:

  • refresh : Refresh the Catalog Repository.

  • Example:

URL: '/v4/catalog_repository_actions'
POST(JSON): {"repository": 1, "action": "refresh"}

catalog_repository_logs

View and post Catalog Repository Logs.

catalog_repository_status

Used to store and update the Catalog Repository statuses. These determine the state and status of a Catalog Repository.

catalogs

Catalogs table allowing you to update/post/delete Catalogs.

certificates

SSL Certificates for your site.

clone_iso

Stores information and status of the Verge.io Clone ISO program.

clone_iso_actions

Actions for the Clone ISO feature.

  • Fields:
  • action : Default is "update." See action list below.

  • Actions:

  • update : Update the ISO image.
  • delete : Delete the ISO image.
  • cancel : Cancel the current build.

  • Example:

URL: '/v4/clone_iso_actions'
POST(JSON): {"action": "update"}

cloud_restore

Stores information when a Cloud Restore is performed.

cloud_snapshot_actions

Actions for the Cloud Snapshot feature.

cloud_snapshot_tenant_actions

Actions for the Cloud Snapshot feature for a Tenant.

cloud_snapshot_tenants

Cloud Snapshots for a Tenant.

cloud_snapshot_vm_actions

Actions for a VM and Cloud Snapshots.

cloud_snapshot_vms

Used to store information when a Cloud Snapshot is downloaded to a VM.

cloud_snapshots

The Cloud Snapshots table includes information about the Cloud Snapshot, as well as a list of VMs, Tenants, and Sync Queues. This can be used to see what VMs are included in a Cloud Snapshot.

cloudinit_files

Operations for the Cloudinit Files feature.

cluster_actions

Cluster Actions is used to send actions for Clusters.

  • Fields:
  • cluster : Cluster row ID (required).
  • action : See action list below.
  • params : Parameters supplied in JSON form (optional).

  • Actions:

  • shutdown : Shutdown the Cluster.
  • cancel_shutdown : Cancel current shutdown request.

  • Example:

URL: '/v4/cluster_actions'
POST(JSON): {"cluster": 1, "action": "shutdown", "params": "{}"}

cluster_stats_history_long

The cluster_stats_history_long table holds Cluster stats history for extended periods.

cluster_stats_history_short

The cluster_stats_history_short table holds Cluster stats for a short period, storing the most recent statistics for quick access.

cluster_status

Handles the status of all the clusters.

cluster_tier_stats

Handles statistics for the vSAN tiers of a cluster.

cluster_tier_stats_history_long

Holds historical statistics for Cluster Tiers over extended periods.

cluster_tier_stats_history_short

Holds historical statistics for Cluster Tiers over short periods, storing the most recent statistics for quick access.

cluster_tier_status

Used for Cluster Tier statuses.

cluster_tiers

Holds a list of Tiers for the cluster.

clusters

The main table for data on the Clusters.

file_actions

The file_actions table sends file actions.

  • Fields:
  • file : File ID from files table (required).
  • action : See action list below.
  • params : Parameters supplied in JSON form (optional).

  • Actions:

  • overwrite : Overwrite the file.
  • add_link : Add a file link.
  • delete_link : Delete a file link.
  • delete_references : Delete file references.

  • Example:

URL: '/v4/file_actions'
POST(JSON): {"file": 1, "action": "add_link", "params": "{}"}

files

Information related to stored files.

Handles public links for files.

group_logs

Logs related to groups.

groups

Group management table.

help_actions

Handles help-related actions.

Search table for help documentation.

licenses

Handles VergeOS licenses.

logs

Handles system logs.

machine_console

Handles machine console interactions.

machine_console_active

Tracks active machine console sessions.

machine_console_active_chat

Tracks chat interactions in active machine consoles.

machine_device_gpu_stats_history_long

Holds historical GPU stats for extended periods.

machine_device_gpu_stats_history_short

Holds historical GPU stats for short periods.

machine_device_settings_nvidia_vgpu

Handles settings for Nvidia vGPU devices.

machine_device_settings_tpm

Handles settings for TPM devices.

machine_device_stats

Tracks device statistics.

machine_device_status

Tracks device status.

machine_devices

Table for machine device information.

machine_drive_phys

Physical drive data for machines.

machine_drive_stats

Drive statistics for machines.

machine_drive_stats_history_long

Holds historical drive statistics for extended periods.

machine_drive_stats_history_short

Holds historical drive statistics for short periods.

machine_drive_status

Tracks drive status for machines.

machine_drives

Table for machine drives.

machine_logs

Tracks machine logs.

machine_nic_stats

NIC statistics for machines.

machine_nic_stats_history_long

Historical NIC statistics over long periods.

machine_nic_stats_history_short

Historical NIC statistics over short periods.

machine_nic_status

NIC status for machines.

machine_nics

Table for NICs in machines.

machine_snapshots

Tracks snapshots for machines.

machine_stats

General statistics for machines.

machine_stats_history_long

Historical statistics for machines over long periods.

machine_stats_history_short

Historical statistics for machines over short periods.

machine_status

Tracks status for machines.

machines

Main table for machine data.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Troubleshooting NAS CIFS Shares

In this guide, we'll walk through common issues you might encounter with NAS CIFS shares and provide step-by-step solutions. Let's empower you to resolve these issues efficiently!


Connectivity Errors

Issue: Unable to Connect to CIFS Shares

If you're experiencing connectivity issues when trying to access CIFS shares, you may need to enable insecure guest logins for SMB shares on your Windows device.

Solution: Enable Insecure Guest Logins
  1. Open Local Group Policy Editor - Press Win + R to open the Run dialog. - Type gpedit.msc and press Enter to open the Local Group Policy Editor.

  2. Navigate to Policy Path - In the console tree, navigate to Computer Configuration > Administrative Templates > Network > Lanman Workstation.

  3. Edit Policy Setting - Locate Enable insecure guest logons in the right pane. - Right-click on it and select Edit.

  4. Enable the Setting - In the policy setting window, select Enabled. - Click OK to apply the changes.

  5. Restart Your Device - Restart your Windows device to ensure the changes take effect.

By enabling insecure guest logins, you should be able to resolve connectivity issues with CIFS shares.


Permission Denied Errors

Issue: Access Denied When Accessing CIFS Share

If you encounter permission denied errors, it may be due to incorrect user permissions or share settings.

Solution: Verify Permissions and Share Settings
  1. Check User Permissions - Ensure the user account has the necessary permissions to access the share. - Navigate to the NAS service and verify the user permissions for the specific share.

  2. Review Share Settings - Ensure that the share settings are correctly configured. - Navigate to NAS > Shares and verify the settings for the specific share. - Ensure that the share is browseable and that the correct users or groups have access.

  3. Force User/Group Options - If using the Force User Option or Force Group Option, ensure that the specified user or group has the correct access permissions.


Slow Performance

Issue: Slow Access to CIFS Shares

If accessing CIFS shares is slow, it might be due to network issues or incorrect configurations.

Solution: Optimize Performance Settings
  1. Check Network Connectivity - Verify that your network is stable and that there are no connectivity issues. - Use tools like ping or traceroute to check network latency and packet loss.

  2. Adjust SMB Protocol Version - Ensure you are using the optimal SMB protocol version. - Navigate to NAS > Volumes, select the volume, and verify the SMB protocol version under Advanced Configuration Options.

  3. Optimize NAS Configuration - Review and optimize NAS configurations such as caching and buffering settings. - Consult VergeOS Support for advanced configuration options to improve performance.


MacOS Issues

Issue: Unable to Access CIFS Shares from MacOS

MacOS users may encounter issues when trying to access CIFS shares due to differences in SMB protocol versions or other configuration settings.

Solution: Adjust MacOS Settings
  1. Ensure SMB Compatibility - Open the Terminal application on your Mac. - Use the following command to check the SMB protocol version:

    smbutil statshares -a
    
    - Ensure the server supports SMB2 or SMB3, as SMB1 is deprecated and may not be supported by MacOS.

  2. Modify nsmb.conf - Create or edit the nsmb.conf file to force a specific SMB protocol version:

    sudo nano /etc/nsmb.conf
    
    - Add the following lines to force SMB3:
    [default]
    smb_neg=smb3_only
    
    - Save the file and exit the editor.

  3. Clear SMB Cache - Use the following command to clear the SMB cache:

    sudo rm -rf /var/db/samba/*
    sudo rm -rf /var/db/smb/*
    

  4. Restart Your Mac - Restart your Mac to apply the changes.

Solution: Verify Share Configuration
  1. Check Share Permissions - Ensure the CIFS share permissions are correctly configured for the MacOS user. - Navigate to NAS > Shares and verify the settings for the specific share.

  2. Use Correct Credentials - When prompted, ensure you are using the correct username and password to access the share. - If anonymous access is required, ensure the share allows guest access.

Solution: Add Advanced Configuration Options

For better support for MacOS clients, you can add specific configurations under "Advanced Configuration Options" in the CIFS settings.

  1. Navigate to NAS CIFS Settings - Go to NAS and click on the CIFS box on the dashboard.

  2. Add Advanced Configuration Options - Under Advanced Configuration Options, add the following settings:

    ea support = yes
    vfs objects = fruit streams_xattr
    fruit:metadata = stream
    fruit:model = MacSamba
    fruit:veto_appledouble = no
    fruit:nfs_aces = no
    fruit:posix_rename = yes
    fruit:zero_file_id = yes
    fruit:wipe_intentionally_left_blank_rfork = yes
    fruit:delete_empty_adfiles = yes
    

  3. Save and Apply Settings - Save the changes and apply the new configuration settings.

By following these troubleshooting steps, you should be able to resolve common issues with NAS CIFS shares effectively. If you continue to experience problems, please consult VergeOS Support for further assistance.


Document Information

  • Last Updated: 2024-09-03
  • VergeOS Version: 4.12.6

VM Disk Discard

The Discard option on a VM Disk in VergeOS is responsible for managing unused storage blocks by issuing TRIM or DISCARD commands. When Discard is enabled, the system automatically frees up unused blocks, helping to maintain efficient storage usage on the vSAN.

Enabling or Disabling Disk Discard

When creating or editing a VM disk, you have the option to enable or disable Discard. By default, Discard is enabled, and it is highly recommended to leave it enabled for optimal storage efficiency. When Discard is disabled, deleted files on the virtual disk do not immediately free up the corresponding storage, leading to potential overuse of storage resources.

Here’s what happens when Discard is enabled:

  • The system periodically identifies and frees unused disk blocks.
  • vSAN storage remains optimized, as unused blocks are reclaimed.
  • Disk space usage more accurately reflects the actual data stored on the VM.

2023-03-30_10_43_52-diskdiscardwindow.png


Only disable Discard for performance reasons

Disabling Discard can lead to storage inefficiencies and should only be done for specific performance-related reasons. Always consult with VergeOS Support before disabling this feature.

Why Use Disk Discard?

  • Efficient Storage Management: When a file is deleted from a VM, the unused blocks are immediately flagged as free, allowing the vSAN to reuse that space for other data.
  • Improved Disk Performance: Discard operations help maintain a clean and optimized storage system, reducing overhead from managing fragmented or unused blocks.
  • Space Reclamation: Particularly in environments with high storage churn (i.e., frequent file creation and deletion), Discard ensures that space is consistently reclaimed, avoiding storage bloat.

When to Disable Disk Discard

In rare circumstances, you may need to disable Discard to improve performance, particularly on certain workloads where the overhead of issuing TRIM/DISCARD commands may cause delays or slowdowns. Before making this change, it's critical to understand the trade-offs in terms of storage efficiency and consult with VergeOS Support for further guidance.


By keeping Discard enabled, you ensure that VergeOS optimizes storage for virtual machines, maintaining high efficiency and minimizing wasted space.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Allow Root to Tenant Site Connection

Overview

Important

Adding this rule will allow tenants to connect on the DMZ network. By default, this is disabled for security reasons.

This guide provides instructions on how to connect a root system to a tenant site in VergeOS. The Sites feature is typically used to connect two VergeOS sites together, but to extend this functionality to a tenant site, you’ll need to add a specific rule on the root system's External network.

Prerequisites

  • Access to the Root system with administrative privileges.
  • A basic understanding of network rules and DMZ interfaces in VergeOS.

Steps

  1. Access External Networks - In the Root system, navigate to Networks and then External Networks. - Double-click on the External network.

  2. Add the Rule - In the left menu, click on Rules. - Before adding a new rule, ensure it doesn’t already exist. - Click New in the left menu. - Enter the following details:

    • Name: Enter a descriptive name such as "Allow Tenant to Root".
    • Action: Translate.
    • Protocol: ANY.
    • Direction: Outgoing.
    • Interface: DMZ.
    • Source: Other Network Address (DMZ).
    • Destination: Any/None.
    • Target: My Router IP.

Rule Configuration

  1. Submit and Apply - Click Submit. - In the left menu or at the top, click Apply Rules to activate the new rule.

After the rule is applied, the root system should now be able to connect to the tenant site.

Testing the Rule

To verify that the rule works, follow these steps:

  1. From the Home screen, click System in the left menu.
  2. Click on Nodes in the left menu.
  3. Double-click on Node1 or select Node1 and click View.
  4. In the left menu, click on Diagnostics.
  5. Change the Query to TCP Connection Test.
  6. Set Host to the UI IP/Host of the tenant system.
  7. Set Port to 443.
  8. Click Send.

Diagnostics

The Response should say Connection successful. If the connection fails, review the rule to ensure accuracy, particularly ensuring that the Interface is set to DMZ rather than Auto.

Troubleshooting

Common Issues

  • Issue: Connection test fails.
  • Solution: Double-check that the rule is configured correctly, especially the interface settings. Also, ensure there are no blocking rules that could prevent the connection.

Additional Resources

Feedback

Need Help?

If you encounter any issues while setting up the root-to-tenant site connection, or have any questions, feel free to contact our support team.


Document Information

  • Last Updated: 2023-09-12
  • VergeOS Version: 4.12.6

System Logs


Overview

System logs are essential for monitoring and troubleshooting the performance and security of your systems. This article provides a guide on how to review system logs within the dashboard, configure third-party logging, and understand the log retention period.

Types of Logs

  1. System Logs: - System logs capture activities related to vSAN, VM activities, and other system-related operations. These logs are essential for understanding the detailed operations and performance of the entire system

  2. Sync Logs: - Sync logs are available on both incoming and outgoing sync dashboards. These logs display entries for the start and completion of each Snapshot sync. Each entry includes statistics for the amount checked, scanned, sent, net sent, and the count of directories and files.

  3. System Event Log (SEL): - The SEL contains events from the hardware IPMI interface. Since this log is stored on hardware, it has limited capacity. The node dashboard displays a percentage bar indicating the amount of SEL capacity currently used.


Reviewing System Logs

Example of Logged Activity

The log in the following screenshot shows several specific events as examples of logged activity.

system_logs.png

  • From the entry time-stamped on March 28th, 2022 at 9:21:35, there is a record of the IP address from where the admin user logged in, along with the date and time of the login.
  • The entry at 9:21:55 shows that the user named 'admin' had the password changed from the root environment.
  • The entry at 9:22:53 records the admin user changing their own password in this environment.

Log Retention Period

  • VergeOS retains logs for 45 days. After this period, logs are automatically deleted. For compliance and troubleshooting, consider this retention period and enable third-party logging for long-term storage.

Viewing Context-Specific Logs

  • In many areas of the platform, such as a specific VM dashboard, there is a Logs button to view logs specific to that context. This helps filter out unrelated logged events.

Reviewing Sync Logs

  • Sync logs can be accessed directly from the sync dashboard.
  • Each log entry provides detailed information about the sync process, including:
  • Start and stop times
  • Amount of data checked
  • Amount of data scanned
  • Amount of data sent
  • Net data sent
  • Directory and file counts

Reviewing SEL

  1. Check SEL Capacity: - The node dashboard displays a percentage bar showing the current usage of SEL capacity. Monitor this to ensure that the SEL does not become full, which would prevent new events from being recorded.

  2. Clear SEL: - If the SEL is nearing full capacity, clear it by following these steps:

    1. From the Main Dashboard, select Nodes.
    2. Double-click the desired node to access the Node dashboard.
    3. Click Clear SEL on the left menu.
    4. Click Yes to confirm.

Enabling 3rd Party Logging

VergeOS logs user-initiated and automated activity and displays it in the system log. System logs are accessible from the Main Dashboard at the bottom of the page or by selecting the Logs button in the left navigation menu. VergeOS keeps logged activity for a maximum of 45 days. To retain logs beyond this period, configure a third-party log collection service.

To configure a third-party system logger:

  1. Select System: - In the left navigation menu from the main dashboard, select System.

  2. Access Settings: - Inside the System menu, select Settings from the left navigation menu.

  3. Enter Advanced Settings: - Select Advanced Settings on the left.

  4. Search and Configure Syslog: - Search for "syslog". - Select and edit Remote syslog server (tcp: @@name/ip:port, udp: @name/ip:port). - Configure this setting according to the required syntax:

    • Examples:
    • For TCP: @@10.10.10.10:514
    • For UDP: @10.10.10.10:514
    • Search "syslog" again.
    • Select and edit Template to define for syslog server (See rsyslog for format).
    • Enter a syslog template format that is compatible with the syslog server.
    • Example:
      GRAYLOGRFC5424,"<%PRI%>%PROTOCOL-VERSION% %TIMESTAMP:::date-rfc3339% %HOSTNAME%.HOSTNAME_HERE %APP-NAME% %PROCID% %MSGID% %STRUCTURED-DATA% %msg%\n"
      
    • For more information on syslog templates, visit the Rsyslog Website.

Best Practices

  • Regular Monitoring: Regularly monitor system logs to stay informed about system health and performance.
  • Clear SEL as Needed: Ensure the SEL is cleared periodically to avoid the loss of new event data.
  • Review Sync Logs: Regularly review sync logs to ensure synchronization processes are running smoothly and to diagnose any potential issues.
  • Utilize 3rd Party Tools: Use third-party logging tools for enhanced log analysis, long-term storage, and better integration with your overall monitoring setup.

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

VLAN Creation in VergeOS

Overview

Key Points

  • Add VLANs to appropriate switchports
  • Create a new external network in the VergeOS UI
  • Configure the network settings
  • Attach workloads to the new VLAN

This guide walks you through the process of creating a VLAN (Virtual Local Area Network) in the VergeOS environment. VLANs are essential for network segmentation and improving network performance and security.

Prerequisites

  • Access to the VergeOS system as an administrator
  • Physical network infrastructure that supports VLANs
  • Basic understanding of networking concepts and VLANs

Steps

  1. Prepare the Physical Network - Add the desired VLAN(s) to the appropriate switchports so they are accessible to the nodes running the VergeOS environment

  2. Navigate to Network Creation - From the Main Dashboard, go to Networks - Select "New External" in the left menu

  3. Configure Network Settings - In the network creation page, enter the following settings: new-vlan.png

Interface Network Selection

For the "Interface Network" option, be sure to select the physical network on the nodes that the VLAN enters the environment on. These are typically appended with the name "Switch" during install. For all other settings, the default options are typically sufficient.

  1. Submit Configuration - Click the submit button to create the new network

  2. Verify Network Status - You will be brought to the newly created network's dashboard - Verify that the status shows as "Running" if the configuration from above was used

  3. Attach Workloads - Workloads can now be attached to the newly created network

Adding VLANs to Tenants

See the Virtual Wires KB article for adding VLANS into Tenants.

Troubleshooting

Common Issues

  • Problem: Network status not showing as "Running"
  • Solution:

    1. Verify that the physical network supports the VLAN configuration
    2. Check if the correct Interface Network was selected
    3. Ensure that the VLAN ID matches the one configured on the physical switch
  • Problem: Unable to attach workloads to the new VLAN

  • Solution:
    1. Confirm that the network is in "Running" status
    2. Verify that the workload has the correct network configuration
    3. Check for any conflicting network policies

Additional Resources

Feedback

Need Help?

If you encounter any issues while creating VLANs or have questions about this process, please don't hesitate to contact our support team.


Document Information

  • Last Updated: 2023-06-06
  • VergeOS Version: 4.12.6

Database Performance Best Practices on VergeOS

Running databases on VergeOS can deliver excellent performance when properly configured. Below are the recommended best practices for optimizing database performance, specifically for databases running on Microsoft Windows within the VergeOS environment.


Key Adjustments for Optimizing Performance

  • Backup Location: Always store database backups directly within VergeOS. This ensures faster read/write access and better overall performance for backup operations.

  • Decrypt Databases Before Migration: If your database is encrypted, it is recommended to decrypt the database before migrating it onto VergeOS. This prevents potential performance degradation during the initial transfer and ensures optimal operation within the environment.

  • Disable Automatic Defragmentation: The built-in Windows automatic defrag job should be disabled. Defragging on virtual disks can lead to performance issues, especially on SSDs or highly fragmented virtual environments like VergeOS.

  • Disable Windows Defender: Windows Defender, while useful for security, can significantly affect database performance due to real-time scanning. Disable Defender or, at the very least, exclude the following from being scanned:

    • The path or drive where the database files are stored
    • Log files and transaction log drives
  • Turn Off Non-Essential Windows Services: Many Windows services are unnecessary for database performance and can consume valuable resources. Disable any non-essential services to free up CPU, RAM, and disk I/O for database operations.

  • Core Overcommitment: Avoid overcommitting CPU cores, especially if multiple database VMs are sharing the same physical CPU cores. Overcommitting can lead to resource contention, reducing performance for each VM.

  • Disable Fsync on Log Drives: For virtual disks used to store logs, consider disabling Fsync. This can improve I/O performance by reducing the frequency of forced data synchronization on log writes. You can do this by editing the specific virtual disk settings in VergeOS.

    Important

    Disabling Fsync can lead to data loss in case of a crash. Ensure this aligns with your database's tolerance for I/O performance versus reliability trade-offs.

  • Core Allocation Limits: Limit the number of cores allocated to a database VM so that it does not exceed the physical cores available on a single CPU socket. Do not count hyperthreaded cores in this calculation.

    Example: On a dual-socket system with 8 physical cores per socket (16 cores, 32 threads), limit the VM to use 8 cores (1 physical socket), avoiding overcommitment across multiple sockets.

  • Memory Allocation: Ensure that the memory allocated to the database VM does not exceed the physical memory available in a single CPU socket. This ensures memory access is localized and reduces memory access latency.


Network and Storage Optimizations

  • Use VirtIO Drivers: For network performance, it is recommended to use VirtIO network drivers whenever possible. These drivers are optimized for performance in virtual environments and provide significantly better throughput compared to emulated drivers (e.g., e1000).

    You can download the latest stable VirtIO drivers from the following link: Download VirtIO Drivers

  • Monitor Disk I/O: Regularly monitor the disk I/O performance, especially on high-write activity volumes like log files or tempdb files, and consider allocating high-performance SSD or NVMe drives if required.

By following these best practices, you can optimize the performance and reliability of your database systems running on VergeOS. If further fine-tuning is required, VergeOS supports additional features that can help monitor and improve VM performance in real-time.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Pre-installation Checklist

Main Items

  • Site Survey completed and approved by VergeOS
  • ISO downloaded and installed on a USB drive
  • Encryption Key USB prepared (if enabling encryption)
  • Nodes powered up with ISO booted to the VergeOS Install screen
  • Crash cart ready, if applicable
  • Remote screen share capability or remote IPMI access (via WAN or VPN)

Hardware

  • Hardware burn-in completed
  • All drives set up for JBOD (No RAID)
  • BIOS configured to the proper boot settings (Legacy / Dual / UEFI)
    • Note: UEFI is required if all drives are NVMe
  • Redundant power supplies connected and set up (recommended)
  • IPMI ports patched and configured
  • IPMI setup tested and configured
  • Latest IPMI firmware installed (recommended)
  • Remote console capability tested via IPMI (in case of licensing issues)

Network

  • All switches online and tested
  • All cables patched and connected
  • All VLANs configured (core and external)
  • All switch ports configured (core and external)
  • Minimum of 2 NICs per node with connections to separate switches
  • Correct supported SFP modules in use (if applicable)
  • IP addresses validated and available

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Creating Bootable Installation Media

This guide explains how to create a bootable USB to install VergeOS on different operating systems.

Windows

  1. Download the VergeOS installation ISO from https://updates.verge.io/download.

  2. Insert a USB drive into your computer.

    Warning

    This USB drive will be overwritten.

  3. Download and launch Rufus from https://rufus.ie/en/.

  4. In Rufus:

    • Select your USB device under Device.
    • Click the Select button and choose the VergeOS installation ISO.
    • Click Start.
  5. Choose ISO mode when prompted by Rufus, then select DD mode to proceed.

    It is critical to choose DD mode during this step. Selecting the wrong mode can result in an unbootable USB drive

  6. Rufus will begin creating the bootable USB. Once complete, your USB is ready to be used for VergeOS installation.


macOS

  1. Download the VergeOS installation ISO from https://updates.verge.io/download.

  2. Insert a USB drive into your computer.

    Warning

    This USB drive will be overwritten.

  3. Download and install BalenaEtcher from https://www.balena.io/etcher/.

  4. Launch BalenaEtcher and:

    • Click Flash from file, and select the VergeOS ISO.
    • Select the target USB disk (be careful not to select hidden drives).
    • Click Flash! to start the process.
  5. Once the flashing process is complete, your USB drive will be ready to boot and install VergeOS.


Linux Mint

  1. Download the VergeOS installation ISO from https://updates.verge.io/download.

  2. Insert a USB drive into your computer.

    Warning

    This USB drive will be overwritten.

  3. Using Mint’s file browser, navigate to the downloaded ISO file:

    • Right-click the ISO and choose Make bootable USB stick.
    • In the USB Image Writer, select the USB media to write the installation file to.
    • Authenticate with your admin password when prompted.
    • Click Authenticate to start writing the ISO to the USB drive.
  4. Once the process is finished, your bootable USB stick will be ready for VergeOS installation.


By following these steps for your specific operating system, you'll have a bootable USB ready to install VergeOS on your server.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Viewing Tenant Consumption Statistics

This information may not pertain to your particular pricing model. Consult your sales representative for more information.

Tenant Consumption Statistics:

  • Navigate to Tenants Dashboard
  • Browse for your tenant, click View
  • Click on History in the left menu
  • Choose your month/year and click Apply
  • Scroll down to the bottom.

consumptionstats-image_(14).png

RAM Consumption: Total RAM Allocated 95th percentile
Storage Consumption: Tier X (Provisioned) - add up all tiers at the 95th percentile

For RAM, tenants consume everything that they are allocated. If the tenant is not using all the RAM that it is allocated, reduce the RAM allocated amount to lower overall consumption.


Document Information

  • Last Updated: 2024-09-03
  • VergeOS Version: 4.12.6

Bypassing TPM Requirements in Windows 11

How to Bypass Windows 11's TPM Requirement Using the Registry Editor during the installation


This only applies to Versions of Verge.io previous to 4.11 (Atria).

If you have the Windows 11 install disk or ISO, you can bypass the Windows TPM and RAM requirements by making registry changes during the install.

Note: This method only works on a clean install and does not allow you to bypass the requirement for at least a dual-core CPU.

  1. Boot off of your Windows 11 install disk. If you don't have one, one can be downloaded from here. The first screen should ask you to choose the language of your install (which should be correct). tpm-1.png

  1. Press SHIFT + F10 to launch the command prompt. tpm-2.png

  1. Type regedit and hit Enter to launch registry editor. tpm-3.png

  1. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\Setup. tpm-4.png

  1. Create a new registry key under Setup and name it LabConfig. To create a registry key, right click in the right window pane and select New->Key. Then enter the key name. tpm-5.png

  1. Within LabConfig, create 2 new DWORD values called BypassTPMCheck and BypassSecureBoot and set each to 1. To create a new DWORD value, right click in the right window and select new DWORD (32-bit) Value then name the key, double-click to open it and set it to 1. If you also want to bypass the RAM requirement, add a DWORD values for BypassRAMCheck. tpm-6.png

  1. Close regedit and exit the command prompt. You can now continue with your Windows 11 installation as normal.

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.11

VMware-Backup-DR-Guide

Overview

The VergeOS VMware feature provides a direct interface with vSphere (storage independent) to run a backup agent for VMware virtual machines. The VergeOS agent initiates snapshots, with the ability to access both full and incremental backups for either a one-time import or ongoing backup and DR for vSphere environments.


Setting up VMware Backups - High-level Steps

  • Create a VMware Service (This creates a direct connection to the vSphere environment.)
  • Create Schedule(s).
  • Assign Schedules to VMs (different schedules can be assigned to different VMs.)

Creating a VMware Service

The first step to creating a backup/import of VMware VMs to VergeOS is to create a VMware Service. The VMware service establishes a direct agent connection with vSphere; network access and admin login credentials to the vSphere environment is required.


To Create a New VMware Service:

  1. From the Main Dashboard, click Backup/DR.
  2. Click VMware on the left menu. (Any existing VMware Services will appear in the list view.)
  3. Click New on the left menu.

dr1.png

VMware Service Settings:

  1. Enter a Name for the VMware service (required).
  2. Typically, it is recommended to keep the 2 cores and 2GB RAM default settings in place; this will be suitable for almost all situations.
  3. Optionally, a specific Cluster can be selected (or leave as --Default--).
  4. Optionally, a Failover Cluster can be selected (or leave as --Default--).
  5. Optionally, a Preferred Node can be selected on which to run this service (or leave as --None-- for the system to select Node.)
  6. Optionally, enter a Description to record additional information, if desired.
  7. Select desired On Power Loss setting:
    • Last State - Service  will only be powered on if it was on at the time of power loss.
    • Leave Off - Service will not be powered on when power is restored (regardless of its state at the time of power loss).
    • Power On - Service will be powered on when power is restored (regardless of its state at the time of power loss).
  8. Select a Network on which to run the VMware service. 

DHCP is required on the selected network.


vSphere Settings:

dr1-1.png

  1. Enter the vSphere DNS or IP (required).  The address should be reachable from the network selected for the service. 

It is recommended to connect to the vSphere cluster rather than an individual ESX(i) node.

  1. The default vSphere Port is 443; this is the typical listening port for VMware client connections.  Change to alternate port if needed. 
  2. Enter the vSphere User name.
  3. Enter the vSphere Password for the above user.
  4. The Allow Insecure Certificates option can be selected if the vSphere address is not using a certificate signed by a certificate authority (e.g. self-signed certificates). 
  5. Click Submit to save the new service. 
  6. You are returned to the VMware Services listing where the new service will appear.  Click the Service to select it.  
  7. Click Power On on the left menu to start the service and attempt connection to vSphere.

After the service is started, double-click to bring up the VMWare Service Dashboard. 


Modify Advanced vSphere Settings (Optional):

Once the service is  powered on, advanced vSphere settings can be changed, if desired. 

Default settings will be appropriate for most installations.

Click Edit on the left menu.

  • Max Concurrent VM backups - the number of simultaneous VMware backups.  The default setting (4) is typically appropriate; however, this number can be increased to speed up backup processes from Vsphere systems with high CPU resources and adequate available bandwidth.  Conversely, this setting can be reduced for systems with lower CPU resources/lower available bandwidth.  
  • Name for the auto-created snapshot during backup - the name given to the temporary, VMware-created snapshot used during the backup operation.
  • Default VM backup schedule - defines the backup schedule to be assigned automatically to all new VMware VMs discovered by the service.  Initially, this is set to  --None-, which will set new VMs to use no Schedule (no backups) by default.  After Schedules are created, the default can be changed to assign a specific backup schedule to any newly detected VMs.
  • Automatically enable change tracking per VM - this setting will automatically turn on the VMware CBT (changed block tracking) feature for each VM included in differential and thin-provisioned backups. By default, this setting is enabled (Enabled is recommended).  If this setting is disabled, and CBT is not otherwise enabled on VMware,  a differential backup will default back to a full backup (backup logs will indicate this change.)
  • Backup storage tier - the VergeOS storage tier in which to store backup data.   By default, this is set to tier 4.  Note: Changing this setting affects new Full Backups only.  (In other words: if a backup has already taken place to a different tier, differential backups will continue to be stored in that tier; the new setting will take effect as soon as another Full backup is performed. 

When vSphere settings have been changed as needed, click Submit.  


Advanced VSphere Settings:

  1. Click Refresh VMs on the left menu to discover VMware Virtual Machines. This will initiate a connection to the vSphere system and detected VMs will appear in the VMware Virtual Machines section of the page.  

On the Dashboard, check the Status (top left). If the service successfully connected to the vSphere system, the status will show as  Online and Running.

An Error Status indicates the connection was not made due to: incorrect login credentials, insecure SSL (without enabling the option for insecure SSL), invalid address, or a network issue reaching the VSphere system. 

See Appendix A: Troubleshooting Connection Errors for more information.


Creating a VMware Backup Schedule

A schedule is a grouping of backup Tasks.  A single schedule might include various backups, such as hourly, daily, weekly and monthly backups, and allow for taking backups at different intervals, each with different retention rules.  Additionally, different types of backups can be included within the same schedule: Full (thick provisioned), Full (thin provisioned), and Differential. 

Different schedules can be created to be applied to different VMs, for example a general schedule could be used for production VMs, while a less rigorous schedule is applied to development and testing VMs; yet another schedule that includes frequent backups with shorter retention might be applied to SQL VMs, etc. 


Default Schedule

When a new VMWare Service is created, a Schedule named “Default” is created automatically. This Schedule can be modified to fit your organization’s needs.  You can also create any number of new Schedules.  


To Create a New Schedule:

  1. From the VMware Service Dashboard (Main Dashboard -> Backup/DR → VMware -> double click VMware service in the list.)  
  2. Click Schedules on the left menu.
  3. Click New on the left menu.

dr2.png

  1. Enter a Name for the new Schedule.
  2. Optionally, a Description can be entered to record more information.
  3. Click Submit.
  4. The Schedules list will appear.  Double-click the new Schedule.

At this point the Schedule is just an empty container; one or more tasks need to be added to the Schedule.  

  1. Click New Task on the left menu or click the + Add Task option on the Schedule Dashboard. 

  2. Enter a descriptive Name for the Task (for ex: Midnight_7days; weekly_1monthretention; yearly_perpetual, etc.)

  3. Select the desired Scheduling for the backup Task.  (Granular options allow for great flexibility in task scheduling.)

Example Task Scheduling:

Ex: Every weekday  at 5:15 PM

dr3.png

Ex: Every 2 hours, from 7 AM - 5 PM, except for Sunday:

dr4.png

Ex: Monthly, on the last day of the month:

dr6.png

Ex: One time only, on 2019-04-01 at Noon:

dr7.png

  1. By default, a recurring Task is set to run perpetually.  Optionally,  a Task Expiration can be defined which will cause the Task to cease on the selected date and time.  To set an expiration for the Task: De-select the Never checkbox and enter desired expiration date and time. 

  2. By default, the Backup Job Name will default to: ScheduleName - TaskName-YYYY-MM-DD HH:MM (ex: prodschedule -  hourly - 2019-01-29 11:00 for a backup created from the “prodschedule” schedule, “hourly” task, at 11 AM).  Optionally, a Backup Job Name can be defined and can include any combination of these formatted date variables: 

  • %Y 4-digit year
  • %m 2-digit month (01 to 12)
  • %d 2-digit day of the month (01 to 31)
  • %H 2-digit hour (24-hour clock)
  • %M 2-digit minute (00 to 59)

Example: The entry: “%m-%d-%Y:%H%M-sqlbackup”, run on Jan 26, 2019 at 11AM produces a backup named “01-26-2019:11:00-sqlbackup”  

  1. Select the desired Backup Job Retention; this is the amount of time to keep the backup.  (Units that can be selected: Minutes,  Days (default), Hours, Years, Forever). 

After a backup is run, the expiration of individual Backup Job instances can be modified manually; backup job instances can also be manually deleted before the expiration date/time.

  1. The Quiesce Snapshots option can be selected to invoke the VMWare quiesce feature (Note: VMware Guest Tools required.)  When this option is enabled, VMWare pauses running processes on the guest operating system so that the file system contents are in a known consistent state when the snapshot is taken; this process might include such operations as flushing dirty buffers from the Operating System’s in-memory cache to disk, or other application-specific tasks. Consult VMware documentation for more information about the quiesce feature.

  2. Optionally,  Minimum Backup Jobs to Keep can be selected.   This setting overrides Individual backup expirations to keep the specified minimum number of backups (most recent) in place.  This can provide a safety-net, intended to prevent all backups from expiring before new backups are created: for situations such as a system being powered off for a period of time or an interval of backup errors. 

  3. Select a Backup Mode.  

  • Differential - only transfers changes since the last Full VMware  backup.  Because of the  way that differential backups are stored in the vSAN, a differential backup can be used directly and does not rely on a full backup or other differentials for a restore operation. 

This requires Changed Block Tracking (CBT) enabled on vSphere VMs.

  • Full Backup (Thick provisioned) - Full Backup, requesting all blocks from VMware.
  • Full Backup (Thin provisioned) - Full Backup, requesting only allocated blocks from VMware.

This requires Changed Block Tracking (CBT) enabled on vSphere VMs.

* Differential and Thin Provisioned Full backups  utilize the CBT vSphere feature.  Please see Appendix B for information and considerations regarding this feature.


Using Differential and Full Backups

A Full backup is needed initially and should also be done on a regular basis.  Differential backups are quicker and use fewer resources/bandwidth as only changes since the last full backup are requested.   A prudent strategy will include performing full backups regularly (ex: daily, weekly, bi-weekly), with differential backups at intervals in between.

  1. When the Task is configured as desired, click Submit.  
  2. You are returned to the Schedule page and the new task will appear in the Tasks section.  Click the + Add Task button and repeat the above steps to append additional tasks to the schedule. 

Assigning Schedules

Once the VMware service is created and successfully connects to the VSphere system, the list of discovered VMware Virtual Machines will appear on the VMware Service Dashboard.    dr8.png By default, all VMs have their schedule set to --None--.


To apply a Schedule to VM(s):

  1. From the VMware Service Dashboard, click Virtual Machines on the left menu. 
  2. Select the desired VM(s) from the list.  (Selected VMs show a checked box on the left.) Hint: If you’d like to select all VMs in the list, click the checkbox in the upper left corner.  
  3. Click Edit Backup Schedules on the left menu.

  4. Select the Schedule from the dropdown list and click Submit.

  5. The Backup Schedule assigned to each VM is displayed in the VMware VMs listing.  

Setting the Default Backup Schedule

The default VM Backup Schedule can be defined to automatically assign a backup schedule to all new VMware VMs discovered by the service.   

  1. From the VMware Service Dashboard, click Edit on the left menu. 
  2. In Default VM Backup Schedule, select the desired Schedule from the dropdown list.  
  3. Click Submit to save the change. 

The Default Backup Schedule is displayed on the VMware Service Dashboard.


Manual Backups

Manual backups can also be performed on VMs using the VMware service; this can be helpful in creating a backup immediately before maintenance work,  such as a guest OS upgrade, application update, or other configuration changes. 


To Perform a Manual VM Backup:

  1. From the VMware Service Dashboard, click Virtual Machines on the left menu. 
  2. Select one or more VM(s) in the list.  (Hint: to select all VMs click the checkbox in the upper left corner.)
  3. Click Backup on the left menu. 
  4. A Confirmation dialog will appear; click Yes to proceed with the backup.  
  5. Return to the VMware Service Dashboard (Hint: you can use the breadcrumb at the top or the browser back button to return to the Service Dashboard.)
  6. Click Backup Jobs on the left menu. 

The Manual Backup should appear at the top of the listing and will display a status of “Running” until it is finished, at which point the status will show as “Complete”.

For manual backups, the Name displayed will be the name of the first VM selected for backup, and the Schedule Task column will indicate  a Manual backup.  Additional columns display the Number of VMs backed up (VM Count),  Started and Finished time and, the Expires setting for the backup. 


To Change the Name and/or Expiration of a Backup Job:

  1. Double-click the Backup Job in the listing.

  2. The Backup Job Dashboard displays.  Click Edit on the left menu. 

  3. Make changes to Name/Expires fields as desired. 
  4. Click Submit to save the changes.

To Delete a Backup Job:

  1. Double-click the Backup Job in the listing.
  2. The Backup Job Dashboard displays.  Click Delete on the left menu. 
  3. Click Yes to confirm the delete operation.

Restores


File-level

The VM is imported to the VergeOS environment (From the Backup Job Dashboard, double click the individual VM -> click Import VM.)

VM is powered on in the VergeOS environment where files can be extracted to the VergeOS NAS and accessed via CIFS or NFS.


Restore systems to a VMware environment

Individual VMs or entire VMware system backups can be pushed back to the VMware environment. 


DR/Business Continuity

VMware VMS are powered up in VergeOS from the backup.  Built-in Site-Sync provides the mechanism to synchronize VMware backups offsite to be prepared for quick recovery in the event of a disaster or primary facility outage. 

Appendix A


Troubleshooting VMware Connection Errors

Note: Check Logs (at the bottom of the Dashboard page) for possible additional information.

  • Verify input of correct Address (IP or domain name)

  • Verify network connection 

  • If using a domain name, verify DNS resolution of the name. 
  • The network on which the VMware service is running must have access to the Vsphere address/port provided on port 443 (or port selected). 
  • The network on which the VMware service is running must be DHCP.  

The built-in Diagnostics engine can assist in testing the network connection.  (VMware Services Dashboard -> View Service -> Diagnostics)

  • Verify Login Credentials to vsphere

    • Must be the correct username/password for a VSphere administrator account
  • SSL Certificate

    • If using a self-signed certificate, the option to allow insecure certificates must be enabled.  To modify an existing VMware service: From the VMware Service Dashboard -> Edit -> check the box for Disable SSL host certificate verification

Appendix B


VMware’s Changed Block Tracking (CBT)

Differential and Full(Thin Provisioned) backups utilize VMware’s CBT feature, to request only blocks that have changed since the last full backup, or blocks in use.  This can provide for quicker operations that utilize less bandwidth.  (There is a VergeOS option to automatically turn on CBT for all VMs.)  The following VMware KB article provides more information, including VMware requirements for using CBT: https://kb.vmware.com/s/article/1020128_


CBT Considerations/Cautions

Utilizing CBT to provide faster and more efficient backups is generally fine.  However, it is important to consider that defects in CBT can compromise backups that have utilized the feature. This is a source issue that is not controlled by any third-party agent accessing VMware for backup.  

The following strategies are recommended to mitigate potential risks posed by using the CBT feature: 

  1. As a VMware customer/user, stay abreast of known issues and apply available updates and patches as they become available. In the past, there have been bugs involving the CBT feature, for which VMware has provided patches to fix known CBT defects.
  2. Although VergeOS stores all backups in the vSAN such that they are stand-alone (any backup, including differential, can be used directly and does not rely on another backup for restore operations), a prudent backup strategy will include a schedule of both Full backups and Differential backups in between.  For example, a common schedule used by many organizations is to run a Full backup weekly or twice weekly and differentials on days in between.  
  3. When possible, use Full-Thick Provisioned backup for those that are intended for long-term retention.

Document Information

  • Last Updated: 2024-09-03
  • VergeOS Version: 4.12.6

Troubleshooting VM Network Connectivity Issues

Before you begin, verify if other virtual machines in the environment can access the internet. If no other machines can, there may be a network issue upstream of the VergeOS platform that is preventing access to the outside world. If other VMs are still able to access the internet, the most likely cause is that a configuration step was missed.

The following are the most common configuration mistakes that cause network issues:

  • Missing NIC Configuration: The newly created VM may not have a NIC configured. To verify this, review the NICs section of the VM dashboard. Ensure at least one NIC is present. If not, add one.
  • Incorrect Network Assignment: The VM's NIC may be connected to the wrong network. In the NICs section, ensure at least one NIC is present with the status set to Up, and verify that the correct network is listed. If not, edit the NIC and assign the correct network (one used by a VM with internet access).
  • Improper IP Configuration: The VM might not have a properly configured IP address. Typically, this is resolved at the guest level. Refer to the guest operating system’s documentation to ensure the NIC is detected, installed (with drivers), and configured correctly.
  • Virtio Drivers Not Installed: If the Virtio drivers are not installed, the NIC may not function properly. For instructions on installing Virtio drivers, refer to the Product Guide.

Document Information

  • Last Updated: 2024-09-03
  • VergeOS Version: 4.12.6

How to Share a VM into a Tenant

VergeOS provides an easy way to share a virtual machine (VM) image from a parent environment into a tenant located beneath the current environment. Follow these steps to accomplish the task:

Steps to Share a VM

  1. Navigate to the VM Dashboard: - Go to the VM dashboard of the VM you want to move into a tenant.

  2. Gracefully Power Down the VM: - It is best practice to gracefully power down the VM using the guest operating system's best practices before moving it.

  3. Take a Snapshot: - In the VM dashboard, expand Snapshots in the left navigation menu to access the snapshot commands. - Click Take Snapshot to launch the Machine Snapshot creation screen.

  4. Complete the Snapshot Creation: - At the Machine Snapshot creation screen, fill in the required fields:

    • Machine: The virtual machine you are moving.
    • Name: Provide a unique name for the snapshot.
    • Expiration Date: Set the date/time when the snapshot will automatically be deleted.
    • Click Submit to create the snapshot.
  5. Share the VM Snapshot: - After clicking Submit, you will be taken to the dashboard of the newly created snapshot. - From this view, click on Share VM in the left navigation menu to launch the Shared Objects creation screen.

  6. Create the Shared Object: - At the New Shared Objects creation screen, fill in the required fields:

    • Name: Name the snapshot of the VM something unique.
    • Type: Select Virtual Machine.
    • Snapshot: This should match the name provided during the snapshot creation.
    • Recipient: Select the tenant where you want to share the VM.
    • Click Submit to create the shared object.
  7. Access the Tenant Environment: - Using a web browser, navigate to the tenant environment where the snapshot object was shared. - Log in with the proper authentication credentials.

  8. Create a New Virtual Machine in the Tenant: - In the tenant environment, navigate to Machines > Virtual Machines, and click New to begin creating a new virtual machine.

  9. Import from Shared Objects: - At the New Virtual Machine creation screen, under Select Type, choose -- Import from Shared Objects --. - In the Selections Available section, select the shared object created earlier, then click Next.

  10. Complete the Virtual Machine Settings:

    • On the Virtual Machine Settings screen, complete the required fields:
    • Shared Objects: Select the shared object created earlier.
    • Click Submit to create the new virtual machine in the tenant.

---

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

How To Efficiently Recover a Single VM from a Remote Cloud Snapshot

This is easily achieved for systems that are successfully configured to send a cloud snapshot to a remote destination tenant and have the Sync-back configured properly.

Note

For more information on configuring Sync-back, refer to the inline help Category titled 'Site Sync' under the section labeled 'Syncing Back'.

Recover a Copy of the VM on the Backup Side

  1. On the destination side (where the snapshots are sent), review all of the received remote snapshots and locate the desired snapshot that closely matches the date/time. This is accomplished from the Main Dashboard > System > Cloud Snapshots.
  2. Once the snapshot is located, select (check) the Cloud Snapshot in the list of available snapshots, and on the left navigation menu, select View VMs.
  3. Wait while the list of available VMs loads. This can take a few minutes.
  4. Once the list of virtual machines contained within the cloud snapshot loads, select (check) the desired VM to recover and then select Recover on the left navigation menu.
  5. The Recover VM Snapshot option appears. It is recommended to rename the VM to reflect the date the snapshot was taken. For example, Domain Controller recovered on 09012022.
  6. Wait while the VM is recovered.


Create a New Cloud Snapshot on the Backup Side

  1. On the destination side (where snapshots are sent), create a new cloud snapshot that will contain the newly recovered VM from the steps above. This is done from Main Dashboard > System > Cloud Snapshots.
  2. On the Cloud Snapshots page, select New on the left navigation menu.
  3. The New Cloud Snapshot creation page will load. Name the snapshot. It is recommended to name it something that is easily referenced in future steps, such as Recoveryon09012022.
  4. Set the expiration date to something logical. It should not exist forever but should be far enough into the future to allow time for the transfer back to the original system.
  5. After setting the name and expiration, select Submit to create the snapshot.


Request a Sync-Back on the Original/Source Side

  1. On the origin (sending) side, navigate to the configured outgoing site sync. This is done from Main Dashboard > Backup/DR > Outgoing Syncs, and then double-clicking into the configured outgoing sync.
  2. From the outgoing sync dashboard, click Refresh Remote Snaps on the left navigation menu. This will query the remote side for any new snapshots and list them. It should detect the snapshot created in the steps above.
  3. Once the newly created snapshot is detected, it will be listed under the Remote Snapshots section. Find the snapshot and click on the Request to Download icon to the far right of the listed snapshot.

Request to Download

  1. The Request Cloud Snapshot menu will load. Set a reasonable expiration date for how long the recovered snapshot will be retained on this system, and click Submit.
  2. The system will load the Sync-Back / Incoming Sync. The length of time it will take to transfer the snapshot back can vary greatly depending on several factors, including bandwidth speed and the size of the data to transfer.
  3. Wait while the synchronization completes. Once finished, a new entry will appear in the log section.

    Example

    Sync for 'Morning_20220901' complete (4m 17s) checked [78.1GB] scanned [1.76TB] sent [5.16GB] sent net [2.16GB] dirs [210] files [641] updated [31]

  4. At this point, the snapshot has been successfully transferred back to the original location. Administrators can now perform standard recovery tasks on the VM contained within the snapshot.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Preferred Tier Usage

How Preferred Tier Settings Determine Which Tier to Use

When creating or modifying a virtual machine (VM) disk drive in VergeOS, users can set a Preferred Tier. In most cases, this is left at default, which can be configured under System > System Settings > Default VM Drive Tier. However, the system's behavior when a specified tier does not exist can be unexpected. Here's how VergeOS determines which tier to use in such cases:

  • Setting a preferred tier to a non-existent higher tier:

    • Example: If a user selects Tier 3 in a system that only has Tier 1 and Tier 4 storage available, the system will attempt to pick the next higher (slower) tier. In this case, the system will default to Tier 4.
  • Setting a preferred tier to a non-existent lower tier:

    • Example: If a user selects Tier 3 in a system that only has Tier 1 and Tier 2 storage, the system will pick the next lower (faster) tier. In this case, the system will default to Tier 2.

In both scenarios, VergeOS ensures that the closest available tier is selected based on the user’s preference.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Best Practices - Running a pfSense Virtual Firewall

pfSense is a widely-used open-source firewall and router software that can be run as a virtual machine (VM) within VergeOS. Leveraging pfSense inside VergeOS allows for highly customizable and flexible firewall configurations. Below are the best practices for creating and maintaining a pfSense virtual firewall in VergeOS.

1. Configuring Disk and Network Interfaces

When deploying pfSense as a virtual machine, ensure that the disk and network interfaces are configured for optimal performance.

  • Disk and Network Interface Type: Set both the disk and network interfaces to VirtIO. This configuration provides better performance compared to the default options.
    • VirtIO for NIC: By default, VergeOS may configure the network interface to use E1000. While this can work, it's recommended to switch to VirtIO for better throughput and reduced CPU overhead. Failure to use VirtIO can lead to intermittent traffic issues or slowness, especially under high network loads.
    • VirtIO for Storage: Using VirtIO for storage ensures faster disk I/O, reducing bottlenecks in the system when dealing with large firewall logs or managing stateful connections.

2. Disabling Hardware Checksum Offloading

In certain environments, pfSense may experience network performance issues like packet loss, slowness, or connection timeouts. This is commonly due to hardware checksum offloading on virtualized NICs.

  • Disable Hardware Checksum Offloading:
    • Within the pfSense UI, navigate to System > Advanced > Networking and disable Hardware Checksum Offloading.
    • When enabled, pfSense offloads the processing of checksums to the virtual NIC. However, this feature is better suited for physical NICs, and in virtualized environments, it can cause performance degradation by generating unnecessary processing overhead on the virtual machine.

pfSense NIC Offloading Settings

3. Assigning Adequate Resources

  • CPU and RAM Allocation:

    • Depending on the size of your network and the complexity of your firewall rules, ensure you assign adequate CPU cores and RAM to your pfSense VM.
    • For small to medium environments, 2 CPU cores and 2GB of RAM is usually sufficient. For more complex configurations or higher network traffic, consider increasing these resources to ensure optimal performance.
  • Disk Space

    • Allocate enough disk space for system logs, caching, and configuration backups. Start with at least 10GB of disk space and increase based on the features in use, such as VPNs or IPS/IDS logging.

4. Snapshots and Rollbacks

  • Use VergeOS Snapshots:

    • Before making significant changes to your pfSense configuration or performing major upgrades, create a VergeOS snapshot of the pfSense VM. This allows for a quick rollback in case of misconfiguration or failure.
  • Automate Snapshots:

    • Automate your snapshots for pfSense to ensure regular backups of your firewall’s state. These snapshots can be scheduled in VergeOS and easily restored when needed.

Following these best practices ensures that pfSense operates efficiently and securely within VergeOS, providing a reliable and high-performance firewall solution for your virtualized network environment.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Making a Non-Persistent VM

How to Create a Non-Persistent VM on Reboot

A Non-Persistent VM reverts to its original state after a reboot, discarding any changes made during the session. This is useful for VDI (Virtual Desktop Infrastructure) environments where the system should reset after each use.

Steps to Create a Non-Persistent VM:

  1. Navigate to the VM dashboard.
  2. Shutdown the VM by selecting Actions > Power Off or using the Power button: nonpersistentvm-img1.png !!! note This ensures the data is in a good state for cloning.
  3. Click the Copy button next to the main disk on the VM. nonpersistent-2.png
  4. Change the Media Type to Non-Persistent and click Submit at the bottom. nonpersistent-3.png
  5. Click the Edit icon editiconpencil.png for the original Disk Media Type. nonpersistent-4.png !!! note The new disk will show a Media Type of Non-Persistent. Any changes made to this disk will be reverted upon a reboot of the VM.
  6. Uncheck the Enabled checkbox. nonpersistentvm-img5.png
  7. Start the VM by selecting Power On from the left-hand menu or clicking the Play button: nonpersistent-5.png

This will boot the VM using the non-persistent disk. The disk is fully writable during the session, but all changes will be discarded upon reboot, reverting the VM back to its original state.

Do not delete the original disk. It will not take up additional space due to Deduplication.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

How to Isolate a Virtual Machine

Isolating a virtual machine (VM) can be done in several ways, depending on the specific requirements of the environment. Below are two common methods for isolating a VM within VergeOS.

Remove the Attached Network from the VM

This method essentially simulates unplugging a network cable from the VM, making it function without any external connectivity. It’s suitable when the VM doesn’t need to communicate with any other network.

Steps to Remove the Network:

  1. Navigate to the Virtual Machine Dashboard.
  2. Click on NICs in the left navigation menu to access the VM's virtual network adapters.
  3. Select the NIC you want to edit and click Edit from the left navigation menu.
  4. In the NIC configuration window, use the drop-down list to change the Network from its current value to --None--.
  5. If the VM has multiple NICs, repeat this process for all active/enabled NICs.

By removing the network from all NICs, the VM will no longer have network access.

Create a New Internal Network

If the VM requires connectivity but still needs to be isolated from other networks, creating a new internal network with no other VMs connected is the preferred solution.

Steps to Create an Internal Network:

  1. From the VergeOS dashboard, navigate to Networking and create a new Internal Network.
  2. Set a Default Gateway for outbound access if needed.
  3. After the internal network is created, return to the VM dashboard and update the NIC to attach the VM to the newly created internal network.

For more detailed instructions on creating internal networks, refer to the VergeOS inline help under Networking in the Internal Networks section.

This method allows the VM to have restricted network access while still providing outbound connectivity through the internal network.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Exporting Virtual Machines from VergeOS

Exporting a virtual machine (VM) from VergeOS allows you to download the VM’s disk in .raw format, which is compatible with many hypervisors. This guide outlines the steps to export a VM and download its virtual disk.

Steps to Export a Virtual Machine

  1. Log in to the VergeOS platform and navigate to the dashboard of the virtual machine you wish to export.
  2. From the left-hand menu, click on Drives to view a list of the virtual disk drives attached to the VM.
  3. Select the drive you want to export, then choose Download from the left-hand menu. The virtual disk will be downloaded in .raw format.
    • The .raw disk format is widely supported by many modern hypervisors.
  4. The system will automatically begin downloading the disk image.
  5. Once the download completes, refer to the documentation for your destination hypervisor for instructions on how to import, upload, or convert the .raw disk image.

Important Considerations

  • .raw format: The exported VM drive is downloaded in .raw format. This format is compatible with most hypervisors, but some may require converting the image to another format such as .qcow2 or .vmdk. Check your destination hypervisor’s documentation for conversion tools or instructions.
  • File size: Depending on the size of the virtual disk, the download can be large. Ensure you have enough disk space available on the system where you are downloading the file.

By following these steps, you can successfully export and download virtual machines from VergeOS for use in other environments.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Accessing the Verge.io UI from a VM

Overview

Key Points

  • Access the VergeOS UI from a VM within your environment
  • Utilize hair-pinning network technique
  • Create a specific network rule on the internal network

This article guides you through the process of setting up access to the VergeOS User Interface (UI) from a virtual machine (VM) running inside the VergeOS system. This is accomplished using a networking technique known as hair-pinning, where a packet travels to an interface, goes out towards the Internet, but instead of continuing, it makes a "hairpin turn" and comes back in on the same interface.

Prerequisites

  • A running VergeOS environment
  • A virtual machine (VM) within your VergeOS environment
  • Access to the VergeOS UI
  • Basic understanding of network rules in VergeOS

Steps

  1. Navigate to the Internal Network - Log into your VergeOS environment - Go to the internal network that your target VM is connected to

  2. Create a New Rule - Locate the option to create a new rule - Configure the rule with the following settings:

    Rule: - Name: Use a reference name, such as "Allow UI" - Action: Translate - Protocol: TCP - Direction: Incoming - Interface: Auto - Pin: No

    Source: - Type: Any / None - Source Ports/Ranges: Leave blank

    Destination: - Type: My Network Address - Destination Ports/Ranges: 80, 443

    Target: - Type: Other Network DMZ IP - Target Network: Core - Target Ports/Ranges: Leave blank

  3. Submit the Rule - Click "Submit" to save the rule

  4. Apply the New Rule - Click "Apply Rules" to activate the newly created rule

  5. Access the UI from the VM - Open a web browser within your VM - Navigate to the IP address of the internal network (e.g., if the internal network IP is 192.168.0.1, use this address)

Pro Tip

Always ensure that your VM's network settings are correctly configured to use the internal network where you've set up this rule.

Visual Guide

Here's a visual representation of the rule configuration:

hairpin.png

Troubleshooting

Common Issues

  • Problem: Unable to access the UI after creating the rule
  • Solution:
    1. Verify that the rule is applied correctly
    2. Check if the VM's network interface is on the correct internal network
    3. Ensure no firewall rules are blocking the connection

Additional Resources

Feedback

Need Help?

If you encounter any issues while setting up UI access or have questions about this process, please don't hesitate to contact our support team.


Document Information

  • Last Updated: 2024-08-29
  • VergeOS Version: 4.12.6

Sharing Media Images to Tenants

Overview

Key Points

  • Service Providers can share files with Tenants
  • Files must already be uploaded to Media Images
  • Process is quick and uses a branch command

This article guides Service Providers through the process of sharing files, specifically media images, with their Tenants in the VergeOS system. This feature allows Tenants to access specific files within their own Media Images section.

Prerequisites

  • Access to the VergeOS system as a Service Provider
  • Files already uploaded to the vSAN
  • Existing Tenants in the system

Steps

  1. Navigate to the Tenants Dashboard - From the Main Dashboard, select "Tenants" on the left menu

  2. Access Tenant List - Select "Tenants" to view a listing of all your Tenants

  3. Select the Desired Tenant - Double click on the Tenant you want to share files with

  4. Access the Add File Feature - Select "Add File" in the left menu

  5. Choose File Type - Select File Type from the dropdown list

Tip

Select "ALL" to get a listing of all files available, regardless of type. This will include .raw files (VM disk images) from the parent VDC.

  1. Select Specific File - Choose the specific file you want to share from the dropdown list

  2. Submit Changes - Click the submit button at the bottom of the page

  3. Confirmation - The process is near-instant as it is done with a branch command - The file is now available to the Tenant within their own Media Images section

Troubleshooting

Common Issues

  • Problem: File not appearing in Tenant's Media Images section
  • Solution:

    1. Verify that the file was successfully uploaded to Media Images
    2. Check if the correct file type was selected
    3. Ensure that the changes were submitted properly
  • Problem: Unable to select a specific file

  • Solution:
    1. Confirm that the file exists in Media Images
    2. Try selecting "ALL" in the File Type dropdown to see if the file appears

Additional Resources

Feedback

Need Help?

If you encounter any issues while sharing media images or have questions about this process, please don't hesitate to contact our support team.


Document Information

  • Last Updated: 2023-08-24
  • VergeOS Version: 4.12.6

How to Reset a Tenant Administrative Password

If you need to change the administrative credentials for a tenant environment in your VergeOS system, follow these steps:

  1. Log in to the VergeOS environment where the tenant is hosted.
  2. Navigate to the Tenant Dashboard of the tenant for which you need to change the admin password.
  3. In the Tenant Dashboard, click the Edit button in the left navigation menu. This will open the Tenant Edit screen.
  4. In the Tenant Edit screen, type the new password in the Admin User Password field.
  5. Re-enter the password in the Confirm Admin User Password field.
  6. After entering the same password in both fields, click Submit. If the passwords do not match, an error message will appear.
  7. After successfully updating the admin password, open a web browser and navigate to the tenant environment where the password was changed.
  8. Log in as the admin. The username will be admin and the password will be the new password you saved in step 6.

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

vSAN Encryption Information

You can confirm that the vSAN has encryption enabled by navigating to Nodes> Node 1> Drives and then double-clicking on the first drive in the list. There is a checkbox for encryption.  If it is encrypted, it will be checked.

encryption.png

  • Encryption for the vSAN is configured during the initial installation only.

  • System startup on an encrypted system can be configured two different ways:

  1. The most common method is by having encryption keys written to a USB drive during the initial installation. In this scenario, these drives are typically plugged into the first two nodes of an encrypted system to boot normally. All other nodes do not require them, as Node 1 and Node 2 are the controller nodes. The USB drive does not require much storage at all, less than 1GB.
  2. If the controller nodes do not have USB encryption keys connected, the system will prompt an operator to type the proper encryption password to complete the power-up process.
  • Default encryption is set for all snapshot synchronizations through a site-sync.

Information about encrypting a Site Synchronization can be found in the Product Guide


Document Information

  • Last Updated: 2024-09-03
  • VergeOS Version: 4.12.6

Reasons for Unexpected / Unexplained vSAN Growth

There are several reasons for the vSAN to start growing at a rate faster than anticipated. Administrators should first determine when the unexplained growth occurred by reviewing the vSAN Tiers' growth history, and then assess potential areas for unexpected growth.

Review vSAN Tiers for Growth History

To isolate unexplained growth, it is important to narrow down when the growth increased exponentially. Using the steps below, administrators can review storage growth and visualize normal growth from daily operations versus spikes in growth, which are typically unexpected.

  1. Navigate to the vSAN Tiers from the Main Dashboard. If vSAN Tiers is not present, then this environment is a tenant of a parent system, and the vSAN tier needs to be examined at the parent system.
  2. Open the vSAN Tier with unexpected growth (for example, vSAN Tier 0).
  3. On the left navigation menu, click on History.
  4. A new menu will appear showing history in various graphs. Modify the filter period to isolate any growth on this tier. - It is recommended to start with a custom filter of 1 day and review the Storage Usage graph.

Things to Note:

  • If you see dips and spikes every hour or once a day, this is likely the result of snapshots falling out of retention (old ones expiring, new ones being created). Note whether the total storage consumed at the start of the day is nearly equivalent to the end of the day. If so, expand the custom filter to a week.
  • When reviewing by week, check if the total storage consumed at the start of the week is similar to the end. If, for example, the growth is roughly 10%, repeat for the previous week. If the weekly growth percentage is consistent, this represents your average weekly growth rate, which can help plan for hardware expansion.
  • Filter the current month and check for any sudden spikes in storage consumption on the Storage Usage graph. Click and drag over the time in question to zoom in on the data, and hover over the graph for specific date/time information.

vsan_unexpected_growth.png

Possible Reasons for Storage Increase

Several areas in the VergeOS platform may contribute to unexpected storage growth. Common areas to check include:

  • Cloud Snapshots:
  • Navigate to System > Cloud Snapshots.
  • Are any being held past their expected expiration time?
  • Are there snapshots without a Snapshot Profile? These may have been taken manually. Investigate when and why they were taken.
  • Are any snapshots set to "Never Expire"? This can lead to large data consumption over time.

  • Virtual Machines (VMs) Snapshots:

  • Navigate to the Machines Dashboard. The Snapshots count box shows the number of machine-level snapshots present. Click this box to list all VM snapshots and their creation date/time. Review if any can be removed.
  • Navigate to Machines > Virtual Machines. Sort by the Snapshot Profile column to identify VMs with machine-level snapshots. These are included in the recurring cloud snapshots, so review whether individual snapshots are necessary or if they can be removed.

  • VMWare Backup Jobs:

  • Navigate to Backup/DR > VMware Services and review each VMware Service instance for Backup Job history.
  • On the left menu, click Backup Jobs to review each specific instance. Check the Expires column for each backup and review if it can be removed.

  • Media Images:

  • Navigate to Media Images and sort by Modified. Check if any upload dates/times match the unexplained growth period.
  • Review whether media images, especially other hypervisor formats (e.g., .ova or .vhdx), can be removed.

  • Incoming Site Syncs:

  • Navigate to Backup/DR > Incoming Syncs. Open each Incoming Sync dashboard and check the Received Snapshots count. Investigate the source (origin) site for increased storage matching the timeframe.

  • Tenant Storage:

  • Navigate to Tenants > Each Tenant Dashboard.
  • Review Total Storage Used by clicking on History in the left menu. Follow the same process listed above to review growth history.
  • If unexpected growth is found, investigate within the tenant for the possible causes of storage increase (as listed above), and within any sub-tenants if applicable.

Document Information

  • Last Updated: 2024-09-03
  • VergeOS Version: 4.12.6

Common Snapshot Synchronization Error Messages Explained

The VergeOS platform provides a feature known as Site Syncs to replicate a copy of a cloud snapshot.

For more information on Snapshots and Site Syncs, refer to our Product Guide on Sync Configuration.

Occasionally, the system may generate a system alert from a new Message Log entry related to the Site Sync functionality. Below is a list of common errors along with a brief explanation:

ybvsan: Error walking tier 3 refs: (2) No such file or directory

  • This error can occur if the VergeOS software version is mismatched between the sending side and the destination side.

Unable to delete snapshot that no longer exists: Resource '/v4/cloud_snapshots/1' not found during delete

  • This error is usually the result of a timing issue when a snapshot is being deleted, and the reference is deleted in the metadata of the system.

Error notifying client with 'notify_complete' Error (403) while communicating with server

  • The snapshot successfully synchronized, but this error appeared during the sync clean-up process. If this error occurs on multiple snapshot synchronizations, the handshake credentials between the two systems may have stopped working. In that case, consult VergeOS support for assistance.

Error - Sync back not found and no registration code supplied

  • This error occurs when requesting a snapshot back from the destination site to the source site. If this message appears, Sync Back is not configured between the two systems. Refer to the Guide on Sync Back for instructions on setting up Sync-Back between the systems.

Error - Sync Request for 'system name' Error notifying client with 'notify_start' Connection timed out

  • This error occurs when requesting a snapshot back from the destination site to the source site, similar to the previous error. Ensure that Sync Back is configured properly between the two systems.

An error has occurred while syncing 'snapshot name': Resource temporarily unavailable. Retrying 1 of 10

  • This error typically results from an interruption of the transfer connection between the source site and the destination site. The sync will automatically retry following the Retry interval setting. The retry count will increase until the connection is re-established or until the maximum Queue retry count has been reached.

Error- Unable to create tenant snapshot 'snapshotinterval_yyyymmdd': This name already exists

  • The local snapshot schedule is naming snapshots the same as the inbound snapshots from the site sync. A simple fix is to rename the origin (sending) side snapshot by editing the auto-sync configuration. Use the field Prefix the snapshot name with this on the destination and add something unique, such as remote-.

Unable to update cloud snapshot: No such file or directory

  • This error indicates a possible timing issue with snapshots. Review the Outgoing Sync configuration on the sending site for any setting mismatches.

Error notifying client with 'notify_start' Connection timed out

  • The sync task was unable to start because the connection timed out. Typically, this error occurs when requesting a snapshot back from the destination side to the original sending side. In most cases, this is caused by a firewall blocking the traffic or missing traffic rules on the destination side. Refer to the Guide on Sync Configuration for the required traffic rules.

---

Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

Scaling Up VS. Scaling Out

Adding Additional Resources

There are several methods to add additional resources to your VergeOS environment. It is recommended that you consult with your sales representative on planning for the option that makes the most sense for your environment.

Here are a few key things to remember when planning for expanding the system:

Scale Up

Expanding resources on current nodes:

When adding additional drives into existing nodes: - It is important to add an equal number of drives to all nodes in that cluster.

When adding additional memory into existing nodes: - It is important to properly place a node into maintenance mode before powering the node off. - This ensures that all running workloads are gracefully migrated to other nodes in the system.

Scale Out

Expanding by adding additional nodes:

Key points to remember: - Clusters must contain two or more nodes of the same configuration. - When adding a new node to a system, N+1 redundancy needs to be maintained to ensure high availability. - Adding a new node needs to match the configuration of another node in the cluster: processor, memory, and physical disk drives should match the cluster.

If adding a matching node is not an option: - A new cluster can be added to the system. - However, every cluster must contain two or more nodes of the same configuration.

Remember, consulting with your sales representative is crucial for planning the expansion that best suits your environment.


Document Information

  • Last Updated: 2023-01-24
  • VergeOS Version: 4.12.6

Scaling Up a vSAN

To scale up a vSAN, follow the steps below. However, before proceeding, ensure that your current vSAN has at least 50% free capacity. If the free capacity is less than 50%, and you are not doubling the number of drives, you will need to scale out by adding a node to the vSAN.

Steps to Scale Up

  1. Physically add the drives into the available empty slots on the node you want to scale up.

  2. Log in to the host system's UI and select the appropriate cluster you want to scale out from the top compute cluster section on the home page.

  3. Select the node that you are scaling up.

  4. Refresh the system to recognize the new drives: - Select Refresh from the left menu, and choose Drives & NICs from the dropdown. - Confirm by selecting Yes.

  5. Select the Scale Up option on the left menu.

  6. The page will now show the newly inserted drives in an offline state. Select the drive(s), then under Node Drives, select the Scale Up function.

  7. Select the appropriate tier for the drive(s) and submit.

scaleupvsan5.png

Important

  • All drives in a tier must be alike. If a drive of an incorrect size is added to an existing tier, the tier will only be able to use the space of the smallest drive.
  • Ensure that your vSAN has at least 50% free capacity unless you are doubling the capacity. If the free space is less than 50% and you are not doubling the drive count, consider scaling out by adding a node.

Upon completion, the screen will refresh and the drives will disappear from the view. Go back to the main page, where you will see the vSAN tiers change color to yellow, indicating that it is in a repair state. This is expected, and the vSAN will return to a green/healthy state after a few minutes, showing the newly added tier or increased space on an existing tier.

Repeat these steps for each node as necessary.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6

How To Identify a Failed Disk In Your VergeOS Environment

VergeOS offers a diagnostic function that allows system administrators to turn a disk drive's LED light on or off, making it easier to physically identify a failed or problematic drive. Follow the steps below to locate a failed disk drive for replacement.

Steps to Identify a Failed Disk

  1. Log in to the VergeOS UI and navigate to the dashboard of the node where the failed disk resides.
  2. On the Node Dashboard, locate and select Diagnostics from the left-hand column.
  3. In the Diagnostics page, change the Query to LED Control (Drive).
  4. In the LED Control (Drive) details section:
    • Path: Enter the path to the drive you want to locate (e.g., /dev/sdb). If you're unsure of the path, check the system alerts and logs for recent error or warning messages.
    • State: Set the LED state to On, then click Send to activate the LED light on the drive.
  5. Locate the drive with the active LED indicator in your physical server.
  6. Once the drive has been identified and replaced, set the State to Off and click Send to deactivate the LED light.

For detailed instructions on drive replacement, refer to the Maintenance section in the inline help under Drive Replacement. This section guides you through the entire process.


Document Information

  • Last Updated: 2024-08-29
  • vergeOS Version: 4.12.6