Type: disk
▶ Watch on YouTube (opens in a new tab)
Note
Thediskdevice 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 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 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:<pool_name>/<volume_name> 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:<fs_name>/<path> 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 and 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:
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 u1Note 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 to an existing profile, and this will then take effect for each new instance you create using this profile:
lxc profile device set <profile\_name> <device\_name> initial.zfs.block\_mode=trueYou can also set an initial configuration directly when creating an instance. For example:
lxc init <image> <instance\_name> --device <device\_name>,initial.zfs.block\_mode=trueNote 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
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
Key: ceph.cluster_name
Type: string
Default: ceph
Required: for Ceph or CephFS sources
ceph.user_name
User name of the Ceph cluster
Key: ceph.user_name
Type: string
Default: admin
Required: for Ceph or CephFS sources
initial.*
Initial volume configuration
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 for more information.
io.bus
Bus for the device
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
Key: io.cache
Type: string
Default: none
Condition: virtual machine
Required: no
Possible values are none, writeback, or unsafe.
limits.max
I/O limit in byte/s or IOPS for both read and write
Key: limits.max
Type: string
Required: no
This option is the same as setting both limits.read and limits.write.
You can specify a value in byte/s (various suffixes supported, see Units for storage and network limits) or in IOPS (must be suffixed with iops). See also Configure I/O limits.
limits.read
Read I/O limit in byte/s or IOPS
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) or in IOPS (must be suffixed with iops). See also Configure I/O limits.
limits.write
Write I/O limit in byte/s or IOPS
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) or in IOPS (must be suffixed with iops). See also Configure I/O limits.
path
Mount path
Key: path
Type: string
Condition: container
Required: yes
This option specifies the path inside the container where the disk will be mounted.
pool
Storage pool to which the disk device belongs
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
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 (opens in a new tab) documentation for a full explanation.
raw.mount.options
File system specific mount options
Key: raw.mount.options
Type: string
Required: no
readonly
Whether to make the mount read-only
Key: readonly
Type: bool
Default: false
Required: no
recursive
Whether to recursively mount the source path
Key: recursive
Type: bool
Default: false
Required: no
required
Whether to fail if the source doesn’t exist
Key: required
Type: bool
Default: true
Required: no
shift
Whether to set up a UID/GID shifting overlay
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
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).
size.state
Size of the file-system volume used for saving runtime state
Key: size.state
Type: string
Condition: virtual machine
Required: no
This option is similar to 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
Key: source
Type: string
Required: yes
See Types of disk devices for details.
source.snapshot
source snapshot name
Key: source.snapshot
Type: string
Required: no
Snapshot of the volume given by source.
source.type
Type of the backing storage volume
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.
Storage volume
To add a storage volume, specify its name as the source of the device:
lxc config device add <instance\_name> <device\_name> disk pool=<pool\_name> source=<volume\_name> \[path=<path\_in\_instance>\]The path is required for file system volumes, but not for block volumes.
Alternatively, you can use the lxc storage volume attach command to Attach the volume to an instance. 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:
lxc config device add <instance\_name> <device\_name> disk source=<path\_on\_host> \[path=<path\_in\_instance>\]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:
lxc config device add <instance\_name> <device\_name> disk source=ceph:<pool\_name>/<volume\_name> ceph.user\_name=<user\_name> ceph.cluster\_name=<cluster\_name> \[path=<path\_in\_instance>\]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:
lxc config device add <instance\_name> <device\_name> disk source=cephfs:<fs\_name>/<path> ceph.user\_name=<user\_name> ceph.cluster\_name=<cluster\_name> path=<path\_in\_instance>ISO file
To add an ISO file, specify its file path as the source:
lxc config device add <instance\_name> <device\_name> disk source=<file\_path\_on\_host>VM cloud-init
To add cloud-init configuration, specify cloud-init:config as the source:
lxc config device add <instance\_name> <device\_name> disk source=cloud-init:configSee Configure devices for more information.