Skip to content

Commit 3e2a63a

Browse files
matveynatormatveynator
authored
Update README.md
1 parent 0a1697e commit 3e2a63a

1 file changed

Lines changed: 130 additions & 169 deletions

File tree

‎README.md‎

Lines changed: 130 additions & 169 deletions
Original file line numberDiff line numberDiff line change
@@ -1,216 +1,177 @@
1-
<img src="https://github.com/matveynator/chicha-ip-proxy/blob/master/chicha-ip-proxy.png?raw=true" width="100%" align="right"></img>
1+
<img src="https://github.com/matveynator/chicha-ip-proxy/blob/master/chicha-ip-proxy.png?raw=true" width="100%" align="right" />
22

3+
# Chicha IP Proxy
34

4-
# Chicha IP Proxy is the fastest and simplest solution for port forwarding.
5+
**Chicha IP Proxy** is a lightweight, high-performance **Layer 2 (L2) IP proxy** written in **Go**.
6+
It forwards TCP and UDP ports with minimal overhead and zero configuration files.
57

6-
Chicha IP Proxy is a lightweight **Layer 2 (L2) proxy** written in **Go**, designed for efficient port forwarding. It’s faster and simpler than traditional tools like `xinetd`, making it ideal for handling high traffic with minimal setup.
8+
Designed as a fast and simple alternative to tools like `xinetd`.
79

810
---
911

10-
### **Why Choose Chicha IP Proxy?**
11-
- **Blazing Fast**: Written in Go, it fully utilizes all CPU cores for optimal performance.
12-
- **Simple to Use**: One command to forward traffic—no complex configurations.
13-
- **Log Rotation**: Rotates logs daily while keeping them uncompressed for easy inspection.
14-
- **Cross-Platform**: Compatible with all major operating systems and architectures.
15-
- **Efficient**: Low resource usage even under heavy load.
12+
## What You Get
13+
14+
* 🚀 **Very fast** — Go, multi-core, low latency
15+
* 🧩 **Zero config files** — CLI only
16+
* 🔁 **TCP & UDP support**
17+
* 🛠 **Interactive auto-configuration**
18+
* 📦 **systemd integration**
19+
* 📝 **Built-in log rotation**
20+
* 🖥 **Single static binary**
1621

1722
---
1823

19-
### **Quick Setup / Краткий запуск**
24+
## Typical Use Cases
25+
26+
* Mirror a website (80 / 443)
27+
* Forward game or VPN ports (UDP)
28+
* Replace `xinetd` / `iptables` port forwarding
29+
* Quickly expose internal services
30+
31+
---
32+
33+
## Download
34+
35+
Download the latest Linux binary:
2036

21-
#### **English — minimal auto-setup**
22-
The built-in wizard does the heavy lifting (systemd unit, enable, start, log tail). You only download the binary and run it. Replace `203.0.113.44` with your origin.
2337
```bash
2438
curl -L https://github.com/matveynator/chicha-ip-proxy/releases/latest/download/chicha-ip-proxy-linux-amd64 -o chicha-ip-proxy
25-
sudo install -m 0755 chicha-ip-proxy /usr/local/bin/chicha-ip-proxy
26-
sudo /usr/local/bin/chicha-ip-proxy
27-
```
28-
Short transcript so you know what to expect:
29-
```
30-
root@mirror:~# /usr/local/bin/chicha-ip-proxy
31-
No routes provided via flags. Starting interactive configuration...
32-
Enter target IP address to proxy to: 203.0.113.44
33-
Enter protocols (comma separated, supported: tcp, udp): tcp
34-
Enter local TCP ports (comma separated): 80, 443
35-
Planned log file: /var/log/chicha-ip-proxy-tcp-443-80.log
36-
Planned systemd service name: chicha-ip-proxy-tcp-443-80.service
37-
Would you like to create a systemd service 'chicha-ip-proxy-tcp-443-80.service'? (y/N): y
38-
Enable the service so it starts on boot? (y/N): y
39-
Start the service now? (y/N): y
40-
Follow the log file now? (y/N): y
41-
========== CHICHA IP PROXY ==========
42-
TCP Routes:
43-
LocalPort=443 -> RemoteIP=203.0.113.44 RemotePort=443
44-
LocalPort=80 -> RemoteIP=203.0.113.44 RemotePort=80
45-
Log file: /var/log/chicha-ip-proxy-tcp-443-80.log
46-
Log rotation frequency: 24h0m0s
47-
======================================
39+
install -m 0755 chicha-ip-proxy /usr/local/bin/chicha-ip-proxy
4840
```
4941

50-
#### **English — quick flags instead of wizard**
51-
- Mirror a site over TCP:
52-
```bash
53-
sudo chicha-ip-proxy -routes "80:198.51.100.5:80,443:198.51.100.5:443" -log /var/log/chicha-ip-proxy.log
54-
```
55-
- Forward WireGuard over UDP:
56-
```bash
57-
sudo chicha-ip-proxy -udp-routes "51820:198.51.100.20:51820" -log /var/log/chicha-ip-proxy.log
58-
```
59-
60-
Daily log rotation keeps files uncompressed for fast inspection.
42+
That’s it. No dependencies.
6143

