Skip to content

Knowledge Base#

Welcome to the VergeOS Knowledge Base

Overview

Key Points

  • The VergeOS Knowledge Base contains troubleshooting guides, best practices, and how-to articles
  • Use the search function, categories, and tags to find relevant information quickly
  • Articles follow a consistent format with overview, prerequisites, steps, and troubleshooting sections
  • Updated regularly to reflect the latest VergeOS features and improvements

Welcome to the VergeOS Knowledge Base! This resource is designed to help you find solutions quickly, optimize your VergeOS environment, and troubleshoot common issues. Whether you're new to VergeOS or an experienced administrator, this guide will help you navigate our documentation effectively.

How to Use the Knowledge Base

Search Functionality

The fastest way to find specific information is through our search function:

  1. Use the search bar at the top of the page
  2. Enter keywords related to your question or issue
  3. Review the search results to find relevant articles
  4. For more focused results, use specific terms (e.g., "UEFI VM boot" instead of just "boot")

Articles are organized into logical categories to help you browse related content:

  • Getting Started: Introductory guides and basic concepts
  • Installation: Guides for installing and setting up VergeOS
  • Virtual Machines: Everything related to virtual machines
  • Networking: Network configuration and troubleshooting
  • Storage & vSAN: Storage management and optimization
  • Tenants: Multi-tenancy setup and management
  • Troubleshooting: Common issues and their solutions
  • API & Automation: Programmatic access and automation guides
  • Best Practices: Recommendations for optimal performance

Using Tags

Tags provide another way to discover related content:

  1. Articles are tagged with relevant keywords
  2. Click on a tag to see all articles with that tag
  3. Use tags to find specific technologies or features (e.g., "UEFI", "virtio", "snapshot")

Understanding Article Structure

Each article follows a consistent format to help you quickly find the information you need:

  1. Title & Overview: A brief description of what the article covers
  2. Key Points: Important takeaways highlighted at the beginning
  3. Prerequisites: What you need before starting
  4. Steps: Clear, numbered instructions
  5. Troubleshooting: Common issues and solutions
  6. Additional Resources: Related articles and external references
  7. Document Information: Last update date and applicable VergeOS version

Types of Content

How-To Guides

Step-by-step instructions for completing specific tasks, such as:

  • Creating a new VM
  • Setting up network routing
  • Configuring backups

Troubleshooting Articles

Guides to diagnose and resolve common issues:

  • VMs not booting
  • Network connectivity problems
  • Storage performance issues

Best Practices

Recommendations for optimizing your VergeOS environment:

  • VM sizing guidelines
  • Network design principles
  • Storage tier usage

Reference Information

Detailed technical information:

  • API documentation
  • Configuration parameters
  • System requirements

Contributing to the Knowledge Base

We continuously improve our documentation based on user feedback:

  • At the bottom of each article, you'll find a "Need Help?" section where you can provide feedback
  • If you discover outdated information or errors, please let us know
  • Suggest new topics that should be covered in the Knowledge Base

Staying Updated

The Knowledge Base is regularly updated to reflect the latest VergeOS features, improvements, and fixes:

  • Check the "Last Updated" date at the bottom of each article
  • Articles are tagged with the applicable VergeOS version
  • New content is added regularly based on user feedback and product updates

Additional Support Resources

If you can't find what you're looking for in the Knowledge Base:

  • Product Guide: For comprehensive information about VergeOS features and capabilities
  • Support Portal: Submit support tickets and track their progress
  • Community Forums: Connect with other VergeOS users and share experiences

Feedback

Need Help?

If you have suggestions for improving the Knowledge Base or can't find the information you're looking for, please reach out to our support team. We're committed to making our documentation as helpful and comprehensive as possible.

Document Information

  • Last Updated: 2025-03-10
  • VergeOS Version: 4.13.0

Network Diagnostics Guide

Overview

This guide provides comprehensive information about the network diagnostic options available in the user interface. These diagnostic tools enable system administrators to monitor, troubleshoot, and maintain Verge deployments effectively.

Critical Warning

The diagnostic commands detailed in this guide are powerful administrative tools. Improper usage can result in:

  • System outages
  • Service interruptions
  • Potential data loss

Exercise extreme caution and ensure proper understanding before execution.

Prerequisites

To use these diagnostic tools, you must have:

  • UI access to your VergeIO cluster
  • Note: Tenants will have their own networking, and therefore their own Network Diagnostics page.

Accessing Network Diagnostics / Issuing Diagnostic Commands

  1. Navigate to Network Diagnostics using either method:
  • From the home screen: Select the Networks count box → Networks (left menu) → Select a network (right side of the screen) → Diagnostics

  • Alternative path: Home screen → Networks (left menu) → Select a network (right side of the screen) → Diagnostics 2. Command execution:

  • Select desired command from the dropdown menu

  • Configure available options if applicable
  • Click SEND→ to execute

Command Visibility

Enable the "Show Command" option to view the exact command being executed. This can be valuable for:

  • SSH execution
  • BASH script integration
  • Advanced command automation

ARP Scan

Purpose: Scans the local network using ARP (Address Resolution Protocol) packets to discover active devices.

Details:

  • Sends ARP requests to all possible addresses in the specified network
  • Displays MAC and IP addresses of responding devices
  • Used for network discovery and inventory

CLI Syntax: 

lxc-attach -n vnet3 -- arp-scan -l -I [interface]

ARP Table

Purpose: Displays the current ARP cache with IP addresses instead of hostnames.

Details:

  • Shows the ARP table maintained by the kernel
  • The -n flag prevents DNS lookups (displays numeric IP addresses)
  • Lists MAC addresses associated with IP addresses the system has communicated with

CLI Syntax: 

lxc-attach -n vnet3 -- arp -n

DHCP Release/Renew

Purpose: Releases the DHCP address for the selected interface, then attempts to renew it.

Details:

  • This command sequence effectively performs a "release and renew" operation for DHCP-assigned IP addresses:
  • Release the current IP address (USR2 signal)
  • Waits for 2 seconds (sleep 2)
  • Request a new IP address (USR1 signal)

CLI Syntax: 

lxc-attach -n vnet3 -- busybox sh -c killall -USR2 udhcpc ; sleep 2 ; killall -USR1 udhcpc

DNS Lookup

Purpose: Performs DNS lookups for specified query types.

Details:

  • Used for troubleshooting DNS issues and domain information gathering
  • Common query types:
  • A: IPv4 address records
  • AAAA: IPv6 address records
  • MX: Mail exchange records
  • NS: Name server records
  • TXT: Text records
  • CNAME: Canonical name records

CLI Syntax: 

lxc-attach -n vnet3 -- host -t Query_Type DNS_Name

FRRouting / BGP/OSPF

Purpose: Allows the configuration of FRRouting.

Details: For more information on other values and variables, refer to FRR documentation & Configuring BGP Hold Down Timers.

CLI Syntax: 

lxc-attach -n vnet3 -- vtysh -c command_goes_here

IP Commands

Purpose: Allows for the configuration of IP and it's subsequent related items.

Address

Purpose: Displays and configures network interface addresses.

Details:

  • Shows IP addresses, subnet masks, and interface states
  • Displays both IPv4 and IPv6 addresses

CLI Syntax: 

lxc-attach -n vnet3 -- /sbin/ip address

Connection Tracking

Purpose: Displays the contents of Netfilter's Connection Tracking file which contains information about network connections.

Details: This file displays the current state of all tracked network connections on the system. Each line in the file represents a single tracked connection. The contents typically include entries with fields such as:

  • Protocol (tcp, udp, icmp)
  • Connection states (ESTABLISHED, TIME_WAIT, etc.)
  • Source and destination IP addresses and ports
  • Connection timeouts
  • Packet and byte counts
  • NAT information if applicable

CLI Syntax: 

lxc-attach -n vnet3 -- dd bs=262144 count=1 if=/proc/net/nf_conntrack

Purpose: Displays network interfaces at layer 2 (data link layer).

Details: - Shows interface states, MTU values, and MAC addresses

CLI Syntax: 

lxc-attach -n vnet3 -- /sbin/ip link

Multicast Address

Purpose: Displays multicast addresses assigned to interfaces.

