### Socks5Config.SpawnRoutine Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/03-api-reference-routines.md

Example of how to start a SOCKS5 server using Socks5Config. It listens on the configured address and routes traffic through a VirtualTun.

```go
config := &Socks5Config{
    BindAddress: "127.0.0.1:1080",
}
go config.SpawnRoutine(tun)

// Client can now: curl -x socks5://127.0.0.1:1080 http://example.com
```

--------------------------------

### Basic HTTP Proxy Setup

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/04-api-reference-http.md

Sets up and starts a basic HTTP proxy server listening on a specified address. Client usage involves configuring `curl` with the proxy address.

```Go
server := &HTTPServer{
    config: &HTTPConfig{BindAddress: "127.0.0.1:8080"},
    dial: tun.Tnet.Dial,
}

go server.ListenAndServe("tcp", "127.0.0.1:8080")

// Client usage:
// curl -x http://127.0.0.1:8080 http://example.com
```

--------------------------------

### HTTPConfig.SpawnRoutine Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/03-api-reference-routines.md

Example of starting an HTTP proxy server using HTTPConfig. It listens on the configured address and routes traffic through a VirtualTun, supporting authentication and HTTPS.

```go
config := &HTTPConfig{
    BindAddress: "127.0.0.1:8080",
    Username: "user",
    Password: "pass",
}
go config.SpawnRoutine(tun)

// Usage: curl -x http://user:pass@127.0.0.1:8080 http://example.com
```

--------------------------------

### HTTP Health Check Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/02-api-reference-wireguard.md

Example of starting an HTTP server with the VirtualTun handler and demonstrating a health check request.

```go
go func() {
    http.ListenAndServe("localhost:9080", tun)
}()

// Then: curl http://localhost:9080/readyz
// Response: {"1.1.1.1":1712796899}
```

--------------------------------

### GET /readyz Request Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Example HTTP GET request to the /readyz endpoint for checking Wireproxy's health status.

```http
GET /readyz HTTP/1.1
Host: localhost:9080
```

--------------------------------

### Install Wireproxy-AWG

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/README.md

Command to install the wireproxy binary using go install, specifying a version or using the latest.

```bash
go install github.com/artem-russkikh/wireproxy-awg/cmd/wireproxy@v1.0.15 # or @latest
```

--------------------------------

### Start WireGuard Device Setup

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/09-errors-reference.md

Handles potential errors during WireGuard device initialization, such as permission issues or network stack failures.

```go
tun, err := wireproxy.StartWireguard(conf, logLevel)
if err != nil {
    log.Fatal(err)  // Device creation failed
}
```

--------------------------------

### TCPClientTunnelConfig.SpawnRoutine Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/03-api-reference-routines.md

Example of starting a TCP client tunnel using TCPClientTunnelConfig. It listens on a local address and forwards connections to a remote target via WireGuard.

```go
config := &TCPClientTunnelConfig{
    BindAddress: &net.TCPAddr{IP: net.ParseIP("127.0.0.1"), Port: 25565},
    Target: "play.cubecraft.net:25565",
}
go config.SpawnRoutine(tun)

// Local app connects to 127.0.0.1:25565
// Traffic forwarded through WireGuard to play.cubecraft.net:25565
```

--------------------------------

### Catching WireGuard Device Setup Errors

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/09-errors-reference.md

Shows how to catch and handle errors that occur when starting the WireGuard device using wireproxy.StartWireguard.

```go
tun, err := wireproxy.StartWireguard(conf.Device, logLevel)
if err != nil {
    log.Fatalf("Failed to start WireGuard: %v", err)
}
```

--------------------------------

### WireProxy Command-line Examples

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/07-configuration-reference.md

Provides practical examples of common WireProxy command-line invocations, such as specifying a config file, running as a daemon, and validating configuration.

```bash
# Run with specific config
wireproxy -c /etc/wireproxy/wg.conf

# Run as daemon with health monitoring
wireproxy -d -i localhost:9080

# Validate config
wireproxy -n -c /etc/wireproxy/wg.conf

# Silent mode
wireproxy -s
```

--------------------------------

### WireProxy Go API: Parse Config and Start Device

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/README.md

Demonstrates the initial steps in the WireProxy Go API: parsing a configuration file and starting the WireGuard device. Ensure necessary imports are present.

```go
// 1. Parse configuration
conf, err := wireproxy.ParseConfig("config.conf")

// 2. Create WireGuard device
tun, err := wireproxy.StartWireguard(conf.Device, logLevel)

// 3. Spawn proxies/tunnels
for _, spawner := range conf.Routines {
    go spawner.SpawnRoutine(tun)
}

// 4. Optional: Health monitoring
http.Handle("/", tun)  // VirtualTun implements http.Handler
go http.ListenAndServe("localhost:9080", nil)

```

--------------------------------

### Complete WireProxy Configuration Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/07-configuration-reference.md

A comprehensive example demonstrating the integration of various WireProxy configuration sections, including interface, peer, SOCKS5, HTTP, tunnels, and DNS settings.

