Metadata-Version: 2.1
Name: alpy
Version: 0.13.0
Summary: Library for testing network virtual appliances using Docker
Home-page: https://gitlab.com/abogdanenko/alpy
Author: Alexey Bogdanenko
Author-email: alexey@bogdanenko.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX :: Linux
Description-Content-Type: text/markdown
Requires-Dist: docker
Requires-Dist: pexpect
Requires-Dist: qmp

# Alpy

*Test network virtual appliance using Docker containers*

This project is a Python library for testing network virtual appliances.

The appliance being tested is referred to as a *device under test* or *DUT*.

This repository includes scripts and modules to build a simple appliance called
Rabbit. Rabbit is Alpine Linux with a few packages pre-installed. Having this
simple DUT allows to quickly test the alpy library and to demonstrate its
features.

The tests for the Rabbit device share a lot of code so the code is organized as
a library. The library is called *carrot*.

Network design
--------------

The DUT communicates with containers attached to each of its network links.

Guest network adapters are connected to the host via tap devices (Figure 1).

```
+-----QEMU hypervisor------+
|                          |   +-------------+
| +-----Guest OS-----+     |   |             |
| |                  |     |   |  docker     |
| | +--------------+ |     |   |  container  |
| | |              | |     |   |  network    |
| | |  NIC driver  | |     |   |  namespace  |
| | |              | |     |   |             |
| +------------------+     |   |   +-----+   |
|   |              |       |   |   |     |   |
|   | NIC hardware +---+-----------+ tap |   |
|   |              |   |   |   |   |     |   |
|   +--------------+   |   |   |   +-----+   |
|                      |   |   |             |
+--------------------------+   +-------------+
                       |
                       |
                       v
                 +-----------+
                 |           |
                 | pcap file |
                 |           |
                 +-----------+
```

*Figure 1. Network link between QEMU guest and a docker container.*

Each tap device lives in its network namespace. This namespace belongs to a
dedicated container - a *node*. The node's purpose is to keep the namespace
alive during the lifetime of a test.

For an application to be able to communicate with the DUT the application is
containerized. The application container must be created in a special way: it
must share network namespace with one of the nodes.

Figure 2 shows an example where application containers *app0* and *app1* share
network namespace with node container *node0*. Application container *app2*
shares another network namespace with *node2*.

This sharing is supported by Docker. All we have to do is to create the
application container with the `--network=container:NODE_NAME` Docker option.
For example, if we want to send traffic to the DUT via its first link, we create
a traffic generator container with Docker option `--network=container:node0`.

```
+----QEMU---+   +------shared network namespace-----+
|           |   |                                   |
|           |   |    eth0                           |
|   +---+   |   |   +---+   +-----+ +----+ +----+   |
|   |NIC+-----------+tap|   |node0| |app0| |app1|   |
|   +---+   |   |   +---+   +-----+ +----+ +----+   |
|           |   |                                   |
|           |   +-----------------------------------+
|           |
|           |
|           |
|           |   +------shared network namespace-----+
|           |   |                                   |
|           |   |    eth0                           |
|   +---+   |   |   +---+   +-----+                 |
|   |NIC+-----------+tap|   |node1|                 |
|   +---+   |   |   +---+   +-----+                 |
|           |   |                                   |
|           |   +-----------------------------------+
|           |
|           |
|           |
|           |   +------shared network namespace-----+
|           |   |                                   |
|           |   |    eth0                           |
|   +---+   |   |   +---+   +-----+ +----+          |
|   |NIC+-----------+tap|   |node2| |app2|          |
|   +---+   |   |   +---+   +-----+ +----+          |
|           |   |                                   |
+-----------+   +-----------------------------------+
```

*Figure 2. Application containers attached to the DUT links.*

Author
------

Alexey Bogdanenko

License
-------

Alpy is licensed under:

    SPDX-License-Identifier: GPL-3.0-or-later

See COPYING for more details.