Details: - Shows IPv4 and IPv6 multicast addresses - Displays which interfaces are subscribed to which multicast groups - Useful for debugging multicast routing and applications

CLI Syntax: 

lxc-attach -n vnet3 -- /sbin/ip maddress

Multicast Routing Cache

Purpose: Displays multicast routing table.

Details: - Shows active multicast routes - Includes source and group addresses - Displays incoming and outgoing interfaces - Useful for troubleshooting multicast routing issues

CLI Syntax: 

lxc-attach -n vnet3 -- /sbin/ip mroute

Neighbor

Purpose: Displays neighbors (ARP table) of the current device.

Details: - Similar to arp -n. - Shows IPv4 and IPv6 neighbors - Includes MAC addresses and states of neighbors

CLI Syntax: 

lxc-attach -n vnet3 -- /sbin/ip neighbor

Routing Table

Purpose: Displays the IP routing table.

Details: - Shows all routes currently configured on the system - Displays default gateway, network routes, and host routes

CLI Syntax: 

ip route show table all

Rule

Purpose: Displays and manipulates the routing policy database.

Details: - Shows policy-based routing rules - Allows for complex routing setups with multiple routing tables - Used for advanced networking configurations - Rules are evaluated in priority order (lower numbers first)

CLI Syntax: 

lxc-attach -n vnet3 -- /sbin/ip rule

Transform (xfrm) - Policy

Purpose: Displays IPSec policies.

Details: - Shows security policies for IPSec communications - Displays source, destination, protocols, and actions

CLI Syntax: 

lxc-attach -n vnet3 -- /sbin/ip xfrm policy

Transform (xfrm) - State

Purpose: Displays IPSec security associations.

Details: - Shows the current security associations (SAs) for IPSec - Displays encryption algorithms, keys, and related information - Used in conjunction with ip xfrm policy

CLI Syntax: 

lxc-attach -n vnet3 -- /sbin/ip xfrm state

IPsec

Purpose: Allows for the configuration of IPsec and it's subsequent related items.

List Cryptographic Algorithms

Purpose: Lists all algorithms supported by the IPSec stack.

Details: - Displays encryption, authentication, and compression algorithms - Shows available key lengths and other parameters

CLI Syntax: 

lxc-attach -n vnet3 -- ipsec listalgs

List IKE Counters

Purpose: Displays statistics and counters for IPSec connections.

Details: - Shows packet counts, bytes transferred, and errors - Useful for monitoring and troubleshooting IPSec tunnels

CLI Syntax: 

lxc-attach -n vnet3 -- ipsec listcounters

IPsec Show Config

Purpose: Displays the contents of StrongSwan's VPN Configuration file which contains information about network VPN connections.

** Details**: This file contains settings for your VPN tunnels including:

  • Connection definitions
  • Authentication methods
  • Encryption algorithms
  • Network settings
  • Tunnel endpoints
  • Identity information
  • Secret key references

CLI Syntax: 

lxc-attach -n vnet3 -- dd bs=262144 count=1 if=/tmp/vpn/ipsec.conf status=none

Status

Purpose: Displays the status of IPSec connections.

Details: - Shows active IPSec tunnels and their current state - Displays connection names, remote endpoints, and status - Useful for quick verification of IPSec connectivity

CLI Syntax: 

lxc-attach -n vnet3 -- ipsec status

Status All

Purpose: Displays detailed status of all IPSec connections.

Details: - Shows comprehensive information about IPSec tunnels - Includes encryption algorithms, key lifetimes, traffic statistics - Displays connection policies and security associations - Valuable for in-depth troubleshooting of IPSec issues

CLI Syntax: 

lxc-attach -n vnet3 -- ipsec statusall

NMAP

Purpose: Network exploration and security auditing tool.

Details: - Scans networks and hosts for open ports and services - Can determine operating systems and service versions - Supports various scanning techniques (SYN, TCP, UDP, etc.) - Offers script-based vulnerability scanning - Essential tool for network administrators and security professionals

CLI Syntax: 

lxc-attach -n vnet3 -- nmap 192.168.0.1 -p22-100

Ping

Purpose: Tests connectivity to a target host.

Details: - Sends ICMP Echo Request packets and waits for ICMP Echo Reply - Measures round-trip time (latency) to the target - Shows packet loss percentage - Basic but essential network troubleshooting tool - Useful for testing basic connectivity and network performance

CLI Syntax: 

lxc-attach -n vnet3 -- busybox ping -c 1 -W 5 8.8.8.8

Show Firewall Rules

Purpose: Displays the current nftables firewall ruleset.

Details: - Shows all tables, chains, and rules configured in nftables - Replacement for the older iptables command - Provides a comprehensive view of the firewall configuration - Useful for troubleshooting connectivity issues and security auditing

CLI Syntax: 

lxc-attach -n vnet3 -- nft list ruleset

TCP Connection Test

Purpose: Uses netcat to connect to checkip.dyndns.org to determine your public IP address.

Details: - Establishes a TCP connection to the specified host and port - Used to determine external IP address

CLI Syntax: 

lxc-attach -n vnet3 -- busybox nc -w5 checkip.dyndns.org 80

TCP Dump

Purpose: Captures and displays network packets on a specific interface.

Details: - There are multiple Verbose Output options - Checking Show Link-Level Header can aid in VLAN troubleshooting - Expressions can be used to filter the output. - Type qualifiers (host, net, port, portrange) - Direction qualifiers (src, dst) - Protocol qualifiers (ether, ip, ip6, tcp, udp, icmp, arp) - Logical operators (and, or, not) - Advanced filters (greater than, less than, TCP flags, byte offsets)

CLI Syntax: 

lxc-attach -n vnet3 -- busybox timeout 15 tcpdump -lni eth0 -c 100

Top CPU Usage

Purpose: Displays system process information in batch mode for a single iteration.

Details: - Shows CPU, memory, and process details - Useful for system monitoring and troubleshooting performance issues

CLI Syntax: 

lxc-attach -n vnet3 -- /usr/bin/top -b -n 1

Top Network Usage

Purpose: Displays bandwidth usage on a network interface by host.

Details: - Shows real-time bandwidth usage by connection - Useful for identifying which hosts are using the most bandwidth

CLI Syntax: 

lxc-attach -n vnet3 -- busybox timeout 10 /usr/sbin/iftop -tNi eth0 -n

Trace Route

Purpose: Traces the route packets take to a destination.

Details: - Displays each hop (router) between your computer and the destination - Shows round-trip time for each hop - Useful for diagnosing routing issues and network latency problems

CLI Syntax: 

traceroute -n -w 3 google.com

Trace/Debug Firewall Rules

Purpose: Monitors and traces packets as they traverse nftables rules.

Details: - Shows which rules packets match and the resulting actions - Extremely useful for debugging complex firewall configurations - Requires root privileges

CLI Syntax: 

lxc-attach -n vnet3 -- busybox timeout 3 nft -nnn monitor trace

What's My IP

Purpose: Queries OpenDNS to determine your public IP address.

Details: - Simple, reliable method to determine your public IP address - Works even when HTTP-based services might be blocked

CLI Syntax: 

lxc-attach -n vnet3 -- dig +short myip.opendns.com @208.67.222.222

Additional Resources

Feedback

Need Help?

If you need further assistance or have any questions about this article, please don't hesitate to reach out to our support team.

Document Information

  • Last Updated: 2024-03-21
  • VergeOS Version: 4.13.4

Enabling System SSH Access

Key Points

  • SSH access to a VergeOS system is generally not needed because full access is provided from the UI.
  • SSH should only be enabled for specific hardware diagnostics or other special circumstances.
  • Although VergeOS employs many safety protections, opening SSH on any system can introduce vulnerability.

Important SSH Security Procedures

  • Always use source-controlled external rules to strictly limit ssh access to trusted addresses.
  • Enable SSH access on a temporary basis; disable rules again when done with the session.

Steps to Enable SSH access

SSH Access rules are auto-created, and disabled, during system installation.

  1. Enable the core network rule: Navigate to the Core network dashboard, modify the "SSH Access" rule, select the Enabled option and Submit to save the change. ssh-rule-core.png

  2. Add source control to the external network rule: Navigate to the external network dashboard, modify the "SSH Access" rule to configure specific source IP address(es) and/or address range(s) to tightly control access.

  3. Enable the external network rule: select the Enabled option and Submit to save the change.
    Ex. External Network Rule: ssh-rule-external.png

  4. Apply Rules to both networks.

