https://github.com/robinohs/phantomlink

phantomlink looks like a multi-hop Internet path, but emulates a virtual end-to-end link
https://github.com/robinohs/phantomlink

linux network-benchmark network-emulation network-emulator rust rust-lang virtual-interface virtual-link

Last synced: 2 months ago
JSON representation

phantomlink looks like a multi-hop Internet path, but emulates a virtual end-to-end link

Host: GitHub
URL: https://github.com/robinohs/phantomlink
Owner: robinohs
License: apache-2.0
Created: 2025-01-27T15:51:12.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2026-04-20T13:11:08.000Z (3 months ago)
Last Synced: 2026-04-20T15:20:04.480Z (3 months ago)
Topics: linux, network-benchmark, network-emulation, network-emulator, rust, rust-lang, virtual-interface, virtual-link
Language: Rust
Homepage: https://dl.acm.org/doi/10.1145/3744200.3744758
Size: 680 KB
Stars: 5
Watchers: 4
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff

Awesome Lists containing this project

README

phantomlink Logo

phantomlink looks like a multi-hop Internet path but emulates a virtual end-to-end link

```phantomlink``` is a tool for studying the impact of a dynamic network environment on the performance of internet protocols and applications. Written in safe Rust, the tool makes use of Linux network namespaces and virtual Ethernet devices to simulate a realistic end-to-end link. Using simple `.csv` scenario files, it is possible to define the time-evolving virtual link parameters, including delay, data rate over time, and route changes.
Since the tool just opens two connected vEth in different namespaces, it is possible to combine ```phantomlink``` with any application, such as the well-known tools like netcat or iperf but also your own custom application.
With the ability to reorder, delay, pace, and drop packets, ```phantomlink``` can be used to test network behavior under various scenarios.

## 🔥 Features

- **connect** two Linux network namespaces over a **dynamic virtual link**
- specify **bottleneck data rate**, **link delay**, and **packet reordering**
- set the virtual link behavior with a **simple input file format**
- **support** for **all protocols** using ethernet frames ➡️ just route the traffic to ```phantomlink```

## 🚀 Use ```phantomlink```

> [!WARNING]
> Phantomlink currently only runs on Linux or the Windows Subsystem for Linux (WSL)

### Installation

#### Debian/Ubuntu

1. Download the ```phantomlink``` debian package.
2. Install the package using (replace [version] with the downloaded version):
```sh
sudo apt install ~/downloads/phantomlink_[version].deb
```

#### Cargo

To get started you have to do the following:

1. Install ```phantomlink``` from crates.io:
```bash
cargo install phantomlink
```

#### Other Distros

To get started you have to do the following:

1. Download the ```phantomlink``` binary.
2. Make the binary executable using:
```bash
chmod +x phantomlink_[version]
```
3. Move the binary to `/bin`.

#### Build from source

It is also possible to build the `phantomlink` binary from source.

##### Prerequisites
- Git installed on your system.
- Rust and Cargo installed (for building the binary).

##### Option 1: Manual Build
1. Clone the `phantomlink` repository from GitHub:
```bash
git clone https://github.com/robinohs/phantomlink
```
2. Navigate to the cloned repository and build the binary using Cargo:
```bash
cargo build --release
```
3. Move the binary to a directory that is in your system's PATH:
```bash
sudo mv target/release/phantomlink /bin/
```

##### Option 2: Use the Install Script
1. Clone the ```phantomlink``` repository from GitHub:
```bash
git clone https://github.com/robinohs/phantomlink
```
2. Navigate to the repository and execute the provided `install.sh` script:
```bash
cd phantomlink
./install.sh
```

### Notes
Verify ```phantomlink``` is correctly installed by running:
```bash
phantomlink --version
```

### Shell completions

```phantomlink``` provides shell completion support for multiple shells, including **bash**, **elvish**, **fish**, **PowerShell**, **zsh**, and **nushell**. It automatically detects your default shell from the environment, so you don’t need to specify it unless you want to.
To generate completions for a specific shell, use the command below. ```phantomlink``` will output the auto-completion code to stdout, allowing you to pipe it into the auto-completion file appropriate for your shell.

```bash
phantomlink generate
```

### Quick-start

1. Download the [input.csv](examples/input.csv) file from examples.
2. Setup the network environment:
```bash
phantomlink setup
```
3. Start the main virtual link (assuming the input file is in ~/Downloads):
```bash
phantomlink start ~/Downloads/input.csv
```
4. Start an application in the server network namespace:
```bash
phantomlink exec server iperf3 -s --port 5000
```
5. Start an application in the client network namespace:
```bash
phantomlink exec client iperf3 -c 192.168.66.2 --port 5000
```
6. To get informations about the client or server network namespace you can use:
```bash
phantomlink exec ifconfig
```
7. After the experiment has finished, you can teardown the network environment:
```bash
phantomlink teardown
```

