1. Managing ZFS File Systems in Oracle Solaris 11.4
  2. Managing Oracle Solaris ZFS File Systems
  3. Retaining Files on Your ZFS File System
  4. ZFS File Retention Properties

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:

Do not use the m unit to specify a value in minutes, as this unit refers to months. Instead, specify the minutes as seconds such as 120s for two minutes.

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 or touch -a command with a date and time specifies the date and time at which the retention period expires.
  • Running the touch -R or touch -a command without a date and time specifies a retention period of the current date and time plus the retention.period.default property value. This method is also used when you remove all write permissions from the file or set the readonly system attribute for 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.