Update Makefile

.gitignore

@@ -24,3 +24,5 @@ NOTES*
 .DS_Store
 vendor/db_generator
 vendor/db_generator-*
+vendor/parameter_files
+vendor/parameter_files-*

Gemfile

@@ -9,3 +9,4 @@ end
 gem "docopt"
 gem "ruby-ip"
 gem "open4"
+gem "ipaddress"

Gemfile.lock

@@ -2,6 +2,7 @@ GEM
   remote: http://rubygems.org/
   specs:
     docopt (0.5.0)
+    ipaddress (0.8.3)
     open4 (1.3.4)
     ruby-ip (0.9.3)
 
@@ -11,8 +12,9 @@ PLATFORMS
 DEPENDENCIES
   bundler
   docopt
+  ipaddress
   open4
   ruby-ip
 
 BUNDLED WITH
-   1.10.6
+   1.15.4

Makefile

@@ -3,3 +3,6 @@
 # (downloads, patches and compiles ClassBench)
 all:
 	make -C vendor all
+
+clean:
+	$(MAKE) -C vendor $@

README.md

@@ -1,42 +1,114 @@
-# Classbench
-
-Utility for generation of firewall/OpenFlow rules based on original (no longer maintained) [Classbench](http://www.arl.wustl.edu/classbench/).
+# ClassBench-ng
+A tool for generation of synthetic classification rule sets for benchmarking, which is based on original (no longer maintained) [ClassBench](http://www.arl.wustl.edu/classbench/).
+The format of the generated rules can be one of the following:
+- IPv4 5-tuple
+- IPv6 5-tuple
+- OpenFlow
 
 ## Requirements
+- Python3
 - Ruby 1.9.3+
 - RubyGems
-
 ```
 sudo gem install open4 ruby-ip docopt ipaddress
 ```
+
 ## Installation
 ```
-git clone https://github.com/lucansky/classbench-ng.git
-make   # Downloads, patches and compiles db_generator in ./vendor/db_generator/db_generator
+git clone https://github.com/classbench-ng/classbench-ng.git
+make   # Downloads, patches and compiles original ClassBench in ./vendor/db_generator
+       # Downloads the parameter files of original ClassBench to ./vendor/parameter_files
 ```
 
-### Patching classbench
-Due to statically initialized arrays in ClassBench, patching is required which increases the limit.
-Patch is automatically applied by make in process of downloading ClassBench.
-(see vendor/Makefile)
+### Patching ClassBench
+Original ClassBench is patched using `./patches/improvements_ipv6.patch` and the size of its statically initialized arrays is increased, where necessary.
+These changes are automatically applied on downloaded original ClassBench during ClassBench-ng installation.
+
+By modifying `./vendor/Makefile` the user can select a different patch from `./patches` directory to be applied during installation.
+Basic characteristics of patches available in `./patches` directory and suggestions when to use them are following:
+
+`improvements.patch`
+- improves precision of IPv4 prefixes generation
+- use when IPv6 prefixes generation is not required
+
+`ipv6.patch`
+- adds support for IPv6 prefixes generation
+- use when IPv6 prefixes generation is required and precision of IPv4/IPv6 prefixes generation is not crucial
+
+`improvements_ipv6.patch`
+- adds support for IPv6 prefixes generation and improves precision of both IPv4 and IPv6 prefixes generation
+- use when IPv6 prefixes generation is required and precision of IPv4/IPv6 prefixes generation is crucial
 
 ## Usage
+ClassBench-ng can be used in two different ways:
+- To analyse an existing rule set and extract a corresponding SEED.
+- To generate a synthetic rule set from an input SEED.
+
 ```
-./classbench analyse FILE
+./classbench -h | --help
 ```
-Analyses file, expecting FILE to be ovs-ofctl dump.
-Fields extracted from dump are:
-- dl_dst, dl_src, dl_type, dl_vlan, dl_vlan_pcp,
-- eth_type, in_port,
-- nw_dst, nw_proto, nw_src, nw_tos,
-- tp_dst, tp_src
+Prints detailed usage information.
 
-Output's original Classbench seed with openflow YAML structure as last section.
+### ClassBench-ng Analyser
+The current version can successfully analyse IPv4 5-tuples, IPv6 5-tuples, and OpenFlow rules.
 
 ```
-./classbench generate v4 SEED [--count=100] [--db-generator=<path>]
+./classbench analyse tuples FILE FORMAT [-l]
+```
+Analyses FILE, expecting FILE to be in the format specified in FORMAT (see `./lib/tuples_analyzer/README` for more information on how to specify the format).
+- `-l` enables printing analysis error logs.
+
+The output is an original ClassBench seed.
+
 ```
-Generates --count of OpenFlow rules.
-If seed without OpenFlow section is provided, regular 5-tuples are generated.
-Output format is "attribute=value", joined by ", ".
+./classbench analyse of FILE
+```
+Analyses FILE, expecting FILE to be in the format used by `ovs-ofctl`.
+Fields extracted from FILE are:
+- in_port,
+- dl_src, dl_dst, eth_type, dl_vlan, dl_vlan_pcp,
+- nw_src, nw_dst, nw_tos, nw_proto,
+- tp_src, tp_dst
+
+The output is an original ClassBench seed with an OpenFlow YAML structure as the last section.
+
+### ClassBench-ng Rule Generator
+The current version can successfully generate IPv4, IPv6 and OpenFlow 1.0 flow rules.
+- IPv4 SEEDs can be found in `./vendor/parameter_files`
+- OpenFlow SEEDs can be found in `./seeds`
+
+```
+./classbench generate v4 SEED [--count=<n>] [--db-generator=<path>]
+```
+Generates IPv4 5-tuples following the properties from SEED.
+- `--count=<n>` specifies the number of 5-tuples to be generated (default: `100`)
+- `--db-generator=<path>` specifies the path to an original ClassBench binary (default: `./vendor/db_generator/db_generator`)
+
+The output format is the same as of original ClassBench outputs.
+
+```
+./classbench generate v6 SEED [--count=<n>] [--db-generator=<path>]
+```
+Generates IPv6 5-tuples following the properties from SEED.
+- `--count=<n>` specifies the number of 5-tuples to be generated (default: `100`)
+- `--db-generator=<path>` specifies the path to an original ClassBench binary (default: `./vendor/db_generator/db_generator`)
+
+The output format is the same as of original ClassBench outputs.
+
+```
+./classbench generate of SEED [--count=<n>] [--db-generator=<path>]
+```
+Generates OpenFlow rules following the properties from SEED that has to contain an OpenFlow section.
+- `--count=<n>` specifies the number of rules to be generated (default: `100`)
+- `--db-generator=<path>` specifies the path to an original ClassBench binary (default: `./vendor/db_generator/db_generator`)
+
+The output consists of `attribute=value` pairs joined by `, `.
+
+## Known Issues
+- the number of generated rules is usually lower than in original ClassBench (i.e., ClassBench-ng generates higher number of redundant rules that are removed in the last phase)
+- ClassBench-ng Analyser does not correctly analyses source/destination port prefixes specified using a bit map in the ovs-ofctl format
 
+## How to Contribute
+Contributions are welcome via:
+- pull requests (preferred)
+- e-mail to imatousek at fit.vutbr.cz

classbench

@@ -5,47 +5,62 @@ require_relative "lib/classbench"
 require "pp"
 require "docopt"
 doc = <<DOCOPT
-Classbench utility
-  Firewall/openflow rule generator.
+ClassBench-ng
+  A tool for generation of synthetic classification rule sets for benchmarking.
 
 Usage:
-  #{__FILE__} analyse FILE
-  #{__FILE__} generate v4 <seed> [--count=<n>] [--db-generator=<path>]
-  #{__FILE__} generate v6 <seed> [--count=<n>]
+  #{__FILE__} analyse tuples FILE FORMAT [-l]
+  #{__FILE__} analyse of FILE
+  #{__FILE__} generate v4 SEED [--count=<n>] [--db-generator=<path>]
+  #{__FILE__} generate v6 SEED [--count=<n>] [--db-generator=<path>]
+  #{__FILE__} generate of SEED [--count=<n>] [--db-generator=<path>]
   #{__FILE__} -h | --help
-  #{__FILE__} version
 
 Options:
-  --db-generator=<path>     Path to binary of original db_generator [default: ./vendor/db_generator/db_generator]
-  --count=<n>               Count of rules to generate [default: 100]
+  -l                        Enable printing analysis error logs.
+  --db-generator=<path>     Path to an original ClassBench binary.
+                            [default: ./vendor/db_generator/db_generator]
+  --count=<n>               The number of rules to be generated.
+                            [default: 100]
   -h --help                 Show this screen.
 
-Analyser accept's as input ovs-ofctl dump.
-Fields extracted from dump are:
-	- dl_dst, dl_src, dl_type, (dl_vlan, dl_vlan_pcp,)
-	- eth_type, in_port,
-	- nw_dst, nw_proto, nw_src, nw_tos,
-	- tp_dst, tp_src
-Output is original Classbench seed
-	with openflow YAML structure as last section.
+Analyser accepts as an input either a rule set in a given format in case of
+"analyse tuples" (the expected structure of a format file is described in
+lib/tuples_analyzer/README, section 7) or an ovs-ofctl dump in case of
+"analyse of".
+The output is an original ClassBench seed or this seed with an OpenFlow YAML
+structure as the last section, respectively.
 
-Generator accept's Classbench seed with openflow section.
-Output's one rule per line in format "attribute=value", joined by ", ".
+Generator accepts as an input an original ClassBench seed that has to contain
+an OpenFlow section in case of "generate of".
+The output is either the same as of original ClassBench outputs or it consists
+of "attribute=value" pairs joined by ", ".
 
 DOCOPT
+# Add the following line to the DOCOPT's "Options" pattern to show support of
+# "version" parameter.
+#  #{__FILE__} version
 
 begin
 	opts = Docopt::docopt(doc)
 	if opts["analyse"]
-		Classbench::analyse(opts["FILE"])
+		if opts["tuples"]
+			Classbench::analyse_tuples(opts["FILE"], opts["FORMAT"], opts["-l"])
+		elsif opts["of"]
+			Classbench::analyse_of(opts["FILE"])
+		end
 	elsif opts["generate"]
-		#pp opts
-		Classbench::generate(opts["<seed>"], (opts["--count"].to_i), opts["--db-generator"])
+		if opts["v4"]
+			Classbench::generate("v4", opts["SEED"], (opts["--count"].to_i), opts["--db-generator"])
+		elsif opts["v6"]
+			Classbench::generate("v6", opts["SEED"], (opts["--count"].to_i), opts["--db-generator"])
+		elsif opts["of"]
+			Classbench::generate("of", opts["SEED"], (opts["--count"].to_i), opts["--db-generator"])
+		end
 	elsif opts["version"]
 		puts "Version: #{Classbench::VERSION}"
-  end
-	# TODO: --version
+	end
 
-rescue Docopt::Exit => e
-	STDERR.puts e.message
+	rescue Docopt::Exit => e
+		STDERR.puts e.message
 end

lib/classbench.rb

@@ -32,23 +32,49 @@ def self.load_prefixes_from_file(filename)
 		t
 	end
 
-	def self.analyse(filename)
+	def self.analyse_tuples(rules_filename, format_filename, logs_enabled)
+		if logs_enabled
+			pid, stdin, stdout, stderr = Open4::popen4("python3", "-m", "lib.tuples_analyzer", "-r", rules_filename, "-f", format_filename, "-l")
+		else
+			pid, stdin, stdout, stderr = Open4::popen4("python3", "-m", "lib.tuples_analyzer", "-r", rules_filename, "-f", format_filename)
+		end
+
+		ignored, status = Process::waitpid2 pid
+
+		if status.exitstatus == 0
+			STDOUT.puts stdout.read.strip
+			if logs_enabled
+				warnings = stderr.read.strip
+				if !warnings.to_s.empty?				
+					STDERR.puts warnings
+				end
+			end	
+		else
+			STDERR.puts stderr.read.strip
+			exit(status.exitstatus)
+		end		
+
+	end		
+
+	def self.analyse_of(filename)
 		analyser = Analyser.new
 		analyser.parse_openflow(File.read(filename))
 
-		analyser.calculate_stats
-
 		puts analyser.generate_seed
 
 	end
 
-	def self.generate(filename, count, db_generator_path)
+	def self.generate(format, filename, count, db_generator_path)
 		generator = Generator.new(filename, db_generator_path)
-		has_openflow = generator.parse_seed
+		if format == "of"
+			if !generator.parse_seed
+				return
+			end
+		end
 
 		#puts  YAML.dump(generator.openflow_section)
-		rules = generator.generate_rules(count)
-		if has_openflow
+		rules = generator.generate_rules(format, count)
+		if format == "of"
 			rules.map!(&:to_vswitch_format)
 		end
 

lib/classbench/analyser.rb

@@ -34,15 +34,15 @@ def parse_openflow(lines)
 				end
 				self.rules << Rule.new(rule)
 			end
+
+			calculate_stats
 		end
 
 		def rules_per_port_class(class_name)
 			self.port_class_prefix_lengths[class_name].values.map(&:values).flatten.inject(&:+)
 		end
 
 		def generate_seed
-			calculate_stats
-
 			seed = ""
 			seed += "-scale\n#{rules.size}\n#\n"
 
@@ -188,7 +188,7 @@ def calculate_stats
 				lengths_of_class = port_class_prefix_lengths[r.port_class_name]
 
 				specific_length = lengths_of_class[r.src_length + r.dst_length] ||= {}
-				specific_length[r.dst_length] = (specific_length[r.dst_length] || 0) + 1
+				specific_length[r.src_length] = (specific_length[r.src_length] || 0) + 1
 			end
 		end