Skip to content

Snapshot#

Restoring a VergeOS System from the Boot Menu

A full-system restore can be performed directly from the VergeOS boot menu. This option is intended for system recovery when you are unable to access the user interface. The following article walks through the steps to restore a complete VergeOS system from a previously taken system snapshot using the boot menu restore option.

This process will overwrite the existing system.

Proceeding with a boot menu restore replaces the current system fully with the selected snapshot, reverting all system components to the snapshot state, including:

  • Virtual Machines
  • Tenant configurations
  • NAS data
  • System settings
  • All other system components

This is a comprehensive restoration that cannot be selectively applied to specific components.

Prerequisites

  • At least one available full system snapshot to restore from
  • Physical console or IPMI access to the nodes
  • Planned shutdown/reboot of all VergeOS nodes
  • All nodes must be available and ready for restore (connected, hardware functional)

Steps

  1. Shut down all nodes in the VergeOS environment before beginning the restore.

  2. Power on Node 1.

  3. At the boot menu, select Verge.io OS System Restore. - Use the up/down arrow keys to highlight the option and press Enter to select it.

    The boot menu has a 5-second timeout.

    Press a key (e.g., an arrow key) within 5 seconds of the menu appearing — otherwise the system will automatically boot to the currently installed version.

  4. Wait for the vSAN to mount. Do not press any keys during this process — any keypress can interrupt the load.

    The next 2 steps (selecting a snapshot number and confirming the snapshot for restore) each operate with a 5-minute timeout - the system will automatically reboot to the current system state when there is no selection or input during that time.

  5. Select the snapshot to restore from. - A numbered list of available system snapshots is displayed. Enter the number corresponding to the desired snapshot and press Enter.

    Snapshots are listed alphabetically by name — not by the date/time they were taken.

  6. Confirm the restore snapshot. - When prompted, type the exact name of the snapshot you are restoring and press Enter. - The name must match exactly as shown.

  7. Optionally take a snapshot of the current system before overwriting. - The system will prompt you with an option to: backup the current system before restoring.

    Considerations for Creating a Snapshot of Current State

    Taking a snapshot of the current system state can be useful for later diagnostic activities. However, if the restore is being performed due to an out-of-space vSAN or a double-failure situation, this pre-restore snapshot may cause the system to show persistent repair activity until the snapshot is deleted.

    Yes is the default — pressing Enter without typing anything or not making a selection here will accept the default and take the snapshot. Snapshot naming convention: Backup_YYYY-MM-dd_hh:mm:ss

    This snapshot is created to Never Expire. After the system has been restored, and you confirm this snapshot is no longer needed: delete the snapshot or modify to set the expiration to a near-future date.

  8. Finish the restore.

    • The restore process will begin.
    • When the following message appears, power on all other nodes:
      Waiting for nodes to be ready for restore: node2
    • Do not press any keys while the restore process is completing. Allow the restore process to complete and reboot each node automatically.

Post-Restore Steps

Verification

After the system reboots, log into the VergeOS UI to verify the health of the restored system:

  • Verify all nodes are detected and show online (green status) in the node list.
  • Review the Alarms dashboard.
  • Check the system log (on the Main Dashboard) for anything unexpected that may have occurred during or after the restore.
  • Confirm all vSAN tiers show online. Tiers may take some time to come fully online after a restore, as the system may perform a journal walk. See Journal Walks and vSAN Tier Status for more information.

Pre-Restore Snapshot

If you opted to take the pre-restore system snapshot, note that it is set to Never Expire. Once the restore is verified and the snapshot is no longer needed, delete it or set its expiration to a near-future date. Snapshots set to never expire can consume significant vSAN storage over time as live data continues to change.

Troubleshooting

Restore operation appears to hang

Symptoms:

  • Restore operation appears to stall with the last message indicating it is waiting for a node (e.g. Waiting for nodes to be ready for restore: node2).

Resolution:

  • Verify the specified node is connected and powered on. All nodes must be functional and able to accept the restore.