```ini
[Interface]
Address = 10.200.200.2/32
PrivateKey = uCTIK+56CPyCvwJxmU5dBfuyJvPuSXAq1FzHdnIxe1Q=
DNS = 10.200.200.1
MTU = 1420
CheckAlive = 1.1.1.1
CheckAliveInterval = 5

[Peer]
PublicKey = QP+A67Z2UBrMgvNIdHv8gPel5URWNLS4B3ZQ2hQIZlg=
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

# SOCKS5 proxy on localhost
[Socks5]
BindAddress = 127.0.0.1:1080

# HTTP proxy with auth
[http]
BindAddress = 127.0.0.1:8080
Username = user
Password = pass

# Local tunnel to game server
[TCPClientTunnel]
BindAddress = 127.0.0.1:25565
Target = play.cubecraft.net:25565

# Server-side tunnel
[TCPServerTunnel]
ListenPort = 3422
Target = localhost:3422

# DNS proxy
[UDPProxyTunnel]
BindAddress = 127.0.0.1:53
Target = 1.1.1.1:53
InactivityTimeout = 60

# DNS strategy
[Resolve]
ResolveStrategy = auto
```

--------------------------------

### GET /metrics Response Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Example response from the /metrics endpoint, providing key-value pairs of WireGuard device metrics. Sensitive fields like private_key are redacted.

```text
private_key=REDACTED
listen_port=51820
public_key=QP+A67Z2UBrMgvNIdHv8gPel5URWNLS4B3ZQ2hQIZlg=
protocol_version=1
endpoint=vpn.example.com:51820
allowed_ip=0.0.0.0/0
allowed_ip=::/0
latest_handshake=1712796979
transfer_rx=1048576
transfer_tx=2097152
persistent_keepalive_interval=25
preshared_key=REDACTED
...
```

--------------------------------

### ListenAndServe Method

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/04-api-reference-http.md

Starts the HTTP proxy server. Use this to begin accepting incoming connections. It blocks until a fatal error occurs.

```go
func (s *HTTPServer) ListenAndServe(network, addr string) error
```

```go
server := &HTTPServer{
    config: &HTTPConfig{BindAddress: "127.0.0.1:8080"},
    dial: tun.Tnet.Dial,
    auth: CredentialValidator{},
}

err := server.ListenAndServe("tcp", "127.0.0.1:8080")
// Blocks until fatal error
```

--------------------------------

### Start WireProxy Service

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Command to start the WireProxy service with a specified configuration file and listening interface for monitoring.

```bash
wireproxy -c config.conf -i 0.0.0.0:9080

```

--------------------------------

### Socks5 Configuration Example (INI)

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/03-api-reference-routines.md

Example INI format for configuring a SOCKS5 proxy server.

```ini
[Socks5]
BindAddress = 127.0.0.1:1080
Username = user
Password = pass
```

--------------------------------

### VirtualTun StartPingIPs Method Signature

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/02-api-reference-wireguard.md

Method signature for starting background ICMP ping probes for health monitoring.

```go
func (d VirtualTun) StartPingIPs()
```

--------------------------------

### GET /metrics Request Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Example HTTP GET request to the /metrics endpoint to retrieve WireGuard device statistics.

```http
GET /metrics HTTP/1.1
Host: localhost:9080
```

--------------------------------

### Resolve Hostname to IP Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/02-api-reference-wireguard.md

Example of resolving a hostname to a netip.Addr using ResolveAddrWithContext and handling potential errors.

```go
addr, err := tun.ResolveAddrWithContext(context.Background(), "example.com")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Resolved to: %s\n", addr)
```

--------------------------------

### Parse and Start Wireguard

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/03-api-reference-routines.md

Parses the configuration file and starts the Wireguard interface. This is typically used during application startup.

```go
conf, err := wireproxy.ParseConfig("config.conf")
tun, err := wireproxy.StartWireguard(conf.Device, logLevel)
```

--------------------------------

### Start Health Monitoring Endpoint

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/00-index.md

Starts an HTTP server on localhost:9080 to expose health status. This is typically used for the /readyz endpoint.

```go
go func() {
    http.ListenAndServe("localhost:9080", tun)
}()
// Then: curl http://localhost:9080/readyz
```

--------------------------------

### Start Wireproxy with Health Endpoint

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Starts Wireproxy with the health monitoring endpoint enabled on localhost:9080. This allows access to /readyz and /metrics.

```bash
wireproxy -c config.conf -i localhost:9080
```

--------------------------------

### Start and Check Wireproxy Service

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/rc.d/README.md

Commands to start the wireproxy-awg service and verify its status.

```shell
sudo service wireproxy-awg start
sudo service wireproxy-awg status
```

--------------------------------

### Environment Variable Substitution Example Execution

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/07-configuration-reference.md

Shows how to export environment variables before running WireProxy to utilize substitution in the configuration file.

```bash
export MY_PRIVATE_KEY="uCTIK+56CPyCvwJxmU5dBfuyJvPuSXAq1FzHdnIxe1Q="
export PEER_PUBLIC_KEY="QP+A67Z2UBrMgvNIdHv8gPel5URWNLS4B3ZQ2hQIZlg="
export VPN_SERVER="vpn.example.com"
wireproxy -c config.conf
```

--------------------------------

### Start WireGuard Device

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/00-index.md

Initializes and starts the WireGuard device with a given configuration and log level. Ensures the device is closed upon function exit.