Warning

Danger

  • VergeOS is a specialized kernel, with a read-only overlay. Do not install additional Debian packages or applications as they can conflict with VergeOS operation and cause system malfunction or data loss. Additionally, extraneous programs are wiped at reboot.
  • Check with VergeOS support before making any modifications at the command line. Issues resulting from unsanctioned command-line changes are the sole responsibility of the customer.

How to Use Root External IPs in Tenants in VergeOS

In VergeOS Virtual Data Centers leveraging Tenants, a tenant may need a public IP address (External IP) from the root External network for use by VMs inside the tenant space.

Using Network Blocks

Network Blocks can be used to assign a group of IPs as a single unit, and often represent the most straightforward method of using an External IP inside a tenant space for VM NICs. They are created on the root External network, or the external interface upon which the IPs you intend to use are routable.

Pro/Cons

Pro - Allows direct assignment of a public IP to a tenant VM's network interface.
Pro - Leverages built-in Layer 3 functions, maintaining full visibility of the configuration for diagnostic and troubleshooting.
Con - Requires at minimum 4 total IP addresses to deliver 1 usable IP to a device; a /30 network block.

Creating a Network Block

In the VergeOS system root:

  1. Navigate to the network that represents the 'edge' of your VergeOS system; this is very often the root External network.
  2. Click Network Blocks from the left menu.
  3. Click New to create a new block.
  4. Enter your Network Block IP address in CIDR format. (a.b.c.d/n)
  5. Optional : Add a helpful description to your block.
  6. Since we're using this block with a tenant, set "Owner Type" to Tenant and set "Owner" to the tenant you'd like to assign this block to.
  7. Click Submit to save and assign the Block.

Block Addressing

When creating Network Blocks, VergeOS will validate the Block when applying the firewall rules in further steps. Failure to set a proper starting IP for a given range will result in an error. e.g. 10.1.2.108/30 would be a valid block. 10.1.2.110/30, while representing in many cases the same block, will fail to validate in the following steps and not function. Validate with a subnet calculator if you are unsure.

  1. Return to the main page for the network you just added the Block to.
  2. At the top, note the "Rule changes need to be applied" message. You may click "Apply Rules" here, or click "Rules" in the left menu to validate before applying. You may also leave rule application for later, but you must return and apply before your Block will be routed and functional.
  3. Navigate to the Tenant Networks view and, using the top filters, select "Needs FW Apply" "Yes"; your tenant network should be listed.
  4. Select the network with a click, then Apply Rules in the left menu to complete delivery of the Network Block to the tenant.

In the Tenant interface:

  1. Navigate to your External network. You will find your root-assigned Network Block listed with the description "External Network Address from service provider".
  2. Select the Block with a click, then click New Network on the left menu. This will create a new Internal network in the tenant using the address block.
  3. Note the Address Type is automatically set to Static with the Network Block address already set. Dynamic DHCP will also be enabled with the available IP range remaining usable already filled.
  4. Give the new network a name.
  5. When finished with any other customizations you require, click Submit to create the network.
  6. You will exit to the new network. Click Power On from the left menu to bring the network online. You will be presented a confirmation window to prevent accidental power-on.

Attach a VM NIC to the network with DHCP enabled to have the IP assigned to the NIC automatically. Alternatively, set the IP address(es) within your guest OS manually.

Creating a Virtual Wire

Virtual Wires are another common method to consume root-level IP space by tenant workloads. These are roughly analogous to physical wires in that they allow Layer 2 network traffic to "skip" routed network segments, in this case allowing a Tenant Internal network to communicate directly with a network outside of VergeOS. This may be a "WAN" network directly, or other network configured outside of VergeOS that has address space usable and is routable out to the internet.

Pro/Cons

Pro - Simple configuration within VergeOS, bypassing internal Layer 3 routing configuration.
Pro - Allows direct usage of External IPs on edge devices by consumers.
Pro - Minimal address space overhead; only the IP addresses used by clients.
Con - Virtual Wires only function when both networks they connect are running on the same node.
-This requires the External network and Tenant Node1 use a High Availability (HA) Grouping to maintain their grouping, which may impact HA event expectations.
Con - May make troubleshooting and diagnostic more difficult by removing VergeOS WebUI and native routing visibility.

For instructions on creating a Virtual Wire, see Creating a Virtual Wire.

Once your Virtual Wire is in place, virtual machines and other workloads with NICs connected to the Internal network the vwire is attached to will have a Layer 2 connection out of VergeOS and will function similarly to a VLAN in a traditional switch with regards to addressing and routing.

Address Translation

If a workload must have a consistent IP address, but does not need the address assigned to it directly, Address Translation may be the best method. This allows standard Layer 3 routing from your Public/External IP pool to any given workload in VergeOS via the built-in Rules and Networking system.

Pro/Cons

Pro - Follows standard and well understood routing conventions.
Pro - Allows full route visibility and control within VergeOS WebUI panels, which can aid troubleshooting and future changes.
Con - Does not allow the end device to be assigned the Public IP natively.
Con - Not all network traffic survives Address Translation, particularly if source/destination validation is required.

Due to the very extensive and flexible nature of VergeOS's network possibilities, we will provide 2 example configurations, with the Address Translation at differing points in the routing journey.

DNAT and SNAT Rules on Tenant Internal Network

  1. Navigate to the network that represents the 'edge' of your VergeOS system; this is very often the root External network.
  2. Click IP Addresses from the left menu.
  3. Click New to create a new IP.
  4. Set "Type" to Virtual IP.
  5. Fill in the IP Address.
  6. Optional : Add a helpful description.
  7. Set "Owner Type" to "Tenant"
  8. Set "Owner" to the tenant you'd like to assign this IP to.
  9. Click Submit to save.
  10. You will be returned to the "IP Addresses" view.
  11. Return to the main page for the network you just added the Block to.
  12. At the top, note the "Rule changes need to be applied" message. You may click "Apply Rules" here, or click "Rules" in the left menu to validate before applying. You may also leave rule application for later, but you must return and apply before your Address will be routed and functional.
  13. Navigate to the Tenant Networks view and, using the top filters, select "Needs FW Apply" "Yes"; your tenant network should be listed.
  14. Select the network with a click, then Apply Rules in the left menu to complete delivery of the IP Address to the tenant.

In the Tenant interface:

  1. Navigate to your External network. You will find your root-assigned IP Address listed with the description "External IP from service provider".
  2. Select the IP Address with a click, then click Edit on the left menu.
  3. Set "Owner Type" to "Network".
  4. Set "Owner" to the network your VM's NIC is attached to.
  5. Click Submit to save.
  6. Return to the Tenant External network view.
  7. Click Apply Rules to activate the automatic rule created to route your IP.
  8. Navigate to the Tenant network you set in step 4.

DNAT Option: (If your workload is compatible)

  1. Click Rules in the left panel.
  2. Click New in the left panel to create a new Rule.
  3. Give your rule a Name.
  4. Optional : Write a helpful Description..
  5. Set "Action" to Translate.
  6. Set "Destination Type" to My IP Addresses.
  7. Select the IP Address you've passed along from the list.
  8. Set "Target" to either:
  9. "Type" My IP Addresses and select the Static IP Address you have already configured for this VM NIC in VergeOS.
  10. OR "Type" IP/Custom and manually enter the static IP you have set the Local IP you have set on the VM NIC already.
  11. Click Submit to save.

SNAT Configuration: (Required for outgoing translation)

  1. Click Rules in the left panel.
  2. Click New in the left panel to create a new Rule.
  3. Give your rule a Name.
  4. Optional Write a helpful Description.
  5. Set "Action" to Translate.
  6. Set "Source" to either: (Using the same IP as the "Target" from the previous steps)
  7. "Type" My IP Addresses and select the Static IP Address you have already configured for this VM NIC in VergeOS.
  8. OR "Type" IP/Custom and manually enter the static IP you have set the Local IP you have set on the VM NIC already.
  9. Set "Destination Type" to My IP Addresses.
  10. Select the IP Address you've passed along from the list.
  11. Set "Pin" to Top to set this Rule above others, ensuring it is applied early.
  12. Click Submit to save.

