Creating a Directory Clone and Exposing It as a View with CLI

  • Updated on Jan 24, 2026
  • 4 minute(s) read
Prev Next

Summary

This guide shows how to use the vastpy command-line interface vastpy-cli to:

  1. Take a snapshot of a directory

  2. Create a clone from the snapshot

  3. Expose the clone as a View for access via protocols like NFS, SMB, etc.

If you want more details on clones, as well as some use cases, please refer to: Global and Local Snapshot Clones

The general sequence you will follow:

  1. Get prerequisites sorted

  2. Take a snapshot of an existing directory

  3. Create a clone of the snapshot

  4. Create a view to expose the clone

Prerequisites

  • VMS IP Address for your VAST Cluster

Host with:

  • vastpy Python package installed

  • Network access to VMS IP, specifically on port 443 (https)

  • VMS Manager with appropriate permissions

Installing vastpy

Install the vastpy package, which includes the vastpy-cli command:

pip install vastpy

Setting Up Authentication

Set up environment variables for authentication:

# Set these environment variables once per session
export VMS_USER=admin
 export VMS_PASSWORD=123456 #change if not default . notice the <space> in front of the command to omit password from command history.
export VMS_ADDRESS=vast-vms-address

Alternatively, you can specify credentials with each command:

vastpy-cli --user=admin --password=your_password --address=vast-vms-address [command]

Step 1: Take a Snapshot of the Source Directory

Create a snapshot of an existing directory you want to clone:

# Create a snapshot of the source directory
vastpy-cli post snapshots path=/path/to/source/directory name=source-snapshot locked=true

The command will return a response containing the snapshot details, including its ID: (response below is a reduced list of the properties available )

property               |value
-----------------------+----------------------------------------------+
id                     |12345
name                   |source-snapshot
url                    |https://10.143.15.201/api/snapshots/12345
title                  |source-snapshot(/path/to/source/directory)
path                   |/path/to/source/directory/
expiration_time        |3001-01-19T07:59:59Z
state                  |SUCCEED

Step 2: Create a Clone from the Snapshot

Use the snapshot ID from the previous step to create a clone:

With Background_sync enabled

# Create a clone using the snapshot ID (replace 12345 with the actual ID)
vastpy-cli post snapshots/12345/clone loanee_root_path=/path/to/clone name=directory-clone enabled=true

With Background_sync disabled

# Create a clone using the snapshot ID (replace 12345 with the actual ID)
vastpy-cli post snapshots/12345/clone loanee_root_path=/path/to/clone name=directory-clone enabled=false

This will create a clone at the specified path.

Step 3: Expose the Clone as a View

Now, expose the clone directory as a view to make it accessible via protocols such as NFS or SMB.

First, find a suitable view policy ID:

# List available view policies
vastpy-cli get viewpolicies fields=id,name

This should produce a table with policy IDs and names:

| id | name              |
|----|-------------------|
| 1  | default           |
| 6  | cosmos-mixed      |
| 5  | cosmos-nfs        |
| 3  | s3_default_policy |
| 4  | smb               |
| 11 | vmware            |

Note the ID of the policy you want to use, then create the view:

# Create a view to expose the clone (replace 1 with your policy ID)
vastpy-cli post views \
  path=/path/to/clone \
  name=clone-view \
  policy_id=1 \
  protocols='["NFS","SMB"]' \
  share=clone-share \
  alias=/clone

How to programmatically create a replicated path from vastpy import VASTClient

client = VASTClient(user='admin',
                    password='xxxxxx',
                    address='vast-file-server-vms-kfs2')
local_tenant_name = "default"
protection_policy_name = "testing"

tenant_id, = [i['id'] for i in client.tenants.get() if i['name'] == local_tenant_name]
protection_policy, = [i for i in client.protectionpolicies.get() if i['name'] == protection_policy_name]

client.protectedpaths.post(name="alon2", source_dir="/alon-rep-test-2", capabilities="ASYNC_REPLICATION",
                           target_exported_dir="/alon-rep-test-target-2", tenant_id=tenant_id, remote_tenant_guid=protection_policy['remote_tenant']['guid'],
                           protection_policy_id=protection_policy['id'])

Troubleshooting

  • Snapshot Creation Failed: Check that the source directory exists and you have permissions.

  • Clone Creation Failed: Ensure the snapshot exists and the provided ID is correct.

  • View Creation Failed: Verify that the clone path exists and the policy ID is valid.

  • Command Format Errors: Make sure you're using the correct parameter format. Key-value pairs should have no spaces around the equals sign (e.g., name=value not name = value).

Command Reference Summary

# Snapshots
vastpy-cli get snapshots                      # List all snapshots
vastpy-cli get snapshots/ID                   # Get snapshot details
vastpy-cli post snapshots [parameters]        # Create a snapshot
vastpy-cli patch snapshots/ID [parameters]    # Modify a snapshot
vastpy-cli delete snapshots/ID                # Delete a snapshot

# Clones
vastpy-cli post snapshots/ID/clone [parameters]  # Create a clone
vastpy-cli get globalsnapstreams/ID
# Views
vastpy-cli post views [parameters]  # Create a view

Conclusion

The vastpy-cli provides a powerful command-line interface to manage VAST snapshots and clones. By combining these commands with shell scripts, you can automate snapshot/clone operations for backup, testing, or development workflows.

For full CLI and API reference for vastpy, refer to https://github.com/vast-data/vastpy

Related articles