Skip to content

System Administration#

Power on/Power off VMs Based on User Login/Logout and Schedule

Automated Task Example

Key Points

  • The VergeOS Task Engine allows you to automate operations, triggered by specific events or scheduled times. Using modular, reusable components (tasks, events, schedules, and webhooks) you can easily configure automation tailored to your environment.
  • The following example displays the use of tags, tasks, events and schedules used together to seamlessly bring workloads online and offline as they are needed, improving resource efficiency.
Use Case

User JThompson relies on multiple GPU-powered virtual machines to perform 3D modeling and animation work. These VMs consume significant compute and memory resources, and leaving them running when idle is wasteful.

By configuring automation to power them on only when needed - when JThompson logs into the system, and to shut them down when the user logs out or at a scheduled time (for example, every Friday at 6pm), we can ensure that resources are available exactly when needed while avoiding unnecessary usage.

The automation consists of creating tags, defining tasks, and attaching event and schedule triggers. The steps below walk you through the full configuration:

1. Create a Tag Category and Tag

A tag category organizes related tags. We then create a specific tag within that category to designate the VMs to control with this automation.

System > Tags > New

Create tag category - Light Mode Create tag category - Dark Mode

Double-click category created above > New

New tag - Light Mode

New tag - Dark Mode

2. Assign the Tag to the VMs to Automatically Power On/Off

This will identify the VMs that should be controlled by the automation.

Virtual Machines > List > select VMs > Assign Tags > select the tag from above

Assign tag to VMs - Light Mode

Assign tag to VMs - Dark Mode

The VMs will now show the assigned tag in the Tags column.

VMs with tag - Light Mode

VMs with tag - Dark Mode

3. Create a Task to Power On VMs

This task defines the action of starting up the tagged virtual machines.

System > Tasks Dashboard > New Task

Task to power on tagged VMs - Light Mode

Task to power on tagged VMs - Dark Mode

4. Configure an Event Trigger for User Login

Here we define the activity that will invoke the task (JThompson logs into the system).

From the new task dashboard: Event Triggers > New

Event trigger user login - Light Mode

Event trigger user login - Dark Mode

5. Create a Task to Power Off the VMs

This defines the action of powering down the tagged virtual machines.

System > Tasks Dashboard > New Task

Task to power off tagged VMs - Light Mode

Task to power off tagged VMs - Dark Mode

6. Configure an Event Trigger for User Logout

This configures the task to launch when JThompson logs out.

From the new task dashboard:
Event Triggers > New

Event trigger user logout - Light Mode

Event trigger user logout - Dark Mode

7. Create a Schedule for Fridays at 6:00pm

Creating a schedule allows us to define specific dates/times. After creating the schedule it can be applied to our task and other tasks.

System > Tasks Dashboard > New Schedule

Schedule COB - Light Mode

Schedule COB - Dark Mode

8. Create a Schedule Trigger for the Power Off

We apply the schedule (Fridays at 6pm) to the task to automatically power off the VMs every Friday evening.

From the dashboard of the new task:
Schedule Triggers > New

Schedule trigger - Light Mode

Schedule trigger - Dark Mode

Verification

  • Log in as JThompson → tagged VMs should power on automatically
  • Log out → VMs should power off
  • At Friday 6:00pm → VMs should power off even if the user is still logged in

Troubleshooting

  • If VMs do not power on, verify the tag is assigned to each VM.
  • If schedule triggers do not fire, confirm the system time zone is correct.
  • If login/logout triggers fail, ensure the user account name matches exactly.

This automation ensures that the GPU‑powered VMs are only active when the designated user is logged in. When the user logs out, or at the scheduled cutoff time (Friday 6pm), the VMs are powered down to conserve resources. The pattern can be applied to other high‑resource workloads such as integration test environments, interactive machine learning, CAD rendering stations, or financial modeling clusters, or any system that benefits from running only when needed.

Understanding VergeOS VM Memory Management

Overview

VergeOS takes a different approach to virtual machine memory management compared to platforms like VMware and Nutanix. Understanding how VergeOS handles memory allocation and reporting is essential for effective capacity planning, performance optimization, and troubleshooting. This article explains why VergeOS memory usage reporting differs from guest operating system reports and the advantages of this design choice.

