Skip to content

Commit 4403742

Browse files
CopilotCopilot
authored
Merge pull request #3 from masterking32/copilot/add-github-action-for-builds
docs: add server download links, fix TOML config comments, add full configuration reference
1 parent 6aceb82 commit 4403742

File tree

11 files changed

+628
-189
lines changed

11 files changed

+628
-189
lines changed

‎.github/workflows/build.yml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
name: Build Executables
2+
3+
on:
4+
push:
5+
branches:
6+
- "**"
7+
workflow_dispatch:
8+
9+
jobs:
10+
build:
11+
name: Build (${{ matrix.os }})
12+
runs-on: ${{ matrix.os }}
13+
permissions:
14+
contents: read
15+
strategy:
16+
matrix:
17+
include:
18+
- os: windows-latest
19+
platform: Windows
20+
arch: AMD64
21+
ext: .exe
22+
- os: ubuntu-latest
23+
platform: Linux
24+
arch: AMD64
25+
ext: ""
26+
- os: macos-latest
27+
platform: MacOS
28+
arch: ARM64
29+
ext: ""
30+
31+
steps:
32+
- name: Checkout repository
33+
uses: actions/checkout@v4
34+
35+
- name: Set up Python
36+
uses: actions/setup-python@v5
37+
with:
38+
python-version: "3.11"
39+
cache: "pip"
40+
41+
- name: Install dependencies
42+
run: |
43+
pip install pyinstaller
44+
pip install -r requirements.txt
45+
46+
- name: Build client
47+
run: |
48+
pyinstaller --onefile --name "MasterDnsVPN_Client_${{ matrix.platform }}_${{ matrix.arch }}" client.py
49+
50+
- name: Build server
51+
run: |
52+
pyinstaller --onefile --name "MasterDnsVPN_Server_${{ matrix.platform }}_${{ matrix.arch }}" server.py
53+
54+
- name: Bundle config templates with executables
55+
shell: bash
56+
run: |
57+
cp client_config.toml.simple dist/client_config.toml
58+
cp server_config.toml.simple dist/server_config.toml
59+
60+
- name: Create client ZIP
61+
shell: bash
62+
run: |
63+
cd dist
64+
if [ "${{ matrix.os }}" = "windows-latest" ]; then
65+
powershell Compress-Archive -Path "MasterDnsVPN_Client_${{ matrix.platform }}_${{ matrix.arch }}${{ matrix.ext }}", "client_config.toml" -DestinationPath "MasterDnsVPN_Client_${{ matrix.platform }}_${{ matrix.arch }}.zip"
66+
else
67+
zip "MasterDnsVPN_Client_${{ matrix.platform }}_${{ matrix.arch }}.zip" \
68+
"MasterDnsVPN_Client_${{ matrix.platform }}_${{ matrix.arch }}${{ matrix.ext }}" \
69+
"client_config.toml"
70+
fi
71+
72+
- name: Create server ZIP
73+
shell: bash
74+
run: |
75+
cd dist
76+
if [ "${{ matrix.os }}" = "windows-latest" ]; then
77+
powershell Compress-Archive -Path "MasterDnsVPN_Server_${{ matrix.platform }}_${{ matrix.arch }}${{ matrix.ext }}", "server_config.toml" -DestinationPath "MasterDnsVPN_Server_${{ matrix.platform }}_${{ matrix.arch }}.zip"
78+
else
79+
zip "MasterDnsVPN_Server_${{ matrix.platform }}_${{ matrix.arch }}.zip" \
80+
"MasterDnsVPN_Server_${{ matrix.platform }}_${{ matrix.arch }}${{ matrix.ext }}" \
81+
"server_config.toml"
82+
fi
83+
84+
- name: Upload client artifact
85+
uses: actions/upload-artifact@v4
86+
with:
87+
name: MasterDnsVPN_Client_${{ matrix.platform }}_${{ matrix.arch }}
88+
path: dist/MasterDnsVPN_Client_${{ matrix.platform }}_${{ matrix.arch }}.zip
89+
90+
- name: Upload server artifact
91+
uses: actions/upload-artifact@v4
92+
with:
93+
name: MasterDnsVPN_Server_${{ matrix.platform }}_${{ matrix.arch }}
94+
path: dist/MasterDnsVPN_Server_${{ matrix.platform }}_${{ matrix.arch }}.zip

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
__pycache__
22
server_config.py
33
client_config.py
4+
server_config.toml
5+
client_config.toml
46
encrypt_key.txt
57
*.key
68
*.pem

‎README.MD‎

Lines changed: 91 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -47,98 +47,88 @@ To make the tunnel functional, you must own a domain and configure the following
4747

4848
## 🚀 Installation & Usage
4949

