fcladm man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

fcladm(1M)							    fcladm(1M)

NAME
       fcladm - 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 ALSO
       vxlsino(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)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net