Except where otherwise noted, everything in this repository is provided under the terms of the Apache 2.0 License.
***PROJECT IN FLUX - INSTRUCTIONS WILL CHANGE DRAMATICALLY IN NEAR FUTURE***

Homepage: http://www.batfish.org
Source:   http://github.com/arifogel/batfish

**************************************************
Instructions for building and running Batfish
**************************************************

Prerequisites:
   ant
   GNU parallel
   java 7 jdk
   logicblox 4.1.X+ (not required for all tasks)
   python
   z3

Steps:
NOTE: Some steps will begin with (SERVER), and some with (CLIENT). The SERVER is the machine running LogicBlox. The CLIENT is the machine containing the test rig and batfish binaries. If the SERVER and the CLIENT are the same machine, then run all steps (except where otherwise indicated).
NOTE: After any step involving modifications to .bashrc or equivalent, make sure to reload your shell or take other action to load the changes.

1. (CLIENT) Install gnu parallel 20150109 or later (20150109 available at <http://alpha.gnu.org/gnu/parallel/paralell-20150109.tar.bz2>)
standard autotools install (extract, configure, make, make install)

2. (CLIENT) Install z3
git clone https://github.com/Z3Prover/z3
cd z3
git checkout unstable
python scripts/mk_make.py --java
cd build
make -j<number-of-jobs>
make install # as administrator (sudo or whatever)

3. (SERVER) Install LogicBlox >= 4.2.1 and fix lb-web-server timeout
- edit <logicblox-root>/config/lb-web-server.conf
- change all tcp_server_max_idle_time lines to read:
tcp_server_max_idle_time = 0

4. (SERVER AND CLIENT) Clone batfish
git clone https://github.com/arifogel/batfish.git

5. prepare your environment for logicblox and batfish by adding the following to your .bashrc or equivalent
#(SERVER)
   export LB_HOME=<logicblox-root>
    . <logicblox-root>/etc/profile.d/logicblox.sh
    alias rlb="killall -9 lb-server; killall -9 lb-pager; lb services stop && rm -rf ~/lb_deployment/* /run/shm/LB_${USER} /tmp/LB_${USER}_* && LB_CONNECTBLOX_ENABLE_ADMIN=1 lb services start"
    alias slb="LB_CONNECTBLOX_ENABLE_ADMIN=1 lb services start"
    alias klb="killall -9 lb-server; killall -9 lb-pager; lb services stop; rm -rf ~/lb_deployment/* /run/shm/LB_${USER} /tmp/LB_${USER}_*"

#(SERVER AND CLIENT)
    . <batfish-root>/tools/batfish_functions.sh
rlb will kill logicblox, completely purge all logicblox data, and restart logicblox
klb will kill logicblox and completely purge all logicblox data
slb will start logicblox
if you want to kill logicblox without purging data, run:
    lb services stop
sourcing batfish_functions.sh will give your shell access to batfish functions.
LB_HOME is needed for ant to compile logic files.
sourcing logicblox.sh is required to run LogicBlox

6. (SERVER) start logicblox
type:
    slb

7. (SERVER) compile logic
    batfish_build lbcompile

8. (CLIENT) compile batfish
    batfish_build # implies lbcompile which only does work if LogicBlox is installed
Note that 'batfish_build' runs 'ant' in the batfish project directory with corresponding args.
You can clean all generated output with:
   batfish_build distclean

9. ***DO THIS STEP ONLY IF CLIENT != SERVER*** (CLIENT)
Set up your .bashrc or equivalent on your CLIENT with batfish common arguments needed to access SERVER
NOTE the default values for the following arguments:
-lbhost -> localhost
-lbport -> 55179
-lbwebport -> 8080
-lbwebadminport -> 55183
NOTE that the built logic will reside on the SERVER at <batfish-repo-root>/projects/batfish/bin/org/batfish/logic
.bashrc:
   export BATFISH_REMOTE_LOGIC_DIR=<MANDATORY_absolute_path_to_built_logic_on_SERVER_filesystem>'
   export BATFISH_COMMON_ARGS="-lbhost <OPTIONAL_hostname_of_SERVER> -lbport <OPTIONAL_ConnectBlox_port_on_SERVER> -lbwebport <OPTIONAL_lb_web_port_on_SERVER> -lbwebadminport <OPTIONAL_lb_web_admin_port_on_SERVER> -logicdir $BATFISH_REMOTE_LOGIC_DIR"
10. run batfish
The output of this step will be placed in the current folder.
If you want to confirm running of each subtask, run:
    batfish_confirm_analyze_multipath /path/to/test/rig <generated-output-prefix>
OR to run everything:
    batfish_analyze_multipath /path/to/test/rig <generated-output-prefix>

**************************************************
Notes on running
**************************************************
This repository should contain an example test rig at <batfish-root>/test_rigs/example
After running step 9 above on the example test rig, as:
   batfish_analyze_multipath <batfish-root>/test_rigs/example example
you should see the following output in the current folder:

example-bgp
example-dp (directory)
example-dump (directory)
example-flows
example-indep (directory)
example-node-set
example-node-set.txt
example-ospf
example-policy
example-query (directory)
example-reach.smt2
example-routes
example-vendor (directory)

Much of the output is in the form of elements of LogicBlox predicates. To see the schema and comments for the LogicBlox predicates, run:
   batfish -predhelp <predicate-name..>
To see help for ALL predicates, including IDB (derived) predicates, use the '-predhelp' flag without arguments:
   batfish -predhelp
Individual predicates for a processed test rig can be dumped to stdout by running:
   batfish_query_predicate <generated-output-prefix> <predicate>

example-vendor:
This folder contains parsed versions of the vendor configuration files, serialized into an XML-like format.

example-indep:
This folder contains vendor-independent representations of the configurations, created by processing the vendor configuration structures. The former are also serialized into an XML-like format.

example-dump:
This folder contains files named for LogicBlox EDB (input) predicates. Note that the files in the 'example-dump' folder are in raw CSV format (with '|' as a delimiter), and may not be very legible, even with the schema.

example-bgp:
This file contains dumps of selected BGP-related predicates for a processed testrig

example-ospf
This file contains dumps of selected OSPF-related predicates for a processed testrig

example-policy
This file contains dumps of selected policy-related predicates for a processed testrig

example-routes:
This file contains dumps of the routing tables for a processed testrig, retrieved using:
   batfish -testrig </path/to/testrig> -query -predicates InstalledRoute

example-dp:
This folder contains information needed to represent the data plane. Specifically, it contains the FIBs (Forwarding Information Bases) and topology edges. This information is enough to represent the data plane when used in conjunction with the static information contained in the vendor-independent configuration structures.

example-node-set:
example-node-set.txt:
These files are an intermediate byproduct, and should be considered opaque and ignored

example-reach.smt2:
This file contains the data plane (reachability relations) of a processed test-rig in the z3 smt-solver's 'smt2' format.

example-query:
This folder contains 4 types of files:
   1. multipath-inconsistency-query-<node>.smt2:
      A z3 query for the z3 fixed-point datalog engine that, when appended to the example-reach.smt2 file, yields the constraints for multipath-inconsistent packets originating at <node>
   2. multipath-inconsistency-query--<node>.smt2.out:
      The output of step 1
   3. multipath-inconsistency-query-<node>-concrete-<number>.smt2:
      These files are z3 queries for the standard smt engine incorporating the constraints found in step 2. These queries should yield 0 or 1 CONCRETE packets per node that exhibit multipath inconsistency when injected at that node.
   4. multipath-inconsistency-query-<node>-concrete-<number>.smt2.out:
      The output of step 3.

example-flows:
This file contains dumps of relevant flow predicates, retrieved using:
   batfish -testrig </path/to/testrig> -query -predicates <flow_predicates..>
These predicates were populated AFTER injecting the concrete packets found in example-query step 4 above into the LogicBlox network model.