## 🔍 Structure of ```phantomlink```

### Input Format

```phantomlink``` runs on scenario files—simple `.csv` files that contain the (time-evolving) parameters of the virtual end-to-end link. This format is motivated by the actual physical variability that an end-to-end connection can be exposed to.
Scenario files define the behavior of the virtual link over time, with parameters such as delay and data rate evolving throughout the experiment.
The `RouteID` column indicates whether there is an actual route change or only updated parameters for the current route.
```phantomlink``` is agnostic of how the scenario file was created and whether the values are realistic. Users can create hand-crafted, synthetic scenarios or use output from any (orbital) dynamics simulator to perform systematic.
Parameters are updated at specified times, creating a step function of changes. For example given the following table:

| Time [ms] | RouteID | Delay [ms] | Btldr [Mbps] |
| --------- | ------- | ---------- | ------------ |
| 0 | 0 | 41.0 | 80.0 |
| 11 000 | 0 | 41.2 | 80.2 |
| 23 000 | 1 | 37.0 | 100.0 |
| 40 000 | 1 | 36.7 | 101.5 |
| 60 000 | 1 | 37.0 | 100.1 |

- From `t = 0 ms`, a route with a one-way delay of `41.0 ms` and a data rate of `80.0 Mbit/s` is used.
- At `t = 11 s`, values are updated to `41.2 ms` and `80.2 Mbit/s`.
- At `t = 23 s`, the route changes, as indicated by a new `RouteID`.

### Architecture

Tool overview

At its core, the ```phantomlink``` toolchain has a binary that operates in conjunction with Linux network namespaces and virtual Ethernet devices.
The toolchain architecture consists of three network namespaces created with `netns`:
- Client Application Namespace
- PhantomLink Binary Namespace
- Server Application Namespace

The client and server namespaces are interconnected with the PhantomLink namespace using two virtual Ethernet devices, resulting in four virtual interfaces. For each virtual Ethernet device:
- One side is moved to the PhantomLink namespace (`sim-veth`)
- The other side is moved to the client or server namespace (`veth`)

After moving the interfaces, MAC and IP addresses are assigned. For each namespace except for the PhantomLink namespace:
- A loopback device is added
- `veth` is configured as the default route to enable traffic flow towards ```phantomlink```

To allow traffic to flow from the client to the server namespace and vice-versa, the ```phantomlink``` binary forwards packets between the two (`sim-veth`) interfaces. This enables applications in the client or server namespace to send and receive traffic over the emulated virtual end-to-end link that evolves according to the scenario file.

### Core Binary

Binary structure

The ```phantomlink``` binary is implemented in safe Rust to benefit from Rust’s performance and memory safety. The internal binary structure is depicted in the picture above.

1. **Namespace and Raw Sockets**:
- ```phantomlink``` is started in the PhantomLink namespace.
- It binds a raw sockets to the interfaces `sim-veth1` and `sim-veth2` each.

2. **libpnet crate**:
- Using the Rust crate `libpnet`, ```phantomlink``` creates a `pnet::datalink::Channel` for each interface.
- This allows ```phantomlink``` to send and receive at the data link layer.

3. **OnewayVirtualLink**:
- All incoming traffic from the client is processed by a `OnewayVirtualLink` and forwarded to the server.
- Similarly, a second `OnewayVirtualLink` instance handles all traffic from the server to the client.

The functionality and role of each individual component is explained in the paper.

## � FAQ

### I need help

Don't hesitate to file an issue or contact one of the authors!

### How can I help?

Please have a look at the issues or open one if you feel that something is needed.

Any contributions are very welcome!

## 🏛 License

`Phantomlink` is dual-licensed under [Apache License, Version 2.0](https://github.com/robinohs/phantomlink/blob/main/LICENSE-APACHE) or [MIT License](https://github.com/robinohs/phantomlink/blob/main/LICENSE-MIT).

## 🙏 Acknowledgement

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under the Marie Skłodowska-Curie grant agreement No [101008233](https://doi.org/10.3030/101008233) (MISSION).

## 🤼 Contributing

We look forward to any kind of contributions!

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.

### Contributors

_{Robin Ohs}
💻 📖 🤔 🚧 🔬

_Gregory
💻 📖 🤔 🔬

_{Andreas Schmidt}
💻 🎨 📖 🤔 🔬 🧑‍🏫

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome 😎.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/robinohs/phantomlink

Awesome Lists containing this project

README