fcladm - VxFS File Change Log administration utility
fcladm clear eventlist mount_point
fcladm -s savefile dump mount_point
fcladm [-s savefile] off mount_point
fcladm on [-o version=ver ] mount_point
fcladm [-cdfghit] print offset mount_point
fcladm -s savefile restore restorefile
fcladm set eventlist mount_point
The fcladm command performs online administration functions for the Veritas File System File Change Log (FCL) feature. This includes operations such as activating, deactivating, and removing the FCL; specifying the set of events for tracking; and saving and restoring the FCL file for off-host processing. The fcladm command also enables you to set a synchronization point in the FCL, display the current FCL state, or print the contents of the FCL in ASCII format.
The File Change Log is a quasi-regular file in the file system namespace that resides at mount_point/lost+found/changelog. This file can be opened, read, and closed. You can also seek to offsets within the file. However, to prevent corruption of the FCL, operations such as write, rename, and memory mapping are prohibited. The FCL file contains an FCL superblock that stores the meta-information about the FCL, followed by a number of FCL records. Each FCL record typically contains information such as file or directory changes along with the type of change. In addition, each record by itself, or in conjunction with adjacent records, tracks a file system event.
When a file system is created and mounted, the FCL is not enabled by default. Changes to the files and directories of the file system are not automatically logged in the FCL. You must enable the FCL using the on keyword. A newly created FCL initially contains only the superblock, along with the superblock state. To stop logging file system activity, use the the off keyword to de-activate the FCL. When the FCL is off, the FCL file remains at mount_point/lost+found/changelog. You can only remove or delete the FCL by using the rm keyword.
If needed, applications may offload FCL processing to a different system. However, physical layout restrictions may prevent the direct transfer of an FCL file to an off-host system. In such cases, you must first transfer an image of the FCL using the dump keyword. You can then restore the saved fileimage on an off-host system using the restore keyword.
The FCL was first introduced in VxFS 4.0. Version 3 was the FCL version for VxFS 4.1. Version 4 is the default version for VxFS 5.0. For backwards compatibility, VxFS 5.0 supports both versions 3 and 4.
No cluster issues; the command operates the same on cluster file systems.
The synchronization point in the FCL can also be set using the VxFS FCL sync API. See the vxfs_fcl_sync(3) manual page.
fcladm operates only on file systems using the Version 6 or 7 disk layout.
The FCL feature is not available on file systems created with the nolargefiles option.
Only a superuser can run the fcladm command.
The VX_FCL_MTIME_CHG
record is updated when the time stamps of the inode are changed by an external event, such as the touch command. During a read or write access of the file, the record is not updated for atime
or mtime
changes.
Access control lists updates do not produce a mode change record.
In some cases, the state printed by the state keyword might differ from the state displayed in the FCL superblock by the print keyword. For example, if the FCL is turned on when a Storage Checkpoint is created, the fcladm print command shows the FCL superblock state as ON. However, if the Storage Checkpoint is mounted as read-only, the fcladm state command shows the Storage Checkpoint state as OFF. No activities are recorded in the FCL file for a read only file system.
If a future release of VxFS containing an FCL file higher than Version 4 is ever downgraded to VxFS 5.0, most fcladm keywords may not function properly. In such cases, it is recommended to remove the higher version FCL file using fcladm rm and to re-activate it using fcladm on.
Disables the recording of events specifed in the eventlist for the File Change Log.
Creates a regular file image of the FCL file that can then be sent to an off-host processing system. This file has a different format than the FCL file. You must restore the file with the restore keyword, before it can be processed through the FCI API.
Deactivates the FCL on a mounted file system and clears the FCL contents. Use the -s option to save a copy of the FCL as needed. See OPTIONS.
Activates the FCL on a mounted file system. VxFS 5.0 supports either FCL file versions 3 or 4. You can specify the version with the on keyword. If no version is specified, fcladm defaults to Version 4.
Prints the contents of the the FCL file starting from the specified offset. If the offset is 0, print displays the FCL super block, which occupies the first block of the FCL file. Otherwise, print displays the FCL records starting from the specified offset to end of the FCL file using the standard output.
Restores a file from an FCL image created by dump keyword. The restored file created by the restore keyword produces a formatted file that can be sent to the FCL API.
Removes the FCL file. You must first deactivate the FCL before removing an FCL file.
Enables the recording specified by the eventlist for the FCL. More than one option can be set to enable the simultaneous logging of multiple events. See OPTIONS.
Writes the current state of the FCL to the standard output.
Brings the FCL to a stable state by flushing the associated data from an FCL recording interval. For cluster file systems, sync also merges the private views or individual FCL records into a single FCL file. In addition, sync prints a standard output of the last offset into the FCL file before the sync operation takes place.
Certain events such as data writes have an associated time interval that specify when the write event can be logged in the FCL. If a write event falls inside the time interval, it is not logged. See fcl_winterval in the vxtunefs(1M) manual page. sync also resets the FCL write interval for data write records, which forces the next write to each file in the file system to write a record in the FCL file.
Specifies where the directory of the file system containing the File Change Log is mounted.
Specifies the version of the FCL file to be created. This can be either Version 3 or 4. If no version is specified, the default is 4.
Specifies an offset (in bytes) in the FCL file. This indicates where to begin printing the FCL file. Use this option in combination with the print keyword to produce an ASCII display of the FCL contents. The offset must always be 32-byte aligned.
Specifies the name of the saved FCL file image. This image can be shipped to a different system and restored for off-host processing.
Specifies the name of the FCL file to restore that was created earlier by savefile. The restored file is a regular file, unlike the original FCL file.
Specifies a list of the following events: accessinfo, fileopen, filestats. You may list multiple events, by separating them with a common. Use this option in conjunction with the set or clear keywords to optionally turn on or off the recording of the specified events.
Enables recording information about the process that accessed the file in each FCL record. This includes the process ID, the real and effective user and group IDs of the process, and the ID of the node from which the file/ directory was accessed. The node ID is significant only in cases where the file system is mounted from multiple nodes. The node ID is specified in the LLT configuration.
Enables file open recordings. Whenever a file is opened, this results in an FCL record that contains the command name of the process that opened the file.
Enables recording of file I/O statistics to the FCL. The FCL is used as a persistent store for the collected I/O statistics. When logging of this event is enabled, the I/O statistics collected in-core, get written to the FCL periodically.
The following options are valid only with the print keyword.
Prints the directory inode number field. The directory inode is only stored in an FCL record when the record is a VX_FCL_LINK, VX_FCL_UNLINK, or VX_FCL_RENAME FCL change type.
Prints the file name field. The file name is only stored after an FCL record when the record is a VX_FCL_LINK, VX_FCL_UNLINK, or VX_FCL_RENAME FCL change type.
Prints the inode generation count field.
Displays the field names before printing the contents of the FCL.
Prints the inode number field.
To turn on the FCL for the file system mounted on /home, type the following:
To turn off the FCL for a file system mounted on /export/data, type the following:
The following example removes the FCL file for a file system mounted on /export/reports. The FCL must be OFF before it can be removed.
To turn on the logging of file openings for the file system mounted on /home once the command is executed, type the following:
To turn off the logging of file openings for the file system mounted on /home, type the following:
To obtain the current FCL state for a file system mounted on /home, type the following:
To disable the logging of file opens, file I/O statistics, and access information for the file system mounted on /home, type the following:
# fcladm clear fileopen,filestats,accessinfo /home
To print all the FCL records present in an FCL file, you can print the contents of the FCL superblock by skipping offset 0, and using the first valid offset (foff) as an argument to the subsequent print.
For example, to print an ASCII display of the on-disk FCL superblock from offset 0 and to obtain information about the FCL for the file system mounted on /export/data, type the following:
time 1087979247 930092 (Wed 23 Jun 2004 04:27:27 PM CST CDT)
Use the foff (1024) as the offset to the next call to print with the -h option to display the field names and the -citdf options to display the change type, inode number, time stamp, directory inode number, and file name for each record.
# fcladm -h -citdf print 0x400 /export/data
Change Type Inode Number Timestamp
Create 5 Thu Apr 10 13:49:54 2003
Extend 5 Thu Apr 10 13:50:02 2003
Create 6 Thu Apr 10 13:50:30 2003
Unlink 6 Thu Apr 10 13:50:38 2003
When the FCL superblock is displayed using the print keyword, the output contains the following information:
When a non-zero offset is specified with the print keyword, fcladm prints the contents of the FCL starting at the specified offset until the end of the file. The output consists of one physical FCL record per line, where each file system event corresponds to one or more physical FCL records. The output also shows the event type whether the tracking of additional information (for example, access information) is enabled or not.
Each physical FCL record typically contains the following basic information:
Certain records have additional information that is specific to each event type. This information is either stored along with the base FCL record or as an extension record. The extension record is another physical FCL record that immediately follows the base record. For instance in the case of a file unlink, the name of the file that was unlinked and the inode number of the file directory is stored as a part of the unlink record. However, if the tracking of access information is enabled, the extra access information is stored as a separate FCL record which immediately follows the original record. For example, if accessinfo has been enabled, a file create results in a "Create" record followed by an "AccessInfo" record.
The following file system events produce an FCL record that contains only the basic information listed above. The change type is the string that is displayed by the print keyword.
--------------------------- -----------------
File system event type Change type
--------------------------- -----------------
--------------------------- -----------------
File undelete through the Undelete
--------------------------- ------------------
Extending write to the file Extend
--------------------------- ------------------
Write to a file that Overwrite
--------------------------- ------------------
File truncates, i.e., Truncate
--------------------------- ------------------
Extended attribute change Ext_Attr_Chg
--------------------------- ------------------
Operations that result in Hole_Punch
--------------------------- ------------------
Symbolic link creation Sym_Link
--------------------------- ------------------
Inode extent attributes ExtnAttrChg
--------------------------- ------------------
Change in the number of ReserveChg
--------------------------- ------------------
File mode change. See the ModeChg
--------------------------- -------------------
File owner change. See OwnerChg
--------------------------- -------------------
File group change. See GroupChg
--------------------------- -------------------
File modification time MtimeChg
--------------------------- -------------------
In addition, the following system events also contain this information:
--------------------------- -----------------
File system event type Change type
--------------------------- -----------------
Create a hard link to an Add_Link
--------------------------- -----------------
File removal or unlink via Unlink
--------------------------- -----------------
Rename an existing file. Rename
--------------------------- -----------------
In 5.0, the information maintained with each record and events cause the following records to be written:
If the FileOpen event is enabled through the set keyword, every file open produces an FCL record, subject to the fcl_ointerval tunable (see the vxtunefs(1m) manual page). A file open record is displayed with the change type, FileOpen, followed by the inode number and generation count of the opened file, along with the time of the file opening and the process command name that opened the file.
This record contains the file I/O statistics which is periodically written to the FCL by VxFS. Apart from the basic information, each FileStats record contains the I/O statistics comprising the number of reads to the file, the number of writes, the number of blocks read, the number of blocks written, the average time for each read, and the average time for each write. This is followed by the last reset time, the node ID from where the statistics were written and the reset flag. The I/O statistics recorded in the FCL are cumulative from the last reset time to the next. The last reset time is updated each time the reset flag is set to 1.
The FclEvntMask record is written to the FCL whenever the recording of a set of events is enabled or disabled through the set or clear keywords. The record contains two hexadecimal numbers that represent the old set of events and the new set of events, i.e., the eventmask that was present in the FCL superblock before and after the set or clear operation.
When recording of access information is enabled through the set keyword, an AccessInfo record is written with each event logged in the FCL, immediately following the change record. The information printed for every AccessInfo record contains the real user ID, group ID of the process that performed the operation, the effective UID and group ID, followed by the node ID and the process ID. The AccessInfo record exists only as an extension record to some existing change type, but never independently. In addition, even if enabled, an AccessInfo record may not always be present for certain file system internal operations or when the access information is not available.
A call to fcladm print with just the offset and no extra options prints all the records in the FCL starting from that offset and all the information that is tracked with each record. However, new record types or information provided in a future VxFS release may not be available to an application or script that uses a Version 4 FCL. For compatibility, make sure that the script tries to interpret only the set of records enumerated in this man page and ignores other records.
The following example provides a script that periodically scans the file system to determine the set of file changes since the last scan. The script performs the following tasks:
# Get the previous synchronization point stored in syncfile.
# Set a synchronization point in the FCL and save the offset to
# syncfile. Print records starting from previous sync offset.
$ fcladm sync /mnt1 > syncfile
$ fcladm -citf print $syncoffset /mnt1
ModeChg 4 Thu 01 Jul 2004 12:51:10 AM
FCL clients can use the information stored in the FCL to:
To obtain the full file path name relative to the root of the file system, the inode number acquired from the FCL record must be passed to the VxFS Reverse Name Lookup (RNL) API. See the vxlsino(1M), vxfs_inotopath(3) and vxfs_inotopath_gen(3) manual pages. In cases where the file was renamed or removed, the directory inode number can be given to the RNL API to help obtain the full path name for the parent directory relative to the root of the file system. The file name stored in the FCL record can then be appended to this path to get the full file path name.
You can use the file generation count to determine whether an inode number was reused when another FCL record has the same inode number. However, you cannot use the file generation count to determine inode number reuse with the remove record. The generation count displayed in the remove record is the generation count of the directory inode and not of the inode that was removed.
Similarly, the user ID and group IDs displayed along in the AccessInfo records can be used in conjunction with the /etc/passwd file to determine the user and group names. The node ID printed with this record is important only in clusters configurations. With this information, you can use the lltstat command to obtain the hostname in a cluster.
/opt/VRTS/include/sys/fs/fcl.h
The header file containing the data structures and definitions used by the FCL.
vxlsino(1M), vxtunefs(1M), vxfs_fcl_sync(3), vxfs_inotopath(3), vxfs_inotopath_gen(3), tunefstab(4), vxfsio(7)