/usr/src/linux/fs//Utils/README
logiso - isofs, iso-9660 file activity logging
Author: Michael Coulter		coulter@cup.hp.com
(C) Copyright 1995 by Michael Coulter.  All rights reserved.

Overview:
Installation:
   Kernel changes:
      Turning off logging:
   Logiso utilities:
      Setting up find_links:
      The config file:
      The cd_files file:
      Setting up the mirror directory:
      Environment variables:
Using the logiso utilities:
   Using logiso_copy:
   Using logiso_get:
   Using logiso_init:
   Using logiso_preview:
   Using logiso_stop:
Copying:
Disclaimer:
Acknowledgements:
History:
Bugs:


Overview:

   In most of what follows, it is presumed that you are executing commands
   as root.

   This package provides a facility to help you migrate to a hard disk
   the files which you use on a cd-rom and use symbolic links for the
   files which you don't use.

   The logiso package contains changes to make to the isofs file system
   to provide logging of disk activity on an iso-9660 cd-rom file system.
   The package also contains utilities to migrate logged files to your
   hard disk.

   The logging facility is on by default, but you can use an ioctl call
   to turn off logging and free up the kernel buffers (about 40K).  See
   "Kernel changes".  The logiso_stop command can be used to turn off
   logging.

   Once you have installed it, a typical usage scenario would be:

      1. You perform an operation and notice cd-rom activity.  You decide
         that you want to be able to do this operation without accessing
         the cd-rom.

      2. Clear the existing log so that you won't install other files.
         This will also start logging if it was turned off.
         Execute:

         	logiso_get /mount/path/cd-rom > /dev/null

         or (slower to execute, but easier to type):

         	logiso_preview > /dev/null

      3. Perform the operation again.  Even though the cd-rom light doesn't
         go on because the blocks are in the memory buffer, the cd-rom 
         file activity is still logged.

      4. If you want to see what you are going to install, execute:

      		logiso_preview 

         to print a list of the files and directories that will be copied
         to your hard disk.  This empties the log, so you must repeat 
         step 3 before proceeding with step 5.

      5. Install the files which were logged:

      		logiso_copy