```go
tun, err := wireproxy.StartWireguard(conf.Device, device.LogLevelVerbose)
if err != nil {
    log.Fatal(err)
}
defunc tun.Dev.Close()
```

--------------------------------

### Complete Monitoring Configuration Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

This INI configuration sets up WireProxy with interface, peer, and SOCKS5 proxy details, including health check parameters.

```ini
[Interface]
Address = 10.200.200.2/32
PrivateKey = uCTIK+56CPyCvwJxmU5dBfuyJvPuSXAq1FzHdnIxe1Q=
DNS = 10.200.200.1
CheckAlive = 1.1.1.1, 8.8.8.8, 2606:4700:4700::1111
CheckAliveInterval = 3

[Peer]
PublicKey = QP+A67Z2UBrMgvNIdHv8gPel5URWNLS4B3ZQ2hQIZlg=
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

[Socks5]
BindAddress = 127.0.0.1:1080

```

--------------------------------

### Health Endpoint Response Example (OK)

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/README.md

Example of a /readyz health endpoint response indicating 'OK' (200). Shows the last pong received time for a single CheckAlive IP.

```text
< HTTP/1.1 200 OK
< Date: Thu, 11 Apr 2024 00:56:21 GMT
< Content-Length: 23
< Content-Type: text/plain; charset=utf-8
< 
{"1.1.1.1":1712796979}

```

--------------------------------

### StartWireguard Function

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/02-api-reference-wireguard.md

Creates and starts a virtual WireGuard interface. Use this to initialize a new tunnel with specific configuration and logging level.

```go
func StartWireguard(conf *DeviceConfig, logLevel int) (*VirtualTun, error)
```

```go
conf := &DeviceConfig{
    SecretKey: "...",
    Endpoint: []netip.Addr{netip.MustParseAddr("10.0.0.2")},
    DNS: []netip.Addr{netip.MustParseAddr("1.1.1.1")},
    MTU: 1420,
}

tun, err := wireproxy.StartWireguard(conf, device.LogLevelVerbose)
if err != nil {
    log.Fatal(err)
}
def tun.Dev.Close()
```

--------------------------------

### Run WireProxy Command

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/README.md

Command to start the WireProxy with a specified configuration file and enable health monitoring on a local port.

```bash
wireproxy -c config.conf -i localhost:9080

```

--------------------------------

### WireGuard Startup Script

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/UseWithVPN.md

A bash script to start the WireGuard proxy. Update the path to your wireproxy executable and configuration file.

```bash
#!/bin/bash
/Users/jonny/wireproxy/wireproxy -c /Users/jonny/vpntabs/ProtonUS.adblock.conf
```

--------------------------------

### Environment Variable Substitution in Configuration

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/07-configuration-reference.md

Demonstrates how to use environment variables for sensitive configuration values like private keys and endpoints. Values starting with '$' are expanded.

```ini
[Interface]
PrivateKey = $MY_PRIVATE_KEY
Address = 10.200.200.2/32

[Peer]
PublicKey = $PEER_PUBLIC_KEY
Endpoint = $VPN_SERVER:51820
```

--------------------------------

### Multiple WireGuard Peer Configurations

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/07-configuration-reference.md

Example demonstrating how to configure multiple WireGuard peers within the same configuration file. Each [Peer] section defines a distinct peer with its own settings.

```ini
[Peer]
PublicKey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
AllowedIPs = 10.254.254.100/32
Endpoint = 192.168.0.204:51820

[Peer]
PublicKey = BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=
AllowedIPs = 10.254.254.1/32
Endpoint = 172.16.0.185:44044
```

--------------------------------

### Kubernetes Readiness Probe Configuration

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Example Kubernetes readiness probe configuration for Wireproxy, targeting the /readyz endpoint with specific timing and failure thresholds.

```yaml
readinessProbe:
  httpGet:
    path: /readyz
    port: 9080
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 3
```

--------------------------------

### HTTP Proxy with Authentication Setup

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/04-api-reference-http.md

Configures and launches an HTTP proxy server that requires authentication. The `CredentialValidator` is used, and client usage involves including credentials in the `curl` command.

```Go
server := &HTTPServer{
    config: &HTTPConfig{
        BindAddress: "127.0.0.1:8080",
        Username: "user",
        Password: "pass",
    },
    dial: tun.Tnet.Dial,
    auth: CredentialValidator{username: "user", password: "pass"},
    authRequired: true,
}

go server.ListenAndServe("tcp", "127.0.0.1:8080")

// Client usage:
// curl -x http://user:pass@127.0.0.1:8080 http://example.com
```

--------------------------------

### Health Endpoint Response Example (Service Unavailable)

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/README.md

Example of a /readyz health endpoint response indicating 'Service Unavailable' (503). Shows last pong received times for specified CheckAlive IPs.

```text
< HTTP/1.1 503 Service Unavailable
< Date: Thu, 11 Apr 2024 00:54:59 GMT
< Content-Length: 35
< Content-Type: text/plain; charset=utf-8
< 
{"1.1.1.1":1712796899,"3.3.3.3":0}

```

--------------------------------

### ASec Configuration Example in INI

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/05-api-reference-asec.md

Example INI configuration for AmneziaWG obfuscation parameters. This demonstrates how to set various junk packet sizes, magic header ranges, and additional obfuscation strings within an INI file's [Interface] section.

