#### NOTE
The `disk` device type is supported for both containers and VMs.
It supports hotplugging for both containers and VMs.
Disk devices supply additional storage to instances.
For containers, they are essentially mount points inside the instance (either as a bind-mount of an existing file or directory on the host, or, if the source is a block device, a regular mount).
Virtual machines share host-side mounts or directories through `9p` or `virtiofs` (if available), or as VirtIO disks for block-based disks.
## Types of disk devices
You can create disk devices from different sources.
The value that you specify for the `source` option specifies the type of disk device that is added.
See [Configuration examples](#devices-disk-examples) for more detailed information on how to add each type of disk device.
Storage volume
: The most common type of disk device is a storage volume.
Specify the storage volume name as the [`source`](#device-disk-device-conf:source) to add a storage volume as a disk device. \`virtual-machine’ storage volumes (and their snapshots) can also be attached as disk devices.
Path on the host
: You can share a path on your host (either a file system or a block device) to your instance.
Specify the host path as the source to add it as a disk device.
Ceph RBD
: LXD can use Ceph to manage an internal file system for the instance, but if you have an existing, externally managed Ceph RBD that you would like to use for an instance, you can add it by specifying `ceph:/` as the source.
CephFS
: LXD can use Ceph to manage an internal file system for the instance, but if you have an existing, externally managed Ceph file system that you would like to use for an instance, you can add it by specifying `cephfs:/` as the source.
ISO file
: You can add an ISO file as a disk device for a virtual machine by specifying its file path as the source.
It is added as a ROM device inside the VM.
This source type is applicable only to VMs.
VM `cloud-init`
: You can generate a `cloud-init` configuration ISO from the [`cloud-init.vendor-data`](https://canonical.com/lxd/docs/default/reference/instance_options/index.html.md#instance-cloud-init:cloud-init.vendor-data) and [`cloud-init.user-data`](https://canonical.com/lxd/docs/default/reference/instance_options/index.html.md#instance-cloud-init:cloud-init.user-data) configuration keys and attach it to a virtual machine by specifying `cloud-init:config` as the source.
The `cloud-init` that is running inside the VM then detects the drive on boot and applies the configuration.
This source type is applicable only to VMs.
Adding such a configuration disk might be needed if the VM image that is used includes `cloud-init` but not the `lxd-agent`. This is the case for official Ubuntu images prior to `20.04`. On such images, the following steps enable the LXD agent and thus provide the ability to use `lxc exec` to access the VM:
```none
lxc init ubuntu-daily:18.04 --vm u1
lxc config device add u1 config disk source=cloud-init:config
lxc config set u1 cloud-init.user-data - << EOF
#cloud-config
#packages:
# - linux-image-virtual-hwe-16.04 # 16.04 GA kernel as a problem with vsock
runcmd:
- mount -t 9p config /mnt
- cd /mnt
- ./install.sh
- cd /
- umount /mnt
- systemctl start lxd-agent # XXX: causes a reboot
EOF
lxc start --console u1
```
Note that for `16.04`, the HWE kernel is required to work around a problem with `vsock` (see the commented out section in the above `cloud-config`).
## Initial volume configuration for instance root disk devices
Initial volume configuration allows setting specific configurations for the root disk devices of new instances.
These settings are prefixed with `initial.` and are only applied when the instance is created.
This method allows creating instances that have unique configurations, independent of the default storage pool settings.
For example, you can add an initial volume configuration for [`zfs.block_mode`](https://canonical.com/lxd/docs/default/reference/storage_zfs/index.html.md#storage-zfs-volume-conf:zfs.block_mode) to an existing profile, and this
will then take effect for each new instance you create using this profile:
```none
lxc profile device set initial.zfs.block_mode=true
```
You can also set an initial configuration directly when creating an instance. For example:
```none
lxc init --device ,initial.zfs.block_mode=true
```
Note that you cannot use initial volume configurations with custom volume options or to set the volume’s size (quota).
## Device options
`disk` devices have the following device options:
`boot.priority`
Boot priority for VMs
[](#device-disk-device-conf:boot.priority)
| **Key:** | `boot.priority` |
|----------------|-------------------|
| **Type:** | integer |
| **Condition:** | virtual machine |
| **Required:** | no |
A higher value indicates a higher boot precedence for the disk device.
This is useful for prioritizing boot sources like ISO-backed disks.
`ceph.cluster_name`
Cluster name of the Ceph cluster
[](#device-disk-device-conf:ceph.cluster_name)
| **Key:** | `ceph.cluster_name` |
|---------------|----------------------------|
| **Type:** | string |
| **Default:** | `ceph` |
| **Required:** | for Ceph or CephFS sources |
`ceph.user_name`
User name of the Ceph cluster
[](#device-disk-device-conf:ceph.user_name)
| **Key:** | `ceph.user_name` |
|---------------|----------------------------|
| **Type:** | string |
| **Default:** | `admin` |
| **Required:** | for Ceph or CephFS sources |
`initial.*`
Initial volume configuration
[](#device-disk-device-conf:initial.*)
| **Key:** | `initial.*` |
|---------------|---------------|
| **Type:** | n/a |
| **Required:** | no |
Initial volume configuration allows setting unique configurations independent of the default storage pool settings.
See [Initial volume configuration for instance root disk devices](#devices-disk-initial-config) for more information.
`io.bus`
Bus for the device
[](#device-disk-device-conf:io.bus)
| **Key:** | `io.bus` |
|----------------|-----------------|
| **Type:** | string |
| **Default:** | `virtio-scsi` |
| **Condition:** | virtual machine |
| **Required:** | no |
Possible values are `virtio-scsi`, `virtio-blk` or `nvme`.
`io.cache`
Caching mode for the device
[](#device-disk-device-conf:io.cache)
| **Key:** | `io.cache` |
|----------------|-----------------|
| **Type:** | string |
| **Default:** | `none` |
| **Condition:** | virtual machine |
| **Required:** | no |
Possible values are `none`, `writeback`, or `unsafe`.
`io.threads`
Thread pool for virtiofs file system shares
[](#device-disk-device-conf:io.threads)
| **Key:** | `io.threads` |
|----------------|-----------------|
| **Type:** | integer |
| **Default:** | `0` |
| **Condition:** | virtual machine |
| **Required:** | no |
This option controls the `virtiofsd` thread pool size, which can help improve I/O performance. Only applies to virtiofs file system shares.
In [`restricted`](https://canonical.com/lxd/docs/default/reference/projects/index.html.md#project-restricted:restricted) projects, it can only be used when [`restricted.virtual-machines.lowlevel`](https://canonical.com/lxd/docs/default/reference/projects/index.html.md#project-restricted:restricted.virtual-machines.lowlevel) is set to `allow`.
`limits.max`
I/O limit in byte/s or IOPS for both read and write
[](#device-disk-device-conf:limits.max)
| **Key:** | `limits.max` |
|---------------|----------------|
| **Type:** | string |
| **Required:** | no |
This option is the same as setting both [`limits.read`](#device-disk-device-conf:limits.read) and [`limits.write`](#device-disk-device-conf:limits.write).
You can specify a value in byte/s (various suffixes supported, see [Units for storage and network limits](https://canonical.com/lxd/docs/default/reference/instance_units/index.html.md#instances-limit-units)) or in IOPS (must be suffixed with `iops`).
See also storage-configure-io.
`limits.read`
Read I/O limit in byte/s or IOPS
[](#device-disk-device-conf:limits.read)
| **Key:** | `limits.read` |
|---------------|-----------------|
| **Type:** | string |
| **Required:** | no |
You can specify a value in byte/s (various suffixes supported, see [Units for storage and network limits](https://canonical.com/lxd/docs/default/reference/instance_units/index.html.md#instances-limit-units)) or in IOPS (must be suffixed with `iops`).
See also storage-configure-io.
`limits.write`
Write I/O limit in byte/s or IOPS
[](#device-disk-device-conf:limits.write)
| **Key:** | `limits.write` |
|---------------|------------------|
| **Type:** | string |
| **Required:** | no |
You can specify a value in byte/s (various suffixes supported, see [Units for storage and network limits](https://canonical.com/lxd/docs/default/reference/instance_units/index.html.md#instances-limit-units)) or in IOPS (must be suffixed with `iops`).
See also storage-configure-io.
`path`
Mount path
[](#device-disk-device-conf:path)
| **Key:** | `path` |
|----------------|-----------|
| **Type:** | string |
| **Condition:** | container |
| **Required:** | yes |
This option specifies the path inside the container where the disk will be mounted.
For containers, this option allows mounting filesystem disk devices, as well as specific paths and individual files within those devices.
For VMs, this option allows mounting filesystem disk devices and paths within them. Mounting individual files is not supported.
`pool`
Storage pool to which the disk device belongs
[](#device-disk-device-conf:pool)
| **Key:** | `pool` |
|----------------|--------------------------------|
| **Type:** | string |
| **Condition:** | storage volumes managed by LXD |
| **Required:** | no |
`propagation`
How a bind-mount is shared between the instance and the host
[](#device-disk-device-conf:propagation)
| **Key:** | `propagation` |
|---------------|-----------------|
| **Type:** | string |
| **Default:** | `private` |
| **Required:** | no |
Possible values are `private` (the default), `shared`, `slave`, `unbindable`, `rshared`, `rslave`, `runbindable`, `rprivate`.
See the Linux Kernel [shared subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) documentation for a full explanation.
`raw.mount.options`
File system specific mount options
[](#device-disk-device-conf:raw.mount.options)
| **Key:** | `raw.mount.options` |
|---------------|-----------------------|
| **Type:** | string |
| **Required:** | no |
`readonly`
Whether to make the mount read-only
[](#device-disk-device-conf:readonly)
| **Key:** | `readonly` |
|---------------|--------------|
| **Type:** | bool |
| **Default:** | `false` |
| **Required:** | no |
`recursive`
Whether to recursively mount the source path
[](#device-disk-device-conf:recursive)
| **Key:** | `recursive` |
|---------------|---------------|
| **Type:** | bool |
| **Default:** | `false` |
| **Required:** | no |
`required`
Whether to fail if the source doesn’t exist
[](#device-disk-device-conf:required)
| **Key:** | `required` |
|---------------|--------------|
| **Type:** | bool |
| **Default:** | `true` |
| **Required:** | no |
`shift`
Whether to set up a UID/GID shifting overlay
[](#device-disk-device-conf:shift)
| **Key:** | `shift` |
|----------------|-----------|
| **Type:** | bool |
| **Default:** | `false` |
| **Condition:** | container |
| **Required:** | no |
If enabled, this option sets up a shifting overlay to translate the source UID/GID to match the container instance.
`size`
Disk size
[](#device-disk-device-conf:size)
| **Key:** | `size` |
|---------------|----------|
| **Type:** | string |
| **Required:** | no |
This option is supported only for the rootfs (`/`).
Specify a value in bytes (various suffixes supported, see [Units for storage and network limits](https://canonical.com/lxd/docs/default/reference/instance_units/index.html.md#instances-limit-units)).
`size.state`
Size of the file-system volume used for saving runtime state
[](#device-disk-device-conf:size.state)
| **Key:** | `size.state` |
|----------------|-----------------|
| **Type:** | string |
| **Condition:** | virtual machine |
| **Required:** | no |
This option is similar to [`size`](#device-disk-device-conf:size), but applies to the file-system volume used for saving the runtime state in VMs.
`source`
Source of a file system or block device
[](#device-disk-device-conf:source)
| **Key:** | `source` |
|---------------|------------|
| **Type:** | string |
| **Required:** | yes |
See [Types of disk devices](#devices-disk-types) for details.
`source.snapshot`
`source` snapshot name
[](#device-disk-device-conf:source.snapshot)
| **Key:** | `source.snapshot` |
|---------------|---------------------|
| **Type:** | string |
| **Required:** | no |
Snapshot of the volume given by `source`.
`source.type`
Type of the backing storage volume
[](#device-disk-device-conf:source.type)
| **Key:** | `source.type` |
|---------------|-----------------|
| **Type:** | string |
| **Default:** | `custom` |
| **Required:** | no |
Possible values are `custom` (the default) or `virtual-machine`. This
key is only valid when `source` is the name of a storage volume.
## Configuration examples
How to add a disk device depends on its [type](#devices-disk-types).
Storage volume
: To add a storage volume, specify its name as the `source` of the device:
```none
lxc config device add disk pool= source= [path=]
```
The path is required for file system volumes, but not for block volumes.
Alternatively, you can use the [`lxc storage volume attach`](https://canonical.com/lxd/docs/default/reference/manpages/lxc/storage/volume/attach/index.html.md#lxc-storage-volume-attach-md) command to [Attach the volume to an instance](https://canonical.com/lxd/docs/default/howto/storage_volumes/index.html.md#storage-attach-volume).
Both commands use the same mechanism to add a storage volume as a disk device.
Path on the host
: To add a host device, specify the host path as the `source`:
```none
lxc config device add disk source= [path=]
```
The path is required for file systems, but not for block devices.
Ceph RBD
: To add an existing Ceph RBD volume, specify its pool and volume name:
```none
lxc config device add disk source=ceph:/ ceph.user_name= ceph.cluster_name= [path=]
```
The path is required for file systems, but not for block devices.
CephFS
: To add an existing CephFS file system, specify its name and path:
```none
lxc config device add disk source=cephfs:/ ceph.user_name= ceph.cluster_name= path=
```
ISO file
: To add an ISO file, specify its file path as the `source`:
```none
lxc config device add disk source=
```
VM `cloud-init`
: To add `cloud-init` configuration, specify `cloud-init:config` as the source:
```none
lxc config device add disk source=cloud-init:config
```
See [Configure devices](https://canonical.com/lxd/docs/default/howto/instances_configure/index.html.md#instances-configure-devices) for more information.