properties.txt

History
=======

```
> This is a revised version of the original proposal/work from Alexander Block
> to introduce a generic framework to set properties on btrfs filesystem objects
> (inodes, subvolumes, filesystems, devices).

>         Currently the command group looks like this:
>         btrfs prop set [-t <type>] /path/to/object <name> <value>
>         btrfs prop get [-t <type>] /path/to/object [<name>] (omitting name dumps all)
>         btrfs prop list [-t <type>] /path/to/object (lists properties with description)
>
>         The type is used to explicitly specify what type of object you mean. This is
>         necessary in case the object+property combination is ambiguous.  For example
>         '/path/to/fs/root' could mean the root subvolume, the directory inode or the
>         filesystem itself. Normally, btrfs-progs will try to detect the type
>         automatically.
```

Command line UI
---------------

The generic commandline UI still looks ok to me, storing properties as xattr’s
is also ok (provided that we can capture the “btrfs.” xattr namespace).

Q: storage
----------

Where are stored properties that are not directly attached to an inode? Ie.
whole-filesystem and device. How can I access props for a subvolume that is not
currently reachable in the directory tree?

A fs or device props must be accessible any time, eg. no matter which subvolume
is currently mounted. This should be probably a special case where the property
can be queried from any inode but will be internally routed to eg. toplevel
subvolume that will store the respective xattrs.

Q: ambiguity
------------

If a property’s object can be ambiguous, how is that distinguished in the
xattrs?

We don’t have a list of props yet, so I’m trying to use one that hopefully
makes some sense. The example here can be persistent-mount-options that are
attached to fs and a subvolume. The fs-wide props will apply when a different
subvolume is explicitly mounted.

Assuming that the xattrs are stored with the toplevel subvolume, the fs-wide
and per-subvolume property must have a differnt xattr name (another option is
to store fs-wide elsewhere). So the question is, if we should encode the
property object into the xattr name directly. Eg.:


- btrfs.fs.persistent_mount
- btrfs.subvol.persistent_mount


or if the fs-wide uses a reserved naming scheme that would appear as xattr named


- btrfs.persistent_mount


but the value would differ if queried with ‘-t fs or ‘-t subvolume’.


Q: property precedence, interaction with mount options
------------------------------------------------------

The precedence should follow the rule of the least surprise, ie. if I set eg. a
compression of a file to zlib, set the subvolume compression type to ‘none’ and
have fs-wide mount the filesystem with compress=lzo, I’m expecting that the
file will use ‘zlib’.

The generic rule says that mount options (that have a corresponding property)
take precedence. There may be exceptions.

What if there are no specific mount options, but the subvolume has eg.
compression set? Should new files inherit that automatically or only if
explicitly marked as such?

The background concern is how far do I need to look and whether this could be a
potential performance problem. The lookup chain can be long: inode -> dir ->
subvol -> fs, plus mount options along the path where applicable.

If the xattr values are cached in structs that are accessed anyway (containing
subvol, fs_info) and updated when property xattr changes, this could work.

Q: behaviour of tools that see the btrfs-specific props
-------------------------------------------------------

What would cp or rsync do when copying the xattrs to a different filesystem?
They may simply ignore it and just try to copy the user. namespace, I haven’t
done any research here.


Q: properties to consider, naming, xattr name namespaces, inheritable props
---------------------------------------------------------------------------

filesystem-wide:
- persistent mount options
- default raid allocation profile
- default compression parameters
- compression ratio target
- label
- scrub ioprio
- last scrub status

subvolume:
- persistent mount options
- default raid allocation profile
- default compression parameters
- writable

device
- writable
- hot-spare
- preferred for metadata
- preferred data reads
- preferred data writes
- no new allocations if possible
- speed profile, io priorities
- allocation group - project idea "Chunk allocation groups"
- "ssd cache", L2ARC
- scrub ioprio
- last scrub status

filesystem
- persistent mount options
- default raid allocation profile
- default.compression.*

file, directory
- compression algo
- compression level
- raid allocation profile

details on compression parameters:
- compression algo
- compression level
- desired compression ratio target
- file compressibility hint - from project idea “Compression updates”
- compression container type - dtto

The props should be self explanatory. This is not a complete or finalized list,
feel free to suggest what you think should be here.

The number of compression parameters suggest that a namespace would be
appropriate. This could establish a common practice for any set of properties
that are not attached to any filesystem object but are grouped logically.

Most of the props are expected to be read-write, I don’t have a counterexample
for a property that makes sense, is persistent and must be read-only. Such can
be exported through the sysfs, so s/Most of/All/.

Q: configurable property inheritance

I don’t have a proposal how to mark inheritable props yet.



Namespace
=========

btrfs.policy.read.mirror

btrfs.policy.write.mirror

btrfs.cleanup.empty-block-group

btrfs.cleanup.stale-qgroup

btrfs.cleanup
btrfs.autostart.skip_balance

btrfs.mount.compress
btrfs.mount.compress-force

btrfs.mount.default

btrfs.alloc.chunk.profile

btrfs.scrub.ioprio

btrfs.scrub.last-status

btrfs.quota.status