```ini
[Interface]
PrivateKey = ...
Address = 10.0.0.1/32
Jc = 10
Jmin = 50
Jmax = 200
S1 = 100
S2 = 50
H1 = 100-200
H2 = 201-300
H3 = 301-400
H4 = 401-500
I1 = obfuscation_string_1
```

--------------------------------

### Reload systemd and enable Wireproxy service

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/systemd/README.md

Reloads the systemd daemon to recognize the new unit file and enables the wireproxy.service to start automatically on boot, also starting it immediately.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now wireproxy.service
```

--------------------------------

### ASec Configuration Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/05-api-reference-asec.md

Example of an ASec configuration block in WireGuard's INI format, including interface settings and junk packet configurations.

```ini
[Interface]
PrivateKey = uCTIK+56CPyCvwJxmU5dBfuyJvPuSXAq1FzHdnIxe1Q=
Address = 10.0.0.1/32
DNS = 10.0.0.254

# Junk packets configuration
Jc = 5
Jmin = 20
Jmax = 100

# Packet-specific obfuscation sizes
S1 = 50
S2 = 30
S3 = 10
S4 = 15
```

--------------------------------

### HTTPServer.ListenAndServe

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/04-api-reference-http.md

Starts the HTTP proxy server and listens for incoming connections. This method blocks until a fatal error occurs.

```APIDOC
## HTTPServer.ListenAndServe

### Description
Starts the HTTP proxy server and blocks until a fatal error occurs. It accepts incoming connections and spawns a goroutine for each to serve requests.

### Method
`ListenAndServe`