Installation:

   First make sure that the following commands are already installed
   on your hard disk or the logiso_copy script will fail in the middle
   of installation when it tries to install a command:

   	cp
   	ln
   	mkdir
   	mv
   	rm

   Also, add /usr/src/linux/fs/isofs/Utils to your (and root's) path string.

   Installing the distributed files:

      Unpack the tar file while in the /usr/src/linux/fs/isofs directory.
      The directories RCS and Utils will be created.  

      Follow the directions in the subsections below to complete the
      installation.

   Kernel changes:

      The kernel changes implement three ioctl calls for the isofs file
      system (used to access iso-9660 file systems on a cd-rom).  The
      three calls are:

	 ISO_IOC_GETLOGSIZE returns the size of the buffer returned by
		   ISO_IOC_READLOG.  It also starts logging if it was off.

	 ISO_IOC_READLOG is given a pointer to a buffer and fills that buffer
		   with log information.  See ioctl.c and iso_fs.h and
		   logiso_get.c.

	 ISO_IOC_STOPLOG turns off logging and frees up the kernel buffers
		   (about 40K bytes) which hold the log information.


      The logging facility is initially on, but the kernel buffers are
      only allocated when the first event is logged.

      Compare your source files against the base versions of the files
      with rcs histories in /usr/src/linux/fs/isofs/RCS.  If the files
      are the same, you can use the last version of the file.  If not,
      make the corresponding changes in your files.  ioctl.c is a new
      file.

      Re-compile the kernel and boot with the new kernel after reading
      the following section, "Turning off logging".

      Turning off logging:

         Once you have gotten settled in, you will want to arrange to
         turn off logging after your system has re-booted.  Here
         are the lines that I added to /etc/rc.d/rc.local:

            # Turn off logging after waiting for the boot process to quiet down.
            if [ 0 = 0 ]
            then
            (sleep 20
             /usr/src/linux/fs/isofs/Utils/logiso_get -v > /tmp/last_isolog 2>&1
             /usr/src/linux/fs/isofs/Utils/logiso_stop >> /tmp/last_isolog 2>&1
	    ) &  > /dev/null 2>&1
	    fi

         The "0 = 0" test makes it easy to turn this code off by changing
         the test to "0 = 1".


   Logiso utilities:

      In the /usr/src/linux/fs/isofs/Utils directory, execute:

      		make

      Setting up find_links:

         The find_links script is used by the check_links script to
         find symbolic links.  If you want to execute find_links
         against "/", you may need to edit find_links to prune certain
         directories on your system or make your own find_links script
         and enter its path in the config file.

      The config file:

	 Edit the file config to match your system requirements.

	 Basically you need to tell the utilities where the cd-rom is
	 mounted and what directory will mirror the cd-rom.

	 I recommend that you use a dedicated directory to mirror the
	 cd-rom rather than using the root directory to mirror the
	 cd-rom.  It will make it easier to account for disk space usage
	 and to back out decisions you make to migrate files to your
	 hard disk.

	 Here is the setup I use:  The Walnut Creek CD-ROM edition of
	 Yggdrasil Plug-and-Play Linux installs itself with /system_cd
	 as the mount point of the cd-rom.  I moved the mount point to
	 /cdmnt and made /system_cd the mirror directory.  It is a good
	 idea to have the mount point in the same directory as the
	 original mount point so that relative paths like
	 ../../var will get to the right place.

	 The basic scheme is that the only links to the cd-rom are from
	 paths or directories below the mirror directory to the real
	 file or directory (not a link) on the cd-rom.  All other
	 links go through the mirror directory.

	 If you have multiple cd-rom drives or want to mirror different
	 cd volumes with separate mirror directories, you can have
	 different config files with different prefixes.  The commands
	 which use the config file have an optional pair of parameters:

	 	-d config_prefix

         For example,

         	logiso_copy -d m2

         would use the m2config config file which could specify a different
         mount point, mirror directory and cd_files file.

      The cd_files file:

         The cd_files file contains a list of all the files on the
         cd-rom and the inode number of each file.  The path to the
         cd_files file is set in the config file.  In the config file
         provided, the name of the file is "cd_files" in the isofs/Utils
         directory.

         If you are want to save disk space, you can compress the
         cd_files file with gzip.  It will be uncompressed for use.
         This will take some time.  If you are using logiso_copy
         frequently, you will want to uncompress the file.

      Setting up the mirror directory:

         Once you have set up the config file, you can initialize the
         mirror directory by executing:

         	logiso_init

         WARNING: logiso_init will remove the mirror directory and 
         everything below it (unless your mirror directory is "/").

         Logiso_init will create the mirror directory and populate it
         with symbolic links to everything in the cd mount point.

         You are now ready to use the utilities.  See the scenario in the
         "Overview" section and the descriptions in the following
         "Using the logiso utilities" section.


Using the logiso utilities:

   Read over the scenario described in the "Overview" section. 

   Note that the log will only hold about 5,000 entries.  The log is
   flushed when it fills, so don't try to do too much work before
   you use logiso_copy.  In any case, you can repeat the operation
   and logiso_copy to get files that were missed on the first round.

   See the section, "The config file" for a discussion of the 
   "-d config_prefix" option which appears in a number of the commands.


   Using logiso_copy:

      USAGE: logiso_copy [ -d config_prefix ]

      Copies the files or directories of the logged inodes to the 
      corresponding location below the mirror directory.

      This command will empty the log.  It will also turn on logging
      if it was turned off with logiso_stop.


   Using logiso_get:

      USAGE: logiso_get  [ -v ] cd_mount_point [ log_file ]

      Get the isofs usage log and place it in log_file.  The log is written
      to stdout if log_file is not given.

      This command will empty the log.  It will also turn on logging
      if it was turned off with logiso_stop.


   Using logiso_init:

      USAGE: logiso_init [ -d config_prefix ]

      Initialize the mirror directory to mirror the top level of the
      mount point directory.

      WARNING: logiso_init will remove the mirror directory and 
      everything below it (unless your mirror directory is "/").


   Using logiso_preview:

      USAGE: logiso_preview  [ -d config_prefix ]

      List the files that would have been installed by logiso_copy.
      This command will empty the log.  It will also turn on logging
      if it was turned off with logiso_stop.


   Using logiso_stop:

       USAGE: logiso_stop  cd-mount-point-or-file

       Stop the logging system.  Deallocate the kernel buffers in which
       the log is kept.

Copying:
  
   Everyone is granted permission to copy and redistribute the files in
   this package provided:
      
        1. No changes are made to any of the files in the distribution and
           all of the files are provided in any copy.

	2. No charge is made for this software.  This clause shall not  
	   be construed as constraining other software distributed on
	   the same medium as this software, nor is a distribution fee
	   considered a charge.

Disclaimer:

   This package is provided as-is.  Michael Coulter makes no express or
   implied warranty of any kind with respect to this package.  Michael
   Coulter shall not be liable for any direct indirect, special, incidental
   or consequential damages (whether based on contract, tort or any other
   legal theory) arising in any way from use of any part of this package.

Acknowledgements:

   Cam Johnson for suggesting that some users might want the cd_files
   file to be compressed to save space and for looking over the
   implementation.

History:

   0.1  Initial version exposed to a handful of people.

   0.2 * Allow the cd_files file to be compressed to save disk space.

       * Support multiple cd-rom drives and/or multiple mirror directories
         with the following features:

	  * Add the device number in addition to the inode number to
	    each log entry.  Provide the device number accessed in the
	    header information.  Logiso_get (and therefore logiso_copy
	    and logiso_preview) only reports the files on the device
	    indicated by mount point.

	  * Add -d option to logiso_copy and logiso_preview to conveniently
	    support multiple cd-rom's or separate mirror directories.   

   0.3 * Added copyright notices.  Copying policy and disclaimer in README.
   
Bugs:

   Sometimes accesses to a directory will continue to be logged after
   the directory has been mirrored with a directory of symbolic links.

   My best guess is that in some cases, a link to a file on the 
   cd-rom results in an access to the directory on the cd-rom which
   contains the file.  Replacing the link with a copy of the
   file (or a directory filled with links if the file is a directory)
   eliminates the access to the cd-rom.  The hard part is figuring out
   which file is involved because only the directory containing it is
   logged.

   1.  /mnt/system_cd/usr/lib/emacs/19.25/lisp/term/x-win.elc showed up
       in the log, but after it was installed, the link
       /mnt/system_cd/usr/lib/emacs/19.25/lisp/term/x-win.el was  causing
       a cd-rom access but only its directory was logged.

       This seems to be a general property.  I have added a kludge to
       mirror a .el file (if it exists) when a .elc file is mirrored in.

   2. Files which were not logged but which resulted in accesses to the
      directory which contained them:

      Simple files:

        WHAT						WHY
        =====================				==========
        *.el files as from note #1.			emacs
      	/system_cd/usr/bin/look				emacs
      	/system_cd/usr/dict/words			emacs
      	/system_cd/usr/lib/emacs/19.25/etc/GNU		emacs

      Directories:

        /system_cd/usr/packages/interviews/bin/LINUX	PATH string
	/system_cd/usr/lib/emacs/19.25/i486-linux	emacs
	/system_cd/usr/packages/sound/man		MANPATH
	/system_cd/usr/packages/pbm/man			MANPATH
	/system_cd/usr/packages/openwin/man		MANPATH
	/system_cd/usr/packages/interviews/man		MANPATH
	/system_cd/usr/packages/andrew/man		MANPATH
	/system_cd/usr/X11/man				MANPATH
