Directory - dir

The directory storage driver is a basic backend that stores its data in a standard file and directory structure. This driver is quick to set up and allows inspecting the files directly on the disk, which can be convenient for testing. However, Incus operations are not optimized for this driver.

dir driver in Incus

The dir driver in Incus is fully functional and provides the same set of features as other drivers. However, it is much slower than all the other drivers because it must unpack images and do instant copies of instances, snapshots and images.

Unless specified differently during creation (with the source configuration option), the data is stored in the /var/lib/incus/storage-pools/ directory.

Quotas

The dir driver supports storage quotas when running on either ext4 or XFS with project quotas enabled at the file system level.

Configuration options

The following configuration options are available for storage pools that use the dir driver and for storage volumes in these pools.

Storage pool configuration

Key	Type	Default	Description
rsync.bwlimit	string	0 (no limit)	The upper limit to be placed on the socket I/O when rsync must be used to transfer storage entities
rsync.compression	bool	true	Whether to use compression while migrating storage pools
source	string	-	Path to an existing directory

Tip

In addition to these configurations, you can also set default values for the storage volume configurations. See Configure default values for storage volumes.

Storage volume configuration

Key	Type	Condition	Default	Description
initial.gid	int	custom volume with content type filesystem	same as volume.initial.uid or 0	GID of the volume owner in the instance
initial.mode	int	custom volume with content type filesystem	same as volume.initial.mode or 711	Mode of the volume in the instance
initial.uid	int	custom volume with content type filesystem	same as volume.initial.gid or 0	UID of the volume owner in the instance
security.shared	bool	custom block volume	same as volume.security.shared or false	Enable sharing the volume across multiple instances
security.shifted	bool	custom volume	same as volume.security.shifted or false	Enable ID shifting overlay (allows attach by multiple isolated instances)
security.unmapped	bool	custom volume	same as volume.security.unmapped or false	Disable ID mapping for the volume
size	string	appropriate driver	same as volume.size	Size/quota of the storage volume
snapshots.expiry	string	custom volume	same as volume.snapshots.expiry	Controls when snapshots are to be deleted (expects an expression like 1M 2H 3d 4w 5m 6y)
snapshots.pattern	string	custom volume	same as volume.snapshots.pattern or snap%d	Pongo2 template string that represents the snapshot name (used for scheduled snapshots and unnamed snapshots) [1]
snapshots.schedule	string	custom volume	same as volume.snapshots.schedule	Cron expression (<minute> <hour> <dom> <month> <dow>), a comma-separated list of schedule aliases (@hourly, @daily, @midnight, @weekly, @monthly, @annually, @yearly), or empty to disable automatic snapshots (the default)

Storage bucket configuration

To enable storage buckets for local storage pool drivers and allow applications to access the buckets via the S3 protocol, you must configure the core.storage_buckets_address server setting.

Storage buckets do not have any configuration for dir pools. Unlike the other storage pool drivers, the dir driver does not support bucket quotas via the size setting.

---

[1]

The snapshots.pattern option takes a Pongo2 template string to format the snapshot name.

To add a time stamp to the snapshot name, use the Pongo2 context variable creation_date. Make sure to format the date in your template string to avoid forbidden characters in the snapshot name. For example, set snapshots.pattern to {{ creation_date|date:'2006-01-02_15-04-05' }} to name the snapshots after their time of creation, down to the precision of a second.

Another way to avoid name collisions is to use the placeholder %d in the pattern. For the first snapshot, the placeholder is replaced with 0. For subsequent snapshots, the existing snapshot names are taken into account to find the highest number at the placeholder’s position. This number is then incremented by one for the new name.