### Endpoint
Not applicable (method call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
server := &HTTPServer{
    config: &HTTPConfig{BindAddress: "127.0.0.1:8080"},
    dial: tun.Tnet.Dial,
    auth: CredentialValidator{},
}

err := server.ListenAndServe("tcp", "127.0.0.1:8080")
// Blocks until fatal error
```

### Response
#### Success Response
None (method blocks)

#### Response Example
None
```

--------------------------------

### Import Wireguard Configuration

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/README.md

Import an existing Wireguard configuration file into Wireproxy. This allows leveraging existing network setups.

```ini
WGConfig = <path to the wireguard config>

[TCPClientTunnel]
...

[TCPServerTunnel]
...

[Socks5]
...

```

--------------------------------

### StartWireguard

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/02-api-reference-wireguard.md

Creates and starts a virtual WireGuard interface with the given configuration. It returns a VirtualTun object representing the active tunnel or an error if the interface creation fails.

```APIDOC
## StartWireguard

### Description
Creates and starts a virtual WireGuard interface with the given configuration. Returns a *VirtualTun on success, or an error if interface creation fails.

### Method
```go
func StartWireguard(conf *DeviceConfig, logLevel int) (*VirtualTun, error)
```

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Parameters
- **conf** (*DeviceConfig): Required - Device configuration including peers and credentials.
- **logLevel** (int): Required - Log verbosity level (device.LogLevelSilent, LogLevelVerbose, etc.).

### Returns
- **VirtualTun**: On success, an active WireGuard tunnel interface.
- **error**: If interface creation fails due to invalid IPC request, configuration errors, device initialization, or interface bring-up issues.

### Example
```go
conf := &DeviceConfig{
    SecretKey: "...",
    Endpoint: []netip.Addr{netip.MustParseAddr("10.0.0.2")},
    DNS: []netip.Addr{netip.MustParseAddr("1.1.1.1")},
    MTU: 1420,
}

tun, err := wireproxy.StartWireguard(conf, device.LogLevelVerbose)
if err != nil {
    log.Fatal(err)
}
defer tun.Dev.Close()
```
```

--------------------------------

### VirtualTun.StartPingIPs

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/02-api-reference-wireguard.md

Starts background ICMP ping probes for health monitoring. This function runs continuously in a goroutine and pings configured IPs at specified intervals.

```APIDOC
## VirtualTun.StartPingIPs

### Description
Starts background ICMP ping probes for health monitoring. Runs continuously in a goroutine.

### Method
(Not specified, likely a method call on a VirtualTun object)

### Parameters
(None)

### Behavior
- Pings each IP in `Conf.CheckAlive` every `Conf.CheckAliveInterval` seconds.
- Updates `PingRecord[ipString]` with Unix timestamp of successful pongs.
- Runs until application shutdown.
- Only active if CheckAlive list is non-empty.
```

--------------------------------

### Start WireProxy with Health Monitoring and Check Status

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/README.md

Starts WireProxy in the background with health monitoring enabled and then checks the readiness status using curl. This is useful for automated testing and deployment.

```bash
wireproxy -c config.conf -i localhost:9080 &
sleep 1
curl http://localhost:9080/readyz

```

--------------------------------

### Socks5Config.SpawnRoutine

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/03-api-reference-routines.md

Starts a SOCKS5 server listening on the configured address, routing connections through WireGuard. It handles incoming connections, routes traffic via the WireGuard tunnel, and optionally requires authentication.

```APIDOC
## Socks5Config.SpawnRoutine

### Description
Starts a SOCKS5 server listening on the configured address, routing connections through WireGuard. It handles incoming connections, routes traffic via the WireGuard tunnel, and optionally requires authentication.

### Method
func (config *Socks5Config) SpawnRoutine(vt *VirtualTun)

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
config := &Socks5Config{
    BindAddress: "127.0.0.1:1080",
}
go config.SpawnRoutine(tun)
```

### Response
#### Success Response
Blocks until server encounters a fatal error.

#### Response Example
None
```

--------------------------------

### WireProxy Go API: Spawn Routine Example

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/README.md

Illustrates the `SpawnRoutine` method signature for a `Socks5Config` type within the WireProxy Go API. This method is responsible for initiating and managing a specific tunnel or proxy.

```go
// SpawnRoutine method on configuration struct
func (config *Socks5Config) SpawnRoutine(vt *VirtualTun) {
    // Listen on BindAddress
    // Route through vt
    // Log errors, continue accepting connections
}

```

--------------------------------

### Use WireProxy with curl

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/README.md

Example of using curl to access a website through the SOCKS5 proxy configured in WireProxy.

```bash
curl -x socks5://user:pass@127.0.0.1:1080 http://example.com

```

--------------------------------

### Handle HTTP GET Requests (Direct Proxying)

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/04-api-reference-http.md

Handles direct HTTP GET requests by extracting the host, dialing the target via WireGuard, and forwarding the original request. The peer connection is returned for response forwarding.

```Go
func (s *HTTPServer) handle(req *http.Request) (peer net.Conn, err error)
```

--------------------------------

### STDIOTunnel Usage with SSH

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/07-configuration-reference.md

Example of how to use the STDIOTunnel configuration with the SSH command's ProxyCommand option.

```bash
ssh -o ProxyCommand='wireproxy -c config.conf' ssh.myserver.net
```

--------------------------------

### Customize systemd unit file for Wireproxy

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/systemd/README.md

Example of customizing the LoadCredential, ExecStartPre, and ExecStart directives in the wireproxy.service unit file to specify custom paths for the executable and configuration file.

```service
LoadCredential=conf:/opt/myfiles/wireproxy.conf
ExecStartPre=/usr/bin/wireproxy -n -c ${CREDENTIALS_DIRECTORY}/conf
ExecStart=/usr/bin/wireproxy -c ${CREDENTIALS_DIRECTORY}/conf
```

--------------------------------

### WireGuard Interface Configuration

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/07-configuration-reference.md

Example of a basic WireGuard interface configuration, including essential parameters like Address, PrivateKey, DNS, MTU, ListenPort, and health check settings. Also demonstrates optional ASec obfuscation parameters.

```ini
[Interface]
Address = 10.200.200.2/32
PrivateKey = uCTIK+56CPyCvwJxmU5dBfuyJvPuSXAq1FzHdnIxe1Q=
DNS = 10.200.200.1
MTU = 1420
ListenPort = 51820
CheckAlive = 1.1.1.1, 8.8.8.8
CheckAliveInterval = 5

# ASec obfuscation
Jc = 10
Jmin = 50
Jmax = 200
S1 = 100
H1 = 5000-6000
```

--------------------------------

### HTTPConfig.SpawnRoutine

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/03-api-reference-routines.md

Starts an HTTP proxy server listening on the configured address, routing traffic through WireGuard. It supports HTTP and HTTPS tunneling, handles authentication, and forwards connections via the WireGuard tunnel.

```APIDOC
## HTTPConfig.SpawnRoutine

### Description
Starts an HTTP proxy server listening on the configured address, routing traffic through WireGuard. It supports HTTP and HTTPS tunneling, handles authentication, and forwards connections via the WireGuard tunnel.

### Method
func (config *HTTPConfig) SpawnRoutine(vt *VirtualTun)

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
config := &HTTPConfig{
    BindAddress: "127.0.0.1:8080",
    Username: "user",
    Password: "pass",
}
go config.SpawnRoutine(tun)
```

### Response
#### Success Response
Blocks until server encounters a fatal error.

#### Response Example
None
```

--------------------------------

### Spawn UDPProxyTunnelRoutine

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/03-api-reference-routines.md

Starts a UDP proxy routine that listens on a specified bind address and forwards UDP traffic to a remote target via WireGuard. It manages sessions based on source address and inactivity.

```go
config := &UDPProxyTunnelConfig{
    BindAddress: "127.0.0.1:53",
    Target: "1.1.1.1:53",
    InactivityTimeout: 30,
}
go config.SpawnRoutine(tun)

// DNS clients can query: dig @127.0.0.1 -p 53 example.com
// Traffic routed through WireGuard to 1.1.1.1:53
```

--------------------------------

### GET /readyz

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Provides a health readiness check for WireGuard status. It returns a JSON object mapping IP addresses to their last successful ping timestamp.

```APIDOC
## GET /readyz

### Description
Health readiness check endpoint. Returns a JSON object mapping IP addresses to their last successful ICMP pong time. A timestamp of 0 indicates no successful ping received yet.

### Method
GET

### Endpoint
/readyz

### Parameters
None

### Request Example
```http
GET /readyz HTTP/1.1
Host: localhost:9080
```

### Response
#### Success Response (200 OK)
- **IP Address** (string) - Last successful ICMP pong time (Unix timestamp)

#### Response Example
```json
{
  "1.1.1.1": 1712796979,
  "8.8.8.8": 1712796979,
  "2606:4700:4700::1111": 1712796979
}
```

#### Partial Health Response (503 Service Unavailable)
Indicates at least one IP is stale (no response within timeout).

#### Response Example
```json
{
  "1.1.1.1": 1712796899,
  "8.8.8.8": 0
}
```

### Status Codes
- **200**: All monitored IPs pinged within CheckAliveInterval+2 seconds.
- **503**: At least one IP is stale (no response within timeout).

### Response Format
- JSON object mapping IP address to Unix timestamp.
- Timestamp is the last successful ICMP pong time.
- Timestamp of 0 means no successful ping received yet.

### When Enabled
This endpoint is only available if the `[Interface]` section includes the `CheckAlive` setting.

```ini
[Interface]
CheckAlive = 1.1.1.1, 8.8.8.8
CheckAliveInterval = 5
```

### When Not Configured
If no `CheckAlive` addresses are configured, returns an empty JSON object `{}` with a status code 200.

### Example Usage
```bash
# Monitor health in a loop
while true; do
  curl http://localhost:9080/readyz
  echo ""
  sleep 5
done

# Check if service is ready
if curl -f http://localhost:9080/readyz > /dev/null 2>&1; then
  echo "Ready"
else
  echo "Not ready"
fi
```

### Kubernetes Readiness Probe Example
```yaml
readinessProbe:
  httpGet:
    path: /readyz
    port: 9080
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 3
```
```

--------------------------------

### Spawn TCPServerTunnelRoutine

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/03-api-reference-routines.md

Starts a TCP server routine that listens on a specified port via the WireGuard interface and forwards connections to a local target. This routine blocks until a fatal error occurs.

```go
config := &TCPServerTunnelConfig{
    ListenPort: 3422,
    Target: "localhost:3422",
}
go config.SpawnRoutine(tun)

// Peer on WireGuard connects to 10.0.0.1:3422
// Traffic forwarded to localhost:3422
```

--------------------------------

### Collect Effective Header Intervals

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/05-api-reference-asec.md

Builds a list of effective magic header intervals, applying default values if configuration is nil or specific headers are not provided. Use this to get a complete set of intervals for validation.

```go
func collectEffectiveHeaderIntervals(config *ASecConfigType) []headerInterval
```

```go
// All defaults used
intervals := collectEffectiveHeaderIntervals(nil)
// Returns: [{h1, 1, 1}, {h2, 2, 2}, {h3, 3, 3}, {h4, 4, 4}]

// Custom H1 and H2
config := &ASecConfigType{
    hasInitPacketMagicHeader: true,
    initPacketMagicHeader: 100,
    initPacketMagicHeaderMax: 200,
    hasResponsePacketMagicHeader: true,
    responsePacketMagicHeader: 300,
    responsePacketMagicHeaderMax: 400,
}
intervals := collectEffectiveHeaderIntervals(config)
// Returns: [{h1, 100, 200}, {h2, 300, 400}, {h3, 3, 3}, {h4, 4, 4}]
```

--------------------------------

### GET /readyz Health Check Logic

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Go code snippet illustrating the logic for determining the health status based on the last successful ping time and the CheckAliveInterval.

```go
for _, record := range PingRecord {
    lastPong := time.Unix(int64(record), 0)
    if time.Since(lastPong) > time.Duration(CheckAliveInterval+2)*time.Second {
        status = http.StatusServiceUnavailable
        break
    }
}
```

--------------------------------

### Define Overall Configuration Structure

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/06-types.md

Defines the complete configuration structure for application startup, including device settings, routine spawners, and DNS resolution strategy.

```go
type Configuration struct {
    Device   *DeviceConfig
    Routines []RoutineSpawner
    Resolve  *ResolveConfig
}
```

--------------------------------

### GET /readyz Success Response (200 OK)

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Successful response from the /readyz endpoint, indicating all monitored IPs are responsive. The JSON maps IP addresses to their last successful ping timestamp.

```json
{
  "1.1.1.1": 1712796979,
  "8.8.8.8": 1712796979,
  "2606:4700:4700::1111": 1712796979
}
```

--------------------------------

### Build Wireproxy-AWG

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/README.md

Instructions to clone the repository and build the wireproxy-awg application using make.

```bash
git clone https://github.com/artem-russkikh/wireproxy-awg
cd wireproxy-awg
make
```

--------------------------------

### Example of Invalid STDIOTunnel Configuration

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/09-errors-reference.md

This is an example of an invalid configuration for STDIOTunnel that would cause a name resolution error.

```ini
[STDIOTunnel]
Target = nonexistent.invalid:22
```

--------------------------------

### WireProxy Command-line Arguments

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/07-configuration-reference.md

Lists the available command-line options for running the WireProxy executable, including configuration file path, silent mode, and daemonization.

```bash
wireproxy [OPTIONS]

Options:
  -c, --config <PATH>    Configuration file path
                         Default: /etc/wireproxy/wireproxy.conf or ~/.config/wireproxy.conf
  -s, --silent           Silent mode (suppress verbose logging)
  -d, --daemon           Run in background as daemon
  -i, --info <ADDR:PORT> Health monitoring endpoint (e.g., localhost:9080)
  -v, --version          Print version and exit
  -n, --configtest       Validate config file and exit
  -h, --help             Print help and exit
```

--------------------------------

### Enable Wireproxy Service in rc.conf

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/rc.d/README.md

Add this line to /etc/rc.conf to enable the wireproxy-awg service on boot.

```shell
wireproxy_enable="YES"
```

--------------------------------

### Check Wireproxy service status

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/systemd/README.md

Commands to check the status of the wireproxy.service and view its logs to ensure it has started correctly.

```bash
systemctl status wireproxy.service
sudo journalctl -u wireproxy.service
```

--------------------------------

### GET /metrics

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Retrieves WireGuard device metrics in a key-value format. Sensitive fields like private keys are redacted.

```APIDOC
## GET /metrics

### Description
WireGuard device metrics endpoint. Returns key-value pairs detailing interface and peer information.

### Method
GET

### Endpoint
/metrics

### Parameters
None

### Request Example
```http
GET /metrics HTTP/1.1
Host: localhost:9080
```

### Response
#### Success Response (200 OK)
- Key-value pairs in `key=value` format, one per line.

#### Response Example
```
private_key=REDACTED
listen_port=51820
public_key=QP+A67Z2UBrMgvNIdHv8gPel5URWNLS4B3ZQ2hQIZlg=
protocol_version=1
endpoint=vpn.example.com:51820
allowed_ip=0.0.0.0/0
allowed_ip=::/0
latest_handshake=1712796979
transfer_rx=1048576
transfer_tx=2097152
persistent_keepalive_interval=25
preshared_key=REDACTED
...
```

### Status Codes
- **200**: Successfully retrieved device metrics.
- **500**: Failed to query device state.

### Response Format
Key-value pairs in `key=value` format, one per line.

### Redacted Fields
The following sensitive fields are redacted for security:
- `private_key=REDACTED`
- `preshared_key=REDACTED`

### Available Metrics
| Key | Type | Description |
|-----|------|-------------|
| private_key | string | (redacted) Interface private key |
| listen_port | int | UDP port the device is listening on |
| public_key | string | Peer public key |
| endpoint | string | Peer endpoint address |
| allowed_ip | CIDR | Peer allowed IP (repeats for each) |
| latest_handshake | uint64 | Unix timestamp of last successful handshake |
| transfer_rx | uint64 | Bytes received from peer |
| transfer_tx | uint64 | Bytes transmitted to peer |
| persistent_keepalive_interval | int | Keepalive interval in seconds |
| preshared_key | string | (redacted) Peer preshared key |
| protocol_version | int | WireGuard protocol version |

### Example Usage
```bash
# Get all device metrics
curl http://localhost:9080/metrics

# Extract specific peer information
curl http://localhost:9080/metrics | grep -E "public_key|endpoint|transfer"

# Monitor data transfer
curl http://localhost:9080/metrics | grep transfer_
```

### Prometheus Integration Example
Parse the endpoint output and expose as Prometheus metrics:

```
# Sample output format for scraping
wireguard_listen_port{device="wg0"} 51820
wireguard_latest_handshake{device="wg0",peer="QP+A67Z2..."} 1712796979
wireguard_transfer_rx_bytes{device="wg0",peer="QP+A67Z2..."} 1048576
wireguard_transfer_tx_bytes{device="wg0",peer="QP+A67Z2..."} 2097152
```
```

--------------------------------

### Basic WireProxy Configuration

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/README.md

This INI-style configuration file sets up a WireGuard interface, a peer, and SOCKS5/HTTP proxies. It includes credentials and endpoint details.

```ini
[Interface]
Address = 10.200.200.2/32
PrivateKey = uCTIK+56CPyCvwJxmU5dBfuyJvPuSXAq1FzHdnIxe1Q=
DNS = 10.200.200.1
CheckAlive = 1.1.1.1
CheckAliveInterval = 5

[Peer]
PublicKey = QP+A67Z2UBrMgvNIdHv8gPel5URWNLS4B3ZQ2hQIZlg=
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25

[Socks5]
BindAddress = 127.0.0.1:1080
Username = user
Password = pass

[http]
BindAddress = 127.0.0.1:8080

```

--------------------------------

### WireProxy CLI Usage

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/00-index.md

Demonstrates the basic command-line interface for running WireProxy, including options for configuration, silent mode, daemonization, and health monitoring.

```bash
wireproxy [OPTIONS]

Options:
  -c, --config <PATH>      Configuration file path
  -s, --silent             Silent mode (no verbose logging)
  -d, --daemon             Run in background
  -i, --info <ADDR:PORT>   Health monitoring endpoint
  -v, --version            Print version
  -n, --configtest         Validate configuration file
  -h, --help               Print help

Examples:
  wireproxy -c /etc/wireproxy/config.conf
  wireproxy -d -c config.conf -i localhost:9080
  wireproxy -n -c config.conf  # Validate only
```

--------------------------------

### Prometheus Integration Sample Output

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Sample output format demonstrating how Wireproxy metrics can be parsed and exposed as Prometheus metrics, including device and peer labels.

```text
# Sample output format for scraping
wireguard_listen_port{device="wg0"} 51820
wireguard_latest_handshake{device="wg0",peer="QP+A67Z2..."} 1712796979
wireguard_transfer_rx_bytes{device="wg0",peer="QP+A67Z2..."} 1048576
wireguard_transfer_tx_bytes{device="wg0",peer="QP+A67Z2..."} 2097152
```

--------------------------------

### Define RoutineSpawner Interface

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/06-types.md

Interface for spawning routines, implemented by various tunnel and proxy configurations. It defines a single method to start a routine with a VirtualTun.

```Go
type RoutineSpawner interface {
    SpawnRoutine(vt *VirtualTun)
}
```

--------------------------------

### Run Wireproxy

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/README.md

Basic command to run wireproxy with a specified configuration file path.

```bash
./wireproxy [-c path to config]
```

--------------------------------

### Interface Configuration for Health Checks

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Example INI configuration for the [Interface] section, enabling health checks by specifying IP addresses and the check interval.

```ini
[Interface]
CheckAlive = 1.1.1.1, 8.8.8.8
CheckAliveInterval = 5
```

--------------------------------

### Validate Configuration Without Running

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/README.md

Command to perform a dry run of the WireProxy configuration, checking for syntax errors without actually starting the proxy service.

```bash
wireproxy -n -c config.conf

```

--------------------------------

### Configuration with Environment Variables

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/README.md

Shows how to use environment variables within the WireProxy configuration file for sensitive values like private keys. Ensure variables are exported before running.

```ini
[Interface]
PrivateKey = $MY_PRIVATE_KEY

[Peer]
PublicKey = $PEER_PUBLIC_KEY

```

--------------------------------

### Spawn Routines

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/00-index.md

Launches multiple routines concurrently based on the provided configuration. Each routine is spawned as a goroutine.

```go
for _, spawner := range conf.Routines {
    go spawner.SpawnRoutine(tun)
}
```

--------------------------------

### Health Endpoint Configuration with CheckAlive

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/README.md

Configure Wireproxy to expose a health endpoint with a CheckAlive setting for monitoring. This example includes interface, DNS, CheckAlive targets, and interval.

```ini
[Interface]
PrivateKey = censored
Address = 10.2.0.2/32
DNS = 10.2.0.1
CheckAlive = 1.1.1.1, 3.3.3.3
CheckAliveInterval = 3

[Peer]
PublicKey = censored
AllowedIPs = 0.0.0.0/0
Endpoint = 149.34.244.174:51820

[Socks5]
BindAddress = 127.0.0.1:25344

```

--------------------------------

### Wireproxy Command Line Arguments

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/README.md

Displays the available command-line arguments for wireproxy, including help, configuration, silent mode, daemonization, info exposure, version, and config testing.

```bash
usage: wireproxy [-h|--help] [-c|--config "<value>"] [-s|--silent]
                 [-d|--daemon] [-i|--info "<value>"] [-v|--version]
                 [-n|--configtest]

                 Userspace wireguard client for proxying

Arguments:

  -h  --help        Print help information
  -c  --config      Path of configuration file
                    Default paths: /etc/wireproxy/wireproxy.conf, $HOME/.config/wireproxy.conf
  -s  --silent      Silent mode
  -d  --daemon      Make wireproxy run in background
  -i  --info        Specify the address and port for exposing health status
  -v  --version     Print version
  -n  --configtest  Configtest mode. Only check the configuration file for
                    validity.

```

--------------------------------

### TCPServerTunnelConfig.SpawnRoutine

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/03-api-reference-routines.md

Starts a TCP server on the WireGuard interface that accepts connections from peers and forwards them to a local target. It handles bidirectional traffic forwarding and blocks until a fatal error occurs.

```APIDOC
## TCPServerTunnelConfig.SpawnRoutine

### Description
Starts a TCP server on the WireGuard interface that accepts connections from peers and forwards to local target. Blocks until server encounters a fatal error.

### Method
*Spawns a routine*

### Endpoint
*N/A (Method on config struct)*

### Parameters
#### Path Parameters
*None*

#### Query Parameters
*None*

#### Request Body
*None*

### Request Example
```go
config := &TCPServerTunnelConfig{
    ListenPort: 3422,
    Target: "localhost:3422",
}
go config.SpawnRoutine(tun)
```

### Response
#### Success Response
*None (blocks until fatal error)*

#### Response Example
*None*
```

--------------------------------

### HTTP Handler Implementation - Route Handling

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/08-endpoints-reference.md

Go code snippet demonstrating the switch statement within the ServeHTTP method that routes requests to either the /readyz or /metrics endpoints.

```go
switch path.Clean(r.URL.Path) {
case "/readyz":
    // Health status endpoint
case "/metrics":
    // Device metrics endpoint
default:
    // 404 Not Found
}
```

--------------------------------

### Handling Proxy Spawning Goroutines

Source: https://github.com/artem-russkikh/wireproxy-awg/blob/master/_autodocs/09-errors-reference.md

Illustrates how proxy servers run in goroutines and call log.Fatal on encountering fatal errors. The application continues until a fatal error occurs, a signal is received, or the context is cancelled.

```go
for _, spawner := range conf.Routines {
    go spawner.SpawnRoutine(tun)
    // If spawner fails, it calls log.Fatal internally
}

// Application continues until:
// 1. Fatal error in spawner
// 2. Signal received (SIGINT, SIGQUIT)
// 3. Context cancelled
```