|
APIs in Category: clone |
API version 1.9 |
clone-clear |
The cloning feature is based on WAFL block sharing and provides fast and almost 100% space efficient file and sub-file cloning, which can also be applied for LUN and sub-LUN cloning. |
| clone-clear | [top] |
Clears information of a failed clone operation. If not successful, the error code will be returned as API error.
Input Name Range Type Description clone-id clone-id-info
ID information of the clone operation.
Errno Description EDENSE_CLONE_NO_OP EDENSE_CLONE_RUNNING_OP EDENSE_CLONE_NOT_FAILED EDENSE_SHUTDOWN EDENSE_FAILOVER EDENSE_CLONE_INVALID_ID EDENSE_CLONE_INVALID_UUID EDENSE_CLONE_VOL_REVERTING EDENSE_VOL_NONEXIST EDENSE_CLONE_DEL_INFO
| clone-list-status | [top] |
Gets the information of a clone operations identified by clone-id. If clone-id is not specified, then it will get the status of all running and failed clone operation on the filer. It will get the status as 'running', 'failed' or 'completed'. User may see some other transient status for the clone operation, but any other status should be considered for polling clone-list-status again. User should keep polling clone-list-status till status returned is 'failed' or 'completed'. If status is 'completed', the clone operation has been completed successfully. If status is 'failed', then user is responsible for doing clone-clear to clean the status of the clone information. When a clone operation is aborted using clone-stop, it may take some time to stop the clone operation. User should poll clone-list-status till status returned is 'completed'. When status returned is 'completed' after clone-stop, the clone operation has been stopped successfully.
Input Name Range Type Description clone-id clone-id-info
optional
ID information of the clone operation. If not specified, it will get the status of all running and failed clone operations on the filer. Output Name Range Type Description status ops-info[]
optional
List of information of running and failed clone operations on the filer.
Errno Description EDENSE_FAILOVER EDENSE_SHUTDOWN EDENSE_CLONE_INVALID_ID EDENSE_CLONE_INVALID_UUID EDENSE_CLONE_VOL_REVERTING EDENSE_VOL_NONEXIST
| clone-start | [top] |
Starts a file/LUN or sub-file/sub-LUN clone operation asynchronously. If clone operation starts successfully, a unique clone-id is returned. User is supposed to poll clone-list-status specifying clone-id to get the status of the clone operation. When clone-list-status returns status as completed, user can consider that the clone operation has been completed successfully. If user gets status as failed, user is responsible for doing clone-clear which will clean the status of the clone operation.
Input Name Range Type Description block-ranges block-range[]
optional
List of block ranges for sub-file/sub-LUN cloning. For sub-LUN cloning the block range specified will be considered as SCSI LBA range. For one set of source and destination block range followings are error conditions: 1) If source and destination block ranges overlap. 2) Source or destination block range is out of file. If multiple set of block ranges are specified in one clone operation, then user is responsible for different block ranges do not overlap with each other. Each set of block range will be processed one by one for cloning. So, user may get random data if different set of block ranges overlap with each other. change-log boolean
optional
If this option is "true", fingerprints of data blocks of the destination file/block ranges created will be change logged to the change log file if A-SIS is enabled on the volume. With change logging clone operation will be slow, as to get fingerprints all the data blocks will be read. Without change logging clone operation deals with only indirect blocks without reading data blocks. Without change logging, fingerprints of the clone blocks are not recorded. The clone blocks are shared with the source blocks, but as later the source blocks are modified, corresponding clone blocks will no longer be shared. If change logging option is not used, clone blocks, which could be involved in sharing with rest of the file system, can not be shared in next sis operation. The only option, in case user had not used change logging while creating clone, will be to start sis from beginning using "sis start -s" to gather fingerprints of clone blocks. destination-path string
optional
Full path of the Destination file or LUN in /vol/<volume-name>/<file-path> format. Destination path should be in same flexible volume where source file is located. For sub-file/sub-LUN clone operation within same file/LUN, destination path is not required. no-snap boolean
optional
If no-snap is false or unspecified, then a temporary snapshot will be taken and source file locked in snapshot will be considered for cloning. So that the clone operation does not get affected by writes to the source file in parallel to the clone operation. User will get atomic point in time copy of the source. Irrespective of clone operation completes successfully or unsuccessfully, any temporary snapshot taken for cloning will be deleted automatically. If no-snap is "true", then the source file in AFS will be used for cloning. In this case user may get random data in clone if source file is modified while clone operation is in progress. This option should only be used when user is assured that the source file will remain consistent during the clone operation. Destination file is not protected against any modification while clone operation is in progress. User should use the destination file or destination block ranges after clone operation is finished. source-path string
Full path of the source file or LUN in /vol/<volume-name>/<file-path> format. Output Name Range Type Description clone-id clone-id-info
Unique ID information for the clone operation returned if clone operation starts successfully. If clone operation does not start, the specific error code will be returned as API error.
Errno Description EDENSE_CLONE_NOT_LICENSED EDENSE_CLONE_LICENSE_EXPIRED EDENSE_REVERTING EDENSE_IRON_RUNNING EDENSE_NLCSR_INPROG EDENSE_VOL_NONEXIST EDENSE_VOL_OFFLINE EDENSE_VOL_NOTSUP EDENSE_VOL_RDONLY EDENSE_VOL_TRANSITING EDENSE_VOL_RESTRICTED EDENSE_SNAPSHOT_CREATE EDENSE_SNAPSHOT_NONEXIST EDENSE_SHUTDOWN EDENSE_FAILOVER EDENSE_UNSUPPORTED_VOLTYPE EDENSE_CLONE_SFSR_INPROG EDENSE_CLONE_FILE_FOLD_INPROG EDENSE_CLONE_SFILE_NONEXIST EDENSE_CLONE_CFILE_NONEXIST EDENSE_CLONE_NO_SLOT EDENSE_CLONE_DIFF_VOLUME EDENSE_CLONE_SAME_FILE EDENSE_CLONE_VOL_REVERTING EDENSE_CLONE_SNAPNAME EDENSE_CLONE_SNAPPATH EDENSE_CLONE_SNAP_FH EDENSE_CLONE_SNAP_ATTR EDENSE_CLONE_SFILE_ATTR EDENSE_CLONE_CFILE_ATTR EDENSE_CLONE_EXIST EDENSE_CLONE_METAFILE EDENSE_CLONE_METAFILE_FH EDENSE_CLONE_METAFILE_WRITE EDENSE_CLONE_LARGE_INFO EDENSE_CLONE_METAFILE_ATTR EDENSE_CLONE_METAFILE_READ EDENSE_CLONE_FH EDENSE_CLONE_DIR_FH EDENSE_CLONE_CREATE EDENSE_CLONE_SETATTR EDENSE_CLONE_SOURCE_FH EDENSE_CLONE_NOT_SUPP EDENSE_CLONE_PROC EDENSE_CLONE_MAX_PROC EDENSE_CLONE_TYPE_SUPP EDENSE_CLONE_SRC_OUTOF_RANGE EDENSE_CLONE_DEST_OUTOF_RANGE EDENSE_CLONE_OVERLAP_RANGE EDENSE_CLONE_INVALID_RANGE EDENSE_CLONE_PENDING_SNAP EDENSE_CLONE_SPLIT_MAP EDENSE_CLONE_INVALID_SOURCE EDENSE_CLONE_INVALID_CLONE EDENSE_CLONE_INVALID_DIR EDENSE_CLONE_NOT_QTREE_ROOT EDENSE_CLONE_SMALL_DATA EDENSE_VDISK_INVALID_NAME EDENSE_VDISK_NOT_IN_QTREE_ROOT EDENSE_VDISK_VOL_SPARSE_WO_SCSI EDENSE_VDISK_INTERNAL_ERROR EDENSE_VDISK_INVALID_FH EDENSE_VDISK_NO_SUCH_VDISK EDENSE_VDISK_LBA_OFFSET_MISALIGNED EDENSE_VDISK_SRC_INVALID_BLOCK_RANGE EDENSE_VDISK_DST_INVALID_BLOCK_RANGE EDENSE_VDISK_SRC_LUN_CLONE EDENSE_CLONE_WORM_VOL EDENSE_CLONE_SPLITTING EDENSE_STALE_DINODE EDENSE_STALE_RINODE EDENSE_STALE_CLONE_DIR_INODE EDENSE_CLONE_CHANGELOG_OFF EDENSE_NON_SUPPORTED_PLATFORM
| clone-stop | [top] |
Stops a running clone operation. If not successful, the error code will be returned as API error.
Input Name Range Type Description clone-id clone-id-info
ID information of the clone operation.
Errno Description EDENSE_FAILOVER EDENSE_CLONE_NO_OP EDENSE_CLONE_NOT_RUNNING EDENSE_SHUTDOWN EDENSE_CLONE_INVALID_ID EDENSE_CLONE_INVALID_UUID EDENSE_CLONE_VOL_REVERTING EDENSE_VOL_NONEXIST EDENSE_CLONE_METAFILE_WRITE
| Element definition: block-range | [top] |
Structure containing source and destination block range for sub-file/sub-LUN cloning.
Name Range Type Description block-count integer
Number of blocks to be cloned. Range: [0..2^32-1]. destination-block-number integer
Starting file block number of destination block range. Range: [0..2^32-1]. source-block-number integer
Starting file block number of source block range. Range: [0..2^32-1].
| Element definition: clone-id-info | [top] |
Structure containing clone ID information.
Name Range Type Description clone-op-id integer
ID of the clone operation. Range: [1..2^64-1]. volume-uuid string
uuid of the volume.
| Element definition: ops-info | [top] |
Structure containing information of a clone operation.
Name Range Type Description block-ranges block-range[]
optional
List of block ranges specified for sub-file/sub-LUN cloning. In case of complete file cloning there will be no output corresponding to this. blocks-copied integer
optional
Number of blocks that have been copied so far for running clone operation. The cloning operation shares destination blocks with source block. But if source block has already reached maximum number of sharing supported by WAFL, then block is copied for destination. It is recommended that if blocks are being copied, then user should change the source for next clone operation. Range: [0..2^64-1]. clone-id clone-id-info
optional
Unique ID information of the clone operation. clone-state string
State of the clone operation. It could be 'running', 'failed' or 'completed'. For 'completed' state there will be no other field in ops-info output. clone-type string
optional
Type of clone. Possible types are 'file', 'sub_file', 'lun' and 'sub_lun'. destination-file string
optional
Destination file path. For sub-file/sub-LUN cloning within the same file/LUN, source-file and destination file will be same. error integer
optional
Error code corresponding to reason of failure. If error code is EDENSE_SHUTDOWN or EDENSE_FAILOVER, the clone operation will be restarted automatically after giveback/takeover or next reboot. If user has not aborted the clone operation using clone-stop, then for any other error code user should do clone-clear. percent-done integer
optional
Percentage cloning completed for running clone operation. Range: [0..100]. reason string
optional
Reason of failure if clone operation could not complete successfully. source-file string
optional
Source file path. total-blocks integer
optional
Total number of blocks to be cloned for running clone operation. Range: [0..2^64-1].
| Element definition: block-range | [top] |
Structure containing source and destination block range for sub-file/sub-LUN cloning.
Name Range Type Description block-count integer
Number of blocks to be cloned. Range: [0..2^32-1]. destination-block-number integer
Starting file block number of destination block range. Range: [0..2^32-1]. source-block-number integer
Starting file block number of source block range. Range: [0..2^32-1].
| Element definition: clone-id-info | [top] |
Structure containing clone ID information.
Name Range Type Description clone-op-id integer
ID of the clone operation. Range: [1..2^64-1]. volume-uuid string
uuid of the volume.