fcladm(1M)fcladm(1M)NAMEfcladm - VxFS File Change Log administration utility
SYNOPSIS
/opt/VRTS/bin/fcladm clear eventlist mount_point
/opt/VRTS/bin/fcladm -s savefile dump mount_point
/opt/VRTS/bin/fcladm [-s savefile] off mount_point
/opt/VRTS/bin/fcladm on [-o version=ver ] mount_point
/opt/VRTS/bin/fcladm [-cdfghit] print offset mount_point
/opt/VRTS/bin/fcladm -s savefile restore restorefile
/opt/VRTS/bin/fcladm rm mount_point
/opt/VRTS/bin/fcladm set eventlist mount_point
/opt/VRTS/bin/fcladm state mount_point
/opt/VRTS/bin/fcladm sync mount_point
AVAILABILITY
VRTSvxfs
DESCRIPTION
The fcladm command performs online administration functions for the
Veritas File System File Change Log (FCL) feature. This includes oper‐
ations such as activating, deactivating, and removing the FCL; specify‐
ing 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 names‐
pace 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 con‐
tains an FCL superblock that stores the meta-information about the FCL,
followed by a number of FCL records. Each FCL record typically con‐
tains 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 sys‐
tem 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 sys‐
tem. 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 ver‐
sion 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.
Cluster File System Issues
No cluster issues; the command operates the same on cluster file sys‐
tems.
NOTES
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 lay‐
out.
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. How‐
ever, 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 ver‐
sion FCL file using fcladm rm and to re-activate it using fcladm on.
KEYWORDS
clear Disables the recording of events specifed in the eventlist
for the File Change Log.
dump Creates a regular file image of the FCL file that can then be
sent to an off-host processing system. This file has a dif‐
ferent format than the FCL file. You must restore the file
with the restore keyword, before it can be processed through
the FCI API.
off 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.
on Activates the FCL on a mounted file system. VxFS 5.0 sup‐
ports 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.
print 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.
restore 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.
rm Removes the FCL file. You must first deactivate the FCL
before removing an FCL file.
set 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.
state Writes the current state of the FCL to the standard output.
sync Brings the FCL to a stable state by flushing the associated
data from an FCL recording interval. For cluster file sys‐
tems, 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.
OPTIONS
mount_point
Specifies where the directory of the file system con‐
taining the File Change Log is mounted.
ver 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.
offset 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.
savefile Specifies the name of the saved FCL file image. This
image can be shipped to a different system and
restored for off-host processing.
restorefile
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.
eventlist 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 option‐
ally turn on or off the recording of the specified
events.
accessinfo
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 or directory was
accessed. The node ID is significant only in
cases where the file system is mounted from mul‐
tiple nodes. The node ID is specified in the LLT
configuration.
fileopen
Enables file open recordings. Whenever a file is
opened, this results in an FCL record that con‐
tains the command name of the process that opened
the file.
filestats
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 col‐
lected in-core, get written to the FCL periodi‐
cally.
The following options are valid only with the print keyword.
-c Prints the change type field.
-d Prints the directory inode number field. The direc‐
tory 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.
-f 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.
-g Prints the inode generation count field.
-h Displays the field names before printing the contents
of the FCL.
-i Prints the inode number field.
-t Prints the time stamp field.
EXAMPLES
To turn on the FCL for the file system mounted on /home, type the fol‐
lowing:
# fcladm on /home
To turn off the FCL for a file system mounted on /export/data, type the
following:
# fcladm off /export/data
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.
# fcladm rm /export/reports
To turn on the logging of file openings for the file system mounted on
/home once the command is executed, type the following:
# fcladm set fileopen /home
To turn off the logging of file openings for the file system mounted on
/home, type the following:
# fcladm clear fileopen /home
To obtain the current FCL state for a file system mounted on /home,
type the following:
# fcladm state /home
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 sys‐
tem mounted on /export/data, type the following:
# fcladm print 0 /home
magic a506fcf5 version 2
time 1087979247 930092 (Wed 23 Jun 2004 04:27:27 PM CST CDT)
state ON sync 1
foff 1024 loff 63744
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
Dir Inode Number Filename
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
2 bar
Printing FCL Contents
When the FCL superblock is displayed using the print keyword, the out‐
put contains the following information:
· The magic number that identifies the FCL file. This is always
a506fcf5.
· The version of the FCL file. This is either 3 or 4 for VxFS 5.0.
· The last time that the FCL was activated. This can be used by a
script that scans the FCL periodically to check if the FCL has
been active continuously since its last scan.
· The activation state of the FCL. If the state is ON, changes to
the file system are logged in the FCL.
· The first and last valid offsets in the FCL: foff and loff. FCL
records are present only between these offsets.
· The eventmask, which is a hexadecimal number representing the set
of events being tracked. If the eventmask is interpreted as a
64-bit number and the event 'e' is defined as '20' in the fcl.h
header, the logging of event 'e' is enabled when the 20th bit is
set in the eventmask.
· The eventmask change time, which represents the time that the
eventmask was last changed, that is, the time when the set of
events was last changed through the set or clear keyword.
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, such as access
information, is enabled.
Each physical FCL record typically contains the following basic
information:
· The change or event type.
· The inode number and generation count of the file or directory
that was changed.
· The time when the event occurred.
FCL Event Types
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 that immediately follows the origi‐
nal 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 create Create
e.g. ls > newfile
--------------------------------------------
File undelete through the Undelete
VxFS internal file promote
API.
---------------------------------------------
Extending write to the file Extend
i.e., one that increases
the size of the file
---------------------------------------------
Write to a file that Overwrite
overwrites existing
contents, but does not
increase the file size
---------------------------------------------
File truncates, i.e., Truncate
operations that reduce the
file size
---------------------------------------------
Extended attribute change Ext_Attr_Chg
---------------------------------------------
Operations that result in Hole_Punch
deallocating some of the
internal blocks of the file
---------------------------------------------
Symbolic link creation Sym_Link
e.g., ln -s
file symlink
---------------------------------------------
Inode extent attributes ExtnAttrChg
change
---------------------------------------------
Change in the number of ReserveChg
blocks reserved to a file.
The reservation can be set
through the
setext command. See the
setext(1M) manual page.
---------------------------------------------
File mode change. See the ModeChg
chmod(1) manual page.
----------------------------------------------
File owner change. See OwnerChg
the
chown(1) manual page.
----------------------------------------------
File group change. See GroupChg
the
chgrp(1) manual page.
----------------------------------------------
File modification time MtimeChg
change. See the
touch(1) manual page.
----------------------------------------------
In addition, the following system events also contain this information:
· A file name.
· The inode number.
· The generation count of the directory containing the file name.
--------------------------------------------
File system event type Change type
--------------------------------------------
Create a hard link to an Add_Link
existing file. See the
ln(1) manual page.
This FCL record contains
the file name and the
directory inode number of
the new link.
--------------------------------------------
File removal or unlink via Unlink
the rm(1) or
unlink(2) manual
pages. The directory
information corresponds to
the removed file.
--------------------------------------------
Rename an existing file. Rename
See the
mv(1) manual page.
This record contains
the old file name.
--------------------------------------------
In 5.0, the information maintained with each record and events cause
the following records to be written:
FileOpen 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.
FileStats This record contains the file I/O statistics that are period‐
ically written to the FCL by VxFS. Apart from the basic
information, each FileStats record contains the I/O statis‐
tics 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.
FclEvntMask
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 hexadeci‐
mal numbers that represent the old set of events and the new
set of events. That is, the numbers represent the eventmask
that was present in the FCL superblock before and after the
set or clear operation.
AccessInfo
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 infor‐
mation 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.
Synchronizing the FCL
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:
· Maintains a syncfile containing the synchronization offset from
the last scan.
· Uses the offset in this file as the starting point for the cur‐
rent scan.
· Gets a synchronization point and updates the syncfile with this
offset.
# 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.
$ syncoffset=`cat syncfile`
$ fcladm sync /mnt1 > syncfile
$ fcladm-citf print $syncoffset /mnt1
ModeChg 4 Thu 01 Jul 2004 12:51:10 AM
Extend 4 Thu 01 Jul 2004 12:51:20 AM
FileOpen 1071 Thu 01 Jul 2004 12:52:10 AM a.out
Interpreting the Contents of the FCL
FCL clients can use the information stored in the FCL to:
· Determine the full path name of every file changed in the file
system, based on several categories of changes
· Determine whether an inode number was reused
· Determine the user and group names and obtain hostnames in a
cluster configuration
To obtain the full file path name relative to the root of the file sys‐
tem, the inode number acquired from the FCL record must be passed to
the VxFS Reverse Name Lookup (RNL) API. See the vxlsino(1M), vxfs_ino‐
topath(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 deter‐
mine 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.
FILES
lost+found/changelog The FCL file.
/opt/VRTS/include/sys/fs/fcl.h
The header file containing the data
structures and definitions used by the
FCL.
/etc/vx/tunefstab VxFS tuning parameters table.
SEE ALSOvxlsino(1M), vxtunefs(1M), vxfs_fcl_sync(3), vxfs_inotopath(3),
vxfs_inotopath_gen(3), tunefstab(4), vxfsio(7)VxFS 5.0 7 Jan 2008 fcladm(1M)