Skip to content

Commit 00f60a6

Browse files
bropinesbropines
committed
updates readme
1 parent b601392 commit 00f60a6

2 files changed

Lines changed: 25 additions & 290 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 290 deletions
Original file line numberDiff line numberDiff line change
@@ -5,315 +5,50 @@
55

66
A wireguard and AmneziaWG client that exposes itself as a socks5/http proxy or tunnels.
77

8-
# What is this
8+
## What is this
99

1010
`wireproxy` is a completely userspace application that connects to a wireguard/AmneziaWG peer,
1111
and exposes a socks5/http proxy or tunnels on the machine. This can be useful if you need
1212
to connect to certain sites via a wireguard peer, but can't be bothered to setup a new network
1313
interface for whatever reasons.
1414

15-
# Credits & Authorship
15+
## Documentation
1616

17-
This project is a heavily modified fork standing on the shoulders of giants:
18-
- **[windtf/wireproxy](https://github.com/windtf/wireproxy)** (formerly octeep): The original creator and upstream maintainer.
19-
- **[artem-russkikh/wireproxy-awg](https://github.com/artem-russkikh/wireproxy-awg)**: Added AmneziaWG (AWG) support.
20-
- **[bropines/wireproxy-awg](https://github.com/bropines/wireproxy-awg)**: Current maintainer. Added dynamic UDP Proxy Tunnel support, refined build systems, and overall structural improvements.
17+
To keep things organized, the documentation is split into several modules. Please refer to the specific guides below:
2118

22-
# Why you might want this
19+
- 🚀 **[Installation & CLI Usage](docs/usage.md)** - How to build, install, and run wireproxy.
20+
- ⚙️ **[Configuration Guide](docs/configuration.md)** - Extensive configuration examples (SOCKS5, HTTP, TCP/UDP tunnels, AmneziaWG parameters).
21+
- 🐳 **[Docker Guide](docs/docker.md)** - How to run wireproxy inside a Docker container.
22+
- 🏥 **[Health Endpoints](docs/health-endpoint.md)** - Monitoring and health checks (`/metrics` & `/readyz`).
23+
- 🦊 **[Use with VPN & Browser Extensions](UseWithVPN.md)** - Setup with Firefox Container Tabs and MacOS auto-start.
2324

24-
- You simply want to use wireguard/AWG as a way to proxy some traffic.
25-
- You don't want root permission just to change wireguard settings.
26-
27-
Currently, I'm running wireproxy connected to a server in another country,
28-
and configured my browser to use wireproxy for certain sites. It's pretty useful since
29-
wireproxy is completely isolated from my network interfaces, and I don't need root to configure
30-
anything.
25+
**System Services Integrations:**
26+
- 🐧 [Running with systemd](systemd/README.md)
27+
- 🧰 [Running with rc.d](rc.d/README.md)
3128

32-
# Feature
29+
## Feature Highlights
3330

3431
- TCP static routing for client and server
3532
- UDP proxy and forwarding tunnel (`UDPProxyTunnel`)
3633
- SOCKS5/HTTP proxy (currently only CONNECT is supported)
3734
- Native AmneziaWG support
3835

39-
# Usage
40-
41-
```bash
42-
./wireproxy [-c path to config]
43-
```
44-
45-
```bash
46-
usage: wireproxy [-h|--help] [-c|--config "<value>"] [-s|--silent]
47-
[-d|--daemon] [-i|--info "<value>"] [-v|--version]
48-
[-n|--configtest]
49-
50-
Userspace wireguard client for proxying
51-
52-
Arguments:
53-
54-
-h --help Print help information
55-
-c --config Path of configuration file
56-
Default paths: /etc/wireproxy/wireproxy.conf, $HOME/.config/wireproxy.conf
57-
-s --silent Silent mode
58-
-d --daemon Make wireproxy run in background
59-
-i --info Specify the address and port for exposing health status
60-
-v --version Print version
61-
-n --configtest Configtest mode. Only check the configuration file for
62-
validity.
63-
```
64-
65-
# Build instruction
66-
67-
```bash
68-
git clone [https://github.com/bropines/wireproxy-awg](https://github.com/bropines/wireproxy-awg)
69-
cd wireproxy-awg
70-
make
71-
```
72-
73-
# Install
74-
75-
```bash
76-
go install [github.com/bropines/wireproxy-awg/cmd/wireproxy@latest](https://github.com/bropines/wireproxy-awg/cmd/wireproxy@latest)
77-
```
78-
79-
# Use with VPN
80-
81-
Instructions for using wireproxy with Firefox container tabs and auto-start on MacOS can be found [here](/UseWithVPN.md).
82-
83-
# Sample config file
84-
85-
```ini
86-
# The [Interface] and [Peer] configurations follow the same semantics and meaning
87-
# of a wg-quick configuration. To understand what these fields mean, please refer to:
88-
# [https://wiki.archlinux.org/title/WireGuard#Persistent_configuration](https://wiki.archlinux.org/title/WireGuard#Persistent_configuration)
89-
# [https://www.wireguard.com/#simple-network-interface](https://www.wireguard.com/#simple-network-interface)
90-
[Interface]
91-
Address = 10.200.200.2/32 # The subnet should be /32 and /128 for IPv4 and v6 respectively
92-
# MTU = 1420 (optional)
93-
PrivateKey = uCTIK+56CPyCvwJxmU5dBfuyJvPuSXAq1FzHdnIxe1Q=
94-
# PrivateKey = $MY_WIREGUARD_PRIVATE_KEY # Alternatively, reference environment variables
95-
DNS = 10.200.200.1
96-
97-
# AmneziaWG specific fields are fully supported here
98-
# Jc = 4
99-
# Jmin = 50
100-
# Jmax = 1000
101-
# S1 = 40
102-
# S2 = 40
103-
# H1 = 1
104-
# H2 = 2
105-
# H3 = 3
106-
# H4 = 4
107-
108-
[Peer]
109-
PublicKey = QP+A67Z2UBrMgvNIdHv8gPel5URWNLS4B3ZQ2hQIZlg=
110-
# PresharedKey = UItQuvLsyh50ucXHfjF0bbR4IIpVBd74lwKc8uIPXXs= (optional)
111-
Endpoint = my.ddns.example.com:51820
112-
# PersistentKeepalive = 25 (optional)
113-
114-
# TCPClientTunnel is a tunnel listening on your machine,
115-
# and it forwards any TCP traffic received to the specified target via wireguard.
116-
# Flow:
117-
# <an app on your LAN> --> localhost:25565 --(wireguard)--> play.cubecraft.net:25565
118-
[TCPClientTunnel]
119-
BindAddress = 127.0.0.1:25565
120-
Target = play.cubecraft.net:25565
121-
122-
# TCPServerTunnel is a tunnel listening on wireguard,
123-
# and it forwards any TCP traffic received to the specified target via local network.
124-
# Flow:
125-
# <an app on your wireguard network> --(wireguard)--> 172.16.31.2:3422 --> localhost:25545
126-
[TCPServerTunnel]
127-
ListenPort = 3422
128-
Target = localhost:25545
129-
130-
# UDPProxyTunnel listens locally and forwards dynamic UDP traffic via wireguard.
131-
# Flow:
132-
# <an app on your LAN> --> localhost:53 --(wireguard)--> 1.1.1.1:53
133-
[UDPProxyTunnel]
134-
BindAddress = 127.0.0.1:53
135-
Target = 1.1.1.1:53
136-
InactivityTimeout = 30 # If its set to 0, it will never timeout
137-
138-
# STDIOTunnel is a tunnel connecting the standard input and output of the wireproxy
139-
# process to the specified TCP target via wireguard.
140-
# This is especially useful to use wireproxy as a ProxyCommand parameter in openssh
141-
# For example:
142-
# ssh -o ProxyCommand='wireproxy -c myconfig.conf' ssh.myserver.net
143-
# Flow:
144-
# Piped command -->(wireguard)--> ssh.myserver.net:22
145-
[STDIOTunnel]
146-
Target = ssh.myserver.net:22
147-
148-
# Socks5 creates a socks5 proxy on your LAN, and all traffic would be routed via wireguard.
149-
[Socks5]
150-
BindAddress = 127.0.0.1:25344
151-
152-
# Socks5 authentication parameters, specifying username and password enables
153-
# proxy authentication.
154-
#Username = ...
155-
# Avoid using spaces in the password field
156-
#Password = ...
157-
158-
# http creates a http proxy on your LAN, and all traffic would be routed via wireguard.
159-
[http]
160-
BindAddress = 127.0.0.1:25345
161-
162-
# HTTP authentication parameters, specifying username and password enables
163-
# proxy authentication.
164-
#Username = ...
165-
# Avoid using spaces in the password field
166-
#Password = ...
167-
168-
# Specifying certificate and key enables HTTPS
169-
#CertFile = ...
170-
#KeyFile = ...
171-
```
172-
173-
Alternatively, if you already have a wireguard config, you can import it in the
174-
wireproxy config file like this:
175-
176-
```ini
177-
WGConfig = <path to the wireguard config>
178-
179-
# Same semantics as above
180-
[TCPClientTunnel]
181-
...
36+
## Why you might want this
18237

183-
[TCPServerTunnel]
184-
...
185-
186-
[Socks5]
187-
...
188-
```
189-
190-
Having multiple peers is also supported. `AllowedIPs` would need to be specified
191-
such that wireproxy would know which peer to forward to.
192-
193-
```ini
194-
[Interface]
195-
Address = 10.254.254.40/32
196-
PrivateKey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=
197-
198-
[Peer]
199-
Endpoint = 192.168.0.204:51820
200-
PublicKey = YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY=
201-
AllowedIPs = 10.254.254.100/32
202-
PersistentKeepalive = 25
203-
204-
[Peer]
205-
PublicKey = ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ=
206-
AllowedIPs = 10.254.254.1/32, fdee:1337:c000:d00d::1/128
207-
Endpoint = 172.16.0.185:44044
208-
PersistentKeepalive = 25
209-
210-
211-
[TCPServerTunnel]
212-
ListenPort = 5000
213-
Target = service-one.servicenet:5000
214-
215-
[TCPServerTunnel]
216-
ListenPort = 5001
217-
Target = service-two.servicenet:5001
218-
219-
[TCPServerTunnel]
220-
ListenPort = 5080
221-
Target = service-three.servicenet:80
222-
223-
[UDPProxyTunnel]
224-
BindAddress = 127.0.0.1:53
225-
Target = 1.1.1.1:53
226-
InactivityTimeout = 30 # If its set to 0, it will never timeout
227-
228-
[Resolve]
229-
# Set DNS Resovle Strategy
230-
# `ipv4`: Prioritize A records.
231-
# `ipv6`: Prioritize AAAA records .
232-
# `auto` (Default): If the WireGuard interface has IPv4 address only, it's equivalent to `ipv4`, otherwise it's equivalent to `ipv6`.
233-
ResolveStrategy = auto
234-
```
235-
236-
Wireproxy can also allow peers to connect to it:
237-
238-
```ini
239-
[Interface]
240-
ListenPort = 5400
241-
...
242-
243-
[Peer]
244-
PublicKey = YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY=
245-
AllowedIPs = 10.254.254.100/32
246-
# Note there is no Endpoint defined here.
247-
```
248-
249-
# Health endpoint
250-
251-
Wireproxy supports exposing a health endpoint for monitoring purposes.
252-
The argument `--info/-i` specifies an address and port (e.g. `localhost:9080`), which exposes a HTTP server that provides health status metric of the server.
253-
254-
Currently two endpoints are implemented:
255-
256-
`/metrics`: Exposes information of the wireguard daemon, this provides the same information you would get with `wg show`.
257-
[This](https://www.wireguard.com/xplatform/#example-dialog) shows an example of what the response would look like.
258-
259-
`/readyz`: This responds with a json which shows the last time a pong is received from an IP specified with `CheckAlive`.
260-
When `CheckAlive` is set, a ping is sent out to addresses in `CheckAlive` per `CheckAliveInterval` seconds (defaults to 5) via wireguard.
261-
If a pong has not been received from one of the addresses within the last `CheckAliveInterval` seconds (+2 seconds for some leeway to account for latency), then it would respond with a 503, otherwise a 200.
262-
263-
For example:
264-
265-
```ini
266-
[Interface]
267-
PrivateKey = censored
268-
Address = 10.2.0.2/32
269-
DNS = 10.2.0.1
270-
CheckAlive = 1.1.1.1, 3.3.3.3
271-
CheckAliveInterval = 3
272-
273-
[Peer]
274-
PublicKey = censored
275-
AllowedIPs = 0.0.0.0/0
276-
Endpoint = 149.34.244.174:51820
277-
278-
[Socks5]
279-
BindAddress = 127.0.0.1:25344
280-
```
281-
282-
`/readyz` would respond with
283-
284-
```text
285-
< HTTP/1.1 503 Service Unavailable
286-
< Date: Thu, 11 Apr 2024 00:54:59 GMT
287-
< Content-Length: 35
288-
< Content-Type: text/plain; charset=utf-8
289-
<
290-
{"1.1.1.1":1712796899,"3.3.3.3":0}
291-
```
292-
293-
And for:
294-
295-
```ini
296-
[Interface]
297-
PrivateKey = censored
298-
Address = 10.2.0.2/32
299-
DNS = 10.2.0.1
300-
CheckAlive = 1.1.1.1
301-
```
38+
- You simply want to use wireguard/AWG as a way to proxy some traffic.
39+
- You don't want root permission just to change wireguard settings.
30240

303-
`/readyz` would respond with
41+
Currently, I'm running wireproxy connected to a server in another country,
42+
and configured my browser to use wireproxy for certain sites. It's pretty useful since
43+
wireproxy is completely isolated from my network interfaces, and I don't need root to configure anything.
30444

305-
```text
306-
< HTTP/1.1 200 OK
307-
< Date: Thu, 11 Apr 2024 00:56:21 GMT
308-
< Content-Length: 23
309-
< Content-Type: text/plain; charset=utf-8
310-
<
311-
{"1.1.1.1":1712796979}
312-
```
45+
## Credits & Authorship
31346

314-
If nothing is set for `CheckAlive`, an empty JSON object with 200 will be the response.
315-
The peer which the ICMP ping packet is routed to depends on the `AllowedIPs` set for each peers.
47+
This project is a heavily modified fork standing on the shoulders of giants:
48+
- **[windtf/wireproxy](https://github.com/windtf/wireproxy)** (formerly octeep): The original creator and upstream maintainer.
49+
- **[artem-russkikh/wireproxy-awg](https://github.com/artem-russkikh/wireproxy-awg)**: Added AmneziaWG (AWG) support.
50+
- **[bropines/wireproxy-awg](https://github.com/bropines/wireproxy-awg)**: Current maintainer. Added dynamic UDP Proxy Tunnel support, refined build systems, and overall structural improvements.
31651

317-
# Stargazers over time
52+
## Stargazers over time
31853

319-
[![Stargazers over time](https://starchart.cc/bropines/awg-wireproxy.svg)](https://starchart.cc/bropines/awg-wireproxy)
54+
[![Stargazers over time](https://starchart.cc/bropines/awg-wireproxy.svg)](https://starchart.cc/bropines/awg-wireproxy)

systemd/README.md renamed to systemd/systemd_docs.md

File renamed without changes.

0 commit comments

Comments
 (0)