About WORM-FS File Systems

Write-once read-many (WORM) technology is used in many applications for data integrity reasons and because of the accepted legal admissibility of stored files that use the technology.

The WORM-FS feature offers default and customizable file-retention periods, data and path immutability, and subdirectory inheritance of the WORM setting.

WORM-FS can operate in one of two modes:

• Sun standard compliance mode (referred to as standard mode), which is the default

• Sun emulation compliance mode (referred to as emulation mode), which is designed to provide compatibility with the emulation mode of the StorageTek 5320 network attached storage (NAS) appliance and is similar to an interface defined by Network Appliance

One difference between standard and emulation mode is a restriction on the nature of files that can be retained. Specifically, in standard mode, files with any UNIX executable permissions cannot be retained. Emulation mode has no such restriction. The restriction in standard mode exists because the retention trigger defined for NFS and FTP specifying that the setuid mode be set on the file. Once a file is retained, a client will see the setuid mode bit set. However, the restriction on executable files will prevent the possible security hole of allowing an executable file owned by the root user to be made WORM and therefore impossible to remove. A benefit of this approach is that the user or application can more easily determine which files on the system are WORM-protected files.

Using WORM-FS With NFS Clients

If you are using WORM-FS on Oracle Solaris 10 or later with NFS clients connected to it, ensure that NFS version 4 is enabled on the NFS clients and sever.

If you are running an older version of the Oracle Solaris OS (before Oracle Solaris 10) and NFS version 3, the NFS client might not show the WORM-FS files. Add the following line to the /etc/system file and then reboot the system:

set nfs:nfs_allow_preepoch_time = 1

Enabling the WORM-FS Feature

The following table shows the four mount options that you can use to enable the WORM-FS feature.

These four mount options are somewhat exclusive. You can upgrade from “lite” to standard WORM mode, but you cannot change from standard WORM mode to emulation mode, or from emulation to standard mode. These options can be provided on the command line when the file system is mounted, listed in /etc/vfstab, or provided in /opt/SUNWsamfs/samfs.cmd. The normal rules of precedence for mount options apply.

The WORM attribute is stored in the mount table and enables WORM files to be created in directories anywhere in the file system.

The following example shows a WORM-FS mount option. The file system samfs1 mounted at /samfs1 is WORM-capable and has the default retention period for files set to 60 minutes.

Example 9-1 Using WORM-FS Mount Options

# cat /etc/vfstab
  #device device mount FS fsck mount mount
  #to mount to fsck point type pass at boot options
  #
  fd - /dev/fd fd - no -
  /proc - /proc proc - no -
  /dev/dsk/c0t0d0s1 - - swap - no -
  samfs1 - /samfs1 samfs - yes worm_capable,def_retention=60
  swap - /tmp tmpfs - yes -

After the WORM-FS feature has been enabled and at least one WORM file is resident in the file system, the file system's superblock is updated to reflect the WORM capability. Any subsequent attempt to rebuild the file system through sammkfs will fail unless you are using the worm_lite or emul_lite mount option.

WORM Lite Options

The worm_lite and emul_lite mount options create a modified WORM environment that eases the restrictions on actions that can be taken on WORM-enabled volumes and retained files. The WORM lite options can be a solution for companies with document management and retention policies requiring data retention guarantees but not the strict constraints that WORM places on systems. Mechanisms exist to alter and even reverse some data retention decisions.

The WORM lite options can also be used for testing and configuring WORM systems and applications before upgrading to the more strict standard WORM policies.

The WORM lite environment behaves similarly to the standard WORM mode. File data and path remain immutable, but the system administrator is allowed to carry out the following special actions:

• Remove WORM files before the retention time has expired

• Shorten the retention time on WORM files

• Delete WORM Lite-enabled volumes or rebuild them using the sammkfs command

Creating WORM Files

A WORM mount option enables a file system to contain WORM files, but it does not automatically create WORM files. To create a WORM file, you must first make the directory WORM-capable. Create directory and then use a WORM trigger command to set the WORM bit on the directory. Depending on the mount option being used, the following WORM trigger commands are available:

