Commit 1bfe4085 authored by Sampo Saaristo's avatar Sampo Saaristo

Initial revision

parents
This diff is collapsed.
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):
autoheader -l ./autoconf
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...>
CRUDE - version 0.60
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
From Webster's Revised Unabridged Dictionary (1913) [web1913]:
Crude \Crude\ (kr[udd]d), a.
Unripe; not mature or perfect; immature.
I come to pluck your berries harsh and crude.
--Milton.
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
CRUDE is the receiver and logging utility for flows that are generated
with the RUDE tool. In the default operation mode CRUDE prints the
information to standard output, so you'll have to redirect it to
file if you like to process it later on.
Our recommendation is to log the data into file with the '-l' option.
This reduces I/O operations because the data is logged in binary
format and soforth improves performance. You can decode the file
later on with the option '-d'.
BUGs and feature wishes should be reported into one of the following
E-mail addresses:
james@cs.tut.fi
sambo@cc.tut.fi
rprior@inescporto.pt
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
Commandline syntax:
crude [ -h | -v | -d <file> | [-p <port>] [-i <add>] [-l <file>] [-n #] ]
-h Print short help.
-v Print version information
-d <file> Use this option to decode the binary
formatted file which was generated from
the capture with the '-l' option.
-p <port> Set the UDP port to listen to. The
default port is 10001.
-i <add> Set the physical interface to listen
from. The <add> argument is the IP
addres for the specific interface in
numerical dotted notation (a.b.c.d).
If this is not set, the program will
use the INADDR_ANY address :)
-l <file> Log the results into file <file> in
binary format. The default behaviour is
to print out the decoded info to stdout.
-n # Set the number of packets to capture. The
default vaulue is 0, which means until
interrupted with CTRL+C.
-s #[,#...] Instead of logging results to a file
calculate some statistics on-the-fly.
-P <priority> Set the process real-time priority.
Only root can do that. Be carefull -
this might lock up your computer !!!
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
RUDE - version 0.60
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
From Jargon File (4.0.0/24 July 1996) [jargon]:
rude [WPI] /adj./
1. (of a program) Badly written.
2. Functionally poor, e.g., a program that is very difficult to
use because of gratuitously poor (random?) design decisions.
Oppose {cuspy}.
3. Anything that manipulates a shared resource without regard for
its other users in such a way as to cause a (non-fatal) problem.
Examples: programs that change tty modes without resetting them
on exit, or windowing programs that keep forcing themselves to
the top of the window stack. Compare {all-elbows}.
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
Commandline syntax:
rude [ -h | -v | -s <script file> ] [ -p <priority level ]
-h Print short help.
-v Print version information
-s <script file> Use this option to point out the correct
script file that describes the flows. This
option is compulsory if you want to generate
traffic.
-P <priority> Set the process real-time priority.
Only root can do that. Be carefull -
this might lock up your computer !!!
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
Configuration file:
Every configuration file should contain at least three (3) commands:
the START, one flow ON and one flow OFF command. If that requirement is
not met or the parser can not recognize all the given commands in the file,
the configuration file will be considered corrupted and the program will
exit without any further action.
Lines starting with '#' or empty lines are treated as comments (i.e. are
not processed). Configuration file can hold any number of comment lines
anywhere in the file.
The START command must be the 1st command in the configuration file.
It may be preceded with comment lines, but nothing else. If your config
file has more than one (1) START command, the parsing will fail and the
program will exit with error.
Configuration file should hold at least two commands for each flow:
the ON and OFF commands. Between the ON and OFF commands can be
random/any number of MODIFY commands, which alter the flow behaviour.
Note that MODIFY commands are not available for every flow type.
Commands for each flow must be ordered according to the time - i.e.
the ON command must be the 1st command for the specific flow and the
MODIFY commands must be ordered by the time-field. The OFF command
must be the last command for the flow. The commands for each flow can
be "mixed" or each flow can have their configuration on different segment
in the file.
See also the well-commented configuration file "example.cfg".
------------------------------------------------------------------------------
------------------------------------------------------------------------------
START <time>
o <time> = { NOW | HH:MM:SS }
- HH = { 0,...,23 } , MM = { 0,...,59 } , SS = { 0,...,59 }
- This must be the 1st action line in the configuration file. The <time>
can be respresented as a symbolic value "NOW" or an absolute time with
the universal 24h notation "hours:minutes:seconds".
- Only/exactly one START command is required/expected.
- Parser tests only 9 characters, so little typos do not affect. In
other words "START NOW\n" = OK and "START NOW \n" = OK and
"START NOWADAYS" = OK ;)
------------------------------------------------------------------------------
<stime> <id> ON <sport> <dst.add>:<dst.port> <type> [type parameters]
o <stime> = { integer }
- Relative time (in milliseconds) to the START TIME when the
flow <id> should be activated (i.e. value 1000 = 1 second).
Must be > 0.
o <id> = { integer } - Unique identifier for this flow.
o <sport> = { integer } - Source UDP port for this flow. Must be > 1024.
o <dst.add> = { string }
- Destination addres either in dotted decimal notation or DNS name.
Must be followed with colon ':' and the destination port number.
o <dst.port> = { integer } - Destination UDP port.
o <type> = { string }
- Flow type. Can be one of the following with type specific parameters:
* CONSTANT <rate> <psize>
o <rate> = { integer } - packets per second. Must be >= 0. If the rate
is equal to zero (rate = 0) the flow will be
silent (= not transmitting) during this
timeslot.
o <psize> = { integer } - packet size. This sets the size of the UDP
data field. It must be between 20 and 32768
bytes. The actual transmitted packet size
depends on the used network interface
encapsulation. For example Ethernet packet
size can be calculated with the following
formula (UDP packet size = 1000 bytes):
<data> + <UDP> + <IP> + <ETH> = <TOTAL>
1000 + 8 + 20 + 18 = 1046 bytes
* TRACE <trace_file>
o <trace_file> = [path +] filename to the trace file
------------------------------------------------------------------------------
TOS <id> <value>
* This optional command allows for the setting of the TOS byte of the
IP header. Some values may only be used by root. If rude fails to
set the specified TOS it uses the default instead.
------------------------------------------------------------------------------
<mtime> <id> MODIFY <type> [type parameters]
* This command is valid only for the following flow type(s):
- CONSTANT
o <mtime> = { integer } - relative time from START to this action
o <id> = { integer } - flow identifier
o <type> = { string } - flow type with parameters (see ON command)
------------------------------------------------------------------------------
<otime> <id> OFF
o <otime> = { integer } - relative time from START to this command
o <id> = { integer } - flow identifier
------------------------------------------------------------------------------
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
Available flow types:
* CONSTANT
This flow simulates stream that looks like constant bitrate traffic.
You may change the flow parameters (packet size and packet rate) with
the MODIFY command. If the generated stream is not "stable" enough, you
should try to run the rude in priviledged priority (-p option).
* TRACE
This flow simulates pre-defined traffic. The trace of the traffic is
given on separate text file which must look like this (2 columns,
where the 1st column describes the packet size and the 2nd column time
to wait for the _next_ transmission):
512 0.040
255 1.1
762 0.000001
Maximum line length (terminated with '\n') is set to 255 characters,
including the terminating newline-character. !!! THERE IS NO NEED TO
EXCEED THIS, SO BE CAREFUL WHEN CREATING YOUR OWN TRACE FILES !!!
The first column sets the size of data field in UDP packet. The second
column is interpreted as a floating point value, which tells us the
time to wait until the next packet/line can be processed. The "maximum"
resolution to the time value is 1 microsecond (= 6 digits after the
comma), although it is very unlikely that the kernel/this program can
process the packets with so high resolution...
If the TRACE flow is configured to STOP before all packets from the
trace file can be processed, no harm is done - "unprocessed" packets
won't be sent. On the other hand, if you configure the flow to
last longer than the trace file describes, rude will start from the
beginning (i.e. loops until STOPped).
-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_
Things to do / under construction:
* update the documentation (README.rude & README.crude)
* systematic testing for the *new* TRACE flow type
* add new flow types (any suggestions? - mail them to authors)
* improve the performance and fix the bugs :)
## This is the example configuration script file for rude.
##
## Empty lines or lines beginning with '#' character are skipped...
##
## The 1ST command line must be the START command, which sets the
## absolute START time for the rude program. You can use "shortcut"
## NOW if no delay is required. Here are two examples.
## START NOW
## START 17:20:00
##
START NOW
## FLOW 1: (flow ID = 30)
##
## Starts 1 second after the START time with following parameters:
## 200 packets/second with 250 bytes/packet = 50kbytes/sec (1kbyte=1000bytes)
##
## 2 seconds from that the flow is modified to following parameters:
## 400 packets/second with 500 bytes/packet = 200kbytes/sec
##
## 1 second from that the flow is modified to following parameters:
## 1000 packets/second with 1000 bytes/packet = 1000kbytes/sec
##
## 1 second from that the flow is turned off...
##
1000 0030 ON 3002 10.1.1.1:10001 CONSTANT 200 250
3000 0030 MODIFY CONSTANT 400 500
4000 0030 MODIFY CONSTANT 1000 1000
5000 0030 OFF
## FLOW 2: (flow ID = 25)
##
## Starts immediately at the specified START time with following params:
## 400 packets/second with 100 bytes/packet = 40kbytes/sec (1kbyte=1000bytes)
##
## Sets the TOS for this flow to LOW_DELAY (0x10)
##
## 9 seconds after that the flow is turned off...
##
0000 0025 ON 3001 10.1.1.1:10001 CONSTANT 400 100
TOS 0025 0x10
9000 0025 OFF
## FLOW 3: (flow ID = 1)
##
## This flow acts as specified in the TRACE configuration file.
## Read the README.rude file for the command and file syntax
##
0000 1 ON 3111 10.1.1.1:10001 TRACE trace_file.txt
9999 1 OFF
## ... and that's it.
# $Id$
#
# autoconf/Makefile.in - the main Makefile template for RUDE and CRUDE
#
# Authors: Juha Laine <james@cs.tut.fi>
# Sampo Saaristo <sambo@cc.tut.fi>
#
# Copyright (C) 1999 Juha Laine, Tampere, Finland
# All rights reserved
#
##############################################################################
SHELL = /bin/sh
SUBDIRS = rude crude
@SET_MAKE@
all:
@for i in $(SUBDIRS); do \
(cd $$i && $(MAKE) all) \
done
clean:
rm -f *~ config.cache config.log config.status
@for i in $(SUBDIRS); do \
(cd $$i && $(MAKE) clean) \
done
distclean:
rm -f *~ config.cache config.log config.status configure Makefile
rm -f doc/*~ autoconf/config.hin include/config.h include/stamp.h
@for i in $(SUBDIRS); do \
(cd $$i && $(MAKE) distclean) \
done
rude:
cd rude && $(MAKE) all
crude:
cd crude && $(MAKE) all
install:
@for i in $(SUBDIRS); do \
(cd $$i && $(MAKE) install) \
done
##############################################################################
# Rules for autoconfiguration file REmaking
##############################################################################
update: include/stamp.h
include/stamp.h: autoconf/config.hin configure autoconf/Makefile.in rude/Makefile.in crude/Makefile.in
./configure
autoconf/config.hin: autoconf/acconfig.h
@autoheader -l ./autoconf
@touch autoconf/config.hin
@echo "****************************"
@echo "* header templates updated *"
@echo "****************************"
configure: autoconf/configure.in
rm -f config.*
@autoconf autoconf/configure.in > configure; chmod 755 configure
@echo "****************************"
@echo "* configure script updated *"
@echo "****************************"
##############################################################################
/***************************************************************************
* autoconfig/acconfig.h *
* - is the template file for autoconfig/config.hin which is generated *
* by the autoheader command *
* *
* autoconfig/config.hin *
* - is the template for include/config.h, that will be gererated by *
* the ./configure script *
* *
* include/config.h *
* - is the file that has the definitions/options for the pre-processor *
* *
***************************************************************************/
@TOP@
@BOTTOM@
/* End of file */
This diff is collapsed.
This diff is collapsed.
# $Id$
#
# autoconf/configure.in for RUDE and CRUDE
#
# Authors: Juha Laine <james@cs.tut.fi>
# Sampo Saaristo <sambo@cc.tut.fi>
#
# Copyright (C) 1999 Juha Laine, Tampere, Finland
# All rights reserved
#
##############################################################################
# Process any command-line arguments and find the source code directory
AC_INIT(rude/main.c)
# Set the auxilary directory, make and install
AC_CONFIG_AUX_DIR(autoconf)
AC_PROG_MAKE_SET
AC_PROG_INSTALL
# Make AX_OUTPUT() create following files with the #define statements
AC_CONFIG_HEADER(include/config.h:autoconf/config.hin)
# Check the machine type
AC_CANONICAL_HOST
# If CC is not set, set it to "gcc" (if found) or "cc"
# ...and after that get rid of the debugging flag '-g'
AC_PROG_CC
my_flags="$CFLAGS"
CFLAGS=
for my_opt in $my_flags; do
if test "$my_opt" != "-g"; then
CFLAGS="$CFLAGS $my_opt"
fi
done
# Check if the system is POSIXized
AC_ISC_POSIX
# Check some required headers
AC_HEADER_STDC
AC_HEADER_SYS_WAIT
AC_HEADER_TIME
AC_CHECK_HEADERS(sys/time.h unistd.h signal.h)
# Check required structures and types
AC_C_CONST
AC_STRUCT_TM
AC_TYPE_UID_T
# Check required structures and types
AC_CHECK_FUNCS(gettimeofday select strerror munlockall sigaction)
AC_CHECK_FUNC(gethostbyname,[true],
AC_SEARCH_LIBS(gethostbyname, nsl))
AC_CHECK_FUNC(socket,[true],
AC_SEARCH_LIBS(socket, socket nsl))
AC_CHECK_FUNC(inet_addr,[true],
AC_SEARCH_LIBS(inet_addr, xnet))
AC_CHECK_FUNC(sched_setscheduler,[true],
AC_SEARCH_LIBS(sched_setscheduler, posix4))
AC_CHECK_FUNC(pow,[true],
AC_SEARCH_LIBS(pow, m))
#########################
# Private configuration #
#########################
### Do machine dependent stuff right here
#case "$host" in
# *-*-solaris*)
# LIBS="-lsocket -lnsl $LIBS"
# ;;
#
# *)
# ;;
#esac
### Enable debugging code
AC_MSG_CHECKING([if we should enable -g])
AC_ARG_ENABLE(debug,
[ --enable-debug Enable compiler option -g],
[ case "$enableval" in
yes)
AC_MSG_RESULT(yes)
CFLAGS="-g $CFLAGS"
;;
*)
AC_MSG_RESULT(no)
;;
esac ], AC_MSG_RESULT(no))
### Enable -Wall option for compiler ???
AC_MSG_CHECKING([if we should enable -Wall])
AC_ARG_ENABLE(wall,
[ --enable-wall Enable compiler option -Wall (gcc only)],
[ if test "$CC" = "gcc"; then
AC_MSG_RESULT(yes)
CFLAGS="$CFLAGS -Wall"
else
AC_MSG_WARN(Your compiler is not gcc - -Wall not enabled.)
fi],AC_MSG_RESULT(no))
### Enable debugging output for program ???
AC_MSG_CHECKING([if we print debugging info])
AC_ARG_WITH(debug-lvl,
[ --with-debug-lvl=[0-7] Set program debugging output level],
[ if test $withval -ge 0; then
AC_MSG_RESULT(yes)
AC_DEFINE_UNQUOTED(DEBUG, $withval, Amount of DEBUGGING output)
else
AC_MSG_WARN(Invalid value $withval.)
fi],AC_MSG_RESULT(no))
###################
# Make it happen. #
###################
CFLAGS="$CFLAGS -I../include"
AC_OUTPUT(Makefile:autoconf/Makefile.in rude/Makefile crude/Makefile, \
echo timestamp > include/stamp.h)
#!/bin/sh
#
# install - install a program, script, or datafile
# This comes from X11R5 (mit/util/scripts/install.sh).
#
# Copyright 1991 by the Massachusetts Institute of Technology
#
# Permission to use, copy, modify, distribute, and sell this software and its
# documentation for any purpose is hereby granted without fee, provided that
# the above copyright notice appear in all copies and that both that
# copyright notice and this permission notice appear in supporting
# documentation, and that the name of M.I.T. not be used in advertising or
# publicity pertaining to distribution of the software without specific,
# written prior permission. M.I.T. makes no representations about the
# suitability of this software for any purpose. It is provided "as is"
# without express or implied warranty.
#
# Calling this script install-sh is preferred over install.sh, to prevent
# `make' implicit rules from creating a file called install from it
# when there is no Makefile.
#
# This script is compatible with the BSD install script, but was written
# from scratch. It can only install one file at a time, a restriction
# shared with many OS's install programs.
# set DOITPROG to echo to test this script
# Don't use :- since 4.3BSD and earlier shells don't like it.
doit="${DOITPROG-}"
# put in absolute paths if you don't have them in your path; or use env. vars.
mvprog="${MVPROG-mv}"
cpprog="${CPPROG-cp}"
chmodprog="${CHMODPROG-chmod}"
chownprog="${CHOWNPROG-chown}"
chgrpprog="${CHGRPPROG-chgrp}"
stripprog="${STRIPPROG-strip}"
rmprog="${RMPROG-rm}"
mkdirprog="${MKDIRPROG-mkdir}"
transformbasename=""
transform_arg=""
instcmd="$mvprog"
chmodcmd="$chmodprog 0755"
chowncmd=""
chgrpcmd=""
stripcmd=""
rmcmd="$rmprog -f"
mvcmd="$mvprog"
src=""
dst=""
dir_arg=""
while [ x"$1" != x ]; do