btrfs-property

List available properties (and descriptions) for the given btrfs object

Get all properties for the given btrfs object
Get the label property for the given btrfs filesystem or device
Get all object type-specific properties for the given btrfs filesystem or device
Set the compression property for a given btrfs inode (either a file or directory)

btrfs property get [-t <type>] <object> <property>
btrfs property set [-t <type>] <object> <property> <value>
btrfs property list [-t <type>] <object>

<object>
    The path to the file, directory, subvolume, or device on which the property operation will be performed.

<property>
    The name of the btrfs property to retrieve or modify (e.g., ro, compression, nodatacow).

<value>
    The new value to assign to the property when using the set subcommand (e.g., true, false, zstd, lzo).

-t <type>
    Specify the type of object explicitly. Possible values are file, inode (default for files/directories), subvolume, or device. This helps clarify which properties are applicable to the object.

btrfs property is a subcommand of the main btrfs filesystem utility. It provides a dedicated interface to interact with btrfs-specific extended attributes, referred to as 'properties', associated with various btrfs objects. These objects can include files, directories, subvolumes, and storage devices.

The command supports three primary operations:

• get: To retrieve the current value of a specific property for an object.
• set: To assign a new value to a property, modifying the object's behavior or metadata.
• list: To enumerate all applicable properties and their current values for a given object.

This utility is crucial for managing btrfs features like subvolume read-only status, compression settings for files and directories, or the CoW (Copy-on-Write) behavior.

• Permissions: Modifying properties usually requires root privileges or ownership of the object.
• Property Applicability: Not all properties are valid for all object types (e.g., ro is for subvolumes, compression for files/directories). Setting an invalid property or value will result in an error.
• Behavioral Properties: Properties like compression or nodatacow on files/directories only affect new data written to them. Existing data will not change its compression or CoW status unless re-written.
• Read-Only Properties: Some properties, such as uuid for subvolumes, are read-only and cannot be modified using set.

Some frequently used btrfs properties include:

• ro (read-only): Used with subvolumes to make them read-only (e.g., btrfs property set -t subvolume /mnt/myvol/subvol ro true).
• compression: Applies to files and directories, setting the default compression algorithm for new data written to them (e.g., btrfs property set /path/to/file compression zstd). Valid values include lzo, zlib, zstd, or none.
• nodatacow: Applies to files and directories, disabling Copy-on-Write for new data written to them (e.g., btrfs property set /path/to/file nodatacow true). This can be useful for databases or virtual machine images.
• uuid / parent_uuid: Read-only properties for subvolumes, providing their unique identifiers and the UUID of their parent subvolume, respectively.

The btrfs property subcommand has been a core part of the btrfs command-line utilities since the early stages of btrfs filesystem development. Its functionality to manage filesystem-level extended attributes was fundamental to exposing and controlling various btrfs-specific features. It evolved as the btrfs filesystem matured, providing a consistent interface for property management, especially for subvolume characteristics and file attributes like compression.

btrfs(8), btrfs-subvolume(8), setfattr(1), getfattr(1)