• Use chmod 4000 directory-name to set the WORM bit if you are using the worm_capable or worm_lite mount option.

• Remove the write permissions on the directory to set the WORM bit if you are using the worm_emul or emul_lite mount option.

After setting the WORM bit on a directory, you can create files in that directory and then use the appropriate WORM trigger to set the WORM bit on files that you want retained. The WORM trigger is the same for both files and directories.

Use care when applying the WORM trigger. The file data and path cannot be changed after the file has the WORM feature applied. Once this feature is applied to a file, it is irrevocable. Further, once the WORM trigger is applied to a file, its volume also become a WORM volume and remains that way. The volume can only be destroyed using a volume management or RAID interface. If one of the WORM lite options was used to create it, the volume can also be rebuilt by using sammkfs.

The following examples illustrate using the WORM trigger for each of the four mount options using the system-wide default retention value.

Example 9-2 chmod 4000 WORM Trigger Using Standard WORM Functionality

This example shows a simple application of the WORM trigger chmod 4000 using standard WORM functionality.

[host1]# grep -i worm /etc/vfstab
samfs1 -       /samfs1  samfs   -       no     bg,worm_capable

[host1]# cd /samfs1
[host1]# mkdir WORM
[host1]# chmod 4000 WORM
[host1]# sls -D

WORM:
  mode: drwxr-xr-x  links:   2  owner: root      group: root
  length:      4096  admin id:      0  inode:     1025.1
  access:      Jan 30 15:50  modification: Jan 30 15:50
  changed:     Jan 30 15:50  attributes:   Jan  1  1970
  creation:    Jan 30 15:50  residence:    Jan 30 15:50
  worm-capable        retention-period: 0y, 30d, 0h, 0m

[host1]# cd WORM
[host1]# touch test
[host1]# chmod 4000 test
[host1]# sls -D

test:
  mode: -r-Sr--r--  links:   1  owner: root      group: root
  length:         0  admin id:      0  inode:     1026.3
  access:      Jan 30 15:51  modification: Jan 30 15:51
  changed:     Jan 30 15:51  retention-end: Mar  1 15:51 2007
  creation:    Jan 30 15:51  residence:    Jan 30 15:51
  retention:   active        retention-period: 0y, 30d, 0h, 0m

[host1]# rm test
rm: test: override protection 444 (yes/no)? yes
rm: test not removed: Read-only file system
[host1]# ls
test

Example 9-3 chmod 4000 WORM Trigger Using WORM Lite Functionality

This example shows a simple application of the WORM trigger chmod 4000 using standard WORM lite functionality.

[root@ns-east-44]# grep -i worm /etc/vfstab
samfs1 -       /samfs1  samfs   -       no     bg,worm_lite

[host1]# mount samfs1
[host1]# cd /samfs1
[host1]# mkdir WORM
[host1]# chmod 4000 WORM
[host1]# sls -D

WORM:
  mode: drwxr-xr-x  links:   2  owner: root      group: root
  length:      4096  admin id:      0  inode:     1025.1
  access:      Jan 30 16:12  modification: Jan 30 16:12
  changed:     Jan 30 16:12  attributes:   Jan  1  1970
  creation:    Jan 30 16:12  residence:    Jan 30 16:12
  worm-capable        retention-period: 0y, 30d, 0h, 0m

[host1]# cd WORM
[host1]# touch test
[host1]# chmod 4000 test
[host1]# sls -D
test:
  mode: -r-Sr--r--  links:   1  owner: root      group: root
  length:         0  admin id:      0  inode:     1026.1
  access:      Jan 30 16:13  modification: Jan 30 16:13
  changed:     Jan 30 16:13  retention-end: Mar  1 16:13 2007
  creation:    Jan 30 16:13  residence:    Jan 30 16:13
  retention:   active        retention-period: 0y, 30d, 0h, 0m

