Description:

mrtopo 0.1.7

Mr. Topo






Author: Faizaan Chishtie

Description
MrTopo is a python application that generates mutant Mininet topology files for network testing purposes.
MrTopo is developed in conjunction with the IoT research being conducted by Dr. Shiva Nejati at the University of Ottawa.
Basic Usage
Option 1: Install the package through pip:
$ pip install mrtopo


Run the following:

$ mrtopo
Usage: mrtopo [OPTIONS] COMMAND [ARGS]...

Options:
--help Show this message and exit.

Commands:
config-file Generate mutations from a configuration file.
mutate-and-test Mutate and Test a Mininet Topology file.
python-file Mutate a Mininet python file.
test-mutation-dir Test a mutated set of networks (directory) against a...
validate-dir Validate a directory of Mininet topologies.
validate-file Validate a Mininet topology python file.

Option 2: Clone the repo:

Clone this repository
In the project directory run $ sh scripts/set-test-env.sh

This creates a temporary venv where mrtopo will be installed


Run $ mrtopo --help

If this doesn't work try $ source tmpenv/bin/activate and retry $ mrtopo --help



Command-Line Options:
All MrTopo commands are executed in this format:
$ mrtopo [COMMAND] [OPTION] [ARGS]

To get help for any command, execute:
$ mrtopo [COMMAND] --help

MrTopo commands:

config-file: Not yet implemented - Generate mutations from a configuration file.
python-file: Mutate a Mininet python file.
mutate-and-test: Mutate and Test a Mininet Topology file.
test-mutation-dir: Test a mutated set of networks (directory) against a given Mininet topology file.
validate-dir: Validate a directory of Mininet topologies.
validate-file: Validate a Mininet topology python file.

Most mrtopo commands will use the option -f to specify (except for validate-dir which takes -d )
Command: python-file
MrTopo command used to generate a folder of mutated mininet topologies.
Options:

-f, --file <path to python file> [Required]: Accepts a Mininet topology file .py

Usage:

The topology file specified must be a mininet topology.

$ mrtopo python-file -f some_topology.py

Help:
$ mrtopo python-file --help  2 ↵  8209  22:19:58
Usage: mrtopo python-file [OPTIONS]

Mutate a Mininet python file.

Options:
-f, --file TEXT Python file that MrTopo should mutate. [required]
--help Show this message and exit.

Output:

A MrTopoGenerated directory - containing:

Multiple mrtopo_gen_topo_<#>.py mutated topology files generated from the input python file.
A desc.txt file describing the mutation operation performed on each mrtopo_gen_topo_<#>.py file.



Command: config-file

Note: This option has not yet been implemented

Options:

-f, --file <path to configuration file> [Required]: Accepts a MrTopo configuration file .json

Usage:
mrtopo python-file -f some_config.json

Help:
$ mrtopo config-file --help  ✔  8210  22:20:01
Usage: mrtopo config-file [OPTIONS]

Generate mutations from a configuration file.

Options:
-f, --file TEXT MrTopo config file. [required]
--help Show this message and exit.


Command: validate-file

Note: validate-file will only run a Mininet VM.

MrTopo command used to test the validity of a Mininet topology file.
Options:

-f, --file <path to python file> [Required]: Accepts a Mininet topology file .py
-t, --topology-name <string> [Optional]: Name of topology found in python file.

Routine:

--not-long [Optional] - Default: Execute short validation routine
--long [Optional]: Execute long validation routine

Usage:
Base:
$ mrtopo validate-file -f some_file.py

Base + Topology Name:
$ mrtopo validate-file -f some_file.py -t 'att'

Base + Routine:
$ mrtopo validate-file -f some_file.py --long

Base + Routine + Topology Name:
$ mrtopo validate-file -f some_file.py -t 'att' --not-long

Help:
$ mrtopo validate-file --help
Usage: mrtopo validate-file [OPTIONS]

Validate a Mininet topology python file.

Options:
-f, --file TEXT Validate a Mininet topology python file. [required]
-t, --topology-name TEXT Name of topology found in python file. Example:
'topos = { 'someName': ... } - someName would be
the topology-name. Only use this option if you
know the topology name.

--long / --not-long Long test flag (i.e. pingall)
--help Show this message and exit.

Output:

A validator.txt file describing the validation operation performed on the specified mutation file.

Command: validate-dir

Note: validate-dir will only run a Mininet VM.

