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 them
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
ortouch -a
command with a date and time specifies the date and time at which the retention period expires. - Running the
touch -R
ortouch -a
command without a date and time specifies a retention period of the current date and time plus theretention.period.default
property value. This method is also used when you remove all write permissions from the file or set thereadonly
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 theretention.period.grace
property value and theretention.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 tohold
, 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.