LinuxCommandLibrary

btrfs-property

Set or get Btrfs object properties

TLDR

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

$ sudo btrfs property list [path/to/btrfs_object]
copy

Get all properties for the given btrfs object
$ sudo btrfs property get [path/to/btrfs_object]
copy

Get the label property for the given btrfs filesystem or device
$ sudo btrfs property get [path/to/btrfs_filesystem] label
copy

Get all object type-specific properties for the given btrfs filesystem or device
$ sudo btrfs property get -t [subvol|filesystem|inode|device] [path/to/btrfs_filesystem]
copy

Set the compression property for a given btrfs inode (either a file or directory)
$ sudo btrfs property set [path/to/btrfs_inode] compression [zstd|zlib|lzo|none]
copy

SYNOPSIS

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

PARAMETERS

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

DESCRIPTION

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.

CAVEATS

  • 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.

COMMON PROPERTY EXAMPLES

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.

HISTORY

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.

SEE ALSO

Copied to clipboard