(devices-disk)=
# Type: `disk`

```{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.

```{warning}
The device name affects the serial generated for the device. If the device name exceeds 14 characters for `nvme` and `virtio-blk`, or 30 characters for `virtio-scsi`, Incus will hash the device value to ensure the generated serial remains within supported length constraints. The device name itself is left unchanged.
```

(devices-disk-types)=
## 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:

Storage volume
: The most common type of disk device is a storage volume.
  To add a storage volume, specify its name as the `source` of the device:

      incus 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 [`incus storage volume attach`](incus_storage_volume_attach.md) command to {ref}`storage-attach-volume`.
  Both commands use the same mechanism to add a storage volume as a disk device.

  It's possible to attach a sub-path of a custom volume to an instance using the `source=<volume_name>/<sub_path>` syntax.
  If the sub-path doesn't exist inside the custom volume, it will be created automatically when the device is started using the `initial.XYZ` configuration keys for ownership and permissions.

Path on the host
: You can share a path on your host (either a file system or a block device) to your instance by adding it as a disk device with the host path as the `source`:

      incus 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
: Incus 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 with the following command:

      incus 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
: Incus 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 with the following command:

      incus 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
: You can add an ISO file as a disk device for a virtual machine.
  It is added as a ROM device inside the VM.

  This source type is applicable only to VMs.

  To add an ISO file, specify its file path as the `source`:

      incus config device add <instance_name> <device_name> disk source=<file_path_on_host>

VM `cloud-init`
: You can generate a `cloud-init` configuration ISO from the {config:option}`instance-cloud-init:cloud-init.vendor-data` and {config:option}`instance-cloud-init:cloud-init.user-data` configuration keys and attach it to a virtual machine.
  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.

  To add such a device, use the following command:

      incus config device add <instance_name> <device_name> disk source=cloud-init:config

VM `agent`
: You can generate an `agent` configuration ISO which will contain the agent binary, configuration files and installation scripts.
  This is required for environments where `9p` isn't supported and where an alternative way to load the agent is required.

  This source type is applicable only to VMs.

  To add such a device, use the following command:

      incus config device add <instance_name> <device_name> disk source=agent:config

Tmpfs
: You can back a disk device with an in-memory file system by using the `tmpfs:` source.

      incus config device add <instance_name> <device_name> disk source=tmpfs: path=<path_in_instance> [size=<size>] [initial.uid=<uid>] [initial.gid=<gid>] [initial.mode=<mode>]

  Both `source` and `path` are required.
  This creates a `tmpfs` mount inside the instance and supports optional properties for size, ownership, and permissions.

Tmpfs with overlayfs behavior
: If you want the same tmpfs behavior but combined with overlayfs semantics, use `tmpfs-overlay:` as the source.

      incus config device add <instance_name> <device_name> disk source=tmpfs-overlay: path=<path_in_instance> [size=<size>] [initial.uid=<uid>] [initial.gid=<gid>] [initial.mode=<mode>]

  Both `source` and `path` are required.
  Additionally, the target `path` must already exist inside the container.
  This provides an ephemeral in-memory file system with overlayfs handling.

(devices-disk-initial-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:

    incus profile device set <profile_name> <device_name> initial.zfs.block_mode=true

You can also set an initial configuration directly when creating an instance. For example:

    incus init <image> <instance_name> --device <device_name>,initial.zfs.block_mode=true

Note that you cannot use initial volume configurations with custom volume options or to set the volume's size.

(devices-disk-initial-uid-gid-mode)=
## `initial.uid`, `initial.gid` and `initial.mode`

`initial.uid`, `initial.gid` and `initial.mode` apply in three different scenarios:

- On root disk devices, they are passed to the storage driver to set the ownership and mode of the instance's root volume at creation time (when supported by the driver).
- On `tmpfs:` and `tmpfs-overlay:` disk devices, they are translated into `uid=`, `gid=` and `mode=` mount options for the underlying `tmpfs` mount.
- On custom volume disks where the `source` includes a sub-path (for example `source=myvol/sub/path`), they are used as the ownership and mode of any sub-directory that has to be created automatically when the device is started.

In all cases, `initial.uid` and `initial.gid` default to `0` and `initial.mode` defaults to `0711` (octal).

## Device options

`disk` devices have the following device options:

% Include content from [../config_options.txt](../config_options.txt)
```{include} ../config_options.txt
    :start-after: <!-- config group devices-disk start -->
    :end-before: <!-- config group devices-disk end -->
```