Symptoms:

  • Restore operation appears to stall with one or more additional characters displaying after the "Waiting for nodes..." message.

Resolution:

  • This may indicate a key was pressed while the restore was in the completion phase, halting the process. If the screen remains unchanged for more than several minutes, reboot node1 to access the boot menu, and repeat restoration steps. Ensure there is no keyboard activity when the restore indicates it is waiting for nodes to be ready.

Error when attempting to log in immediately after restore

Symptoms:

  • After selecting the User Interface option, the browser loads and reports: Site Can't be Reached or Invalid JSON format received from the server

Resolution:

  • After a restore, networks must restart before the UI becomes accessible. Wait 1–2 minutes for networks to automatically come back online, refresh the browser page to retry connecting to the VergeOS UI.

Need Help?

If you need further assistance, please contact the VergeOS Support Team.

How to Configure a Volume for VM Exports

The VergeOS NAS supports a volume type specifically for exporting selected virtual machines (VMs). The VM Export volume provides a controlled way to export selected VMs to a NAS volume that can then be synchronized to a remote storage system (e.g. existing NAS appliance) or shared via CIFS or NFS for access by external backup tools or other applications.

This export mechanism can be useful for customers who want to synchronize VergeOS VM snapshots to storage hardware they already own, rather than deploying an additional VergeOS system for backup purposes. While VergeOS recommends using its native replication features for the most efficient and fully integrated protection workflow, the VM Export Volume offers flexibility for environments that need to meet compliance requirements or maintain external portability of their VM data.

The following steps describe how to configure and use a NAS-hosted VM export volume.

Preparing the VMs for Export

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

Setting Up the NAS Service

To host the VM export volume, you will need a NAS service. Use an existing NAS service or create a new service using the following instructions:

  1. Navigate to NAS > List.

A listing of current NAS services is displayed. You can select an existing service or continue the following instructions to create a new service.

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

Starting the NAS Service

  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.

Creating a NAS User

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

  1. Navigate to NAS > List > double-click the NAS Service to be used.
  2. Click NAS Users > New.
  3. Provide a username and password.
  4. Click Submit to save the new NAS user.

Creating a New Volume for VM Export

  1. Select NAS > + New Volume from the top menu.
  2. Configure the volume:
    • NAS Service: Select the NAS service from above
    • Name: Provide a name for the volume, e.g. "VM-export"
    • Filesystem Type: Verge.io VM Export
    • VM configuration output file format: Select the format used for the exported VM configuration file.
      • Verge.io Virtual Machine (.ybvm) — A human‑readable, JSON‑based format that is non‑binary and non‑proprietary. This format is ideal for portability, transparency, and interoperability with external tools or workflows that prefer open, inspectable configuration data.
      • Open Virtualization Format (.ovf) — A widely supported industry-standard format used by many third‑party virtualization platforms and import utilities.
    • Quiesced: Typically should be selected to provide application-consistent VM snapshots. ⚠️ VM Guest Agent must be installed and registered to provide a quiesced VM snapshot.
    • Max exports to store: default=3; determines the maximum number of export instances that will be stored at a time
    • Enable current folder: default=enabled; Exports are contained in folders named according to date/time of the export. With this option enabled, an additional folder named "current" is created to continually contain a branch of the most recent export. This is often helpful to provide an absolute path to retrieve the latest VM snapshots.
  3. Click Submit.

After you click Submit, the export volume’s dashboard opens where you can run operations on it. To access this dashboard later, navigate to NAS > Volumes in the top menu, then double-click the volume in the list.

Running the VM Export (manual start)

  1. Under Export VMs (mid-page), click the Start button to initiate the VM export process.
  2. Confirm by clicking Yes at the prompt.

Accessing the Exported Data

You can quickly view the contents of the export volume using the Browse option on the left menu.

To access the exported VM snapshots, set up a CIFS or NFS share for the NAS volume:

Setting up a CIFS Share for the Exported Data

  1. Create a CIFS Share:

    • Navigate to NAS > CIFS Shares > New.
    • Select the export volume 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.

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.