6244
---
6345

64-
#### **Русский — минимальная автонастройка**
65-
Мастер сам создаёт unit, включает, запускает и показывает лог. Вам нужно только скачать бинарник и запустить его. Замените `203.0.113.44` на ваш источник.
46+
## Quick Start (Recommended)
47+
48+
Just run the binary **without flags**.
49+
6650
```bash
67-
curl -L https://github.com/matveynator/chicha-ip-proxy/releases/latest/download/chicha-ip-proxy-linux-amd64 -o chicha-ip-proxy
68-
sudo install -m 0755 chicha-ip-proxy /usr/local/bin/chicha-ip-proxy
69-
sudo /usr/local/bin/chicha-ip-proxy
51+
chicha-ip-proxy
7052
```
71-
Короткий диалог мастера:
53+
54+
### What happens next?
55+
56+
An interactive wizard starts automatically and asks a few simple questions:
57+
58+
* target IP address
59+
* protocol (TCP / UDP)
60+
* local ports
61+
* systemd service creation
62+
* enable on boot
63+
* start now
64+
* follow logs
65+
66+
### Example Session
67+
7268
```
73-
root@mirror:~# /usr/local/bin/chicha-ip-proxy
7469
No routes provided via flags. Starting interactive configuration...
70+
7571
Enter target IP address to proxy to: 203.0.113.44
76-
Enter protocols (comma separated, supported: tcp, udp): tcp
77-
Enter local TCP ports (comma separated): 80, 443
78-
Planned log file: /var/log/chicha-ip-proxy-tcp-443-80.log
79-
Planned systemd service name: chicha-ip-proxy-tcp-443-80.service
80-
Would you like to create a systemd service 'chicha-ip-proxy-tcp-443-80.service'? (y/N): y
81-
Enable the service so it starts on boot? (y/N): y
82-
Start the service now? (y/N): y
83-
Follow the log file now? (y/N): y
84-
========== CHICHA IP PROXY ==========
85-
TCP Routes:
86-
LocalPort=443 -> RemoteIP=203.0.113.44 RemotePort=443
87-
LocalPort=80 -> RemoteIP=203.0.113.44 RemotePort=80
88-
Log file: /var/log/chicha-ip-proxy-tcp-443-80.log
89-
Log rotation frequency: 24h0m0s
90-
======================================
72+
Enter protocols (tcp, udp): tcp
73+
Enter local TCP ports: 80,443
74+
75+
Planned log file:
76+
/var/log/chicha-ip-proxy-tcp-443-80.log
77+
78+
Planned systemd service:
79+
chicha-ip-proxy-tcp-443-80.service
80+
81+
Create systemd service? (y/N): y
82+
Enable on boot? (y/N): y
83+
Start now? (y/N): y
84+
Follow logs now? (y/N): y
9185
```
9286

93-
#### **Русский — запуск с флагами вместо мастера**
94-
- Зеркало сайта по TCP:
95-
```bash
96-
sudo chicha-ip-proxy -routes "80:198.51.100.5:80,443:198.51.100.5:443" -log /var/log/chicha-ip-proxy.log
97-
```
98-
- Проброс WireGuard по UDP:
99-
```bash
100-
sudo chicha-ip-proxy -udp-routes "51820:198.51.100.20:51820" -log /var/log/chicha-ip-proxy.log
101-
```
87+
---
88+
89+
## Result
10290

103-
Логи ротируются ежедневно без сжатия и остаются удобными для просмотра и поиска.
91+
After the wizard finishes:
92+
93+
✅ Ports are forwarded
94+
✅ systemd service is running
95+
✅ Logs are written and rotated daily
96+
✅ Service starts automatically on reboot
97+
98+
You don’t need to touch anything else.
10499

105100
---
106101

107-
### **Command reference / Справка по командам**
102+
## Run Without Wizard (Flags Only)
108103

109-
```
110-
chicha-ip-proxy-linux --help
111-
Usage of chicha-ip-proxy-linux:
112-
-log string
113-
Path to the log file (default "chicha-ip-proxy.log")
114-
-rotation duration
115-
Log rotation frequency (e.g. 24h, 1h, etc.) (default 24h0m0s)
116-
-routes string
117-
Comma-separated list of TCP routes in the format LOCALPORT:REMOTEIP:REMOTEPORT
118-
-udp-routes string
119-
Comma-separated list of UDP routes in the format LOCALPORT:REMOTEIP:REMOTEPORT
120-
-version
121-
Print the version of the proxy and exit
122-
```
104+
### TCP Port Forwarding
123105

