zfs.resource.rename

Rename a ZFS resource (filesystem or volume), remounting it at its new location.

To rename snapshots, use zfs.resource.snapshot.rename instead. A dataset rename can never be recursive; renaming a resource renames its descendants along with it.

Warning

No check is made whether the resource is in use. If it is used by services such as SMB, iSCSI, snapshot tasks, replication, or cloud sync, renaming it may cause disruptions or service failures. Proceed only if you are certain the resource is not in use.

A validation error is raised when:

  • a snapshot path (containing @) is supplied

  • the resource does not exist (ENOENT)

  • the new name is already taken (EEXIST)

  • either name is a protected path (EACCES)

  • the last component of the new name begins or ends with a space (EINVAL)

  • force is not set

Example:

{"current_name": "tank/documents", "new_name": "tank/archive", "force": true}
Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: data

data

Type: object

Rename parameters for renaming a ZFS resource.

 No Additional Properties

Current Name

Type: string

The existing name of the zfs resource to be renamed. Snapshot paths (containing '@') are not accepted; use zfs.resource.snapshot.rename instead.

Must be at least 1 characters long

New Name

Type: string

The new name for the zfs resource. It must stay within the same pool and may contain alphanumeric characters along with underscore, hyphen, colon and period.

Must be at least 1 characters long

No Unmount

Type: boolean Default: false

Do not remount filesystems during the rename. A filesystem whose mountpoint property is legacy or none is never unmounted regardless of this setting.

Force Unmount

Type: boolean Default: true

Force unmount any filesystem that has to be unmounted in the process.

Force

Type: boolean Default: false

Acknowledge that no check is made whether the resource is in use. Renaming an active resource may disrupt SMB shares, iSCSI targets, snapshot tasks, replication and other services. The rename is refused unless this is set.

Result

Type: null


Required roles: ZFS_RESOURCE_WRITE