README 5.65 KB
Newer Older
Sampo Saaristo's avatar
Sampo Saaristo committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
				RUDE and CRUDE
				==============


 This project is distributed under the terms of GNU General Public License
 Version 2, which can be found e.g. in the file COPYING that is located
 in this very same directory. Read it for more detailed information.


 The copyright is owned by the authors:

 (C) 1999 Juha Laine and Sampo Saaristo



INTRODUCTION (very short):
--------------------------


* RUDE [Real-time UDP Data Emitter]

       As the name says, this piece of program can generate UDP traffic
       to the network. Read more from "README.rude".


* CRUDE [Collector for RUDE]

       This program can log the traffic that is generated with the RUDE
       for later processing. Read more from "README.crude".



COMPILATION AND INSTALLATION INSTRUCTIONS:
------------------------------------------

 1. This package you have received should contain the automatic 'configure'
    script in the source code root directory. If this is true you can jump
    into the step 4. Otherwise read also the steps 2. and 3. that explain
    the procedure how to create the configure script with the GNU autoconf
    utilities.


 2. So you have the very clean version. Alright. Before you can compile
    the program you should make the configuration script(s) and other
    files with the GNU autoconf utilities. In other words you require
    properly installed 'autoheader' and 'autoconf' programs. At least
    version 2.13 of the GNU autoconf tools seems to work fine.
    [ After those programs are installed you can move on.... ]


 3. You need to generate some header file(s) and the configuration script
    with the following commands (you must be in the program's source code
    root directory):

yorn's avatar
yorn committed
55
	autoheader autoconf/configure.in
Sampo Saaristo's avatar
Sampo Saaristo committed
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
	autoconf autoconf/configure.in > configure
	chmod 755 configure


 4. Now you are ready to go on and configure this software package. As
    usual, you can say './configure --help' to get the full list of
    configuring switches. Here are only the usually required options:

	--prefix=PREFIX         = Installation directory root (/usr/local/)
	--enable-debug          = Enable compiler option -g
	--enable-wall           = Enable compiler option -Wall (gcc only)
	--with-debug-lvl=[0-7]  = Set program debugging output level

    RECOMMENDED CONFIGURATION COMMAND IS:
    -------------------------------------

	./configure --enable-wall --with-debug-lvl=3


 5. 'make all'

    So far this program is tested on Linux and Solaris2.6 OS's and
    seems to compile/operate without any major drawbacks. Your mileage
    may vary...


 6. 'make install'

    USE MANUAL INSTALLATION IF THIS FAILS. SORRY 'BOUT THAT :)
    Only ROOT can successfully execute this command.

 ...and that's it.


EXAMPLES AND SOME HELPER APPLICATIONS
-------------------------------------

 ** You can find well-commented example script for the rude in this
    directory under name "example.cfg". Read also the "README.rude" file.


 ** There are some example scripts (made with Perl) that can manipulate
    the decoded output from CRUDE. They are located in the "scripts"
    directory. They parse the decoded/text output from the crude and
    produce somewhat more informatic output e.g. to use with gnuplot
    program.

    BEFORE EXECUTING, CHECK THAT THE FIRST LINE OF THOSE SCRIPTS MATCH
    YOUR CONFIGURATION - i.e. the correct path to the Perl, which must
    be installed in your system.


    crude_jitter.pl produces N output files (one for each detected flow)
    under names "jitter.<flow ID>". These files contain 2 columns.

	- 1st = column lists the packet sequence numbers
	- 2nd = column lists the time between this and the previous packet

    So it is not actually "jitter" but if plotted it can be easily observed.
    If the packet was lost the script skips to the next packet and marks
    the error into the 3rd usually invisible column with negative error
    index...


    crude_parse.pl produces also N output files (one for each detected flow)
    under names "data.<flow ID>". These files contain 6 columns.

	- 1st = flow ID
	- 2nd = timeslot ("sample time")
	- 3rd = average bandwith usage during this timeslot
	- 4th = total number of sent bytes for this flow
	- 5th = received packet INDEX
	- 6th = stamped packet sequence number


    Both of these scripts understand the "-h" command line option that
    prints out the short usage/command line switch instructions. The
    input file should be the decoded (text formatted) file produced by
    the crude utility.

    Use with care - they are still under construction :)


HOW TO ADD/CREATE NEW TRAFFIC CLASS
-----------------------------------

  Here will be short (step by step) instructions for programmers that
  wish to add own traffic/flow types to rude.


  -=* THIS SECTION IS STILL UNDER CONSTRUCTION, SO IT GIVES JUST AN *=-
  -=* OVERVIEW AND SOME IMPORTANT STEPS ARE PROPABLY MISSING :)     *=-


  1)	Add your flow type to the 'enum f_type' in "../include/rude.h"

  2)	Create the private struct for this flows parameters in
        "../include/rude.h"

  3)    Add the new struct to the 'union params' in 'struct flow_cfg'
        in "../include/rude.h"

  4)    Add the name->f_type conversion in the function 'check_type()'
	in "../rude/parse.c"

  5)    Add the flow transmission function in to "../rude/flow_txmit.c"

  6)	Add the parsing to the function 'flow_on()' in "../rude/parse.c"

  7)	Add the parsing to the function 'flow_modify()' in "../rude/parse.c"

  8)	Add the case that checks the maximum packet size to the end of
	'read_cfg()' in "../rude/parse.c"

  9)	Add necessary commands to free acquired memory (if required) in
	'clean_up()' in "../rude/flow_cntl.c"

<...Here should be more info when the implementation gets more stable...>