Skip to content

NAS#

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

NAS Volume Browser API Reference

Overview

Key Points

  • The volume_browser API is asynchronous - create a job, then poll for results
  • You must include ?fields=id,status,result when polling or the result won't be returned
  • Use empty string "" for the root directory path (not /)
  • The NAS service VM must be running to browse volumes

The volume_browser API provides file system browsing capabilities for NAS volumes. This is useful for automation, integrations, and building custom file management tools.

Prerequisites

  • A running NAS service with at least one online volume
  • API access with appropriate permissions
  • The volume's SHA1 key identifier (found in the volume dashboard URL or API)

How It Works

Browsing a volume is a two-step process:

  1. POST to /api/v4/volume_browser to create a browse job
  2. GET to /api/v4/volume_browser/{job_id}?fields=id,status,result to poll for results

Step 1: Create a Browse Request

Endpoint

POST /api/v4/volume_browser

Request Body

{
  "volume": "62db5fcd888082246b9346c0e65311334d91ed2c",
  "query": "get-dir",
  "params": {
    "dir": "",
    "limit": 1000,
    "offset": null,
    "filter": {
      "extensions": ""
    },
    "volume": "62db5fcd888082246b9346c0e65311334d91ed2c",
    "sort": ""
  }
}

Field Reference

Field Type Required Description
volume string Yes Volume key (SHA1 hash identifier)
query string Yes Operation type: get-dir, rename, delete, paste
params object Yes Query parameters (see below)

Params Object

Field Type Description
dir string Directory path to browse. Use "" for root.
limit integer Maximum number of entries to return (e.g., 1000)
offset integer/null Pagination offset, null for first page
filter.extensions string Filter by file extensions (empty string for all)
volume string Volume key (must match top-level volume)
sort string Sort field (empty string for default)

Response

{
  "location": "/v4/volume_browser/9a00434b882b9933512cc9d3abfd557a182d8fd3",
  "dbpath": "volume_browser/9a00434b882b9933512cc9d3abfd557a182d8fd3",
  "$row": 1,
  "$key": "9a00434b882b9933512cc9d3abfd557a182d8fd3"
}

The $key field contains the job ID needed for polling.

Step 2: Poll for Results

Endpoint

GET /api/v4/volume_browser/{job_id}?fields=id,status,result

Critical: Request the Result Field

The result field is NOT returned by default. You must explicitly request it with ?fields=id,status,result. Without this parameter, you will only receive status information.

Without ?fields=id,status,result: 

{
  "id": "9a00434b882b9933512cc9d3abfd557a182d8fd3",
  "query": "get-dir",
  "status": "complete",
  "command": ""
}

With ?fields=id,status,result: 

{
  "id": "9a00434b882b9933512cc9d3abfd557a182d8fd3",
  "status": "complete",
  "result": [
    {"name": "documents", "size": 4096, "date": 1706120819, "type": "directory"},
    {"name": "file.txt", "size": 1024, "date": 1769198797, "type": "file"}
  ]
}

Status Values

Status Description
running Job is still processing
complete Job finished successfully
error Job failed (check result for error message)

Polling Strategy

1. POST to create job
2. Wait 200-500ms
3. GET with ?fields=id,status,result
4. If status == "running", wait and retry (up to 30 attempts)
5. If status == "complete", process result
6. If status == "error", handle error

Result Format

When status is complete, the result field contains an array of file/directory entries:

[
  {
    "name": "document.pdf",
    "n_name": "document.pdf",
    "size": 102400,
    "date": 1769136871,
    "type": "file"
  },
  {
    "name": "images",
    "n_name": "images",
    "size": 4096,
    "date": 1769197982,
    "type": "directory"
  }
]

Entry Fields

Field Type Description
name string File or directory name
n_name string Normalized name (lowercase)
size integer Size in bytes
date integer Modification time (Unix timestamp)
type string "file" or "directory"

Empty Directories

For empty directories, result will be an empty array:

{
  "id": "8cb12559b689f5a52472bd8882dde1c095b2ab64",
  "status": "complete",
  "result": []
}

Examples

cURL

# Step 1: Create browse job
JOB_ID=$(curl -s -X POST "https://your-vergeos.example.com/api/v4/volume_browser" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "volume": "62db5fcd888082246b9346c0e65311334d91ed2c",
    "query": "get-dir",
    "params": {
      "dir": "",
      "limit": 1000,
      "offset": null,
      "filter": {"extensions": ""},
      "volume": "62db5fcd888082246b9346c0e65311334d91ed2c",
      "sort": ""
    }
  }' | jq -r '."$key"')

# Step 2: Poll for results (IMPORTANT: include fields parameter)
sleep 1
curl -s "https://your-vergeos.example.com/api/v4/volume_browser/${JOB_ID}?fields=id,status,result" \
  -H "Authorization: Bearer $TOKEN" | jq

Python

import requests
import time

def browse_volume(base_url, token, volume_key, path=""):
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }

    # Step 1: Create browse job
    payload = {
        "volume": volume_key,
        "query": "get-dir",
        "params": {
            "dir": path,  # Use "" for root
            "limit": 1000,
            "offset": None,
            "filter": {"extensions": ""},
            "volume": volume_key,
            "sort": ""
        }
    }

    response = requests.post(
        f"{base_url}/api/v4/volume_browser",
        headers=headers,
        json=payload,
        verify=False
    )
    job_id = response.json()["$key"]

    # Step 2: Poll for results
    for _ in range(30):
        time.sleep(0.5)

        # IMPORTANT: Request the result field explicitly
        response = requests.get(
            f"{base_url}/api/v4/volume_browser/{job_id}?fields=id,status,result",
            headers=headers,
            verify=False
        )
        data = response.json()

        if data["status"] == "complete":
            return data.get("result") or []
        elif data["status"] == "error":
            raise Exception(f"Browse failed: {data.get('result')}")

    raise TimeoutError("Browse operation timed out")

Troubleshooting

Common Issues

Result field is empty or missing

  • You must include ?fields=id,status,result in your GET request
  • Without this parameter, only status information is returned

"VM must be in running state to issue a query"

  • The NAS service VM is not running
  • Navigate to NAS > NAS Services and start the service

"Error getting volumes VM service: No such file or directory"

  • The volume's NAS service doesn't exist or was deleted
  • Verify the volume is associated with a valid NAS service

"Resource '/v4/volume_browser/' not found"

  • Empty job ID in poll request
  • Ensure you extract $key correctly from the POST response

Common Mistakes

  1. Using path instead of dir - The field is named dir, not path
  2. Sending params as JSON string - The params field must be an object, not a JSON-encoded string
  3. Missing params fields - All fields in the params object are expected
  4. Forgetting ?fields=id,status,result - Without this, no file data is returned

Requirements

  • The NAS service VM must be running to browse volumes
  • The volume must be online (mounted)
  • User must have read permissions on the volume

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 the VergeOS Support Team.

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