Routing Option: (May be useful if your workload is not DNAT compatible)

If your workload does not support DNAT, clients must access it with the native IP on the device, AND you have only 1 IP available, there is an alternative to the "DNAT Option" above. Follow the "DNAT Option" instructions above, and at Step 5 set your action to Route rather than Translate. This will send traffic for the public IP to the VM via the native private IP. Then, on the NIC in your Guest OS, set a secondary IP with the public IP and a /32 (255.255.255.255) subnet. Follow the "SNAT Configuration" as written to translate the outbound traffic. This option is entirely GuestOS dependent and may not work in all situations.

To use this method, follow the "DNAT Option" instructions above with 1 change, Step 5. changes to: 5. Set "Action" to Route.

Set the Public/External IP address as a secondary address on the VM NIC, inside the guest OS. This will allow traffic bound for the IP to be routed to the native internal IP, then allow the guest OS to handle it on the /32 single IP. The "SNAT Configuration" steps will likely still need to be followed; the outbound traffic from the VM NIC will still originate from the local IP, not the public assigned as a secondary address, and thus Source NAT will need to change it on the way out.

Document Information

  • Last Updated: 2025-02-17
  • VergeOS Version: 4.13.3

Settings that Influence VM Node Selection

Each time a VM is powered on or migrated, the system decides where to run the VM based on user-specified VM options as well as balancing workloads across available nodes.

VM options used in deciding node selection for running a VM:

  • HA Group

    • Node Affinity: (value starts with a "+", e.g. "+commapp") The system attempts to run VMs with the same HA Group value on the same node. This is used to coalesce application-related workloads to a single physical node for performance optimization.
    • Node Anti-affinity: (value does NOT with "+", e.g. "webservers") VMs with the same HA Group value are run on separate nodes to provide high availability of applications or services.

  • Preferred Node: a specific node is selected as the first-choice

  • Preferred Cluster: nodes in specified cluster used as first choice
  • Failover Cluster: nodes in specified cluster used as next choice when preferred cluster is not available

For more information about these and other VM options, see: Product Guide - Virtual Machine Fields

Provide Layer 2 Access to a Tenant

Key Points

  • These instructions pertain to environments with specific requirements for tenant layer 2 connectivity (e.g. utilizing existing non-virtualized network infrastructure or tenant customers with direct MPLS lines, etc.)
  • Virtual Wires (virtual network uplinks) are used.

High-Level Steps

  1. Prepare the physical network: verify VLANs are configured on the appropriate physical switch ports so that they are accessible within the VergeOS environment.

Warning

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

  1. Create the Virtual Wire Determine whether the tenant will need access to a single VLAN or multiple VLANs. This will determine the virtual wire configuration:

Virtual Wire Host Placement

When using a virtual wire, both networks participating in that virtual wire must be on the same host. Failure to meet this requirement can lead to network connectivity issues.

  1. Add VLANs Inside the Tenant

Creating a 1:1 Virtual Wire

  1. Ensure the VLAN(s) have been configured 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 the first half of the virtual wire:

    • Name: a descriptive name, e.g., VLAN from host, etc.
    • Network: the external network with the corresponding VLAN to pass to the tenant
    • Destination Wire: field should display --Empty List-- or select --None--
    • PVID: 1.
      Example Configuration: virtual-wire-create-settings.png

  5. Submit your changes and return to the virtual wires list view.

  6. Select New to create the second half of the virtual wire:

    • Name: a name to identify the wire such as vlan id, tenant, purpose, etc
    • Network: the tenant network, typically named tenant_'$TENANTNAME'.
    • Destination Wire: the other half of the virtual wire created above.
    • PVID: VLAN ID of the network being attached.
      Example Configuration: virtual-wire-create-settings-tenant.png

  7. Submit your changes.

  8. Navigate to the Networks Dashboard, select Networks, and Apply Rules for both networks connected by the virtual wires.

Creating a Trunk Mode Virtual Wire

Bridge Mode Required

To use trunk mode virtual wires, the corresponding physical network (tied to node NICs) must be set to Bridge mode.

Set the 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.

Tip

A physical Network typically has "Switch" appended to the name and represents a physical NIC on a node.

  1. Select Edit to enter the network configuration page.
  2. In the configuration page, enable Physical Bridged to activate Bridge Mode. It is best to set the On Power Loss setting to Power On so that the network starts up automatically after a system power loss.
  3. Submit your changes.
  4. Reboot the necessary nodes for Bridge Mode to become active.

Follow proper Maintenance Mode procedures when rebooting a node to avoid workload disruptions.

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, navigate to Networks > Virtual Wires.

  3. Select New to create the first half of the virtual wire.

    • Name: identify the wire, e.g., "trunk from host"
    • Network: physical network with the corresponding VLAN to pass to the tenant.
    • Destination Wire: should display --Empty List-- or select --None--
    • PVID: 0
    • Allowed VLAN List: comma-delimited and with ranges as necessary
      Example Configuration: vw-trunk-host.png

  4. Submit your configuration.

  5. Select New to create the second half of the virtual wire.

    • Network dropdown, select the tenant network that the VLAN will be passed to, typically named tenant_'$TENANTNAME'.
    • PVID: 0
    • Allowed VLAN List: comma-delimited and with ranges as necessary
      Example Configuration: vw-trunk-tenant.png

  6. Submit your changes.

  7. Navigate to the Networks Dashboard, select Networks, and Apply Rules for both networks connected by the virtual wires.

Add 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. Configure settings:
    • Name: a label to identify the network (name, vlan ids, purpose, etc.)
    • Layer 2 Type: VLAN
    • Layer 2 ID: VLAN ID
    • Interface Network: Physical
    • IP Address Type: None
      Example Configuration: virtual-wire-network-in-tenant.png

Leave other fields at default settings unless specific configuration needed. For information about additional external network options, see: How to Create an External Network

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

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

Force Power Off a VM Using the API

Overview

Key Points

  • Use the VergeOS API to force power off a stuck VM
  • Requires API/Swagger access
  • Process involves multiple API calls to ensure accurate targeting
  • Should only be used when normal power off methods fail

This guide explains how to force power off a non-responsive virtual machine (VM) using the VergeOS API when standard power-off methods are unsuccessful.

Prerequisites

  • Access to the VergeOS UI with administrative privileges
  • The name of the stuck/non-responsive VM
  • Basic understanding of API operations

Important

This procedure should only be used when standard power-off methods have failed. Forcing a VM to power off can lead to data loss or corruption if not used carefully.

Steps

1. Access the API Documentation

  1. Navigate to System in the VergeOS UI
  2. Click on API Documentation (also known as Swagger)

2. Locate the VM ID

  1. In the API interface, locate and expand the VMs table
  2. Click the blue GET button
  3. In the parameters section: - Use filter name eq your_vm_name to find a specific VM
  4. Click Execute
  5. Note the Machine number from the response

3. Get Machine Status ID

  1. Navigate to the machines table
  2. Click the blue GEt /machines/{id}
  3. In the parameters: - Set id to the Machine number from the previous response - Set fields to status
  4. Click Execute
  5. From the response, note the status value

4. Verify Machine Status

  1. Go to the machine_status table
  2. Click the blue GET /machine_stats/{id}
  3. In the parameters: - Set id to status_number (using the status value from step 3) - Set fields to most
  4. Click Execute
  5. Verify this is the correct VM by checking: - Number of cores - RAM allocation - Status information - Machine number

5. Force Power Off

  1. In the machine_status table, click PUT
  2. Enter the status number as the id resource id
  3. In the request body, enter the following JSON:
{
    "running": false,
    "migratable": true,
    "status": "stopped",
    "state": "offline"
}
  1. Click Execute

6. Verify Power Off

  1. Return to the VergeOS UI
  2. Verify that the VM shows as powered off

Troubleshooting

Common Issues

  • If the VM doesn't show as powered off after the API call, wait a few minutes for the status to update
  • If the status doesn't update, verify that all IDs were correct in the previous steps
  • In case of errors, check the API response for specific error messages

Additional Notes

  • Always document the VM's ID and status values before making changes
  • Consider taking a snapshot of the VM before forcing power off if possible
  • Monitor the VM after forcing power off to ensure it starts properly when needed