What You'll Learn

  • Why VergeOS shows allocated memory rather than active memory usage
  • How VergeOS memory management differs from memory ballooning platforms
  • The performance and reliability benefits of VergeOS's approach
  • Best practices for monitoring memory across host and guest levels
  • How this design improves capacity planning and workload migration reliability

Key Concepts

Memory Allocation vs. Memory Usage

Memory Allocation: The amount of physical RAM reserved by the hypervisor for a virtual machine, regardless of how much the guest OS and applications are actively using.

Memory Usage: The amount of memory actually consumed by applications and the operating system within the virtual machine.

In VergeOS, when you assign 8GB of RAM to a VM, the hypervisor immediately reserves 8GB of physical memory on the host, even if the guest OS shows only 2GB in use.

Why VergeOS Shows Allocated Memory

When memory is allocated to a VM, the hypervisor must reserve that full amount in physical RAM regardless of what applications inside the VM are actually using. This is because the guest operating system could request access to any portion of its allocated memory at any time, and the hypervisor must guarantee that memory is available.

VergeOS displays this reserved/allocated memory because it represents the actual physical resources consumed on the host, providing a true picture of resource utilization for capacity planning and performance management.

How VergeOS Differs from Other Platforms

VergeOS Approach: No Memory Ballooning

VergeOS intentionally avoids memory ballooning techniques used by other virtualization platforms. Key characteristics include:

  • Allocated vs. Used: VergeOS shows what's allocated to each VM, which typically isn't the same as guest-level usage
  • Performance First: This eliminates ballooning overhead and complexity
  • Predictable Resource Allocation: What you see is exactly what's reserved on the physical host

Traditional Ballooning Approach

Many virtualization platforms use memory ballooning drivers that:

  • Dynamically report memory usage to the hypervisor
  • Allow memory "overcommitment" by sharing unused memory between VMs
  • Require special drivers (balloon drivers) within each guest OS
  • Create complexity in memory management and potential performance impacts

Benefits of VergeOS's Memory Management Design

1. Predictable Performance

By eliminating balloon driver overhead, VergeOS provides more predictable VM performance. There's no dynamic memory management that could impact application response times or cause unexpected memory pressure.

2. Simplified Capacity Planning

With clear allocation visibility, administrators can easily calculate: - Total memory committed across all VMs - Available memory capacity for new workloads - Resource utilization without complex ballooning calculations

3. Enhanced Reliability

VergeOS avoids dynamic memory management issues that can occur with ballooning, such as: - Memory reclamation delays - Guest OS memory pressure during balloon inflation - Potential application instability during memory operations

4. Guaranteed Migration Success

Critical for High Availability: VergeOS's approach ensures predictable workload migration during node failures. Since the full allocated memory is always reserved, the system can guarantee that all VMs can be migrated to available nodes without memory overcommitment surprises.

If VergeOS used memory ballooning, it could not ensure reliable migration of all workloads to another node during a failure scenario, as the actual memory requirements might exceed the target node's capacity when balloons are deflated.

Migration Reliability

Memory ballooning can create unpredictable migration scenarios. When VMs that appeared to use less memory suddenly require their full allocation during migration, target nodes may lack sufficient resources, potentially causing migration failures during critical moments.

Memory Monitoring Best Practices

Host-Level Monitoring (VergeOS Dashboard)

Use VergeOS dashboards to monitor: - Total allocated memory across all VMs on each node - Available physical memory for new VM deployments
- Memory utilization trends for capacity planning - Node memory status during maintenance and migration operations

Guest-Level Monitoring

Within each VM, use appropriate tools to monitor: - Application memory consumption for performance tuning - Operating system memory usage for optimization - Memory leaks or excessive usage by specific processes - Guest-level performance metrics for troubleshooting

Combined Monitoring Strategy

For comprehensive memory management:

  1. Capacity Planning: Use VergeOS allocation data to plan hardware expansion
  2. Performance Optimization: Use guest-level data to tune applications
  3. Troubleshooting: Compare host allocation with guest usage to identify issues
  4. Resource Optimization: Right-size VMs based on actual guest usage patterns

Practical Example

