NetApp

ONTAP Volume Move Cutover and iSCSI LIF Migration Runbook

Published May 25, 2026 | 12 min read

Where This Runbook Fits

This runbook is for a planned ONTAP storage change where a FlexVol volume needs to move to another aggregate and the related host access path needs to be checked during cutover. It is based on the kind of work that shows up in real maintenance plans: move the data, control the cutover window, verify client access, and leave enough evidence for the change record.

There is one important distinction before any commands are run:

A NAS data LIF can be migrated with network interface migrate.
A SAN LIF, including many iSCSI LIFs, is handled differently. NetApp documents that SAN LIF movement uses an offline, modify home node or port, and online workflow, not network interface move.
ONTAP supports iSCSI LIF migration on ASA platforms running ONTAP 9.11.1 or later, with restrictions. On non-ASA platforms, plan to create or move SAN access according to the SAN LIF procedure instead of assuming a NAS-style LIF migration.

NetApp's command reference lists the volume move command set, including volume move start, volume move show, volume move trigger-cutover, and volume move abort: Commands for moving volumes in ONTAP. NetApp's LIF documentation covers both migrating a LIF and moving a SAN LIF.

Pre-Change Checklist

Do not start with the move command. Start by proving that the volume, destination, client path, and rollback decision are understood.

Check	CLI Evidence	Why It Matters
Cluster health	`system health status show`	Avoid starting a mobility operation during a cluster issue
Aggregate capacity	`storage aggregate show`	Confirm the target aggregate can absorb the volume footprint
Volume state	`volume show -vserver <svm> -volume <volume>`	Confirm the source volume, SVM, type, and current aggregate
Volume space	`volume show-space -vserver <svm> -volume <volume>`	Catch snapshot or metadata growth before the move
LUN mapping	`lun show -vserver <svm>`	Identify the host-facing objects if this is SAN-backed
LIF location	`network interface show -vserver <svm>`	Confirm current node, current port, home node, and home port
Host multipath	Host MPIO command	Make sure hosts have redundant healthy paths before SAN work
Snapshot or backup	Backup platform evidence	Avoid making rollback depend only on the move operation

Record the change variables before the work starts:

SVM:             svm_prod01
Volume:          app_lun_vol01
Source aggregate: aggr_node01_ssd
Target aggregate: aggr_node02_ssd
Cutover window:  60 seconds
Cutover action:  wait
Related iSCSI LIFs:
  - iscsi_lif_node01_a
  - iscsi_lif_node02_a
Host validation:
  - multipath paths healthy
  - application owner confirms I/O
  - no host path down alerts after cutover

CLI Process: Volume Move

First, capture the current location and status:

volume show -vserver svm_prod01 -volume app_lun_vol01 \
  -fields aggregate,state,type,size,used,available,junction-path

volume show-space -vserver svm_prod01 -volume app_lun_vol01

storage aggregate show -aggregate aggr_node02_ssd \
  -fields size,usedsize,availsize,percent-used,state

If the destination aggregate is valid, start the move. The -cutover-action wait pattern is useful in change windows because ONTAP can copy data in the background and wait for an explicit cutover command.

volume move start \
  -vserver svm_prod01 \
  -volume app_lun_vol01 \
  -destination-aggregate aggr_node02_ssd \
  -cutover-window 60 \
  -cutover-action wait

Monitor the move:

volume move show -vserver svm_prod01 -volume app_lun_vol01

When ONTAP reports that the move is waiting for cutover, validate the host path before triggering cutover:

network interface show -vserver svm_prod01
lun mapping show -vserver svm_prod01
lun igroup show -vserver svm_prod01

Trigger the cutover:

volume move trigger-cutover \
  -vserver svm_prod01 \
  -volume app_lun_vol01

Then verify the final aggregate and volume state:

volume show -vserver svm_prod01 -volume app_lun_vol01 \
  -fields aggregate,state,size,used,available

volume move show -vserver svm_prod01 -volume app_lun_vol01

If the move must be stopped before cutover, use the abort command and document the reason:

volume move abort -vserver svm_prod01 -volume app_lun_vol01

CLI Process: NAS LIF Migration

For NAS data LIFs, a manual LIF migration is a normal tool during maintenance. NetApp describes network interface migrate as a best-effort operation that can move a logical interface to a destination node and port when the destination is operational.