124-
```
125-
chicha-ip-proxy-linux --help
126-
Подсказка по флагам:
127-
-log string
128-
Путь к файлу логов (по умолчанию "chicha-ip-proxy.log")
129-
-rotation duration
130-
Как часто ротировать логи (например 24h, 1h и т.д.) (по умолчанию 24h0m0s)
131-
-routes string
132-
TCP-маршруты через запятую в виде LOCALPORT:REMOTEIP:REMOTEPORT
133-
-udp-routes string
134-
UDP-маршруты через запятую в виде LOCALPORT:REMOTEIP:REMOTEPORT
135-
-version
136-
Показать версию и выйти
106+
```bash
107+
chicha-ip-proxy \
108+
-routes "80:198.51.100.5:80,443:198.51.100.5:443" \
109+
-log /var/log/chicha-ip-proxy.log
137110
```
138111

139-
### **Why Chicha IP Proxy?**
140-
- **Go-Powered Performance**: Written in Go, ensuring speed and reliability.
141-
- **Multi-Port Support**: Easily forward traffic for one or multiple ports.
142-
- **No Complexity**: Simple commands, no bloated configs.
143-
- **Ready for Production**: Log rotation with readable archives and systemd integration make it production-ready.
112+
### UDP Port Forwarding (example: WireGuard)
113+
114+
```bash
115+
chicha-ip-proxy \
116+
-udp-routes "51820:198.51.100.20:51820" \
117+
-log /var/log/chicha-ip-proxy.log
118+
```
144119

145120
---
146-
### **Benchmarks**
147121

148-
#### **chicha-ip-proxy:**
122+
## Logs
123+
124+
* Logs are **plain text**
125+
* Rotated automatically
126+
* Default rotation: **every 24 hours**
127+
* No compression (easy to grep)
128+
129+
Example:
149130

150131
```
151-
siege http://localhost:8081 -t 15s -c 100
152-
** SIEGE 4.0.4
153-
** Preparing 100 concurrent users for battle.
154-
The server is now under siege...
155-
Lifting the server siege...
156-
Transactions: 15728 hits
157-
Availability: 100.00 %
158-
Elapsed time: 14.65 secs
159-
Data transferred: 124.07 MB
160-
Response time: 0.03 secs
161-
Transaction rate: 1073.58 trans/sec
162-
Throughput: 8.47 MB/sec
163-
Concurrency: 33.37
164-
Successful transactions: 11824
165-
Failed transactions: 0
166-
Longest transaction: 0.25
167-
Shortest transaction: 0.00
132+
/var/log/chicha-ip-proxy-tcp-443-80.log
168133
```
169134

170-
#### **xinetd:**
171-
```
172-
siege http://localhost:8082 -t 15s -c 100
173-
** SIEGE 4.0.4
174-
** Preparing 100 concurrent users for battle.
175-
The server is now under siege...
176-
Lifting the server siege...
177-
Transactions: 14863 hits
178-
Availability: 100.00 %
179-
Elapsed time: 14.57 secs
180-
Data transferred: 117.20 MB
181-
Response time: 0.04 secs
182-
Transaction rate: 1020.11 trans/sec
183-
Throughput: 8.04 MB/sec
184-
Concurrency: 36.99
185-
Successful transactions: 11178
186-
Failed transactions: 0
187-
Longest transaction: 0.55
188-
Shortest transaction: 0.00
189-
135+
---
136+
137+
## Command Reference
138+
139+
```bash
140+
chicha-ip-proxy --help
190141
```
191142

192-
#### **direct requests:**
193143
```
194-
siege http://files.zabiyaka.net:80 -t 15s -c 100
195-
** SIEGE 4.0.4
196-
** Preparing 100 concurrent users for battle.
197-
The server is now under siege...
198-
Lifting the server siege...
199-
Transactions: 14778 hits
200-
Availability: 100.00 %
201-
Elapsed time: 14.14 secs
202-
Data transferred: 116.52 MB
203-
Response time: 0.03 secs
204-
Transaction rate: 1045.12 trans/sec
205-
Throughput: 8.24 MB/sec
206-
Concurrency: 35.07
207-
Successful transactions: 11112
208-
Failed transactions: 0
209-
Longest transaction: 0.19
210-
Shortest transaction: 0.00
144+
-log string
145+
Path to log file (default: chicha-ip-proxy.log)
146+
147+
-rotation duration
148+
Log rotation interval (default: 24h)
149+
150+
-routes string
151+
TCP routes:
152+
LOCALPORT:REMOTEIP:REMOTEPORT[, ...]
153+
154+
-udp-routes string
155+
UDP routes:
156+
LOCALPORT:REMOTEIP:REMOTEPORT[, ...]
157+
158+
-version
159+
Print version and exit
211160
```
212161

213162
---
214163

164+
## Performance
165+
166+
Chicha IP Proxy is designed to be as close as possible to direct traffic.
167+
168+
### Benchmark Summary
169+
170+
| Method | Requests/sec | Response Time |
171+
| --------------- | ------------ | ------------- |
172+
| Direct requests | ~1045 | ~0.03s |
173+
| chicha-ip-proxy | ~1073 | ~0.03s |
174+
| xinetd | ~1020 | ~0.04s |
175+
176+
215177

216-
Chicha IP Proxy is the **fastest and simplest solution** for port forwarding. Whether forwarding one port or dozens, it's the ideal tool for sysadmins looking for performance and ease of use!

0 commit comments

Comments
 (0)