Consider this scenario:

  • VM Allocated Memory: 8GB (shown in VergeOS)
  • Windows Task Manager: Shows 3GB used
  • Physical Host: Has 8GB reserved for this VM

This is normal and expected behavior. The VergeOS dashboard correctly shows that 8GB of physical memory is committed to this VM, while the guest OS shows its internal usage of that allocated memory.

Troubleshooting Memory Issues

When VergeOS Shows High Memory Usage

If VergeOS shows high memory utilization:

  1. Review VM allocations: Check if VMs are over-allocated for their actual needs
  2. Plan capacity expansion: High allocation percentages indicate need for more physical RAM
  3. Optimize VM sizing: Consider reducing allocations for underutilized VMs

When Guest OS Shows Memory Pressure

If applications report memory issues while VergeOS shows available allocation:

  1. Check guest OS configuration: Verify VM has adequate allocated memory
  2. Review application requirements: Ensure sufficient memory is allocated
  3. Monitor memory leaks: Look for applications consuming excessive memory over time

Memory Performance Issues

For memory-related performance problems:

  1. Verify adequate allocation: Ensure VMs have sufficient memory allocated
  2. Check host memory pressure: Avoid overcommitting total physical RAM
  3. Review storage impact: Memory pressure can cause increased swap activity

Best Practices for Memory Management

Right-Sizing Virtual Machines

  • Start with manufacturer-recommended memory allocations
  • Monitor guest-level usage over time to identify optimization opportunities
  • Avoid significant over-allocation that wastes physical resources
  • Leave adequate buffer for memory spikes and growth

Capacity Planning

  • Plan physical memory capacity based on total VM allocations, not guest usage
  • Account for hypervisor overhead and system memory requirements
  • Maintain 10-15% free capacity for maintenance and unexpected demand
  • Consider future growth when sizing new nodes

Performance Optimization

  • Allocate sufficient memory to avoid guest OS memory pressure
  • Use memory monitoring tools within VMs to identify optimization opportunities
  • Consider workload patterns when planning memory allocation
  • Test application performance with different memory allocations

Next Steps

To deepen your understanding of VergeOS memory management:

Additional Resources

For specific questions about memory allocation in your environment, consult the VergeOS support team at support@verge.io or review the performance monitoring sections in the product documentation.

Document Information

  • Last Updated: 2024-08-15
  • VergeOS Version: 4.12.6+

Proper VergeOS System Shutdown Procedure

Overview

This document provides the step-by-step procedure for properly shutting down a VergeOS system. Following the correct shutdown sequence is critical to ensure data integrity, prevent corruption, and maintain the health of your VergeOS environment.

Prerequisites

  • Administrative access to the VergeOS UI
  • Understanding of your cluster topology
  • Identification of all running workloads and tenants
  • Knowledge of controller node locations (Node1 & Node2)

Shutdown Sequence

Step 1: Inventory Running Workloads

Before beginning the shutdown process, you must identify all active workloads across your environment.

  1. Navigate to each Node Dashboard in your cluster
  2. Review the Running Machines section on each node
  3. Document all running workloads including: - Virtual machines (VMs) - Tenant nodes - VMware backup services - NAS services - Any other active services

Step 2: Shutdown Tenant Workloads

If tenants are running on any nodes in your cluster:

  1. Log into each tenant environment that has active workloads
  2. Gracefully shut down all running workloads within each tenant
  3. Verify shutdown completion before proceeding to the next step

Important

Ensure all tenant workloads are properly shut down before proceeding. Failing to do so may result in data loss or corruption.

Step 3: Power Off Host-Level Workloads

After all tenant workloads are shut down, power off all remaining workloads on each node:

  1. Virtual Machines (VMs): Use the graceful shutdown option when possible
  2. Tenant Nodes: Ensure these are powered off after their internal workloads
  3. VMware Backup Services: Stop any active backup operations
  4. NAS Services: Safely stop all NAS-related services
  5. Other Services: Power off any remaining active services

vNet Containers

vNet containers do not need to be manually stopped. They will be gracefully stopped automatically during the cluster shutdown process.

Step 4: Shutdown Individual Nodes

