Skip to main content
ONTAP commands
A newer release of this product is available.

volume file clone create

Contributors
Suggest changes
PDFs

Create file or LUN full or sub file clone

Availability: This command is available to cluster and Vserver administrators at the admin privilege level.

Description

The volume file clone create command creates a clone of a file, a LUN or an NVMe namespace. You can optionally specify the following parameters for the clone file creation process:

  • Vserver in which the volume resides

  • Name of the parent snapshot

  • The range of blocks to be cloned

  • The option to avoid space reservations for the new file or LUN clone

  • The option to assign a QoS policy group to the new file or LUN clone

  • The option to assign a caching policy to the new file or LUN clone

  • The option to mark the new file, LUN or NVMe namespace clone created for auto deletion

  • The option to overwrite an existing file, LUN or NVMe namespace clone

File, LUN or NVMe namespace clones create a duplicate copy of another file, LUN or NVMe namespace, but don't require copying the data itself. This allows the clone operation to occur in constant time, taking the same amount of time to complete no matter the size of the file being cloned. This also means that clones require only a small amount of additional storage space because the clone shares the data with the source file, LUN or NVMe namespace.

Parameters

-vserver <vserver name> - Vserver Name

This specifies the Vserver in which the parent volume resides. If only one data Vserver exists, you do not need to specify this parameter.

[-volume <volume name>] - Volume

This specifies the name of volume in which a file, LUN or NVMe namespace is going to be cloned.

-source-path <text> - Source Path

This specifies the path to the file, LUN or NVMe namespace to be cloned relative to the specified volume.

-destination-path <text> - Destination Path

This specifies the path for the newly-created cloned file, LUN or NVMe namespace relative to the specified volume. If the file, LUN or NVMe namespace clone to be created is a whole file, LUN or NVMe namespace, the destination file, LUN or NVMe namespace must not exist. If the range parameter is specified, the destination file or LUN must exist. If the snapshot-name parameter is specified, this option is mandatory.

[-s, -snapshot-name <snapshot name>] - Source Snapshot

The name of the Snapshot copy to use as the source for the clone operation. If this value is not specified, the active filesystem will be used instead.

{ [-r, -range [source start block>:<destination start block>:<block length],…​] - Block Range

This specifies the block range to be cloned. If the range is not specified, the entire file, LUN, or NVMe namespace is cloned. The block range should be specified in the format s:d:n where s is the source start block number, d is the destination start block number, and n is the length in blocks to be cloned. The range of n should be from 1 to 32768 or 1 to 16777216 in case of clone from Active File System or Snapshot copy respectively. If this parameter is used in the path provided by the destination-path , the parameter must refer to a file, LUN, or NVMe namespace which already exists. If either the source or destination is a LUN or NVMe namespace, then the block size is measured in LBA blocks. The source object block size and destination block size must be equal. If neither the source nor destination is a LUN or NVMe namespace, then the block size will be 4KB. If 512-byte sectors are used, the source and destination offsets must have the same offset within 4KB blocks. + This option is most likely to be used by external automated systems in managing virtual disk configurations and not by human administrators.

| [-o, -no-reserve <true>] - Do not reserve clone }

If this option is used, the clone file or LUN will not be guaranteed space in the underlying aggregate. While this out-of-space condition persists, writes to the clone file or LUN would fail. This option may be useful if few writes to the clone are expected to be needed, or to allow a file or LUN clone to be created under space-constrained conditions for recovery purposes. If this option is not specified the clone will inherit the space reservation properties from the source.

[-i, -ignore-streams <true>] - Ignore streams

This parameter specifies whether streams should be ignored during cloning of files, LUNs, or NVMe namespaces. If you set this parameter to false, the streams are ignored; otherwise, they are included in the clones. The default value is false.

[-k, -ignore-locks <true>] - Ignore locks

This parameter specifies whether byte-range locks and shared-mode locks on files, LUNs or NVMe namespaces should be ignored during cloning. If you set this parameter to true, the locks are ignored; otherwise, clone operation fails if locks are present on files, LUNs or NVMe namespaces. The default value is false.

[-d, -overwrite-destination <true>] - Overwrite Destination

Specify this parameter to overwrite the destination file, LUN, or NVMe namespace, if it exists. The default is not to overwrite the destination file. The command will fail if the destination file exists.

{ [-qos-policy-group <text>] - QoS Policy Group Name

This optionally specifies which QoS policy group to apply to the file or LUN. This policy group defines measurable service level objectives (SLOs) that apply to the storage objects with which the policy group is associated. If you do not assign a policy group to a file or LUN, the system will not monitor and control the traffic to it. You cannot associate a file to a QoS policy group if a LUN was created from the file.

| [-qos-adaptive-policy-group <text>] - QoS Adaptive Policy Group Name }

This optionally specifies which QoS adaptive policy group to apply to the file or LUN. This policy group defines measurable service level objectives (SLOs) and Service Level Agreements (SLAs) that adjust based on the file or LUN's allocated space or used space.

[-caching-policy <text>] - Caching Policy Name

This optionally specifies the caching policy to apply to the file. A caching policy defines how the system caches this volume's data in Flash Cache modules. If a caching policy is not assigned to this file, the system uses the caching policy that is assigned to the containing volume. If a caching policy is not assigned to the containing volume, the system uses the caching policy that is assigned to the containing Vserver. If a caching policy is not assigned to the containing Vserver, the system uses the default cluster-wide policy. The available caching policies are:

  • none - Does not cache any user data or metadata blocks.

  • auto - Read caches all metadata and randomly read user data blocks, and write caches all randomly overwritten user data blocks.

  • meta - Read caches only metadata blocks.

  • random_read - Read caches all metadata and randomly read user data blocks.

  • random_read_write - Read caches all metadata, randomly read and randomly written user data blocks.

  • all_read - Read caches all metadata, randomly read and sequentially read user data blocks.

  • all_read_random_write - Read caches all metadata, randomly read, sequentially read, and randomly written user data.

  • all - Read caches all data blocks read and written. It does not do any write caching.

Default caching-policy is auto.

[-autodelete {true|false}] - Mark Clone for Autodeletion

This parameter marks the file, LUN or NVMe namespace clones created for auto deletion. When set to true, the file, LUN or NVMe namespace clones get automatically deleted when the volume runs out of space. The default value is false.

[-bypass-throttle {true|false}] - Bypass Throttle Checks (privilege: advanced)

This parameter specifies whether clone throttle checks should be skipped during clone creation. When set to true, clones are created without enforcing any clone throttle checks. The default value is false.

[-is-backup {true|false}] - Is a Clone for Backup

This parameter is used to mark the destination file as a backup clone, where divergence is expected on the source file and no divergence is expected on the destination file. It is applicable only for full-file clones created from Active File System volumes. The default value is false .

[-destination-volume <volume name>] - Destination Volume

This specifies the name of the volume where the destination file resides. This can be different from volume , whereas parameter volume specifies the volume on which source file resides. This is an optional argument that applies only to a MetaWAFL volume where the source and destination volumes for the clone operation can be different. If this parameter is not given, the destination file will be created in the volume where source_file resides.

Examples

The following command creates a FlexClone file of the file named myfile contained in a volume named vol . The file myfile is located in the root directory of that volume. The cloned file myfile_copy resides in the root directory same volume.

cluster1::> volume file clone create -volume vol -source-path /myfile -destination-path /myfile_copy

The following command optionally associates the FlexClone file named myfile_copy with the fast QoS policy group and the caching policy named random-read.

cluster1::> volume file clone create -volume vol -source-path /myfile -destination-path /myfile_copy -qos-policy-group fast -caching-policy random-read