From 47cd451c803b82d7511e9c6dba170c1896519924 Mon Sep 17 00:00:00 2001 From: Lars Gerber <75072836+larsgerber@users.noreply.github.com> Date: Fri, 31 Jan 2025 16:59:57 +0100 Subject: [PATCH] docs: add syntax highlighting and Go install command (#158) * docs: add syntax language for codeblocks * docs: add install instructions for Go --- README.md | 50 ++++++++++++++++++++++++++++++++++++++------------ UseWithVPN.md | 17 ++++++++++++----- 2 files changed, 50 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 9e36158..575c596 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # wireproxy + [![ISC licensed](https://img.shields.io/badge/license-ISC-blue)](./LICENSE) [![Build status](https://github.com/octeep/wireproxy/actions/workflows/build.yml/badge.svg)](https://github.com/octeep/wireproxy/actions) [![Documentation](https://img.shields.io/badge/godoc-wireproxy-blue)](https://pkg.go.dev/github.com/octeep/wireproxy) @@ -6,12 +7,14 @@ A wireguard client that exposes itself as a socks5/http proxy or tunnels. # What is this + `wireproxy` is a completely userspace application that connects to a wireguard peer, and exposes a socks5/http proxy or tunnels on the machine. This can be useful if you need to connect to certain sites via a wireguard peer, but can't be bothered to setup a new network interface for whatever reasons. # Why you might want this + - You simply want to use wireguard as a way to proxy some traffic. - You don't want root permission just to change wireguard settings. @@ -24,19 +27,22 @@ Users who want something similar but for Amnezia VPN can use [this fork](https:/ of wireproxy by [@artem-russkikh](https://github.com/artem-russkikh). # Feature + - TCP static routing for client and server - SOCKS5/HTTP proxy (currently only CONNECT is supported) # TODO + - UDP Support in SOCKS5 - UDP static routing # Usage -``` + +```bash ./wireproxy [-c path to config] ``` -``` +```bash usage: wireproxy [-h|--help] [-c|--config ""] [-s|--silent] [-d|--daemon] [-i|--info ""] [-v|--version] [-n|--configtest] @@ -54,21 +60,29 @@ Arguments: -v --version Print version -n --configtest Configtest mode. Only check the configuration file for validity. - ``` # Build instruction -``` + +```bash git clone https://github.com/octeep/wireproxy cd wireproxy make ``` +# Install + +```bash +go install github.com/pufferffish/wireproxy/cmd/wireproxy@v1.0.9 # or @latest +``` + # Use with VPN + Instructions for using wireproxy with Firefox container tabs and auto-start on MacOS can be found [here](/UseWithVPN.md). # Sample config file -``` + +```ini # The [Interface] and [Peer] configurations follow the same semantics and meaning # of a wg-quick configuration. To understand what these fields mean, please refer to: # https://wiki.archlinux.org/title/WireGuard#Persistent_configuration @@ -135,7 +149,8 @@ BindAddress = 127.0.0.1:25345 Alternatively, if you already have a wireguard config, you can import it in the wireproxy config file like this: -``` + +```ini WGConfig = # Same semantics as above @@ -151,7 +166,8 @@ WGConfig = Having multiple peers is also supported. `AllowedIPs` would need to be specified such that wireproxy would know which peer to forward to. -``` + +```ini [Interface] Address = 10.254.254.40/32 PrivateKey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX= @@ -183,7 +199,8 @@ Target = service-three.servicenet:80 ``` Wireproxy can also allow peers to connect to it: -``` + +```ini [Interface] ListenPort = 5400 ... @@ -193,7 +210,9 @@ PublicKey = YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY= AllowedIPs = 10.254.254.100/32 # Note there is no Endpoint defined here. ``` + # Health endpoint + Wireproxy supports exposing a health endpoint for monitoring purposes. 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. @@ -204,7 +223,8 @@ Currently two endpoints are implemented: `/readyz`: This responds with a json which shows the last time a pong is received from an IP specified with `CheckAlive`. When `CheckAlive` is set, a ping is sent out to addresses in `CheckAlive` per `CheckAliveInterval` seconds (defaults to 5) via wireguard. 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. For example: -``` + +```ini [Interface] PrivateKey = censored Address = 10.2.0.2/32 @@ -220,8 +240,10 @@ Endpoint = 149.34.244.174:51820 [Socks5] BindAddress = 127.0.0.1:25344 ``` + `/readyz` would respond with -``` + +```text < HTTP/1.1 503 Service Unavailable < Date: Thu, 11 Apr 2024 00:54:59 GMT < Content-Length: 35 @@ -231,15 +253,18 @@ BindAddress = 127.0.0.1:25344 ``` And for: -``` + +```ini [Interface] PrivateKey = censored Address = 10.2.0.2/32 DNS = 10.2.0.1 CheckAlive = 1.1.1.1 ``` + `/readyz` would respond with -``` + +```text < HTTP/1.1 200 OK < Date: Thu, 11 Apr 2024 00:56:21 GMT < Content-Length: 23 @@ -253,4 +278,5 @@ If nothing is set for `CheckAlive`, an empty JSON object with 200 will be the re The peer which the ICMP ping packet is routed to depends on the `AllowedIPs` set for each peers. # Stargazers over time + [![Stargazers over time](https://starchart.cc/octeep/wireproxy.svg)](https://starchart.cc/octeep/wireproxy) diff --git a/UseWithVPN.md b/UseWithVPN.md index cb50538..6257258 100644 --- a/UseWithVPN.md +++ b/UseWithVPN.md @@ -1,11 +1,12 @@ # Getting a Wireguard Server + You can create your own wireguard server using a host service like DigitalOcean, or you can get a VPN service that provides WireGuard configs. I recommend ProtonVPN, because it is highly secure and has a great WireGuard config generator. -Simply go to https://account.protonvpn.com/downloads and scroll down to the +Simply go to and scroll down to the wireguard section to generate your configs, then paste into the appropriate section below. @@ -25,9 +26,11 @@ naming should also be similar (e.g. `/Users/jonny/Library/LaunchAgents/com.ProtonUS.adblock.plist`) ## Config File + Make sure you use a unique port for every separate server I recommend you set proxy authentication, you can use the same user/pass for all -``` + +```ini # Link to the Downloaded config WGConfig = /Users/jonny/vpntabs/ProtonUS.adblock.server.conf @@ -43,24 +46,27 @@ BindAddress = 127.0.0.1:25344 # Update the port here for each new server ``` ## Startup Script File + This is a bash script to facilitate startup, not strictly essential, but adds ease. Note, you MUST update the first path to wherever you installed this code to. Make sure you use the path for the config file above, not the one you downloaded from e.g. protonvpn. -``` + +```bash #!/bin/bash /Users/jonny/wireproxy/wireproxy -c /Users/jonny/vpntabs/ProtonUS.adblock.conf ``` ## MacOS LaunchAgent + To make it run every time you start your computer, you can create a launch agent in `$HOME/Library/LaunchAgents`. Name reference above. That file should contain the following, the label should be the same as the file name and the paths should be set correctly: -``` +```xml @@ -70,7 +76,7 @@ name and the paths should be set correctly: Program /Users/jonny/vpntabs/ProtonUS.adblock.sh RunAtLoad - + KeepAlive @@ -82,6 +88,7 @@ To enable it, run `launchtl start ~/Library/LaunchAgents/com.PortonUS.adblock.plist` # Firefox Setup + You will need to enable the Multi Account Container Tabs extension and a proxy extension, I recommend Sideberry, but Container Proxy also works.