MrTopo command used to test the validity of a Mininet topology file.
Options:

-d, --dir <path to directory of python files> [Required]: Accepts directory of Mininet topology files

Will only parse python files from given directory - folder can contain other files.


-t, --topology-name <string> [Optional]: Name of topology found in python file.

Routine:

--not-long [Optional] - Default: Execute short validation routine
--long [Optional]: Execute long validation routine

Usage:
Base:
$ mrtopo validate-dir -d some_dir/

Base + Topology Name:
$ mrtopo validate-file -d some_dir/ -t 'att'

Base + Routine:
$ mrtopo validate-file -d some_dir/ --long

Base + Routine + Topology Name:
$ mrtopo validate-file -d some_dir/ -t 'att' --not-long

Help:
$ mrtopo validate-dir --help  ✔  8213  22:40:45
Usage: mrtopo validate-dir [OPTIONS]

Validate a directory of Mininet topologies.

Options:
-d, --dir TEXT Validate a directory of Mininet topologies.
[required]
-t, --topology-name TEXT Name of topology found in python file. Example:
'topos = { 'someName': ... } - someName would be
the topology-name. Only use this option if you
know that all python files in the specified
dirfollow the topology name given.
--long / --not-long Long test flag (i.e. pingall)
--help Show this message and exit.

Output:

A validator.txt file describing the validation operation performed on the each mutation file in the specified
directory.


Command: mutate-and-test
MrTopo command used to mutate a Mininet topology and then execute a test on the outputs.

Note: depending on the command file provided this command may only be able to execute on ONOS machines.

Options:

-f, --file <path to python file> [Required]: Accepts a Mininet topology file .py
-cf, --command-file <path to bash file> [Required]: Accepts a bash file

Usage:

The topology file specified must be a mininet topology.

$ mrtopo mutate-and-test -f some_topology.py -cf some_commands.sh
// note .sh is not required as long as the -cf file is a bash file

Help:
$ mrtopo mutate-and-test --help  2 ↵  8209  22:19:58
Usage: mrtopo mutate-and-test [OPTIONS]

Mutate and Test a Mininet Topology file.

Options:
-f, --file TEXT Python file that MrTopo should mutate. [required]
-cf, --command-file TEXT Bash file that contains ONOS testing commands to
execute. [required]

--help Show this message and exit.

Output:

A MrTopoGenerated directory - containing:

Multiple mrtopo_gen_topo_<#>.py mutated topology files generated from the input python file.
A desc.txt file describing the mutation operation performed on each mrtopo_gen_topo_<#>.py file.


A MrTopoTest directory - containing:

A copy of the original topology should anything have gone wrong during testing.
A test.txt file detailing the output of each test



Command: test-mutation-dir
MrTopo command used to test a mutated set of networks (directory) against a given Mininet topology file.

Note: depending on the command file provided this command may only be able to execute on ONOS machines.

Options:

-f, --file <path to python file> [Required]: Accepts a Mininet topology file .py
-cf, --command-file <path to bash file> [Required]: Accepts a bash file

Usage:

The topology file specified must be a mininet topology.

$ mrtopo mutate-and-test -d dir_of_mutated_files/ -tf original_topology -cf some_commands.sh
// note .sh is not required as long as the -cf file is a bash file

Help:
$ mrtopo test-mutation-dir --help  2 ↵  8209  22:19:58
Usage: mrtopo test-mutation-dir [OPTIONS]

Test a mutated set of networks (directory) against a given Mininet
topology file.

Options:
-d, --dir TEXT A directory of Mininet topologies. [required]
-tf, --target-file TEXT Name of file that MrTopo mutated and should
substitute out during testing. [required]

-cf, --command-file TEXT Bash file that contains ONOS testing commands to
execute. [required]

--help Show this message and exit.

Output:

A MrTopoTest directory - containing:

A copy of the original topology should anything have gone wrong during testing.
A test.txt file detailing the output of each test



Examples

Copy the /examples/temp_topo.py code to a local python file named temp_topo.py
Run mrtopo python-file -f temp_topo.py
This should create a MrTopoGenerated folder containing the mutated topology files generated from the temp_topo.py file.
Replace temp_topo.py with the path to your Mininet topology file.

Further Notes
Further documentation is available on the MrTopo GitHub pages site.
Links

PyPi MrTopo Package
Mininet Custom Topologies
Mininet Downloads

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter