Happy is a tool that builds complex network topologies using Linux tools. For example, on a local computer Happy can create multiple nodes that have independent from each other network stacks. Some nodes may be connected to simulated Thread networks, other may connect to simulated WiFi, WAN (Internet), and cellular networks.
Happy was designed to address the following problems:
-
testing of network protocols and other distributed execution programs on a single Linux development machine without using hardware.
-
performing automated functional testing across a network.
-
running multiple concurrent, parallel networks on the same system to improve testing throughput
Happy solves these problems by creating network topology abstractions with minimal user overhead. Complex topologies may be created with a single shell command call. Happy supports both interactive use and automated scripting. During development users may prefer to use Happy shell commands to setup, test, and debug their code. The same networking configuration and test programs may then be scripted and used in the automated testing.
Happy has a strong dependence on Linux Network Namespaces, and as a result, is only supported in the Linux environment.
# Mandatory: python-setuptools
sudo apt-get install python-setuptools
# Mandatory: Linux bridge utilities
sudo apt-get install bridge-utils
# Mandatory: python-lockfile
sudo apt-get install python-lockfile
# Mandatory: python-psutil
sudo apt-get install python-psutil
# Optional: Graphic Tools
sudo apt-get install python-networkx
sudo apt-get install python-matplotlib
# Optional: Tmux
sudo apt-get install tmux
Before using Happy, it must be installed. Running Happy from the source tree is not supported. To install, run:
make
This does two things:
-
creates a happy python package at
/usr/local/lib/python2.7/dist-packages -
copies happy shell scripts to
/usr/local/bin
After installation, Happy Python packages can be imported into Python
environment as any other Python module (e.g. import happy). Post installation,
all system users can make Happy shell calls. (e.g. $ happy-state).
At this point Happy commands should be visible from the shell. Calling
happy-state should return the following:
$ happy-state
NETWORKS Name Type State Prefixes
NODES Name Interface Type IPs
Before removing happy make sure that all virtual node and networks are
deleted. The simplest way of wiping out happy past work is by calling
happy-state-delete -a:
happy-state-delete -a
To remove happy itself, call make uninstall within happy repo and remove
happy/bin from the host's $PATH:
make uninstall
# Delete happy files from ~ (user home directory)
rm -f ~/.happy_state.json
rm -f ~/.happy_conf.json
rm -f ~/.happy_state.json.lock
cd /usr/local/lib/python2.7/dist-package
rm -f happy*
-
Happy changes host's network configuration that is controlled by Linux kernel. Since only root can change kernel configuration, as a user runs Happy once in a while the user needs to enter
sudopassword. Happy uses system environment variable to callsudo; specifically, happy callssysenv $SUDO. If$SUDOis not defined, happy simply makes asudocall. The user can change thesudocommand value through$SUDO. -
Happy is using host's Linux tools, therefore it interferes with host's networking configuration. As a result, while using Happy, Google Desktop will show messages reporting changes in host's network interfaces.
Architectural overview of Happy can be found in this document. Additional Happy documentation is maintained on https://github.com/openweave/happy/wiki Significant contributions or alterations to the Happy functionality must be accompanied by documentation on the wiki or within this repository.
Contributions are welcome and encouraged. See CONTRIBUTING.md for details.