Feedback

Need Help?

If you do not feel confortable with this process, please reach out to our support team for assistance.

Document Information

  • Last Updated: 2024-01-28
  • VergeOS Version: All

Configuring VergeOS as an OIDC Client

Overview

Key Points

  • Configure VergeOS to use OIDC authentication
  • Connect to a VergeOS OIDC identity provider
  • Enable automatic user creation and synchronization
  • Customize login appearance and behavior

This guide explains how to configure a VergeOS system or tenant to authenticate using another VergeOS system as an OIDC identity provider.

Prerequisites

  • Access to the VergeOS OIDC provider system
  • Well Known Configuration URL from the provider
  • Client ID and Client Secret from the provider
  • Administrative access to the client VergeOS system
  • Full URL of the client VergeOS system

Steps

1. Access Authorization Settings

  • Navigate to the Main Dashboard
  • Click System in the left menu
  • Select Authorization Sources
  • Click New

2. Configure Basic Settings

  • Name: Enter an identifier for this auth source (appears on login button)
  • Driver: Select OpenID (Well Known Config)
  • Base URL: Enter the Well Known Configuration URL
  • Redirect URI: Enter the full URL of this VergeOS system
  • Client ID: Paste the client ID from the provider
  • Client Secret: Paste the client secret from the provider

3. Configure Authentication Parameters

Default values typically work best for these settings: - Token hint parameter: Leave as post_logout_redirect_uri - Redirect parameter: Leave as post_logout_redirect_uri - Scope: Leave as openid profile email groups - Group Scope: Leave as groups

Check these boxes for optimal functionality: - Decode ID Token - Update Remote User - Update User Email Address - Update User Display Name - Update Group Membership

5. Configure User Creation

Choose your preferred user creation method: - Auto-Create Users: Enter .* to create all users automatically - Auto-Create Users in Group: Specify groups for restricted auto-creation

6. Customize Login Appearance

Optionally configure: - Button background color - Button text color - Custom Font Awesome icon - Icon color (using HEX codes)

7. Save Configuration

  • Click Submit to create the authorization source

Best Practices

  • Test authentication with a test user before rolling out widely
  • Keep debug mode disabled unless troubleshooting
  • Document your configuration choices for future reference
  • Regular verify user synchronization is working as expected

Troubleshooting

Common Issues

  • Authentication Fails

    • Verify Client ID and Secret are correct
    • Check Well Known Configuration URL
    • Ensure Redirect URI matches exactly

  • User Sync Issues

    • Verify Group Scope is enabled
    • Check group membership settings
    • Enable Debug Mode temporarily

  • Login Button Missing

    • Verify authorization source is enabled
    • Check login styling settings
    • Clear browser cache

Additional Resources

Feedback

Need Help?

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

Document Information

  • Last Updated: 2024-01-22
  • VergeOS Version: 4.12 and later

Setting Up VergeOS as an Identity Provider with OIDC

Overview

Key Points

  • Create an OIDC application to establish VergeOS as an identity provider
  • Enable single sign-on for other VergeOS systems and tenants
  • Configure centralized authentication with third-party providers
  • Support multiple client systems with a single OIDC setup

This guide walks you through the process of configuring VergeOS as an identity provider using OpenID Connect (OIDC), allowing centralized authentication for multiple VergeOS systems and tenants.

Prerequisites

  • Administrative access to the VergeOS system
  • Valid SSL certificate installed on the VergeOS system
  • Basic understanding of OIDC concepts
  • URLs of client systems that will use this authentication

Steps to Create an OIDC Application

  1. Access OIDC Settings - Navigate to the Main Dashboard - Click System in the left menu - Select OIDC Applications - Click New

  2. Configure Basic Settings - Enter a descriptive Name for the application - Check the Enabled box - Add an optional Description

  3. Set Up Redirect URIs - Enter the callback URL(s) where users will be redirected after authentication - Format: https://your-system-name.example.com - Multiple URIs can be added for different client systems

!!! tip "Using Wildcards" You can use wildcards in redirect URIs: - For multiple systems: https://examplecorp-site*.example.com - For multiple subdomains: https://vergesystem.*.example.com

  1. Configure Authentication Options - Force Authorization Source: Optionally select a third-party provider - Map User: Choose if all verified users should map to a specific account - Set Scope Settings (Profile, Email, Groups) - Configure access restrictions if needed

  2. Save Configuration - Click Submit to create the OIDC application - The system will generate a Client ID and Secret

Retrieving Client Credentials

  1. Access Application Dashboard - Navigate to System > OIDC Applications - Double-click your OIDC application

  2. Copy Required Information - Client ID: Copy using the displayed value or copy icon - Client Secret: Use the copy icon (value is hidden) - Well Known Configuration URL: Copy the displayed URL

Best Practices

  • Create separate OIDC applications for different client groups
  • Regularly review and update access restrictions
  • Use specific redirect URIs instead of wildcards when possible
  • Document which systems are using each OIDC application

Troubleshooting

Common Issues

  • Authentication Fails

    • Verify SSL certificate is valid and not expired
    • Check redirect URI matches exactly
    • Ensure client ID and secret are correctly copied

  • Scope Access Denied

    • Verify required scopes are enabled
    • Check user permissions in restriction settings

  • Redirect Problems

    • Confirm URL format matches redirect URI
    • Verify wildcard patterns if used
    • Check for SSL certificate issues

Additional Resources

Feedback

Need Help?

If you encounter any issues while setting up OIDC 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 and later

vSAN Diagnostics Guide

Overview

This guide provides comprehensive information about the vSAN diagnostic options available in the user interface. These diagnostic tools enable system administrators to monitor, troubleshoot, and maintain vSAN deployments effectively.

Critical Warning

The diagnostic commands detailed in this guide are powerful administrative tools. Improper usage can result in: - System outages - Service interruptions - Potential data loss

Exercise extreme caution and ensure proper understanding before execution.

Prerequisites

To use these diagnostic tools, you must have:

  • Root-level access to your VergeIO cluster
  • Note: Tenants do not have a vSAN.

Accessing vSAN Diagnostics

  1. Navigate to vSAN Diagnostics using either method:
  • From the home screen: Select the vSAN Tiers count box → vSAN Diagnostics (left menu)

  • Alternative path: Home screen → System (left menu) → vSAN Diagnostics 2. Command execution:

  • Select desired command from the dropdown menu

  • Configure available options if applicable
  • Click SEND→ to execute

Command Visibility

Enable the "Show Command" option to view the exact command being executed. This can be valuable for: - SSH execution - BASH script integration - Advanced command automation

Diagnostic Commands

Add Drive to vSAN

Running this command allows you to manually add a drive via the UI. Drives are normally added either during the installation, or via the Nodes > Nodes Drives page. However adding them in that way does not allow for the addition of drives to Tier0.

Prerequisites:

  • Drive must be physically present in the system
  • Drive must be visible from Nodes > Nodes Drives page

Usage Parameters:

  • Selecting Add Drive to vSAN
  • From the right menu, select the Node that we will be adding the drive to.
  • Enter the appropriate path, E.G. `/dev/nvme0n1```<br>
  • You can use the "Click here to view devices" to get the path. !!! warning "The contents of this drive will be overwritten."
  • Select the Tier you want to assign the drive to.
  • Check the Swap box if you want Swap enabled on this drive. !!! info "This will use the cluster settings for the Swap size."
  • Verify. You will need to TYPE Yes I know what I'm doing in the Verify box.
  • Select SEND →

CLI Syntax:

vcmd newdevice --path=PATH [OPTIONS]
  --path=PATH    Path to target device
  --tier=NUM     Tier number assignment

Cancel Integrity Check

Terminates any active integrity check operations. See Integrity Check for additional information.

CLI Syntax:

vcmd cancelintegcheck

Clear Reference Counts

Reference counts are how the vSAN tracks the number of times a file is referenced in the vSAN. Clearing this count will force a full vSAN walk and a refresh of the Reference Counts.

Function:

  • Clears existing reference counts
  • Initiates full vSAN traversal
  • Rebuilds reference count data

Support Authorization Required

Execute only under direct support guidance.