[host1]# rm test
rm: test: override protection 444 (yes/no)? yes
[host1]# ls
[host1]#

Example 9-4 chmod -w WORM Trigger Using WORM Emulation Mode

This example show a simple application of the WORM trigger using WORM emulation mode.

[root@ns-east-44]# grep -i worm /etc/vfstab
samfs1 -       /samfs1  samfs   -       no     bg,worm_emul

[host1]# mount samfs1
host1]# cd /samfs1
[host1]# mkdir WORM
[host1]# chmod -w WORM
[host1]# sls -D

WORM:
  mode: drwxr-xr-x  links:   2  owner: root      group: root
  length:      4096  admin id:      0  inode:     1025.1
  access:      Jan 30 16:26  modification: Jan 30 16:26
  changed:     Jan 30 16:26  attributes:   Jan  1  1970
  creation:    Jan 30 16:26  residence:    Jan 30 16:26
  worm-capable        retention-period: 0y, 30d, 0h, 0m

[host1]# cd WORM
[host1]# touch test
[host1]# chmod -w test
[host1]# sls -D

test:
  mode: -r--r--r--  links:   1  owner: root      group: root
  length:         0  admin id:      0  inode:     1026.1
  access:      Jan 30 16:26  modification: Jan 30 16:26
  changed:     Jan 30 16:26  retention-end: Mar  1 16:26 2007
  creation:    Jan 30 16:26  residence:    Jan 30 16:26
  retention:   active        retention-period: 0y, 30d, 0h, 0m

[host1]# rm test
rm: test: override protection 444 (yes/no)? yes
rm: test not removed: Read-only file system
[host1]# ls
test

Example 9-5 chmod -w WORM Trigger Using WORM Emulation Lite Mode

This example shows a simple application of the WORM trigger using WORM emulation lite mode.

[root@ns-east-44]# grep -i worm /etc/vfstab
samfs1 -       /samfs1  samfs   -       no     bg,emul_lite

[host1]# mount samfs1
[host1]# cd /samfs1
[host1]# mkdir WORM
[host1]# chmod -w WORM
[host1]# sls -D

WORM:
  mode: drwxr-xr-x  links:   2  owner: root      group: root
  length:      4096  admin id:      0  inode:     1025.1
  access:      Jan 30 16:36  modification: Jan 30 16:36
  changed:     Jan 30 16:36  attributes:   Jan  1  1970
  creation:    Jan 30 16:36  residence:    Jan 30 16:36
  worm-capable        retention-period: 0y, 30d, 0h, 0m

[host1]# cd WORM
[host1]# touch test
[host1]# chmod -w test
[host1]# sls -D

test:
  mode: -r--r--r--  links:   1  owner: root      group: root
  length:         0  admin id:      0  inode:     1026.1
  access:      Jan 30 16:36  modification: Jan 30 16:36
  changed:     Jan 30 16:36  retention-end: Mar  1 16:36 2007
  creation:    Jan 30 16:36  residence:    Jan 30 16:36
  retention:   active        retention-period: 0y, 30d, 0h, 0m

[host1]# rm test
rm: test: override protection 444 (yes/no)? yes
[host1]# ls
[host1]#

Retention Periods

The WORM-FS feature also includes file-retention periods that can be customized. Assigning a retention period to a file maintains the WORM features in that file for the specified period of time.

Do one of the following to set a retention period for a file:

• Advance the file's access time using the touch utility, or with a program using the libc subroutine utimes(). The file's retention period is stored in minutes. After the access time is advanced, use the appropriate WORM trigger to set the WORM bit.

• Use the default retention period for a file by applying the appropriate WORM trigger. The file system will apply the default retention period. For more information, see Setting the Default Retention Period.

The following example shows the creation of a file in a WORM-capable directory, using the WORM trigger on the file (with the chmod 4000 command), and using the sls command to display the file's WORM features. This example uses the default retention period of the file system (60 minutes, as set in Example 9-1).

