ZFS File Retention Properties

The ZFS file retention feature uses properties to describe the file retention policy of your file system. For a description of each property, see the zfs(8) man page.

The following zfs get example output shows the file retention properties and their values: 

# zfs get -e retention.all retain/mand
NAME         PROPERTY                      VALUE      SOURCE
retain/mand  retention.period.default      none       -
retain/mand  retention.period.deletegrace  60s        -
retain/mand  retention.period.grace        60s        -
retain/mand  retention.period.max          5y         -
retain/mand  retention.period.min          none       -
retain/mand  retention.policy              mandatory  -
retain/mand  retention.policy.changeacl    off        -
retain/mand  retention.policy.onexpiry     off        -
retain/mand  retention.status.expiry       -          -
retain/mand  retention.status.files        0          -

You can change the following file retention properties from these default values:

  • retention.period.min=0
  • retention.period.max=5years
  • retention.period.default=0
  • retention.period.grace=0
  • retention.period.deletegrace=0
  • retention.policy=off
  • retention.policy.changeacl=off
  • retention.policy.onexpiry=off

Note:

Use the minutes unit to specify minutes, such as 2minutes. The m unit specifies months.

The retention.status.files property shows the count of retained files.

The retention.status.expiry property shows the latest-expiring retention timestamp of a file. If that time has passed, the property value appends (expired) to the expiration timestamp. The retention.status.expiry value depends on how you retain the file, as follows:

  • Running the touch -R command with a date, time, or both specifies the date and time at which the retention period expires.
  • Running the touch -R command without a date or time specifies a retention period of the current date and time plus the retention.period.default property value.
  • Removing all write permissions from the file or setting its readonly system attribute retains the file until the current date and time plus the default retention period. You can use the access time of a file to set its retention time by running the following commands:
    • Use the touch -a command to specify an access time in the future
    • Use the chmod command to remove write permissions from the file
  • Enabling automatic retention by setting the retention.period.grace value to a positive integer specifies a retention period to the last time the file was modified (mtime) plus the retention.period.grace property value and the retention.period.default property value.

The retention.policy.onexpiry property specifies what occurs when the retention time of a file (rtime) expires. The following values are valid:

  • off: After a file's retention period expires, the file remains. Note that the file might be deleted by a process that has the appropriate privileges. This is the default value.
  • delete: Deletes a retained file automatically after the retention period expires.
  • hold: Treats a file that has an expired retention as if the retention period has not expired. As a result, the ZFS file retention feature continues to block deletions. When set to hold, a file system that has a mandatory retention policy and its pool are blocked from destruction.

The retention.policy.changeacl property enables you to change the file permissions and ACL, other than write, on a retained file. The following values are valid:

  • on: Enables you to change file permissions and ACL, except for write, on a retained file.
  • off: Prevents you from changing file permissions and ACL on a retained file. This is the default value.

The retention.period.deletegrace property enables you to delay the deletion of a retained file by a specified amount of time. The default value is 0. This property depends on the retention.policy.onexpiry property being set to delete. The property value must be less than 100 years.