Usage Parameters:

  • Verify. You will need to TYPE Yes I know what I'm doing in the Verify box.
  • Select SEND →

CLI Syntax:

vcmd clearrefcounts

Find Inode

Running this query will allow you to find out what an Inode (Index Node) referrences. Inode is a data structure that stores information about a file or directory, such as its owner, access rights, date and time of creation and modification, size and location on the vSAN. Each file or directory in the system has its own unique index node number (inode number), which can be used to perform various operations with a file or directory. This can be used to troubleshoot errors in the vSAN.

Purpose:

  • Retrieves inode reference information
  • Maps inode numbers to filesystem entities
  • Assists in vSAN troubleshooting

CLI Syntax:

find /vsan -inum inode_number_here -printf /%P\n

Get Cache Info

Retrieves detailed cache information for specified nodes.

Output Information:

  • Total cache capacity
  • Available cache space
  • Cache page statistics
  • Performance metrics

CLI Syntax:

vcmd getcacheinfo

Get Clients

Retrieves client connection information for specified nodes.

Output Information:

  • Connected node information
  • IP address mappings
  • Worker thread statistics

CLI Syntax:

vcmd getclients

Get Cluster Rates

Retrieves cluster-wide performance metrics.

Output Information:

  • Read/write rates
  • Throttle status
  • Performance statistics

CLI Syntax:

vcmd getclusterrates

Get Cluster Usage

Provides cluster-wide storage utilization information.

Output Information:

  • Maximum storage capacity
  • Current utilization
  • Repair operation counts

CLI Syntax:

vcmd getclusterusage

Get Current Master

Retrieves master node information from each cluster member.

Output Information:

  • Master node identification
  • Online status
  • Transaction logging information

CLI Syntax:

vcmd getcurmaster

Get Device Integrity

Retrieves integrity check results for specified nodes.

CLI Syntax:

vcmd getdeviceinteg

Get Device List

Provides comprehensive device inventory.

Output Information:

  • Device identifiers
  • System paths
  • Tier assignments

CLI Syntax:

vcmd getdevicelist

Get Device Status

Retrieves detailed device status information.

Output Information:

  • Device paths
  • Operational status
  • Capacity metrics
  • Performance statistics

CLI Syntax:

vcmd getdevicestatus

Get Device Usage

Provides device utilization metrics.

Output Information:

  • Total capacity
  • Current utilization
  • Usage trends

CLI Syntax:

vcmd getdeviceusage

Get File Status

Retrieves detailed file metadata.

Output Information:

  • Inode information
  • File type
  • Tier assignment
  • Hash key data

CLI Syntax:

vcmd stat /path/to/file.raw

Get Fuse Info

Retrieves FUSE (Filesystem in Userspace) statistics.

Output Information:

  • Mount point information
  • Thread statistics
  • Throttling metrics

CLI Syntax:

vcmd getfuseinfo

Get Integrity Check Status

Retrieves results from the most recent integrity check.

Output Information:

  • Check status
  • Path information
  • Temporal data
  • Verification results

CLI Syntax:

vcmd getintegcheckstatus

Get Journal Status

Retrieves journal system status information.

Output Information:

  • Operational status
  • Redundancy status
  • System metadata

CLI Syntax:

vcmd getjournalstatus

Get Node Device List

Retrieves detailed hardware information for storage devices.

Output Information:

  • Driver information
  • Model specifications
  • Firmware versions
  • Physical attributes

CLI Syntax:

vcmd getnodedevicelist

Get Node Info

Retrieves comprehensive node configuration data.

Output Information:

  • Node identification
  • Cluster configuration
  • System parameters
  • Operational status

CLI Syntax:

vcmd getnodeinfo

Get Node List

Provides cluster-wide node inventory.

Output Information:

  • Node identification
  • Online status
  • Version information
  • Tier utilization

CLI Syntax:

vcmd getnodelist

Get Path from Inode

Resolves filesystem paths from inode numbers.

CLI Syntax:

vcmd getpathfromino $1

Get Read Ahead

Retrieves read-ahead buffer statistics.

Output Information:

  • Queue statistics
  • Thread utilization
  • System status

CLI Syntax:

vcmd getreadahead

Get Repair Status

Monitors ongoing repair operations.

Output Information:

  • Device repair status
  • Operation progress
  • System health

CLI Syntax:

vcmd getrepairstatus

Get Running Configuration

Retrieves active system configuration.

Output Information:

  • Worker thread allocation
  • System throttles
  • Operational parameters

CLI Syntax:

vcmd getrunningconf

Get Sync List

Monitors synchronization operations.

Output Information:

  • Operation frequency
  • Start times
  • File processing status

CLI Syntax:

vcmd getsynclist

Get Tier Device Maps

Retrieves tier-to-device mapping information.

Output Information:

  • Physical device mappings
  • Tier assignments
  • System configuration

CLI Syntax:

vcmd gettierdevicemaps

Get Tier Node Maps

Retrieves tier-to-node mapping information.

Technical Details:

  • Base-0 indexing (0=Node1, 1=Node2, etc.)
  • 65536 buckets per tier map
  • Primary (tier_x.0) and redundant (tier_x.1) mappings

CLI Syntax:

vcmd gettiernodemaps

Get Tier Status

Retrieves comprehensive tier health information.

Output Information:

  • Redundancy status
  • Walk statistics
  • Transaction data
  • Health metrics

CLI Syntax:

vcmd gettierstatus

Get Top Usage Rates

Monitors real-time I/O statistics.

Real-time Data

Multiple executions may be necessary for trend analysis.

CLI Syntax:

vcmd getfhlist | grep -Eo '(ino|rrate|wrate)\b.*'

Get Volume Usage

Retrieves detailed volume utilization statistics.

Parameters:

  • Path specification (optional)
  • Recursive flag
  • Human-readable output
  • Preferred tier display

CLI Syntax:

vcmd getvolusage --path=/ --recursive=1 --human=1

Integrity Check

Initiates system integrity verification.

Parameters:

  • Path specification (required)
  • Recursive operation
  • Fix mode (destructive)
  • Meta-tier only option

Data Loss Risk

Fix mode zeros bad blocks. THIS IS DESTRUCTIVE. Use only under support guidance.

CLI Syntax:

vcmd integcheck /vol

Integrity Check Device

Performs device-level integrity verification.

Parameters:

  • Node selection
  • Device ID (-1 for all devices)

CLI Syntax:

vcmd integcheckdevice --id=x

Summarize Disk Usage

Generates storage utilization summaries.

Parameters:

  • Path specification
  • Recursive operation
  • Preferred tier display
  • Deduplication analysis
  • Fast deduplication option

CLI Syntax:

vcmd du /vol

Additional Resources

Feedback

Need Help?

If you need further assistance or have any questions about this article, please don't hesitate to reach out to our support team.

Document Information

  • Last Updated: 2024-12-27
  • VergeOS Version: 4.13.2

Updating the VergeOS System

Overview

Key Points

  • System updates should be performed during a maintenance window
  • Updates can be performed with zero downtime when adequate resources are available
  • System updates are only run from the host system (top-level parent)
  • Tenant systems are automatically updated from their host system
  • Updates can be scheduled or performed on-demand
  • The system automatically handles workload migration during updates

This guide provides detailed instructions for performing system updates in VergeOS, whether on-demand or scheduled.

Prerequisites

  • Administrative access to the VergeOS Cloud Dashboard
  • Adequate system resources to allow workload migration during updates
  • A maintenance window (recommended, though not required due to zero-downtime capability)

Performing On-Demand Updates

1. Check for Updates

  1. Navigate to System > Updates in the Cloud Dashboard
  2. Click Check For Updates in the left menu
  3. Click Yes to confirm
    • The Packages section will show available updates
    • A cloud icon indicates downloadable packages
    • Version information displays current and available versions

2. Download Updates

  1. Click Download in the left menu
  2. Click Yes to confirm
  3. Wait for the download to complete

3. Install Updates

  1. Click Install in the left menu
  2. Click Yes to confirm
  3. Wait for installation to complete
    • Status will show "Idle - Reboot Required" when ready
    • The Reboot option will become enabled

Note

Updates that don't include VergeOS package changes won't require full node reboots, but still need the Reboot option to apply changes.

