Nest Labs Happy -- a network topology orchestration tool
Happy simulates complex network topologies. On a single Linux machine, Happy can create multiple nodes with network stacks that are independent from each other. Some nodes may be connected to simulated Thread networks, others may connect to simulated Wi-Fi, WAN (Internet), or cellular networks.
Happy addresses the following use cases:
- 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.
Use Happy shell commands to set up, test, and debug their code during development. The same networking configuration and test programs may then be scripted and used in automated testing.
The quickest and easiest way to get started with Happy is to go through our Getting Started with Happy and Weave Codelab. It walks the user through all the Happy fundamentals, including:
- Creating and deleting a topology
- Networking nodes together
- Saving and restoring topologies
- Connecting a topology to the internet
- Weave fundamentals
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:
This does two things:
- Creates a happy python package at
- Copies happy shell scripts to
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.
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 nodes and networks are
deleted. The simplest way of wiping out past Happy work is by calling
To remove Happy itself, call
make uninstall within the Happy repo and remove
happy/bin from the host's
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*
Most Happy commands follow the same basic syntax. Common flags are:
||Show help information for the command|
||Turn off command output|
||Create/add; the default action for a command is -a unless otherwise specified|
||Delete; this action must be specified to perform a delete action|
For all commands, the short and long flags are interchangeable, and in some instances can be omitted entirely. For example, all three of these commands are equivalent:
$ happy-node-join ThreadNode ThreadNetwork $ happy-node-join -i ThreadNode -n ThreadNetwork $ happy-node-join --id ThreadNode --network ThreadNetwork
-d is used,
-a is assumed. For example, these two commands are
$ happy-dns onhub 220.127.116.11 $ happy-dns -a onhub 18.104.22.168
Usage of sudo
Happy changes the network configuration that is controlled by the Linux kernel. Since only root can change the kernel configuration, Happy prompts you to enter the sudo password during operation.
Happy uses the
$SUDO system environment variable to call sudo. If $SUDO is
not defined, Happy makes a normal
sudo call. The user can change the
command value through
Comprehensive end-user documentation, including Setup and Usage guides, are located at openweave.io/happy.
An architectural overview of Happy can be found in ARCHITECTURE.md. Significant contributions or alterations to the Happy functionality must be accompanied by documentation within this repository, or submitted as an Issue for incorporation on openweave.io.
Want to contribute?
Contributions are welcome and encouraged. See CONTRIBUTING.md for details.