Example 9-6 Creation of a WORM-Capable Directory and WORM File

# cd WORM
# echo "This is a test file" >> test
# sls -D
test: 
            mode: -rw-r--r-- links: 1 owner: root group: other 
            length: 20 admin id: 0 inode: 1027.1 
            access: Oct 30 02:50 modification: Oct 30 02:50 
            changed: Oct 30 02:50 attributes: Oct 30 02:50 
            creation: Oct 30 02:50 residence: Oct 30 02:50 

            checksum: gen no_use not_val algo: 0 

# chmod 4000 test
# sls -D
test: 
            mode: -r--r--r-- links: 1 owner: root group: other 
            length: 20 admin id: 0 inode: 1027.1 
            access: Oct 30 02:50 modification: Oct 30 02:50 
            changed: Oct 30 02:50 retention-end: Oct 30 2005 03:50 
            creation: Oct 30 02:50 residence: Oct 30 02:50 
            retention: active retention-period: 0y, 0d, 1h, 0m 
            checksum: gen no_use not_val algo: 0

With the addition of the WORM-FS feature, three states are possible for a file in a Sun QFS file system:

• Normal

• Retained

• Expired

The normal state represents the state of an ordinary file in a Sun QFS file system. A transition to the retained, or active, state occurs when the WORM bit is set on a file. The expired, or over, state occurs when the file's retention period is exceeded.

When a retention period is assigned to a file and the WORM trigger is applied to it, the file's path and data are immutable. When the retention period expires, the state is changed to expired but the path and data remain immutable.

When a file is in an expired state, only two operations are available:

• Extension of the retention period. (The retention period cannot be shortened unless you are using a WORM lite option.)

• Deletion of the file.

If the retention period is extended, the file's state returns to active and the new end date and duration are set accordingly.

Both hard and soft links to files can be used with the WORM-FS feature. Hard links can be established only with files that reside in a WORM-capable directory. After a hard link is created, it has the same WORM characteristics as the original file. Soft links can also be established, but a soft link cannot use the WORM features. Soft links to WORM files can be created in any directory in a Sun QFS file system.

Another attribute of the WORM-FS feature is directory inheritance. New directories created under a directory that includes a WORM attribute inherit this attribute from their parent. If a directory has a default retention period set, this retention period is also inherited by any new subdirectories. The WORM bit can be set on any file whose parent directory is WORM-capable. Users can set the WORM feature on directories and files that they own or have access to by using normal UNIX permissions.

Setting the Default Retention Period

The default retention period for a file system can be set as a mount option in the /etc/vfstab file. For example:

samfs1 - /samfs1 samfs - nobg,worm_emul,def_retention=1y60d

The format for setting the default retention period is MyNdOhPm, in which M, N, O and P are non-negative integers and y,d,h and m stand for years, days, hours, and minutes respectively. Any combination of these units can be used. For example, 1y5d4h3m indicates 1 year, 5 days, 4 hours, and 3 minutes; 30d8h indicates 30 days and 8 hours and 300m indicates 300 minutes. This format is backward compatible with software versions prior to 4U5, in which the retention period was specified in minutes. Although the granularity of the period is in minutes, the accuracy of the period is based on one day. Also, the function that handles days, hours, and minutes does not account for leap years when determining retention periods.

You can also use the default retention period to set a file or directory's retention period beyond the year 2038. Set the default retention period to a value which exceeds 2038 and mount the file system. Then use the appropriate WORM trigger to apply the default retention period. The following example shows how to use the default retention period to set a retention period on a directory and file which exceeds the year 2038.

Example 9-7 Extending the Retention Period Beyond 2038

[root@ns-east-44]# grep samfs1 /etc/vfstab
samfs1 - /samfs1 samfs - no 
bg,worm_capable,def_retention=34y 
    [root@ns-east-44]# mount samfs1 
    [root@ns-east-44]# cd /samfs1
    [root@ns-east-44]# mkdir WORM 
    [root@ns-east-44]# chmod 4000 WORM 
    [root@ns-east-44]# sls -D 
WORM: 
        mode: drwxr-xr-x links: 2 owner: root group: root 
        length: 4096 admin id: 0 inode: 1026.1 
        access: Feb 20 14:24 modification: Feb 20 14:24 
        changed: Feb 20 14:24 attributes: Jul 26 1970 
        creation: Feb 20 14:24 residence: Feb 20 14:24 
        worm-capable retention-period: 34y, 0d, 0h, 0m 

[root@ns-east-44]# cd WORM 
[root@ns-east-44]# touch test 
[root@ns-east-44]# chmod 4000 test 
[root@ns-east-44]# sls -D 
test: 
        mode: -r-Sr--r-- links: 1 owner: root group: root 
        length: 0 admin id: 0 inode: 1027.1 
        access: Feb 20 14:24 modification: Feb 20 14:25 
        changed: Feb 20 14:25 retention-end: Feb 20 14:25 2041 
            creation: Feb 20 14:24 residence: Feb 20 14:24 
    retention: active retention-period: 34y, 0d, 0h, 0m

You can also set a default retention period for a directory using the touch utility, as described in the next section. This retention period overrides the default retention period for the file system and is inherited by any subdirectories.

Setting the Retention Period Using touch

You can use the touch utility to set or extend a file's or directory's retention period. You can also use touch to shorten the default retention period for a directory (but not for a file).

To set the retention period, you must first advance the file's or directory's access time using touch, and then apply the WORM trigger by using the chmod command or removing write permissions, depending on the WORM mode in place at the time.

The following example shows the use of the touch utility to set a file's retention period, followed by the application of the WORM trigger.

Example 9-8 Using touch and chmod to Set the Retention Period

# touch -a -t200508181125 test 
# sls -D 
test: 
        mode: -rw-r--r-- links: 1 owner: root group: root 
        length: 0 admin id: 0 inode: 1027.1 
        access: Aug 18 2005 modification: Aug 18 11:19 
        changed: Aug 18 11:19 attributes: Aug 18 11:19 
        creation: Aug 18 11:19 residence: Aug 18 11:19 

# chmod 4000 test 
# sls -D 
test: 
        mode: -r-Sr--r-- links: 1 owner: root group: root 
        length: 0 admin id: 0 inode: 1027.1 
        access: Aug 18 2005 modification: Aug 18 11:19 
        changed: Aug 18 11:19 retention-end: Aug 18 2005 11:25 
        creation: Aug 18 11:19 residence: Aug 18 11:19 
        retention: active retention-period: 0y, 0d, 0h, 6m

The -a option for touch changes the access time of the file or directory. The -t option specifies the time to be used for the access time field. The format for the time argument is [[CC]YY]MMDDhhmm[.SS], as follows:

• [CC] – The first two digits of the year.

• [YY] – The second two digits of the year.

• MM – The month of the year (01—12).

• DD – The day of the month (01—31).

• hh – The hour of the day (00—23).

• mm – The minute of the hour (00—59).

• [SS] – The second of the minute (00—61).

The CC, YY, and SS fields are optional. If CC and YY are not given, the default is the current year. See the touch(1) man page for more information about these options.

To set the retention period to permanent retention, set the access time to its largest possible value: 203801182214.07.

The following example shows how to use touch to extend a file's retention period.

Example 9-9 Using touch to Extend a File's Retention Period

# sls -D test 
test: 
        mode: -r-Sr--r-- links: 1 owner: root group: root 
        length: 0 admin id: 0 inode: 1029.1 
        access: Aug 18 11:35 modification: Aug 18 11:33 
        changed: Aug 18 11:33 retention-end: Aug 18 2005 11:35 
        creation: Aug 18 11:33 residence: Aug 18 11:33 
        retention: over retention-period: 0y, 0d, 0h, 2m 
