Skip to main content
Hitachi Vantara Knowledge

Cloning files and directory trees

Two types of cloning are available:

  • File cloning
  • Directory tree cloning

The file clone feature allows for the quick copying of a file, which is space efficient when the source file and its copies ("clones") do not diverge significantly from each other over time. This feature is intended for situations in which long-lived and mostly unchanging copies of a large master file are required (for example, deploying many copies of an OS disk image for virtualized desktops). When a file clone is created, a snapshot of the master file is created, preserving an image of the source file at that point in time. The snapshot is only of the file, it is accessible only by the NAS server, and it is read-only. This snapshot allows the source file and clone to share common data blocks. If additional clones of the master file are created, new snapshots are created if necessary.

The maximum number of clones is limited by the availability of space in the file system. File cloning is most space efficient when related clones do not diverge significantly from each other. File clones are less space efficient when some clones are short-lived and others are long-lived, because the data blocks that were once shared between the source (master) file and all related clones are not freed until all related clones are deleted.

The directory tree cloning feature provides a way to quickly create space-efficient writeable copies of a directory tree. Space efficiency is achieved by creating clones of the source files in the destination tree. Space efficiency is reduced over time, as the source files and clones diverge. The source directory's structure is recreated in the destination directory, and all of the contained files are cloned. Security information from the source files and directories is applied to the destination.

NoteSome types of files in a directory tree are not cloneable. For example, files that are not regular (such as sockets, FIFOs, block special devices, and character devices) are not cloneable, and links such as hard links or cross volume links are not cloneable.
NoteIt is not possible to tree-clone a snapshot directory.

During a directory tree cloning operation, timing can have an effect on what is cloned, because the directory tree is not protected against modification during the clone operation. The cloned directory tree is not a point-in-time replica (like a snapshot), because the source tree is online and may be in use during the clone operation, so the directory tree (or the files in the tree) may be modified while the tree clone operation is in progress. When a directory tree is modified during a tree clone operation, none, some, or all of the modifications may be included in the clone. To ensure that the directory tree is cloned precisely as it is at the time the clone operation is initiated (a consistent copy), you must ensure that the directory tree is not modified until after the clone operation is complete.

Tree cloning uses the same mechanism as file cloning to clone individual files within the tree, so the same limitations apply, and a File Clone license is required to enable file or directory tree clones features.

NotesFile cloning is supported on all NAS Platform models.

After this feature has been used, certain downgrade restrictions will apply. If you downgrade to a release that does not support file clones, file systems on which file cloning has been used cannot be mounted. Contact customer support for more information about downgrade restrictions when using file clones.

Cloning symlinks in directory trees

When a symlink is encountered during the cloning of a directory tree, only the symlink itself is cloned, the target of the symlink is not cloned. The symlink is cloned without change, and the path contained by the symlink is not altered in any way.

When a symlink is cloned, if the symlink contains:

  1. A relative path to a directory or a file within the directory being cloned, the cloned symlink will function just as it did before being cloned. The path resolves correctly because the target of the symlink is also cloned by the tree clone operation.
  2. A relative path to a directory or a file outside the directory being cloned, then target path contained by the cloned symlink will resolve correctly only if a target of the same name exists in the same location relative to the cloned symlink location.
  3. An absolute path to a directory or a file (a global symlink), the path contained in the copied symlink should resolve correctly.

File clone commands

Currently NAS Manager does not include support for file cloning; to use this feature, you must use CLI commands. See the following CLI man pages for detailed information on configuring and using the file clone feature:

  • file-clone

    Provides a description of the file cloning mechanism.

  • file-clone-create

    Creates a new file, and makes its data stream a clone of the source file’s data stream.

  • file-clone-stat

    Displays information about a clone object; specifically, the handles of the snapshot file objects on which the clone object depends.

  • file-clone-report-block-sharing

    Reports on the amount of block sharing between a clone and each of its predecessor snapshot file objects.

  • file-clone-declone

    Removes the dependency of a cloned file from its snapshot object, converting the clone into a normal file.

  • file-clone-stat-snapshot-file

    Displays information about a snapshot file object based on the file handle or object number of the snapshot file object.

Tree clone commands

Currently NAS Manager does not include support for tree cloning; to use this feature, you must use CLI commands. See the following CLI man pages for detailed information on configuring and using the tree clone feature:

  • tree-clone-job-submit

    Submits a request to clone a directory tree.

  • tree-clone-job-status

    Gets the status of a tree cloning job specified by its job id.

  • tree-clone-job-list

    Lists the status of tree cloning jobs.

  • tree-clone-job-abort

    Aborts a tree cloning job specified by its job id.


  • Was this article helpful?