How policies are applied

An object's policy consists of three attributes: its Storage Class, its trash retention, and its extra attributes. The precedence described in Patterns decides which object gets which values. The object first inherits from its parent directory. A matching pattern overrides the inheritance in the same operation. An assignment made by hand afterwards stays in effect until the object's next rename. This page describes that chain step by step: what exactly is inherited, how the winning pattern is chosen, and what a rename does and does not reopen.

Creation copies the policy of the parent directory

A new file or directory gets three things from its parent directory: the Storage Class, the trash retention, and the extra attributes. Every other kind of object gets only the attributes. Such an object gets no class. The trash retention of such an object is set to 24 hours, regardless of the parent's retention. A symbolic link, a FIFO, a socket, and a device file hold no data of their own, so neither value has anything to act on. Both values are set to a constant instead of being inherited.

The attributes are not copied in full. The three protection flags (undeletable, appendonly, immutable) and the flag that marks a snapshot all start clear on every new object. noentrycache, which concerns directory entries, starts clear on everything that is not a directory. The other attributes are copied as the parent has them at that moment.

One pattern wins and applies alone

In the same call that creates the object, the Master Server matches the new name against the patterns and applies the best match over what was inherited. A pattern defines any combination of a class, a trash retention, attributes to set, and attributes to clear. Each of these that the pattern defines replaces the inherited value. The fields that the pattern leaves out stay as the directory gave them (noentrycache is again ignored for anything that is not a directory). Only files and directories get the class and the retention. Every other type gets only the attributes. A symbolic link is the only object created without consulting the patterns at all. The Master Server matches the patterns against a symbolic link for the first time when the link is renamed.

Matching uses the name alone, with the glob that the pattern was written with. A pattern narrowed to a user is skipped for everyone else. The narrowing compares the pattern's user ID against the effective user ID of the creating process. The narrowing also compares the pattern's group ID against every group of that process. Among the matching patterns, the pattern with the highest priority is used. Priorities range from 0 (lowest) to 255 (highest). The default priority is 128. The winning pattern applies alone. Its fields are used. No lower-priority pattern is consulted to fill the fields that the winning pattern left out. When two matching patterns share the highest priority, it is unspecified which of them is used.

A cluster holds at most 1024 patterns. Adding a pattern beyond that limit is refused. A second pattern with the same glob and the same user and group narrowing is refused as well. So is a pattern that defines no class, no trash retention, and no attribute to set or clear.

A rename reopens the rules, but an exchange does not

After creation, the rules are not applied again on their own. A class, a retention, or an attribute set by hand stays in effect. A pattern added later is never applied to the objects that already exist. Only a rename reopens the rules. The Master Server matches the destination name against the patterns the same way as at creation. The Master Server then applies the winning pattern over the values that the object had, whether they were inherited, matched, or set by hand. When this changes the class of a file, every chunk of the file is governed by the new class at once. Changing the copies and parts to match the new class is the ordinary repair work described in Storage Class evaluation.

The rename triggers the patterns, not the new name. Creating an additional hard link applies no patterns, even though a hard link also puts a new name on a file. Names: link, unlink, rename, and exchange covers what a rename means for names and links. On this page, the rename matters only as the trigger.

The exception is the exchange rename. It comes from a client as renameat2() with the RENAME_EXCHANGE flag. The exchange rename swaps two names in one operation. The swap applies no patterns to either object. Each object keeps its class, retention, and attributes, and continues under the other name.

A pattern holds its class, and is deleted with it

A pattern that assigns a class holds the class itself, not its name. After a class is renamed, its patterns therefore assign the renamed class. Deleting a class deletes every pattern that assigned it. The deletion is refused as long as any file or directory still uses the class, but a pattern does not count as use. A pattern does not protect its class, and is deleted with it.