# touch -a -t200508181159 test 
# sls -D
test: 
        mode: -r-Sr--r-- links: 1 owner: root group: root 
        length: 0 admin id: 0 inode: 1029.1 
        access: Aug 18 11:35 modification: Aug 18 11:33 
        changed: Aug 18 11:33 retention-end: Aug 18 2005 11:59 
        creation: Aug 18 11:33 residence: Aug 18 11:33 
        retention: active retention-period: 0y, 0d, 0h, 26m

In this example, the retention period is extended to Aug 18, 2005 at 11:59AM, which is 26 minutes from the time the WORM trigger was initially applied.

Using sls to View WORM-FS Files

Use the sls command to view WORM file attributes. The -D option shows whether a directory is WORM-capable. Use this option on a file to display when the retention period began, when it will end, the current retention state, and the duration as specified on the command line.

The retention period start time and duration (in minutes) are stored in the file's inode.

To access this information directly you must use a program similar to the following example.

Example 9-10 Program for Direct Access to Retention Period Start Time and Duration

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
/*
* SAMFS includes in /opt/SUNWsamfs/include
*/
#include "stat.h"
#include "lib.h"

/*
* SAMFS libraries in /opt/SUNWsamfs/lib
*/
int
main(int argc, char **argv)
{
   char ibuf[1000];
   struct sam_stat buf;

   if (argc != 2) {
       printf("usage: sam_worm_stat filename\n");
       exit(-1);
   }

   if (sam_stat(argv[1], &buf, sizeof(buf)) == 0) {
       (void)time_string(buf.rperiod_start_time, 
buf.rperiod_start_time, ibuf);
       printf("retention period start is %s\n", ibuf);
       printf("retent period duration is %ld minutes\n", 
buf.rperiod_duration);
   } else {
       printf("can not sam_worm_stat %s\n", argv[1]);
   }
}

The following example shows how sls -D displays a file's retention status.

Example 9-11 Using sls to Find a File's Retention Status

# sls -D test 
test: 
        mode: -r-Sr--r-- links: 1 owner: root group: root 
        length: 5 admin id: 0 inode: 1027.1 
        access: Aug 18 2008 modification: Aug 18 11:19 
        changed: Aug 18 11:19 retention-end: Aug 18 2008 11:25 
        creation: Aug 18 11:19 residence: Aug 18 11:19 
        retention: active retention-period: 0y, 0d, 0h, 6m

In this example, the retention state is active, as shown by the retention: active designation, meaning that the file has the WORM bit set. The retention period started on August 18, 2008, at 11:19 and will end on August 18, 2008, at 11:25. The retention period was specified to be 0 years, 0 days, 0 hours, and 6 minutes.

Using sfind to Find WORM-FS Files

Use the sfind utility to search for files that have certain retention periods. See sfind(1) in Sun QFS and Sun Storage Archive Manager 5.3 Reference Manual for more information on the options. The following options are available:

• -ractive — Finds files whose retention period is active.

• -rover — Finds files whose retention periods have expired.

• -rafter date — Finds files whose retention period will end after the specified date. The date is specified as YYYYMMDDHHmm, where YYYY is the year, MM is the month, DD is the day, HH is the hour, and mm is minutes. The following example shows the command to find files whose retention period expires after 12/24/2004 at 15:00.

  # sfind -rafter 200412241500

• -rremain time — Finds files that have retention periods with at least the specified amount of time left. The time is specified as MyNdOhPm, where M, N, O,, and P are arbitrary non-negative integers and y, d, h,and m represent the number of years, days, hours, and minutes, respectively. For example, the following command finds files for which more than 1 year, 10 days, 5 hours, and 10 minutes remain before expiration.

  # sfind -rremain 1y10d5h10m

• -rlonger time — Finds files that have retention periods longer than the specified amount of time. The time is specified as MyNdOhPm, where M, N, O, and P are arbitrary non-negative integers and y, d, h, and m represent the number of years, days, hours, and minutes, respectively. For example, the following command finds files that have retention periods longer than 10 days.

  # sfind -rlonger 10d

• -rpermanent — Finds files whose retention period is permanent.