50-
### 1. Install Dependencies
50+
### Option A: Download Pre-built Executable (Recommended)
5151

52-
Clone the repository and install the required Python libraries:
53-
```bash
54-
git clone https://github.com/masterking32/MasterDnsVPN.git
55-
cd MasterDnsVPN
56-
pip install -r requirements.txt
57-
```
52+
You can download the latest pre-built binary for your platform — no Python installation required.
5853

59-
#### 🔌 Offline Installation (Server Without Internet Access)
54+
**Client Downloads:**
6055

61-
If your **server has no internet access** and you cannot run `pip install` directly, follow these steps from a machine that **does** have internet access:
56+
| Platform | Download |
57+
|----------|----------|
58+
| 🪟 Windows (AMD64) | [MasterDnsVPN_Client_Windows_AMD64.zip](https://github.com/masterking32/MasterDnsVPN/releases/latest/download/MasterDnsVPN_Client_Windows_AMD64.zip) |
59+
| 🐧 Linux (AMD64) | [MasterDnsVPN_Client_Linux_AMD64.zip](https://github.com/masterking32/MasterDnsVPN/releases/latest/download/MasterDnsVPN_Client_Linux_AMD64.zip) |
60+
| 🍎 macOS (ARM64) | [MasterDnsVPN_Client_MacOS_ARM64.zip](https://github.com/masterking32/MasterDnsVPN/releases/latest/download/MasterDnsVPN_Client_MacOS_ARM64.zip) |
6261

63-
**Step 1 — Download Python installer (if Python is not installed on the server):**
64-
```bash
65-
# On the internet-connected machine, download the Python installer for Linux
66-
wget https://www.python.org/ftp/python/3.11.9/Python-3.11.9.tgz
67-
# Transfer it to your offline server using scp, USB, or any available method
68-
scp Python-3.11.9.tgz user@your-server:/tmp/
69-
```
62+
**Server Downloads:**
7063

71-
**Step 2 — Install Python from source on the offline server:**
72-
```bash
73-
# On the offline server
74-
cd /tmp
75-
tar xzf Python-3.11.9.tgz
76-
cd Python-3.11.9
77-
./configure --enable-optimizations
78-
make -j$(nproc)
79-
sudo make altinstall
80-
# Verify
81-
python3.11 --version
82-
```
64+
| Platform | Download |
65+
|----------|----------|
66+
| 🪟 Windows (AMD64) | [MasterDnsVPN_Server_Windows_AMD64.zip](https://github.com/masterking32/MasterDnsVPN/releases/latest/download/MasterDnsVPN_Server_Windows_AMD64.zip) |
67+
| 🐧 Linux (AMD64) | [MasterDnsVPN_Server_Linux_AMD64.zip](https://github.com/masterking32/MasterDnsVPN/releases/latest/download/MasterDnsVPN_Server_Linux_AMD64.zip) |
68+
| 🍎 macOS (ARM64) | [MasterDnsVPN_Server_MacOS_ARM64.zip](https://github.com/masterking32/MasterDnsVPN/releases/latest/download/MasterDnsVPN_Server_MacOS_ARM64.zip) |
8369

84-
**Step 3 — Download pip packages on the internet-connected machine:**
85-
```bash
86-
# On the internet-connected machine
87-
mkdir pip_packages
88-
pip download -r requirements.txt -d ./pip_packages
89-
# Transfer the entire folder to your offline server
90-
scp -r pip_packages user@your-server:/tmp/
91-
```
70+
Each client ZIP contains the executable and a `client_config.toml` template file. Each server ZIP contains the executable and a `server_config.toml` template file.
9271

93-
**Step 4 — Install packages from the downloaded folder on the offline server:**
94-
```bash
95-
# On the offline server
96-
pip install --no-index --find-links=/tmp/pip_packages -r requirements.txt
97-
```
72+
**Steps:**
9873

99-
> 💡 Make sure the Python version and OS architecture on both machines match (e.g., both Linux x86_64) so the downloaded wheel files are compatible.
74+
1. Extract the ZIP archive.
75+
2. Open `client_config.toml` in any text editor and set your values:
76+
- `ENCRYPTION_KEY` — copy from your server log on first run.
77+
- `DOMAINS` — your tunnel subdomain (e.g. `v.example.com`).
78+
- `RESOLVER_DNS_SERVERS` — public DNS resolvers (e.g. `8.8.8.8`).
79+
3. Place `client_config.toml` in the **same folder** as the executable and run it.
10080

10181
---
10282

103-
### 2. Server Configuration
83+
### Option B: Run from Source
84+
85+
#### 1. Install Dependencies
86+
87+
Clone the repository and install the required Python libraries:
88+
```bash
89+
git clone https://github.com/masterking32/MasterDnsVPN.git
90+
cd MasterDnsVPN
91+
pip install -r requirements.txt
92+
```
93+
94+
#### 2. Server Configuration
10495

10596
Copy the sample configuration:
10697

10798
```bash
108-
cp server_config.py.simple server_config.py
99+
cp server_config.toml.simple server_config.toml
109100
```
110101

111-
Edit `server_config.py` to include your domain and target forwarding IP/Port:
112-
- Install a proxy server (e.g., SOCKS5, VLESS, VMESS, SSH, MTProto, OpenVPN TCP, etc.) on the server machine to forward traffic to the internet.
113-
- Configure `FORWARD_IP` and `FORWARD_PORT` in `server_config.py` to point to your proxy server.
114-
- Configure `DOMAIN` to match the subdomain you set up in your DNS records (e.g., `v.example.com`). You can add multiple domains for redundancy.
115-
- Set `UDP_HOST` to `"0.0.0.0"` to listen on all interfaces (required for a public server).
116-
- After the first run, note the optimal MTU values for download and upload, then set `MAX_UPLOAD_MTU` and `MAX_DOWNLOAD_MTU` accordingly. This will significantly speed up subsequent runs.
102+
Edit `server_config.toml` to include your domain and target forwarding IP/Port.
103+
- Install a proxy server (e.g., SOCKS5, VLESS, VMESS, SSH, MTProto, OpenVPN TCP and etc) on the server machine to forward traffic to the internet.
104+
- Configure `FORWARD_IP` and `FORWARD_PORT` in `server_config.toml` to point to your proxy server.
105+
- Configure `DOMAIN` to match the subdomain you set up in your DNS records (e.g., `v.example.com`).
117106

118-
### 3. Run the Server
107+
#### 3. Run the Server
119108

120109
```bash
121110
python server.py
122111
```
123112

124113
On the first run, the server will generate an encryption key. **Save this key**; you will need it to configure the client.
125114

126-
### 4. Configure the Client
115+
#### 4. Configure the Client
127116

128117
Copy the sample client configuration:
129118

130119
```bash
131-
cp client_config.py.simple client_config.py
120+
cp client_config.toml.simple client_config.toml
132121
```
133122

134-
Edit `client_config.py`:
123+
Edit `client_config.toml`:
124+
125+
- `DOMAINS`: Your tunnel subdomain (e.g., `v.example.com`).
126+
127+
- `ENCRYPTION_KEY`: The key displayed in the server log.
135128

136-
- **`DOMAINS`**: Your tunnel subdomain(s) (e.g., `v.example.com`). Add multiple for redundancy.
137-
- **`ENCRYPTION_KEY`**: The key printed by your server on first run.
138-
- **`RESOLVER_DNS_SERVERS`**: List of public DNS resolvers to use (e.g., `8.8.8.8`, `1.1.1.1`, `9.9.9.9`). Add as many as possible for better reliability.
139-
- **`PACKET_DUPLICATION_COUNT`**: How many resolver+domain paths to use per packet (see emergency tip below).
129+
- `RESOLVER_DNS_SERVERS`: List of public DNS resolvers (e.g., `8.8.8.8`, `1.1.1.1`).
140130

141-
### 5. Run the Client
131+
#### 5. Run the Client
142132

143133
```bash
144134
python client.py
@@ -152,9 +142,9 @@ The client starts a local SOCKS5 proxy on `127.0.0.1:1080` (configurable via `LI
152142

153143
> **When the network is almost completely down and only DNS queries are getting through (extremely high packet loss and disruption):**
154144
155-
1. **Collect as many DNS resolver IP addresses as possible.** Add them all to `RESOLVER_DNS_SERVERS` in `client_config.py`. You can use public resolvers from Google (`8.8.8.8`, `8.8.4.4`), Cloudflare (`1.1.1.1`, `1.0.0.1`), Quad9 (`9.9.9.9`), OpenDNS (`208.67.222.222`, `208.67.220.220`), and others.
145+
1. **Collect as many DNS resolver IP addresses as possible.** Add them all to `RESOLVER_DNS_SERVERS` in `client_config.toml`. You can use public resolvers from Google (`8.8.8.8`, `8.8.4.4`), Cloudflare (`1.1.1.1`, `1.0.0.1`), Quad9 (`9.9.9.9`), OpenDNS (`208.67.222.222`, `208.67.220.220`), and others.
156146

157-
2. **Increase `PACKET_DUPLICATION_COUNT`** in `client_config.py`. This parameter controls how many different resolver+domain paths each packet is sent through **simultaneously**.
147+
2. **Increase `PACKET_DUPLICATION_COUNT`** in `client_config.toml`. This parameter controls how many different resolver+domain paths each packet is sent through **simultaneously**.
158148

159149
- With 6 resolvers and 2 domains, you have **12 potential paths**.
160150
- Setting `PACKET_DUPLICATION_COUNT = 6` means every packet is sent across 6 different paths at once.
@@ -166,6 +156,46 @@ The client starts a local SOCKS5 proxy on `127.0.0.1:1080` (configurable via `LI
166156

167157
---
168158

159+
## ⚙️ Configuration Reference
160+
161+
### 🖥️ Server — `server_config.toml`
162+
163+
> 🔑 The encryption key is **auto-generated** on first run and saved to `encrypt_key.txt` next to the server executable. It is also printed in the server log. Copy it to the client's `ENCRYPTION_KEY` field. Delete `encrypt_key.txt` and restart to rotate the key.
164+
165+
| Parameter | Default | Description |
166+
|-----------|---------|-------------|
167+
| `LOG_LEVEL` | `"INFO"` | Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
168+
| `UDP_HOST` | `"0.0.0.0"` | IP address the DNS/UDP server binds to. `"0.0.0.0"` = all interfaces. |
169+
| `UDP_PORT` | `53` | UDP port for the DNS server. Port `53` (standard DNS) requires root/admin privileges. |
170+
| `DOMAIN` | `["t.example.com"]` | Tunnel domain(s) this server accepts. Must match the client's `DOMAINS` list. |
171+
| `DATA_ENCRYPTION_METHOD` | `1` | Encryption algorithm. **Must match the client.** `0`=None, `1`=XOR, `2`=ChaCha20, `3`=AES-128-CTR, `4`=AES-192-CTR, `5`=AES-256-CTR |
172+
| `SESSION_TIMEOUT` | `300` | Inactivity time (seconds) before a client session expires. |
173+
| `SESSION_CLEANUP_INTERVAL` | `60` | Interval (seconds) at which expired sessions are removed. |
174+
| `FORWARD_IP` | `"127.0.0.1"` | IP of the local proxy/service that decrypted traffic is forwarded to. |
175+
| `FORWARD_PORT` | `8080` | Port of the local proxy/service (e.g. `1080` for SOCKS5, `443` for VLESS). |
176+
177+
### 💻 Client — `client_config.toml`
178+
179+
| Parameter | Default | Description |
180+
|-----------|---------|-------------|
181+
| `LOG_LEVEL` | `"INFO"` | Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
182+
| `RESOLVER_DNS_SERVERS` | `["8.8.8.8"]` | Public DNS resolvers that tunnel queries are forwarded through. Add multiple for redundancy and load balancing. |
183+
| `MIN_UPLOAD_MTU` | `40` | Minimum upload MTU (bytes) a resolver must achieve to be used. Set to `0` to disable. |
184+
| `MIN_DOWNLOAD_MTU` | `40` | Minimum download MTU (bytes) a resolver must achieve to be used. Set to `0` to disable. |
185+
| `MAX_UPLOAD_MTU` | `160` | Upper bound (bytes) for upload MTU auto-probing. |
186+
| `MAX_DOWNLOAD_MTU` | `200` | Upper bound (bytes) for download MTU auto-probing. |
187+
| `RESOLVER_BALANCING_STRATEGY` | `1` | Load-balancing strategy across resolvers: `1`=Random, `2`=Round-Robin, `3`=Least-Loss |
188+
| `DOMAINS` | `["t.example.com"]` | Tunnel domain(s) pointing to your server via NS records. Add multiple for multi-path redundancy. |
189+
| `DATA_ENCRYPTION_METHOD` | `1` | Encryption algorithm. **Must match the server.** `0`=None, `1`=XOR, `2`=ChaCha20, `3`=AES-128-CTR, `4`=AES-192-CTR, `5`=AES-256-CTR |
190+
| `ENCRYPTION_KEY` | `""` | Key from the server's `encrypt_key.txt` or first-run log. Must match the server. |
191+
| `DNS_QUERY_TIMEOUT` | `5` | Seconds to wait for a DNS response before considering a query failed. |
192+
| `LISTEN_IP` | `"127.0.0.1"` | Local IP the SOCKS5 proxy listens on. |
193+
| `LISTEN_PORT` | `1080` | Local port for the SOCKS5 proxy. Point your application to this address. |
194+
| `NUM_DNS_WORKERS` | `4` | Number of concurrent async DNS worker tasks. Increase for higher traffic. |
195+
| `PACKET_DUPLICATION_COUNT` | `3` | How many resolver+domain paths each packet is sent through simultaneously. Higher = more reliable but more bandwidth. |
196+
197+
---
198+
169199
## 🛠️ How It Works
170200

171201
### System Architecture

0 commit comments

Comments
 (0)