File Retention Lock was recently released on ZFSSA and I wanted to take the time to explain how to set the retention time and view the retention of locked files. Below is an example of what happens. You can see that the files are locked until January 1st 2025
![ZFS Retention Lock]( "ZFS Retention Lock")
![]()
![zfs file retention lock]( "zfs file retention lock")
![zfssa file retention lock]( "zfssa file retention lock")
The best place to start for information on how this works is by looking at my last blog post on authorizations.
Grace period
The grace period is used to automatically lock a file when there has not been updates to the file for this period of time.
If the automatic file retention grace period is "0" seconds, then the default retention is NOT in effect.
NOTE: even with a grace period of "0" seconds files can be locked by manually setting a retention period. Also, once a grace period is set (non "0") it cannot be increased or disabled if there are files that can be affected.
Default retention
The most common method to implement retention is by using the default retention period. This takes effect when the grace period expired for a file.
In the example above you can see that all files created on this share are created with a default retention of 1 day (24 hours).
.
Minimum/Maximum File retention
The second settings you see on the image above are the "minimum file retention period" and the "maximum file retention period".
These control the retention settings on files which follows the rules below.
- The default retention period for files MUST be at least the minimum file retention period, and not greater than the maximum file retention period
- If the retention date is set manually on a file, the retention period must fall within the minimum and maximum retention period.
Display current Lock Expirations.
In order to display the lock expiration on Linux the first thing you need to do is to change the share/project setting to "Update access time on read" off . Through the CLI this is a "set atime=false".
Once this settings is made, the client will then display the lock time as the "atime". In my example at the top of the block, you can see by executing "ls -lu" the file lock time is displayed.
NOTE: you can also use the find command to search for files using the "atime" This will allow to find all the locked files.
Manually setting a retention date
It is possible to set a specific date/time that a file is locked until.
NOTE: If you try to change the retention date on a specific file, the new retention date has to be greater than current retention date (and less than or equal to the maximum file retention period). This makes sense. You cannot lower the retention period for a locked file.
Now how do you manually set the retention date ? Below is an example of how it is set for a file.
Setting File retention lock
There are 3 steps that are needed to lock the file with a specific lock expiration date.
1. Touch the file and set the access date. This can be done with
- "-a" to change the access date/time
- "-d" or "-t" to specify the date format
2. Remove the write bit with chmod guo-2
3. execute a cmod to make the file read only.
Below is an example where I am taking a file that does not contain retention, and setting the date to January 1, 2025.
First I am going to create a file and touch it setting the atime to a future data.
$echo 'xxxx'> myfile4.txt
$ls -al myfile4.txt
-rw-r--r--. 1 nobody oinstall 5 Jul 15 20:40 myfile3.txt
$ls -lu myfile3.txt
-rw-r--r--. 1 nobody oinstall 5 Jul 15 20:40 myfile3.txt
$ touch -a -t "2501011200" myfile3.txt
$ ls -lu myfile3.txt
-rw-r--r--. 1 nobody oinstall 5 Jan 1 2025 myfile3.txt
$rm myfile3.txt
$ls -lu myfile3.txt
ls: cannot access myfile3.txt: No such file or directory
You can see that I set the "atime" and it display a future date, but I was still able to delete the file.
Now I am going to move to remove the write bit before deleting.
$echo 'xxxx'> myfile4.txt
$ls -al myfile4.txt
-rw-r--r--. 1 nobody oinstall 5 Jul 15 20:40 myfile3.txt
$ls -lu myfile3.txt
-rw-r--r--. 1 nobody oinstall 5 Jul 15 20:40 myfile3.txt
$ touch -a -t "2501011200" myfile3.txt
$ ls -lu myfile3.txt
-rw-r--r--. 1 nobody oinstall 5 Jan 1 2025 myfile3.txt
$chmod ugo-w myfile3.txt
$rm myfile3.txt
ls: cannot access myfile3.txt: No such file or directory
Still, I am able to delete the file.. Finally I am going to do all three
$echo 'xxxx'> myfile4.txt
$ls -al myfile4.txt
-rw-r--r--. 1 nobody oinstall 5 Jul 15 20:40 myfile3.txt
$ls -lu myfile3.txt
-rw-r--r--. 1 nobody oinstall 5 Jul 15 20:40 myfile3.txt
$ touch -a -t "2501011200" myfile3.txt
$ ls -lu myfile3.txt
-rw-r--r--. 1 nobody oinstall 5 Jan 1 2025 myfile3.txt
$chmod ugo-w myfile3.txt
$chmod a=r myfile3.txt
#$rm myfile3.txt
rm: remove write-protected regular file ‘myfile3.txt’? y
rm: cannot remove ‘myfile3.txt’: Operation not permitted
echo 'xxxx'> myfile3.txt
touch -a -t "2501011200" myfile3.txt
chmod ugo-w myfile3.txt
chmod a=r myfile3.txt