Once all workloads are stopped:

  1. Navigate to the Cluster Dashboard for the cluster you wish to power off
  2. Select Power Off from the left-hand menu
  3. The system will begin shutting down each node in the cluster
  4. Monitor the shutdown progress through the cluster dashboard

Step 5: Shutdown the Entire Cluster

After individual nodes have been shut down:

  1. Navigate to System → Clusters
  2. Select the cluster you want to shut down
  3. Select Power Off from the left menu
  4. Confirm the shutdown when prompted

Multi-Cluster Environment Considerations

Critical Warning

If your environment contains multiple clusters, you must ALWAYS shut down the cluster containing the controller nodes (Node1 & Node2) LAST.

Shutdown Order for Multi-Cluster Environments:

  1. Shut down all non-controller clusters first
  2. Shut down the controller cluster (containing Node1 & Node2) last

This ensures that cluster coordination and management services remain available until all other clusters are safely shut down.

Alternative Method: API Shutdown

For advanced users or automation purposes, you can use the VergeOS API to shutdown clusters:

POST /v4/cluster_actions
{
    "cluster": [cluster_id],
    "action": "shutdown",
    "params": "{}"
}

Proper Power-On Sequence

When powering your VergeOS system back on, follow this sequence:

Single Cluster Environment:

  1. Power on Node1 first
  2. Wait for Node1 to come online completely
  3. Power on Node2
  4. Power on remaining nodes one at a time, waiting approximately 1 minute between each
  5. Verify system status on the main dashboard (should show Green and Online)

Multi-Cluster Environment:

  1. Power on the controller cluster first (Node1, then Node2, then remaining controller nodes)
  2. Wait for controller cluster to be fully online
  3. Power on other clusters following the single-cluster sequence for each

Verification and Monitoring

After completing the shutdown or startup process:

  1. Check the main dashboard for system status indicators
  2. Verify all nodes show appropriate status (Offline for shutdown, Online for startup)
  3. Monitor system logs for any errors or warnings
  4. Test critical services after startup to ensure proper operation

Troubleshooting

Common Issues During Shutdown:

Workloads Won't Shut Down Gracefully: - Check guest OS ACPI settings - Use "Hard Reset" or "Kill Power" options as last resort - Review VM power management settings

Nodes Won't Enter Shutdown: - Verify all workloads are stopped - Check for stuck or non-responsive VMs - Review node logs for error messages

Cluster Shutdown Fails: - Ensure individual nodes are properly shut down first - Check cluster status and connectivity - Verify no active migrations or maintenance operations

Getting Help:

If you encounter issues during the shutdown process: 1. Document the error messages and current system state 2. Check the VergeOS logs for detailed error information 3. Contact VergeOS support with specific details about the issue

Best Practices

  • Plan shutdown windows during low-usage periods
  • Notify users before beginning shutdown procedures
  • Document your specific environment including cluster topology and critical workloads
  • Test the shutdown process in non-production environments first
  • Maintain current backups before performing system shutdowns
  • Use maintenance mode for individual nodes when possible instead of full shutdowns

Summary Checklist

  • Inventory all running workloads across all nodes
  • Shut down tenant workloads gracefully
  • Power off all host-level workloads (VMs, services, etc.)
  • Navigate to Cluster Dashboard and select Power Off
  • Navigate to System → Clusters and power off the entire cluster
  • For multi-cluster: Shut down controller cluster (Node1 & Node2) LAST
  • Verify shutdown completion through dashboard monitoring
  • Document any issues encountered for future reference

Following this procedure ensures a safe and controlled shutdown of your VergeOS environment while maintaining data integrity and system health.

Document Information

  • Document Type: Knowledge Base Article
  • Category: System Administration
  • Tags: shutdown, power-off, cluster-management, system-maintenance
  • Applies to: VergeOS 4.12.6 and later versions

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.

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

  • Click System in the top menu
  • Select Auth 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 System > OIDC Applications from the top menu - 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

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

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

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 Resource 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. Navigate to Infrastructure > 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: navigate to Infrastructure > 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 (Infrastructure > 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. ↩↩↩↩↩↩

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 environment. - Navigate to Files - Upload the downloaded ISO file to the Files 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 Files. - 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 System 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

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.