--- title: "Migrate from NFS Export to VAST NFS" slug: "migrate-from-nfs-export-to-vast-nfs-34" updated: 2026-10-24T13:46:13Z published: 2026-10-23T15:27:23Z canonical: "kb.vastdata.com/migrate-from-nfs-export-to-vast-nfs-34" --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.vastdata.com/llms.txt > Use this file to discover all available pages before exploring further. # Migrate from NFS Export to VAST NFS ## Overview The NFS connector scans the source NFS export over NFSv3, stores the resulting index under a shared index path, and copies files with `rsync` to the destination export with POSIX ACLs preserved. The following capabilities are supported for NFS migrations: - To determine when data synchronization occurs: - [Periodic Resync](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#periodic-resync) - To manage which items are being synchronized: - [Exclude List](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#exclude-list) - [Mirror Deletions](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#mirror-deletions) - To configure SyncEngine processes: - [Configure connector ports for managed NFS environments](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#configure-connector-ports-for-managed-nfs-environments) Complete these steps to set up migration from a source NFS export to a destination NFS export: 1. Ensure that the [prerequisites](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#before-you-begin) are met. 2. [Create](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#create-nfs-connector) two NFS connectors: one for source NFS export and the other for destination NFS export. 3. [Create](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#create-migration) a migration. 4. [Start](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#start-migration) the migration. > **Note:** This step is only required when the migration does not have periodic resynchronization enabled. 5. [Monitor](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#monitor-migration) migration progress and completion. 6. If necessary, [troubleshoot](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#troubleshoot). The following limitations apply: - SyncEngine does not preserve NFSv4.1 ACLs. ## Features ### Periodic Resync In addition to starting a migration once it is created, SyncEngine can be configured to automatically run a resynchronization at user-supplied intervals. - In SyncEngine UI, set the **SyncMode** to **Automatic** and enter an interval (in hours) in the **Sync Interval** field. - In SyncEngine CLI, include the `--sync-mode automatic=true` and `--sync-interval <interval>` options when submitting the `migration create` command. For migrations set to **Automatic** synchronization mode, the first synchronization starts immediately after the migration is created, and the subsequent synchronizations are performed periodically with the specified interval. A subsequent synchronization cannot be triggered manually. To be able to manually start a synchronization on demand, set **SyncMode** to **Manual**. ### Exclude List You can supply a list of files or directories to be skipped during migration. The list can contain file paths or wildcard patterns, one path or pattern per line. Supported wildcards are: `*` (zero or more characters), `?` (one character), and `[seq]` (one character from the sequence or range). The wildcards can appear anywhere in the path. For example: ``` /mnt/source/projects/logs/*.log /mnt/source/projects/data/temp/* /mnt/source/projects/reports/image[1-2000].jpg ``` Do not add trailing slashes to directory paths, e.g. specify `/path/dir` (but not `/path/dir/`). Common patterns include: | Pattern | Effect | | --- | --- | | `/path/to/file.txt` | Exclude the specified file | | `/path/to/dir` | Exclude the directory and its entire subtree | | `/path/to/dir/*` | Create an empty directory but exclude anything within that directory | | `/path/to/dir/*.tmp` | Excludes matching files in that directory | To supply an exclude list: - In SyncEngine UI, upload the exclude list file in the **Exclusion list** field when creating a migration. - In SyncEngine CLI: - Include the `--exclusion-file <file path>` option on the `migration create` command, or - Run this command after the migration is created: ``` migration exclusion-file upload --migration-id= ``` The exclude list file must use the UTF-8 encoding. The following limitations apply: - An exclude list can contain up to 10,000 lines. - Comment lines (#) are not supported. ### Mirror Deletions You can determine how SyncEngine handles the items in the source store that have been deleted since the previous migration run. By default, SyncEngine does not delete such items from the destination. If you want to have them deleted, configure the migration to mirror source deletions at the destination: - In SyncEngine UI, select the **Mirror source deletions at destination** option when creating a migration. - In SyncEngine CLI, include the `--enable-deletes=true` option when submitting the `migration create` command. > **Note:** Deletion of items at the destination cannot be undone by disabling this setting. ### Configure Connector Ports for Managed NFS Environments When you configure the NFs connector, you can specify ports to be used by SyncEngine in a managed NFS environment where the RPC portmapper (TCP port 111) is not reachable. To do so: - In SyncEngine UI, use the **NFS Port** and **Mount Port** options in connector settings. - In SyncEngine CLI, include the `--nfs-port` and `--mount-port` options on the `connector create` command. ## Before You Begin Ensure that the prerequisites are met: ### Source NFS Store - IPs to reach the source NFS server are known. ### VAST Cluster #### Create View Policies Create a view policy that will control access to the destination data view and the index view. You can use a single vie policy for both, or create two different policies. In the view policy: - Select the **NFS** security flavor. - Set NFS host-based rules to *nosquash* for the worker IPs. - Set **Name length limit** to **Native Protocol Limit**. - Set **Allowed Characters** to **Native Protocol Limit**. #### Create Destination View Create an Element Store view exposing the destination VAST NFS export. In the view settings: - Select the **NFSv3** protocol. - Select the view policy you created. #### Create Index View Create an Element Store view exposing the VAST NFS export that will be used to maintain scan index during the migration. When running a migration, SyncEngine creates a directory named `migration_<id>` under the index view to store scan index files. The directory is removed when the migration is complete. In the view settings: - Select the **NFSv3** protocol. - Select the view policy you created. > **Note:** The index cannot reside under a source or destination NFS export, on a local disk or in a host-local directory. ### SyncEngine - The SyncEngine control plane and at least one worker are up and running. - At least one worker label of a deployed worker is known. (The worker label is set when you deploy the worker.) - Hosts that run workers can reach the source and destination NFS servers. - The source NFS export, destination NFS export and the index view must be mounted on all workers (labeled for a particular NFS migration) using the same absolute path names. > **Tip:** Run `findmnt -T <path> -t nfs,nfs4` to verify. - The SyncEngine worker must have read access to the source NFS export and read/write access to the destination NFS export and the index view. #### Mount Source, Destination and Index on Worker Hosts Below are examples of the required mounts for NFS to NFS migrations. 1. Mount the source: ``` sudo mkdir -p /mnt/nfs-source sudo mount -t nfs -o vers=3 :/export/path /mnt/nfs-source ``` 2. Mount the destination: ``` sudo mkdir -p /mnt/nfs-dest sudo mount -t nfs -o vers=3 :/view/path /mnt/nfs-dest ``` 3. Mount the index: ``` sudo mkdir -p /mnt/syncengine-index sudo mount -t nfs -o vers=3 :/syncengine-index /mnt/syncengine-index ``` 4. Verify that `findmnt` returns the mounts: ``` findmnt -T /mnt/nfs-source -t nfs,nfs4 findmnt -T /mnt/nfs-dest -t nfs,nfs4 findmnt -T /mnt/syncengine-index -t nfs,nfs4 ``` 5. Ensure that the mounts are visible inside the worker. Workers only see host paths that are bind-mounted into the worker container. When you deploy a worker, include every top-level directory that holds your NFS mounts (default is often `/mnt`). For example, if mounts are under `/mnt` and `/data`, deploy the worker with both paths in the worker volume list (e.g. `VOLUMES=/mnt/data`). After deploy, from inside a worker shell (or by checking the host mounts the container inherits), confirm the same paths exist and remain NFS mounts. If you mount a new export on the host after the worker started, restart the worker (or remount) so the container sees it. ## Create NFS Connector An NFS connector is used to connect to a source NFS export or a destination VAST NFS export. ### SyncEngine UI 1. In the **Connectors** page, click **New Connector**. A wizard dialog appears to walk you through the connector creation steps. 2. In the **Type & name** step: - Select the **NFS** connector type. - In the **Connector name** field, enter a unique name for the connector. The name can contain up to 63 characters, including uppercase and lowercase English letters, digits, periods (.), hyphens (-) and underscores (_). 3. In the **Endpoint** step: - Under **NFS Endpoint**, enter the index path and NFS endpoint IPs: | Field | Description | | --- | --- | | **Index Path** | Enter the absolute mount path of the index view created in [Before you begin](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#before-you-begin). For NFS to VAST NFS migrations, the same index path must be specified in both NFS connectors (source and destination). | | **NFS Endpoint IPs** | Enter a comma-separated list of NFS server endpoint IPs. | - Under **NFS Ports**, specify ports to be used by SyncEngine in a managed NFS environment where the RPC portmapper (TCP port 111) is not reachable. | Field | Description | | --- | --- | | **NFS Port** | Enter the NFS daemon port. Port 2049 is commonly used for this purpose. | | **Mount Port** | Enter the mount port. Port 20048 is commonly used for this purpose. | 4. In the **Tunables** step, optionally configure migration scan settings. 5. In the **Rsync** step, optionally configure `rsync` flags for NFS file transfers. 6. In the **Review** step, review the settings you've made. If you want to make changes, click **Back**. Otherwise, click **Create Connector**. The connector is created and displayed in the **Connectors** page. ### SyncEngine CLI The following command creates an NFS connector named `src-nfs` to migrate from an NFS export reachable through `<IP>` using index path `/mnt/syncengine-index`: ``` syncengine-cli connector create \ --type=nfs \ --name=src-nfs \ --index-path=/mnt/syncengine-index \ --endpoint-ips= ``` Optional flags: ``` --nfs-port --nfs-mount-port --block-size --batch-size-gb --batch-file-count --task-flush-threshold --local-queue-timeout --scan-task-max-duration --local-queue-max-dirs --local-queue-split-size --rsync-archive --rsync-compress --rsync-checksum --rsync-hard-links --rsync-acls --rsync-xattrs --rsync-no-perms --rsync-no-owner --rsync-no-group --rsync-bwlimit --rsync-timeout ``` The output should be similar to the following: ``` Successfully created connector 'src-nfs' with ID 15 ``` > **Tip:** Note the connector ID in the output. ## Create Migration Create a migration to copy files from a source mount path to a destination mount path on SyncEngine workers. ### SyncEngine UI 1. In the **Migrations** page, click **New Migration**. A wizard dialog appears to walk you through the migration creation steps. 2. In the **Source** step, select the NFS connector that will be used to connect to the source NFS export. 3. In the **Destination** step, select the NFS connector that will be used to connect to the destination NFS export on the VAST cluster. 4. In the **Paths** step: - Under **Migration Label**, specify a SyncEngine worker label for the migration. The label is used to route migration jobs to the appropriate SyncEngine worker. One worker can be associated with one or more migration labels. Workers deployed with a certain label handle jobs for all migrations that have that label. You can create a new label or use an existing one. - To create a new label, select **Create new label** and enter a text string in the **New Label** field. The label can contain up to 128 characters, including uppercase and lowercase English letters, digits, periods (.), hyphens (-) and underscores (_). - To use an existing label, select **Use existing label** and enter the label string in the **Existing Label** field. - Under **Paths**, specify the paths to the migration source and destination. - Under **Source Path**, enter the absolute mount path of the NFS export to migrate data from. The export must be mounted at the same path on all workers with read permissions. You can specify a subdirectory under the mount root, for example: `/mnt/nfs-source/projectA`. - In the **Destination Path**, enter the absolute mount path of the destination NFS export. The export must be mounted at the same path on all workers with write permissions. 5. In the **Sync mode** step: - Under **Sync Mode**, specify if you want to run the migration once or [periodically](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#periodic-resync): - To run the migration once, select **Manual** in the **SyncMode** field. Migration will be started after you submit the migration job manually. - To run the migration automatically at certain intervals, select **Automatic** in the **Sync Mode** field and enter an interval (in hours) in the **Sync Interval** field. The default interval is 24 hours. - Under **Include & exclude lists**: optionally add an exclude list for the migration: - Use the **Exclusion list** field to upload a file listing specific file paths to be skipped during the migration. To learn more about this feature, see [Exclude list](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#exclude-list). 6. In the **What you're copying** step: - Under **What you're copying**: - Review the settings you've made. If necessary, click **Back** and change as needed. - Under **Delete propagation**: - Decide how SyncEngine [handles the files that have been deleted](/documentation/docs/migrate-from-nfs-export-to-vast-nfs-34#mirror-deletions) since the previous migration run. By default, SyncEngine does not delete such files from the destination NFS export. If you want to have them deleted, select **Mirror source deletions on the destination**. 7. In the **Batch sizing** step, optionally adjust the size of batches that SyncEngine uses when copying the data. By default (if no values are entered in the fields provided), SyncEngine uses VAST cluster's defaults which are suitable for most workloads. - In the **Batch size** field, specify the maximum allowed batch size in GB. If not specified, a default of 1024GB is used. - In the **Batch file count** field, specify the maximum allowed count of files per batch. If not specified, a default of 1000 files is used. 8. In the **Per-task timeouts** step, optionally configure suitable timeouts for the migration jobs. 9. In the **Review** step, review the settings you've made. If you want to make changes, click **Back**. Otherwise, click **Create Migration**. The migration is created and displayed in the **Migration** page. ### SyncEngine CLI The following command creates a migration from `/mnt/nfs-source` to `/mnt/nfs-dest`. The migration is to be accomplished by workers labeled with `MYFIRSTMIGRATION` using connectors with connector IDs `12` and `14`. ``` syncengine-cli migration create \ --source-connector-id=12 \ --destination-connector-id=14 \ --source-path=/mnt/nfs-source \ --destination-path=/mnt/nfs-dest \ --label=MYFIRSTMIGRATION ``` Optional flags: ``` --sync-mode {manual | automatic --sync-interval } --enable-deletes={true|false} --exclusion-file --batch-size --batch-file-count ``` The CLI creates a migration and displays its properties. > **Tip:** Note the migration ID in the output. ## Start Migration Manual migration start is only relevant for migrations that do not have periodic resynchronization configured. For migrations with periodic resynchronization, the migration starts automatically upon creation. ### SyncEngine UI Navigate to the ​**Migrations**​​ page and click the start button for the migration you want. ### SyncEngine CLI Run the command: ​ syncengine-cli migration start --migration-id=
​
The output should be similar to the following:
​
Starting sync job for migration: MYFIRSTMIGRATION
✓ Sync job created successfully!
Job ID: 2
Status: pending ## Monitor Migration As the migration progresses, its status changes as follows: `Not Started` (or `init`) -> `Waiting for Worker` (or `pending`) -> `Syncing` -> `Synced`. When complete, the destination mount path will have files and directories copied from the source mount path. To verify, compare file counts or spot-check files on the destination NFS path from a worker host. ### SyncEngine UI Check the migration status in the **Migrations** page. ### SyncEngine CLI Run the command: ``` syncengine-cli migration status --migration-id= ``` The output should be similar to the following: ``` === Migration Status: MYFIRSTMIGRATION === ID: 125 Status: synced Source: /mnt/nfs-source Destination: /mnt/nfs-dest Sync Mode: manual Last Sync: 2026-07-15 14:06:08 Copy Tags: always Settings: Error Retry: 0s Task Retry: 0 Batch Size: 0 GB Batch File Count: 0 Sync Jobs: 1 Recent Sync Jobs: +----+-----------+------------------+-------------+-------+------+ | ID | STATUS | START TIME | DURATION | FILES | SIZE | +----+-----------+------------------+-------------+-------+------+ | 96 | completed | 2026-07-15 14:06 | PT4.623401S | 1 | 29 B | +----+-----------+------------------+-------------+-------+------+ ``` ## Troubleshoot | Symptom | Likely Cause | Solution | | --- | --- | --- | | Sync job stays *pending* | Migration label does not match worker label | Update the migration to use the same label as the deployed worker. | | `Path <…> is not on an NFS mount` | Source, destination, or index path is local disk / missing mount / not visible in the worker. | Mount the export on the host, confirm with `findmnt -T <path> -t nfs,nfs4`, ensure the worker volume list includes that parent path, then restart the worker if needed. | | `Index path <…> does not exist (mount missing?)` | Index directory missing inside the worker | Create and mount the index path on every worker before starting the migration. | | `Index path <…> is not read-write` | Index mount is read-only or workers lack write on the view | Remount read-write; on VAST, update the view policy (*nosquash* /write access for all worker hosts). | | Mount timeout / portmap failure | RPC portmapper (TCP 111) blocked | Set NFS port 2049 and NFS mount port 20048 in the connector settings. | | Path missing inside worker but present on host | Host mount not bind-mounted into the worker | Add the parent directory to the worker volume list (for example, include `/mnt`) and redeploy or restart the worker. | | Index errors / unexpected reuse | Index on local disk, host-local path, or mixed into data view | Use a dedicaged VAST NFS view mounted at the same path on all workers; do not use an index path which is under the source or destination directory. | | Permission denied on mount/export | Export rejects unprivileged client ports or UID mapping | Update export options (allow non-privileged ports if required) and UID/GID mapping on workers. | | Permission denied on copy | Mount or export permissions | Update export ACLs and UID/GID mapping on workers. |