Setting up an NFS Share for the Exported Data

Instructions for creating an NFS share can be found here.

Synchronizing Exported Data to an External System

Exported VM data can be pushed to an external system using a NAS volume sync.

  1. Create a Remote Volume to mount the external volume to the VergeOS NAS (requires standard NFS or CIFS access)
  2. Create a Volume Sync to synchronize data to the Remote Volume. Volume syncs can be started on-demand manually and can also be scheduled using the Start Profile setting.

Automating the VM Export

You can schedule regular exports by configuring a task and a schedule trigger.

Available Schedules

VergeOS includes multiple pre-installed schedules (e.g., "Daily at midnight"). Refer to the Schedules Guide for instructions on creating custom schedules.

Creating a Scheduled Export Task

  1. Navigate to the VM Export Volume: NAS > Volumes > double-click the export volume.
  2. Scroll down to the Export VMs section and click the Tasks button.
  3. Click New on the left menu to create a new export task.
  4. Configure the new task fields:
    • Name: provide a descriptive name, e.g. start-vm-export
    • Object Type: VM Export (pre-selected when accessed from the volume)
    • Object: select the export volume (pre-selected when accessed from the volume)
    • Action: Start Export
  5. Click Submit to save the new task.

Assigning a Schedule to the Task

  1. After submitting, the task detail page opens. Click Schedule Triggers in the left menu.
  2. Click New on the left menu.
  3. Select the desired Schedule from the dropdown list (e.g., "Daily at midnight").
  4. Click Submit to activate the scheduled export.

Configuring Export Settings

Use the Settings button in the Export VMs section to modify export options such as the quiesce setting and maximum exports to store.

By completing these steps, you will have a VM export volume configured to generate exportable snapshots of selected VMs and make them available to third‑party backup solutions or external storage systems.

For most environments, VergeOS’s built‑in snapshot and replication features remain the most efficient and integrated method for protecting and synchronizing VM data between VergeOS systems. The VM Export volume workflow is intended for scenarios where compliance policies, existing storage investments, or portability requirements call for VM data to be maintained outside the primary VergeOS infrastructure. This provides organizations with flexibility and assurance that their VM data can be integrated into broader backup strategies or external storage ecosystems when needed.

Document Information

  • Last Updated: 2026-02-11
  • vergeOS Version: 26.1

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

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

Note

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

Recover a Copy of the VM on the Backup Side

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


Create a New System Snapshot on the Backup Side

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


Request a Sync-Back on the Original/Source Side

  1. On the origin (sending) side, navigate to the configured outgoing site sync. This is done from Backup/DR > Outgoing Syncs, and then double-clicking into the configured outgoing sync.
  2. From the outgoing sync dashboard, click Refresh Remote Snaps on the left navigation menu. This will query the remote side for any new snapshots and list them. It should detect the snapshot created in the steps above.

  3. Once the newly created snapshot is detected, it will be listed under the Remote Snapshots section. Find the snapshot and click on the Request to Download icon to the far right of the listed snapshot.

  4. The Request System Snapshot menu will load. Set a reasonable expiration date for how long the recovered snapshot will be retained on this system, and click Submit.

  5. The system will load the Sync-Back / Incoming Sync. The length of time it will take to transfer the snapshot back can vary greatly depending on several factors, including bandwidth speed and the size of the data to transfer.

  6. Wait while the synchronization completes. Once finished, a new entry will appear in the log section.

    Example

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

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

Document Information

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

Exporting Virtual Machines from VergeOS

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

Steps to Export a Virtual Machine

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

Important Considerations

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

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

Document Information

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

Common Snapshot Synchronization Error Messages Explained

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

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

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

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

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

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

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

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

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

Error - Sync back not found and no registration code supplied

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

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

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

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

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

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

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

Unable to update system snapshot: No such file or directory

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

Error notifying client with 'notify_start' Connection timed out

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

---

Document Information

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