/* 
* Copyright (c) 2001 by Sun Microsystems, Inc.
# All rights reserved.
#
#
*/ 

TEST NAME 

      CON5 - stress disk controllers and device drivers 

SYNOPSIS 

      CON5repeat [options] SOURCE_DIR TARGET_DIR iterations|duration [instances]

DESCRIPTION 

      CON5repeat is a test program designed to stress disk controllers and
      their device drivers, and test that the system functions correctly under
      heavy load. CON5repeat accomplishes this by running many concurrent
      instances of a basic test that copies and compares directories, and
      reports trouble if any of the copies fails or does not compare as
      expected.

      CON5 can also be made to function as an NFS stress test by using an NFS
      mount as the target directory.

OPTIONS 

       -n                        No commit; do the preliminary calculations
                                 and testing for preconditions, but don't really
                                 do the copying. If there is an error in any of
                                 the arguments, then exit(1); if there are no
                                 errors, then print the number instances that
                                 will actually be used to start, then exit(0).

       -v                        Verbose. Print various extra trace messages 
                                 to stderr. This is used primarily for 
				 debugging. The nature of the messages 
                                 produced is subject to change and is not part 
                                 of the supported CON5 interface. 

       -nofsck                   Normally, CON5 runs fsck -n on the file
                                 systems containing the source directory, the
                                 target directory, and root, after every
                                 iteration. This option prevents CON5 from
                                 running fsck. 

                                 Always enable -nofsck due to error running
                                 fsck during the test. If fsck is not disabled,
                                 the error causes CON5 to abort after one
                                 iteration. 

       -nofsck-root              Do not run fsck on the root file system. 
                                 This is useful when you want to run fsck 
				 on the source and destination directories, 
				 but you know that there is other activity 
				 on the system, such as other tests. So, it 
				 makes no sense to try to check the root 
				 file system because it will not be quiescent. 

       -disk-reserve kbytes      If you reserve disk space, it will be as 
                                 if the amount of disk space available is 
                                 that much less than it really is, and 
                                 that is reflected in the calculation of 
                                 the number of instances supportable by 
				 the available disk space. 

       -processes-per-instance   CON5 autoconfigures number of instances
                                 based on available space and available
                                 processes. It computes a budget based on its
                                 knowledge of how many processes each
                                 instance uses. This option overrides the
                                 number of processes per instance, and so,
                                 indirectly change the number of instances
                                 that are configured. 

       instances                 If instances is provided (it's optional), 
				 then CON5 never exceeds the given number of
				 concurrent instances. CON5 calculates the
				 largest number of instances that available
                                 disk space allows. If instances is specified 
                                 on the command line, then CON5 uses the
                                 smaller of the two numbers. If instances is 
                                 not specified, then CON5 uses the calculated
                                 value. 

OPERANDS 

       SOURCE_DIR   SOURCE_DIR is the path name of the directory from
                    which CON5 reads. CON5 does not modify anything
                    in this directory, so it can reside in a file system that
                    is mounted read-only. 

                    A good source-directory would be a copy of /kernel.
                    Although, CON5 does not modify /kernel explicitly,
                    it still causes the root file system to be modified
                    because all the files that are read have their access
                    times updated. If an error occurs while modifying a
                    block of inodes, the root file system can be lost. 

                    This directory should reside on the disk connected to
                    the controller being tested. 

       TARGET_DIR   All target copies get written to subdirectories of this
                    directory. Do not put anything you want in this
                    directory, as it might be lost or overwritten. 

                    This directory should reside on the disk connected to
                    the controller being tested. If CON5 is being used as
                    a network stress test, this directory should be NFS
                    mounted from a remote system. 

       iterations   How many times to repeat the whole process,
                    sequentially. How long an iteration lasts depends on
                    many things about the configuration of the system
                    and its load. You can usually specify 100 iterations
                    and then tell CON5 to terminate later. 

       duration     The test can be limited by a set duration in the
                    format hh:mm:ss. This duration might be exceeded
                    to allow completion of the last iteration started. 

      All options starting with -fault- are part of a mechanism for injecting
      artificial faults into CON5. These options are not ordinarily used. They
      are provided for debugging. They are used to run quick, controlled tests
      of the behavior of the higher layers in the face of failures. If CON5 is
      designed properly, then such failures would be rare. So, many code paths
      that should work reliably on the rare occasions when they are needed
      will not have been exercised very much, if CON5 were not tested by
      fault injection. 

       -fault-max-instances instances   Tells CON5 to artificially inject a
                                        failure of a fork() system call, with
                                        errno of EAGAIN for all instances
                                        above the given number. This is
                                        used to test behavior in the face of
                                        resource exhaustion, without really
                                        having to run tests that are large
                                        enough to exhaust system resources.

       -fault-cpio                      Cause a thread, chosen at random,
                                        to pretend that cpio failed, even if
                                        there was no error. 

       -fault-diff                      Cause a thread, chosen at random,
                                        to pretend that diff failed, even if
                                        there was no error and there were
                                        no differences. 

       -fault-file-add                  For a thread, chosen at random,
                                        after cpio runs but before running
                                        diff, add an extra file to the target
                                        directory. 

       -fault-file-drop                 For a thread, chosen at random,
                                        after cpio runs but before running
                                        diff, remove an arbitrary file from
                                        the target directory. 

OUTPUT 

      The test first outputs summary information about the duration,
      directories to be used and the number of concurrent instances. After that
      are produced results, line by line, showing the progress of the test.

      A progress line comprises four fields. The first field is the time (in
      UNIX seconds), and the second field is the time in the format
      YYYYMMDDhhmmss. The third field is the time since the test started, and
      the last field is a text entry describing the status of the test.

DURATION 

      24 hours 

POSSIBLE CONCURRENT TESTS 

      This test is designed to use most of the resources of the machine, so it
      does not run well with other tests. 

CAVEATS 

      * Run CON5 with the '-nofsck' option to avoid problems running fsck after
        each iteration.

      * Create a source directory. Note that it is safer not to use /kernel due
        to the possibility of file system corruption. For example:

        # cp -r /kernel /tmp/kernelcopy 

      * If CON5 fails, it creates a file called 'CON5.failed'. You must remove
        this file for CON5 to start normally.

EXAMPLES 

      This example runs CON5 using /tmp/CON5src as the source, and
      /tmp/CON5dest as the actual test directory. It should run for 1 hour.
      Because each loop of the test (in this case) takes 17 to 18 minutes
      to run, the test actually lasts 1 hour, 11 minutes.

      # ./CON5repeat -nofsck /tmp/CON5src /tmp/CON5dest 1:00:00
      Source      directory: /tmp/CON5src
      Destination directory: /tmp/CON5dest
      Time limit           :    1:00:00 (3600 sec)
      Concurrent  instances: 12
      950098596 20000209121636    0:00:00: Start.
      950099636 20000209123356    0:17:20: Iteration 001 complete.
      950100754 20000209125234    0:35:58: Iteration 002 complete.
      950101811 20000209131011    0:53:35: Iteration 003 complete.
      950102866 20000209132746    1:11:10: Iteration 004 complete.
      950102866 20000209132746    1:11:10: !PASS: Done.
      # 

REFERENCES 

      fsck(1M) 