4. Apply Updates

  1. Click Reboot in the left menu
  2. Click Yes to confirm - The system will process one node at a time:
    • Node enters maintenance mode
    • Workloads migrate to other nodes
    • Application restarts/node reboots
    • Node exits maintenance mode
    • Progress shows in the Status field
    • Nodes Updated status tracks completion

Tip

Use Cancel Reboot to halt automatic reboots if needed (e.g., for workload rebalancing)

Scheduling Updates

1. Create Update Task

  1. Navigate to System > Updates > Tasks
  2. Click New in the left menu

2. Configure Schedule

  1. Choose scheduling option:
    • One-time: Keep default "Does Not Repeat"
    • Recurring: Select frequency (weekly, bi-weekly, monthly)
  2. Set Start Date and time
  3. For recurring tasks, optionally set end date

3. Configure Task Details

  1. Enter required Name
  2. Add optional Description
  3. Select Task Type:
    • Choose "Download, Install, and Reboot" for complete update
  4. Optional: Enable Delete After Running
  5. Click Submit to save

Best Practices

  • Schedule updates during low-usage periods and during maintenance windows
  • Ensure adequate system resources for workload migration
  • Monitor system during update process
  • Keep regular backups before major updates
  • Review available updates before applying

Troubleshooting

Common Issues

  • Issue: Workloads fail to migrate

  • Solution: Verify adequate resources on target nodes

  • Issue: Update process hangs

  • Solution: Check system logs and contact support if needed

  • Issue: Node fails to rejoin after reboot

  • Solution: Review logs and network connectivity

Feedback

Need Help?

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

Document Information

  • Last Updated: 2024-12-19
  • VergeOS Version: All

Adding Tier 0 to an Existing System

Overview

Key Points

  • Tier 0 is normally configured during initial installation
  • This procedure is for special cases requiring post-installation configuration
  • Requires careful attention to device paths and hardware compatibility

This guide outlines the process for adding Tier 0 storage to an existing VergeOS system. While Tier 0 is typically configured during installation, these steps provide a method for adding it to production systems that cannot be reinstalled.

Critical Warning

  • This procedure should only be performed by qualified VergeOS engineers or under direct support guidance
  • Selected devices will be formatted and all existing data will be destroyed
  • Incorrect device path selection can seriously damage your system

Prerequisites

Before beginning this procedure, ensure:

  • Storage devices are physically installed in the system
  • Tier 0 devices are consistent across controller nodes
  • Hardware meets specifications from the Node Sizing Guide

Steps

1. Identify Device Paths

  1. Navigate to System > vSAN Diagnostics from the Main Dashboard
  2. Select Get Node Device List from the Query dropdown
  3. Click Send
  4. Identify unused devices (marked as "vsan = false")
  5. Note the device paths (/dev/sd*) for each controller node

Tip

Verify current vSAN drive assignments by checking vSAN Tiers > [select tier] > Drives to avoid selecting drives already in use.

2. Add Drives to Tier 0

For each drive:

  1. In vSAN Diagnostics:
    • Set Query to Add Drive to vSAN
    • Select the appropriate Node (node0 or node1)
    • Enter the correct Path for the device
    • Set Tier to Tier 0
    • Configure Swap setting

Swap Configuration

  • Enable swap on only ONE storage tier
  • If swap is enabled on another tier, disable it for Tier 0
  • Contact VergeOS Support for guidance on swap configuration if needed
  1. Enter the verification phrase: Yes I know what I'm doing
  2. Click Send to execute

3. Verify Configuration

  1. Monitor the system dashboard for tier status - Status will show "online-no redundancy" during meta migration
  2. Refresh node information: - Navigate to each controller node's dashboard - Select Refresh > Drives & NICs

Post-Configuration

Monitor the vSAN tier status in the system dashboard. The tier should transition from "online-no redundancy" to "online" once meta migration completes.

Additional Resources

Document Information

  • Last Updated: 2024-11-25
  • VergeOS Version: 4.13

Change External Network to Bonded with Tagged VLAN

Overview

Key Points

  • This procedure creates an active-backup bond across vlanned physical networks.
  • It is recommended for bare-metal installations with a limitation of 2 NICs per node.
  • System downtime is not required to make this change.

This guide outlines the process to create a bonded external network across vlanned physical networks. The outlined method provides optimal redundancy for bare-metal installations that are limited to two NICs per node, allowing for two independent core-fabric networks and a single-VLAN, bonded external network.

Prerequisites