Check the current LIF placement:

network interface show -vserver svm_nfs01 \
  -fields lif,address,home-node,home-port,curr-node,curr-port,status-oper,failover-policy

Migrate a NAS LIF:

network interface migrate \
  -vserver svm_nfs01 \
  -lif nfs_lif01 \
  -destination-node lab-02 \
  -destination-port e0c

Verify the current node and port:

network interface show -vserver svm_nfs01 -lif nfs_lif01 \
  -fields home-node,home-port,curr-node,curr-port,status-oper,is-home

After maintenance, revert the LIF if that is the intended design:

network interface revert -vserver svm_nfs01 -lif nfs_lif01

CLI Process: iSCSI LIF Movement

Treat iSCSI LIF changes as SAN path work, not as a simple NAS cutover. Before touching a SAN LIF, confirm host multipath health and make sure each host has surviving paths through other target LIFs.

Check the iSCSI LIFs:

network interface show -vserver svm_prod01 \
  -data-protocol iscsi \
  -fields lif,address,home-node,home-port,curr-node,curr-port,status-admin,status-oper

Check portsets if they are used. NetApp notes that some iSCSI or FCP LIF properties, such as home node and home port, cannot be modified while the LIF is in a portset.

lun portset show -vserver svm_prod01

Move the SAN LIF by taking it offline, modifying the home location, and bringing it online:

network interface modify \
  -vserver svm_prod01 \
  -lif iscsi_lif_node01_a \
  -status-admin down

network interface modify \
  -vserver svm_prod01 \
  -lif iscsi_lif_node01_a \
  -home-node lab-02 \
  -home-port e0d

network interface modify \
  -vserver svm_prod01 \
  -lif iscsi_lif_node01_a \
  -status-admin up

Validate from ONTAP:

network interface show -vserver svm_prod01 -lif iscsi_lif_node01_a \
  -fields address,home-node,home-port,curr-node,curr-port,status-admin,status-oper

iscsi session show -vserver svm_prod01
lun mapping show -vserver svm_prod01

Validate from the host as well. For Linux hosts, that usually means checking multipath, iSCSI sessions, and application I/O:

multipath -ll
iscsiadm -m session
lsblk

REST API Process: Discover the Volume and LIFs

For REST API workflows, start by discovering the UUIDs. The ONTAP REST API uses UUIDs for most object-specific PATCH operations.

Get the target volume:

curl -k -u admin:'<password>' \
  "https://cluster-mgmt.example.com/api/storage/volumes?svm.name=svm_prod01&name=app_lun_vol01&fields=uuid,name,svm.name,aggregates.name,movement,state,space"

Get the related IP interfaces:

curl -k -u admin:'<password>' \
  "https://cluster-mgmt.example.com/api/network/ip/interfaces?svm.name=svm_prod01&fields=uuid,name,ip.address,location,enabled,services"

NetApp's REST API documentation states that a volume move can be started by PATCHing the volume endpoint with the movement object. It also maps volume move fields such as destination aggregate and cutover window to REST attributes: ONTAP volume REST mapping and storage volume PATCH documentation.

REST API Process: Start and Monitor Volume Move

Use validate_only=true first when you want ONTAP to validate the request without performing the operation:

curl -k -u admin:'<password>' \
  -X PATCH \
  "https://cluster-mgmt.example.com/api/storage/volumes/<volume_uuid>?validate_only=true" \
  -H "Content-Type: application/json" \
  -d '{
    "movement": {
      "destination_aggregate": {
        "name": "aggr_node02_ssd"
      },
      "cutover_window": 60
    }
  }'

Start the move:

curl -k -u admin:'<password>' \
  -X PATCH \
  "https://cluster-mgmt.example.com/api/storage/volumes/<volume_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "movement": {
      "destination_aggregate": {
        "name": "aggr_node02_ssd"
      },
      "cutover_window": 60
    }
  }'

Monitor movement state and percent complete:

curl -k -u admin:'<password>' \
  "https://cluster-mgmt.example.com/api/storage/volumes/<volume_uuid>?fields=name,aggregates.name,movement"

Trigger cutover when the change window is ready:

curl -k -u admin:'<password>' \
  -X PATCH \
  "https://cluster-mgmt.example.com/api/storage/volumes/<volume_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "movement": {
      "state": "cutover"
    }
  }'

Abort an in-progress move if the change must be backed out before completion:

curl -k -u admin:'<password>' \
  -X PATCH \
  "https://cluster-mgmt.example.com/api/storage/volumes/<volume_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "movement": {
      "state": "aborted"
    }
  }'

REST API Process: LIF Updates

For IP interfaces, the REST equivalent is a PATCH to the interface object. NetApp's REST API documentation for updating IP interfaces lists PATCH /network/ip/interfaces/{uuid} and relates it to network interface migrate: Update an IP interface.

Before changing an iSCSI LIF, identify whether the desired operation is a supported migration, a SAN LIF move, or a new LIF build. Do not blindly copy the NAS LIF process into SAN.

Disable the LIF:

curl -k -u admin:'<password>' \
  -X PATCH \
  "https://cluster-mgmt.example.com/api/network/ip/interfaces/<lif_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Change the home location:

curl -k -u admin:'<password>' \
  -X PATCH \
  "https://cluster-mgmt.example.com/api/network/ip/interfaces/<lif_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "home_node": {
        "name": "lab-02"
      },
      "home_port": {
        "name": "e0d"
      }
    }
  }'

Enable the LIF:

curl -k -u admin:'<password>' \
  -X PATCH \
  "https://cluster-mgmt.example.com/api/network/ip/interfaces/<lif_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

Then confirm placement and operational state:

curl -k -u admin:'<password>' \
  "https://cluster-mgmt.example.com/api/network/ip/interfaces/<lif_uuid>?fields=name,ip.address,location,enabled,state"

Backout Plan

The backout path depends on where the change failed.

Failure Point	Backout
Volume move validation fails	Do not start the move; fix aggregate, volume, or policy issue
Volume move running but not cut over	Abort the move with `volume move abort` or PATCH `movement.state` to `aborted`
Volume moved but host path degraded	Restore the intended LIF layout, validate MPIO, and involve host owner before further movement
SAN LIF disabled and host impact is visible	Bring the LIF back online on its original home port if still valid
Application validation fails after cutover	Decide whether to move the volume back or continue remediation based on host path and ONTAP health

Do not call a completed volume move a rollback by itself. If the cutover has completed and hosts are writing to the volume, moving it back is another controlled change.

Post-Change Evidence

Capture enough evidence that another engineer can understand the final state without joining a bridge call.

system health status show
storage aggregate show
volume show -vserver svm_prod01 -volume app_lun_vol01 -fields aggregate,state,size,used,available
volume show-space -vserver svm_prod01 -volume app_lun_vol01
network interface show -vserver svm_prod01
iscsi session show -vserver svm_prod01
lun mapping show -vserver svm_prod01

For REST API-driven changes, save the final GET responses for the volume and affected interfaces:

curl -k -u admin:'<password>' \
  "https://cluster-mgmt.example.com/api/storage/volumes/<volume_uuid>?fields=name,aggregates.name,movement,state,space"

curl -k -u admin:'<password>' \
  "https://cluster-mgmt.example.com/api/network/ip/interfaces?svm.name=svm_prod01&fields=name,ip.address,location,enabled,state,services"

Practical Change Record Template

Use this compact evidence block in the change ticket:

Pre-check:
- Cluster health:
- Source volume:
- Source aggregate:
- Target aggregate:
- Host multipath:
- Related LIFs:

Execution:
- Volume move start time:
- Cutover trigger time:
- Cutover result:
- LIF changes:

Validation:
- Volume final aggregate:
- LIF final placement:
- iSCSI sessions:
- Host multipath:
- Application owner confirmation:

Backout used:
- No / Yes, with details:

Common Mistakes

Treating a SAN LIF like a NAS LIF without checking platform and ONTAP version support.
Starting a move without confirming target aggregate capacity.
Letting ONTAP choose cutover timing when the change requires an explicit application validation point.
Forgetting portsets before trying to change iSCSI or FCP LIF home settings.
Checking only ONTAP and not the host multipath view.
Calling the change complete before the application owner confirms I/O.

The operational goal is not just to make ONTAP report success. The goal is to prove that data moved, host access remained healthy, and the final path design is the one the team intended.