Disk Image Directories

Introduction
----------

By default, Cloudmin will create KVM or Xen virtual disk images in the directory or LVM volume group selected on the Host System page for the virtual system's host. All additional virtual disks will be created in the same location. Virtualization types that use a directory on the host's filesystem will always be placed in a sub-directory under the path specified for the host system.

Cloudmin versions 6.0 and later give you more flexibility in placing disk images and virtual filesystems, using the new **Disk Image Directories** page. This lets the master administrator define additional paths on host systems that can be selected when a virtual system is created, moved or cloned, instead of using the host system default. For example, this could be used to control if a system is created on storage local to the host, or a directory mounted from a common file server, or faster local disks.

Creating A Shared Disk Image Directory
--------------------------------

Before adding a directory to Cloudmin, it should first be created on all the host systems that you intend to use it on. If it will only exist locally, it can either be simply created with the `mkdir` command, or mounted from an additional local disk, RAID device or LVM logical volume.

If you want to use NFS to share a directory between hosts, it must first be exported from a file server. This could be a dedicated device such as one sold by NetApp, or a Linux system with a suitably large and fast local disk or RAID array. In the latter case, you can use Webmin to export a directory as follows :

1. SSH into the system as root, and create the directory with a command like `mkdir /shared`
2. Login to Webmin (or Cloudmin or Virtualmin) on the system, and go **Networking** -> **NFS Exports**.
3. Click the **Add a new export** button, and enter `/shared` into the `Directory to export` field.
4. In the **Export to..* field, enter the IPs of the host systems that will share this directory.
5. Click the **Create** button, then click **Apply Changes**.

One a directory is shared, it can be mounted on each of your host systems as follows :

1. Select the host system from the left menu in Cloudmin, and click on **Link to Webmin** or **Open Webmin**
2. In Webmin on the host, go to **System** -> **Disk and Network Filesystems**
3. Select **Network Filesystem** from the menu, and click the **Add mount** button.
4. In the **Mounted As** field, enter the directory you are sharing, like `/shared`
5. In the **NFS hostname** field, enter the hostname or IP address of the NFS server setup above.
6. In the **NFS directory** field, enter the path exported by the NFS server - this will typically be the same as in step 4.
7. Click the **Create** button.

Adding A Disk Image Directory
--------------------------------

Once the directory exists on all the hosts you want to use it on, it can be added to Cloudmin as follows :

1. Login as the master administrator, and go to **Host Systems** -> **Disk Image Directories**.
2. Click the **Add a new disk image directory** link.
3. In the **Directory path on host** field, select **Directory on host** and enter the path (like `/shared`) into the adjacent text box.
4. Fill in the **Description** field with a short description of the directory.
5. To limit the hosts on which the directory can be used, select them in the **For use on host systems** field.
6. By default virtual systems of any type will be able to use the directory, but you can restrict it to a subset of types by selecting them in the **For use by virtualization types** field.
7. If you have created any system owner plans, access to the directory can be limit to owners on those plans using the **For use by system owners** field. Alternately, you can restrict access to only the `root` (master administrator) user.
8. Finally, click the **Create** button. The directory will now be selectable when creating new virtual systems.

Selecting A Directory At Creation Time
-------------------------------

Once you have created a disk directory, you can select it when creating a virtual system of a supported type using the **Disk image directory** field in the **Resource limit options** section of the creation form. For Xen and KVM systems, all disk image and config files will be created in that directory instead of the host's default directory or volume group. For OpenVZ and LXC systems, the directory that contains the filesystem will be created below the selected path. However, other configuration files will remain in their regular directories.

If creating a system using the Cloudmin command-line API, you can use the `--disk-directory` flag follow by a path to specify the path. When creating via the remote API, use the `disk-directory` parameter followed by the path. In all cases, if creating a system while logged in as a system owner you can only select directories that have been made available to the owner's plan.

Changing The Directory For New Disks
-------------------------------

If you add an additional disk to a KVM or Xen system after creation, it will by default be created in the directory selected at creation time. However, this can be changed as follows :

1. Select the virtual system from the left menu.
2. Open the **Resources** category and click on **Manage Disks**.
3. In the **Default disk image directory** section, select an alternate path from the **New directory** menu, and click **Save**.

The default can also be changed using the `modify-system` API command, with the `--disk-directory` flag.

Moving And Cloning Virtual Systems
-----------------------------

By default when a virtual system with a non-standard disk directory is moved, Cloudmin will attempt to keep the same directory on the destination system as was used on the source. If the directory is not available on the destination, the move or clone operation will fail.

Both the forms for moving and cloning a system have a field for selecting a new disk image directory to use, similar to the field on the system creation form. Also, the `clone-system` and `move-system` API commands accept the `--disk-directory` flag followed by a directory to use. The `--no-disk-directory` flag can be used instead to revert to the default directory on the destination host.

Directory Permissions
-----------------

As mentioned above, the master administrator (`root`) can limit access to disk directories by system owners based on their plan. For example, a directory that is mounted from faster and more expensive storage (like RAID or SSD) might be reserved for only a subset of users.

You can also control if system owners are allowed to use the default disk directory or logical volume on host systems, by editing the special **Host system default** path on the **Disk Image Directories** page. This entry cannot be renamed or deleted, but its permissions can be changed to restrict access to some system owners, or none at all.