Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yaa110/tokio-tun
Asynchronous allocation of TUN/TAP devices in Rust using tokio
https://github.com/yaa110/tokio-tun
async crates rust tap tokio tun
Last synced: about 4 hours ago
JSON representation
Asynchronous allocation of TUN/TAP devices in Rust using tokio
- Host: GitHub
- URL: https://github.com/yaa110/tokio-tun
- Owner: yaa110
- License: apache-2.0
- Created: 2020-10-03T05:04:24.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-10-23T11:05:11.000Z (2 months ago)
- Last Synced: 2024-12-15T08:03:14.628Z (7 days ago)
- Topics: async, crates, rust, tap, tokio, tun
- Language: Rust
- Homepage: https://crates.io/crates/tokio-tun
- Size: 42 KB
- Stars: 82
- Watchers: 3
- Forks: 29
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# Tokio TUN/TAP
[](https://github.com/yaa110/tokio-tun/actions) [](https://crates.io/crates/tokio-tun) [](https://docs.rs/tokio-tun) [](examples)
Asynchronous allocation of TUN/TAP devices in Rust using [`tokio`](https://crates.io/crates/tokio). Use [async-tun](https://crates.io/crates/async-tun) for `async-std` version.
## Getting Started
- Create a tun device using `Tun::builder()` and read from it in a loop:
```rust
#[tokio::main]
async fn main() {
let tun = Arc::new(
Tun::builder()
.name("") // if name is empty, then it is set by kernel.
.tap() // uses TAP instead of TUN (default).
.packet_info() // avoids setting IFF_NO_PI.
.up() // or set it up manually using `sudo ip link set up`.
.try_build() // or `.try_build_mq(queues)` for multi-queue support.
.unwrap(),
);
println!("tun created, name: {}, fd: {}", tun.name(), tun.as_raw_fd());
let (mut reader, mut _writer) = tokio::io::split(tun);
// Writer: simply clone Arced Tun.
let tun_c = tun.clone();
tokio::spawn(async move{
let buf = b"data to be written";
tun_c.send_all(buf).await.unwrap();
});
// Reader
let mut buf = [0u8; 1024];
loop {
let n = tun.recv(&mut buf).await.unwrap();
println!("reading {} bytes: {:?}", n, &buf[..n]);
}
}
```
- Run the code using `sudo`:
```bash
sudo -E $(which cargo) run
```
- Set the address of device (address and netmask could also be set using `TunBuilder`):
```bash
sudo ip a add 10.0.0.1/24 dev
```
- Ping to read packets:
```bash
ping 10.0.0.2
```
- Display devices and analyze the network traffic:
```bash
ip tuntap
sudo tshark -i
```
## Supported Platforms
- [x] Linux
- [ ] FreeBSD
- [ ] Android
- [ ] OSX
- [ ] iOS
- [ ] Windows
## Examples
- [`read`](examples/read.rs): Split tun to (reader, writer) pair and read packets from reader.
- [`read-mq`](examples/read-mq.rs): Read from multi-queue tun using `tokio::select!`.
```bash
sudo -E $(which cargo) run --example read
sudo -E $(which cargo) run --example read-mq
```