zfs.resource.rename
===================

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

To rename snapshots, use :doc:`zfs.resource.snapshot.rename <api_methods_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:

.. code:: json

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

.. raw:: html

    <div id="json-schema">
    <span class="badge badge-dark value-type">Type: object</span><br/>
    <div class="accordion" id="accordionCall_parameters">
    <div class="card">
    <div class="card-header" id="headingCall_parameters">
    <h2 class="mb-0">
    <button aria-controls="Call_parameters" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters" data-toggle="collapse" onclick="setAnchor('#Call_parameters')" type="button"><span class="property-name">Call parameters</span></button>
    </h2>
    </div>
    <div aria-labelledby="headingCall_parameters" class="collapse property-definition-div" data-parent="#accordionCall_parameters" id="Call_parameters">
    <div class="card-body pl-5">
    <span class="badge badge-dark value-type">Type: array</span><br/>
    <span class="badge badge-info no-additional">No Additional Items</span><h4>Tuple Validation</h4>
    <h5>Parameter 1: data</h5>
    <div class="card">
    <div class="card-body items-definition" id="Call_parameters_items_i0">
    <h4>data</h4><span class="badge badge-dark value-type">Type: object</span><br/>
    <span class="description"><p>Rename parameters for renaming a ZFS resource.</p>
    </span> <span class="badge badge-info no-additional">No Additional Properties</span>
    <div class="accordion" id="accordionCall_parameters_items_i0_current_name">
    <div class="card">
    <div class="card-header" id="headingCall_parameters_items_i0_current_name">
    <h2 class="mb-0">
    <button aria-controls="Call_parameters_items_i0_current_name" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i0_current_name" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i0_current_name')" type="button"><span class="property-name">current_name</span> <span class="badge badge-warning required-property">Required</span></button>
    </h2>
    </div>
    <div aria-labelledby="headingCall_parameters_items_i0_current_name" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i0_current_name" id="Call_parameters_items_i0_current_name">
    <div class="card-body pl-5">
    <h4>Current Name</h4><span class="badge badge-dark value-type">Type: string</span><br/>
    <span class="description"><p>The existing name of the zfs resource to be renamed. Snapshot paths (containing '@') are not accepted; use <code>zfs.resource.snapshot.rename</code> instead.</p>
    </span>
    <p><span class="badge badge-light restriction min-length-restriction" id="Call_parameters_items_i0_current_name_minLength">Must be at least <code>1</code> characters long</span></p>
    </div>
    </div>
    </div>
    </div>
    <div class="accordion" id="accordionCall_parameters_items_i0_new_name">
    <div class="card">
    <div class="card-header" id="headingCall_parameters_items_i0_new_name">
    <h2 class="mb-0">
    <button aria-controls="Call_parameters_items_i0_new_name" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i0_new_name" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i0_new_name')" type="button"><span class="property-name">new_name</span> <span class="badge badge-warning required-property">Required</span></button>
    </h2>
    </div>
    <div aria-labelledby="headingCall_parameters_items_i0_new_name" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i0_new_name" id="Call_parameters_items_i0_new_name">
    <div class="card-body pl-5">
    <h4>New Name</h4><span class="badge badge-dark value-type">Type: string</span><br/>
    <span class="description"><p>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.</p>
    </span>
    <p><span class="badge badge-light restriction min-length-restriction" id="Call_parameters_items_i0_new_name_minLength">Must be at least <code>1</code> characters long</span></p>
    </div>
    </div>
    </div>
    </div>
    <div class="accordion" id="accordionCall_parameters_items_i0_no_unmount">
    <div class="card">
    <div class="card-header" id="headingCall_parameters_items_i0_no_unmount">
    <h2 class="mb-0">
    <button aria-controls="Call_parameters_items_i0_no_unmount" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i0_no_unmount" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i0_no_unmount')" type="button"><span class="property-name">no_unmount</span></button>
    </h2>
    </div>
    <div aria-labelledby="headingCall_parameters_items_i0_no_unmount" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i0_no_unmount" id="Call_parameters_items_i0_no_unmount">
    <div class="card-body pl-5">
    <h4>No Unmount</h4><span class="badge badge-dark value-type">Type: boolean</span> <span class="badge badge-success default-value">Default: false</span><br/>
    <span class="description"><p>Do not remount filesystems during the rename. A filesystem whose mountpoint property is legacy or none is never unmounted regardless of this setting.</p>
    </span>
    </div>
    </div>
    </div>
    </div>
    <div class="accordion" id="accordionCall_parameters_items_i0_force_unmount">
    <div class="card">
    <div class="card-header" id="headingCall_parameters_items_i0_force_unmount">
    <h2 class="mb-0">
    <button aria-controls="Call_parameters_items_i0_force_unmount" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i0_force_unmount" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i0_force_unmount')" type="button"><span class="property-name">force_unmount</span></button>
    </h2>
    </div>
    <div aria-labelledby="headingCall_parameters_items_i0_force_unmount" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i0_force_unmount" id="Call_parameters_items_i0_force_unmount">
    <div class="card-body pl-5">
    <h4>Force Unmount</h4><span class="badge badge-dark value-type">Type: boolean</span> <span class="badge badge-success default-value">Default: true</span><br/>
    <span class="description"><p>Force unmount any filesystem that has to be unmounted in the process.</p>
    </span>
    </div>
    </div>
    </div>
    </div>
    <div class="accordion" id="accordionCall_parameters_items_i0_force">
    <div class="card">
    <div class="card-header" id="headingCall_parameters_items_i0_force">
    <h2 class="mb-0">
    <button aria-controls="Call_parameters_items_i0_force" aria-expanded="" class="btn btn-link property-name-button" data-target="#Call_parameters_items_i0_force" data-toggle="collapse" onclick="setAnchor('#Call_parameters_items_i0_force')" type="button"><span class="property-name">force</span></button>
    </h2>
    </div>
    <div aria-labelledby="headingCall_parameters_items_i0_force" class="collapse property-definition-div" data-parent="#accordionCall_parameters_items_i0_force" id="Call_parameters_items_i0_force">
    <div class="card-body pl-5">
    <h4>Force</h4><span class="badge badge-dark value-type">Type: boolean</span> <span class="badge badge-success default-value">Default: false</span><br/>
    <span class="description"><p>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.</p>
    </span>
    </div>
    </div>
    </div>
    </div>
    </div>
    </div>
    </div>
    </div>
    </div>
    </div>
    <div class="accordion" id="accordionReturn_value">
    <div class="card">
    <div class="card-header" id="headingReturn_value">
    <h2 class="mb-0">
    <button aria-controls="Return_value" aria-expanded="" class="btn btn-link property-name-button" data-target="#Return_value" data-toggle="collapse" onclick="setAnchor('#Return_value')" type="button"><span class="property-name">Return value</span></button>
    </h2>
    </div>
    <div aria-labelledby="headingReturn_value" class="collapse property-definition-div" data-parent="#accordionReturn_value" id="Return_value">
    <div class="card-body pl-5">
    <h4>Result</h4><span class="badge badge-dark value-type">Type: null</span><br/>
    </div>
    </div>
    </div>
    </div>
    </div><br><br>

*Required roles:* ZFS_RESOURCE_WRITE

