Skip to content

Commit fcd540d

Browse files
seladbseladb
committed
Add server README
1 parent 0e63a48 commit fcd540d

File tree

1 file changed

+105
-0
lines changed

1 file changed

+105
-0
lines changed

‎server/README.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# ToyVPN Server 🌐
2+
3+
## Overview 🛠️
4+
This is the VPN server implemented in C++. It utilizes various networking libraries to handle packet forwarding, routing, and tunneling. The server is designed to manage VPN connections, forward traffic, and provide essential network functionalities.
5+
6+
It is heavily inspired by Android ToyVpn and provides a robust solution for handling VPN connections.
7+
8+
## Features 🚀
9+
- Supports multiple clients
10+
- Single-threaded, utilizing epoll for efficient event handling
11+
- Automatic configuration: creates tun interface, configures iptables and IP routing, and handles automatic teardown
12+
- Records pcapng files with traffic per VPN client
13+
14+
## Dependencies 🔗
15+
This project relies on the following libraries:
16+
- [PcapPlusPlus](https://github.com/seladb/PcapPlusPlus) for packet parsing and saving packets to pcapng files
17+
- [concurrentqueue](https://github.com/cameron314/concurrentqueue) for passing packets to save without interfering with the main processing thread
18+
- [argparse](https://github.com/p-ranav/argparse) for parsing CLI arguments
19+
- [AixLog](https://github.com/berkus/AixLog) for logging
20+
21+
## Building the Project 🛠️
22+
### Prerequisites ✅
23+
Ensure you have the following installed:
24+
- A C++ compiler supporting C++17
25+
- CMake (version 3.20 or higher)
26+
- `libpcap-dev` (required for `pcapplusplus`)
27+
28+
### Installing PcapPlusPlus 📦
29+
- Go to the latest release page: https://github.com/seladb/PcapPlusPlus/releases
30+
- Download the relevant binary for your operating system
31+
- Extract the archive file under `libs/`
32+
- Rename the folder to `pcapplusplus`
33+
34+
### Build Instructions 🏗️
35+
```sh
36+
mkdir build && cd build
37+
cmake ..
38+
make
39+
```
40+
41+
## Running the Server 🚀
42+
```sh
43+
sudo ./ToyVpnServer --port 5678 --public-network-iface eth0 --secret my_secret
44+
```
45+
46+
## How to Use ⚙️
47+
The server supports various CLI flags for configuration:
48+
49+
```sh
50+
Usage: ToyVpnServer [--help] [--version] [-t, --tun VAR] --port VAR [--private-network VAR] --public-network-iface VAR --secret VAR [--route VAR] [--mtu VAR] [--dns-server VAR] [--save-to-files VAR] [--verbose]
51+
52+
Optional arguments:
53+
-h, --help shows help message and exits
54+
-v, --version prints version information and exits
55+
-t, --tun the TUN interface name to create [nargs=0..1] [default: "tun0"]
56+
-p, --port the port to listen to for incoming connections [required]
57+
-e, --private-network the private network to use for the VPN connection [nargs=0..1] [default: "10.0.0.0/24"]
58+
-i, --public-network-iface the public network interface to use to send VPN traffic to the internet [required]
59+
-s, --secret the secret to verify the client [required]
60+
-r, --route the forwarding route [nargs=0..1] [default: 0.0.0.0/0]
61+
-m, --mtu maximum transmission unit (MTU) [nargs=0..1] [default: 1400]
62+
-d, --dns-server DNS server to use
63+
-f, --save-to-files save all network traffic to pcapng files [nargs=0..1] [default: ""]
64+
-l, --verbose print verbose log messages
65+
```
66+
67+
## Architecture 🏛️
68+
### Platform Support 🐧
69+
This server is designed to work exclusively on Linux.
70+
71+
### Main Components 🔩
72+
- `EpollWrapper.h`: Manages event-driven networking
73+
- `ServerSocketWrapper.h`: Manages the UDP socket that listens to incoming clients
74+
- `ClientHandler.h`: Handles the lifecycle of individual VPN clients - connecting to a new client, performing the handshake protocol, managing traffic from the client to the external network and vice versa, handling client disconnection
75+
- `TunInterfaceWrapper.h`: Creates and manages the TUN interface used for the VPN connection
76+
- `NatAndRoutingWrapper.h`: Configures IP forwarding and routing. Uses `iptables` and `ip route`
77+
- `PacketHandler.h`: Run in a separate thread, accepts packets from the main thread and saves them to pcapng files per VPN client
78+
- `ToyVpnServer.h`: Orchestrates all of the above and manages the server lifecycle
79+
80+
### Flow 🔄
81+
1. The server initializes and sets up a TUN interface.
82+
2. It configures IP forwarding and routing.
83+
3. Opens a UDP socket and starts listening to incoming clients.
84+
4. Clients connect, go through the handshake protocol and establish a VPN session.
85+
5. Packets are forwarded between clients and the external network (Internet).
86+
6. If requested by the user, packets are also passed to a different thread for saving them to pcapng files.
87+
7. When a client disconnects, the server cleans up the resources.
88+
8. When the server shuts down it removes the TUN interface and restores the IP forwarding and routing configurations.
89+
90+
### Handshake Protocol 🤝
91+
The handshake process establishes a connection between the client and the server, exchanging configuration details and authentication data:
92+
1. The client connects to the UDP socket the server listens on
93+
2. It sends the secret to the server and the server verifies the secret
94+
3. The server allocates a new internal IP address for the client and send configuration parameters to the client that include:
95+
- Client internal IP address
96+
- The forwarding route (`0.0.0.0/0` by default)
97+
- MTU
98+
- DNS server to use if configured by the server
99+
4. The client sends control packets once in a while to indicate it's still connected
100+
5. When a client wants to disconnect, it sends a special control message
101+
6. If the server shuts down, it sends a special disconnect control message to all connected clients
102+
103+
## License 📜
104+
This project is licensed under the MIT License.
105+

0 commit comments

Comments
 (0)