Warning

  • This process should be performed with local server access because external network changes can affect remote UI access. This will also allow you to test the bond configuration by removing one of the network cables to verify expected bond failover.
  • Before making any significant system changes confirm you have the name/password for the "admin" user (user ID #1 (1)), in case command-line operations become needed.
  1. Hint: "Key=1" parameter is in the URL of the user's dashboard

Steps

  1. Navigate to the external network dashboard (Main Dashboard > Networks > Externals > double-click external network) and click Edit on the left menu.
  2. Change Layer 2 Type to vLAN and enter appropriate Layer 2 ID (VLAN number).
  3. Select the checkbox option for both physical networks.
  4. Click Submit to save the change.

Post Configuration

  1. Check the external network by accessing the UI from a remote connection.
  2. Test Bond failover: Navigate to the external network dashboard and select NICs to view the network adapters. Physically disconnect one network cable. The UI should now indicate the NIC is in a "Down" status; verify remote UI access is still available.

Verify core network redundancy is in place before disconnecting network cables.

Troubleshooting

Common Issues

  • Problem: Loss of remote access
  • Solution:
    1. Check correct VLAN was entered in the external network config
    2. Verify network switch ports are correctly configured for the VLAN tag.

Additional Resources

Feedback

Need Help?

If you need further assistance or have any questions about this article, please don't hesitate to reach out to our support team.

Document Information

  • Last Updated: 2024-11-26
  • vergeOS Version: 4.13.1
  • in VM
  • 2 min read

Emulating USB Devices in VergeOS

Overview

Key Points

  • Create emulated USB devices for VMs
  • Enables legacy application support
  • Allows hotplugging storage for driver installation
  • Requires specific VM configuration

Prerequisites

Before creating an emulated USB device, ensure your VM meets these requirements:

  • VM settings:
  • Allow Hotplug must be enabled
  • Machine Type must be 9.0 or higher
  • VirtIO drivers installed in the guest OS

Machine Type Changes

Before modifying a VM's machine type, create a short-term snapshot (24-hour expiration) to enable rollback if needed.

VirtIO Driver Installation

  • Linux distributions typically include VirtIO drivers
  • For Windows, drivers are available in VergeOS custom ISOs or can be downloaded from: VirtIO Drivers

Steps to Create USB Device

  1. Access VM Settings - Navigate to the VM dashboard (Main Dashboard > Machines > Virtual Machines) - Double-click your target VM

  2. Create New Drive - Click Drives in the left menu - Select New from the left menu

  3. Configure USB Device - Set Media to either Disk or Clone Disk - Set Interface to USB - Optional: Enter a custom name (system will auto-generate if blank) - If using Clone Disk, select the appropriate *.raw file

  4. Enable Device - Click Submit to create the device - Select the new USB device from the drive list - Click HotPlug in the left menu

For additional drive configuration options, see: VM Drives

Troubleshooting

Common Issues

  • Problem: Device stays in "hot plugging" status
  • Solution:
    1. Check VM dashboard logs for errors
    2. Verify all prerequisites are met
    3. Try restarting the VM if settings were recently changed
  • Problem: Device shows as offline
  • Solution: Ensure hotplug is enabled and VirtIO drivers are installed

Document Information

  • Last Updated: 2024-11-19
  • VergeOS Version: 4.13
  • in Network
  • 2 min read

Configuring BGP Hold Down Timers

BGP (Border Gateway Protocol) hold timers are critical for maintaining stable BGP sessions between routers. This document will guide you through configuring the BGP hold down timers to 5 seconds for the keepalive interval and 15 seconds for the hold time.

Prerequisites

  1. Basic BGP Configuration: You should have a basic BGP configuration set up.
  2. Basic Knowledge of FRR Configuration: Familiarity with FRR configuration commands and procedures.

Configuration Steps

Step 1: Setup BGP

  1. Create a new External Network.
  2. Set its IP address type to BGP/OSPF.
  3. Set an ASN (Autonomous System Number).
  4. Define the IP address and Network Address.
  5. If this is a VLAN, configure the Layer 2 ID.
  6. Select an interface network.

Step 2: Open the BGP Network

  1. Open the network you created.
  2. Select Routers from the left menu.
  3. Open the ASN you defined during network creation.
  4. Select New from the left menu.
  5. Select Timers from the command menu.
  6. Under Parameters, enter bgp x y where x is the keepalive interval and y is the hold time. For example, bgp 5 15.
  7. Select Submit. This will return you to the Router page.
  8. Navigate back to the BGP network. A restart is required for the recent changes to take effect. Click Restart to apply changes.

Step 3: Verify the Setting

  1. Navigate back to the BGP network you configured.
  2. Select Network Diagnostics from the left menu.
  3. Choose FRRRouting BGP/OSPF from the Query dropdown.
  4. Run the default command show running-config.
  5. The settings modified in Step 2 should now appear in the running configuration.

For more information on other values and variables, refer to the FRR documentation.

Device Passthrough Advanced Configuration (Manual Creation/Editing of Resource Rules)

Although allowing auto-generation of resource rules (e.g. when you select a device and use the Make Passthrough menu option) is easiest and usually recommended, there may be situations where it may be useful to manually create a resource rule or to modify an auto-generated resource rule.

It is important to read and be familiar with PCI Passthrough Risks and Precautions before making passthrough configurations.

Manually Create a New Resource Rule

  1. From the main dashboard, click Resources.
  2. Click Rules (ui card or on the left menu).
  3. Click New on the left menu.
  4. Provide a Name for the Rule; it is recommended to use a descriptive name can be helpful in future administration.
  5. Select the Resource Group to which the resource rule will apply.
  6. Select a specific Node or select --None-- to apply the rule to all nodes.
  7. Select the Type (PCI, USB, SR-IOV, or NVIDIA vGPU).
  8. Leave the default value set to --None-- in the field labeled Automatically created based on PCI Device.
  9. Configure device filters as desired; filter fields will vary depending on the device type selected; see below. (Advanced Entry 1 option also available)

Information on installed PCI devices, for use in filters, you can use the PCI devices listing: from the Main Dashboard, navigate to the Resources -> PCI Devices. To show additional fields, right-click in the heading section to select from the full list of available columns that can be displayed.

Edit an Existing Resource Rule

  1. Navigate to the Associated Resource Group dashboard (Main Dashboard > Resources > Groups > double-click the particular group).
  2. In the Rules section, locate and click the desired resource rule.
  3. Click Edit on the left menu.
  4. Node selection and PCI Filters can be modified as needed. (Advanced Entry 1 option also available)

  1. The Advanced Entry section allows you to manually input filter syntax rather than using the filter entry fields. Generally, it is preferable to allow system-generated syntax based on your filter field selections. ↩↩

Scaling Up a vSAN

To scale up a vSAN, follow the steps below. However, before proceeding, ensure that your current vSAN has at least 10% free capacity.

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 10% free capacity unless you are doubling the capacity. If the free space is less than 10% and you are not doubling the drive count, consider scaling out by adding a node.

Steps to Scale Up

  1. Physically add the drives or Fiber Channel LUNs 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.

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.13

Setting Up Storware on VergeOS

This guide outlines the steps for configuring Storware on VergeOS to protect your virtual machines.

For more comprehensive information on Storware's capabilities and additional backup configuration options, visit the Storware Backup and Recovery Documentation.

Prerequisites

  • VergeOS on version 4.13 or higher.
  • Access to a Storware Backup and Recovery instance on version 7 or higher.
  • Credentials for an account with the appropriate permissions to configure both VergeOS and Storware.

Setup a dedicated Verge NAS Service for Storware

  1. Deploy the NAS Service:
  1. Configure NFS Settings:
  • Before powering on the NAS service, click on Edit NFS Settings.
  • Enable NFSv4 by selecting the checkbox for this option.
  • Click Submit to save the changes.
  • Power on the NAS service.

Depending on the size of your environment you may want to increase the amount of CPU and RAM for the NAS Service. Storware recomends 8 cores and 12 GB of RAM as a good starting point

Adding Your VergeOS System to Storware

  1. Log in to Storware:
  • Access the Storware Backup and Recovery management console.
  1. Add VergeOS as a Virtual Environment:
  • Navigate to Virtual Environments > Virtualization Providers and click Create.
  • Select VergeOS as the Virtualization Provider.
  1. Configure the Connection Details:

  • General Tab:

    • URL: Enter the VergeOS URL in the format https://<VERGE_IP>.
    • Username: Provide the username for VergeOS.
    • Password: Enter the password for the specified user.
    • Verge Settings Tab:
    • Enter the name of the NAS service created in the previous step.
  1. Test the Connection:
  • Select the newly added Verge system from the list
  • Click Test Connectivity to verify that Storware can successfully communicate with the VergeOS environment.

Important Notes

NFS Version Selection

Enabling NFSv4 on VergeOS ensures compatibility with modern backup solutions like Storware, providing improved security and performance.

Snapshot Optimization

Using Storware's snapshot management in conjunction with VergeOS’s built-in vSAN capabilities allows for efficient incremental backups, reducing the time and storage required for VM protection.

Feedback

Need Help?

If you have any questions or encounter issues while setting up Storware on VergeOS, please reach out to our support team for assistance.

Document Information

  • Last Updated: 2024-11-07
  • VergeOS Version: 4.13
  • in Network
  • 2 min read

How to Create an External Network

This guide provides steps for creating an external network in VergeOS. The example assumes that the physical network in VergeOS is named External Switch, the VLAN for the new network is 50, and a static IP address is being used.

Steps

  1. Access Network Configuration:
  • From the home screen of the UI, click on Networks and select New External.
  1. Configure Network Settings:
  • Network Name: Enter a name for your network. In this example, use WAN1.
  • Layer 2 Type: Set to vLAN.
  • Layer 2 ID: Enter the VLAN ID, in this example, 50.
  • MTU: Leave as 1500 (Advanced users may adjust this as needed).
  • Interface Network: Select the physical network, in this example, External Switch.
  1. Configure Network Router:
  • IP Address Type: Select Static. (If using DHCP, select it here and skip the remaining router steps).
  • IP Address: Enter the IP address for this network. Example: 192.168.212.2.
  • Network Address: Enter the network address in CIDR format. Example: 192.168.212.0/24.
  • Gateway Monitoring: Enabling this feature is recommended for network reliability.
  1. Save and Activate the Network:
  • Click Save and wait for the network to power on. Once it displays as Running, proceed to set up routing rules.
  1. Add Default Routing Rule:
  • Click on Rules and select New.
  • Rule Name: Enter a name for this rule, such as default route.
  • Action: Select Route.
  • Direction: Choose Outgoing.
  • Source and Destination Filters: Leave as any and default since this is the default route.
  • Target:
    • Type: Select IP/Custom.
    • Target IP: Enter the router IP of your gateway. Example: 192.168.212.1.
  • Click Save, then Apply Rules.

Feedback

Need Help?

If you have any questions or encounter issues while creating an external network, please reach out to our support team for assistance.

Document Information

  • Last Updated: 2024-10-30
  • VergeOS Version: 4.12.6

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
  • in API
  • 8 min read

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.

  2. 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.

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.

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-11-14
  • 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

  • System updates should be performed during a maintenance window
  • 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

Air-gap licensing is not common and requires justification. Please see Licensing and Software Updates for more information.

Overview

Key Points

  • VergeOS requires a valid license for operation
  • Air-gapped 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.

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.
  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.

  2. 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.

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

tenant_apply_rules.png

  1. Select Apply Rules in the highlighted warning.

  2. 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

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
  • in VPN
  • 5 min read

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).
  5. Click Next at the bottom of the screen.
  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.
  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
  • in VPN
  • 5 min read

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
  • in VM
  • 1 min read

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
  • in Network
  • 2 min read

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.
  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.

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.
  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
  • in API
  • 4 min read

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.

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.

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

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
  • in Tenant
  • 1 min read

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

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.

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.

  4. Enter a Name for the new Schedule.

  5. Optionally, a Description can be entered to record more information.
  6. Click Submit.
  7. 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