# How to Configure Rate Limiting on the MasterDnsVPN SOCKS5 Proxy

> Learn how to configure rate limiting on the MasterDnsVPN SOCKS5 proxy. Discover how to tune hardcoded constants by editing the source and recompiling for optimal performance.

- Repository: [Amin Mahmoudi/MasterDnsVPN](https://github.com/masterking32/MasterDnsVPN)
- Tags: how-to-guide
- Published: 2026-05-10

---

**MasterDnsVPN implements automatic IP-based rate limiting for SOCKS5 connections via hardcoded constants in [`internal/client/socks_ratelimit.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/client/socks_ratelimit.go) that you tune by editing the source and recompiling.**

The MasterDnsVPN repository provides a DNS-over-HTTPS and SOCKS5 proxy solution written in Go. Its built-in rate limiter protects the SOCKS5 authentication endpoint from brute-force attacks by tracking failures per IP address within a sliding time window. Unlike external middleware, this protection is embedded directly in the client package and operates automatically for every incoming connection.

## How the Rate Limiter Works

The implementation uses a sliding-window counter with escalating penalties to distinguish between accidental mistakes and malicious automation.

**Sliding Window**: Failed authentication attempts are accumulated inside a 2‑minute window (`socksRateLimitWindow`). 

**Failure Threshold**: When an IP records 10 or more failures (`socksRateLimitMaxFailures`), it is immediately banned.

**Escalating Bans**: The first ban lasts 1 minute (`socksRateLimitBaseBan`). Each subsequent violation doubles the ban duration (exponential back‑off) until it reaches the ceiling of 15 minutes (`socksRateLimitMaxBanDuration`).

**Decay Mechanism**: If an IP remains clean for 10 minutes after a ban expires (`socksRateLimitBanDecayAfter`), its escalation counter resets to the base duration.

**Maintenance Tasks**: Stale entries are purged every 60 seconds (`socksRateLimitPurgeInterval`) to prevent memory bloat. Loopback addresses (127.0.0.1 and ::1) are unconditionally exempt from blocking. All state mutations are guarded by a `sync.Mutex` to ensure thread‑safety under concurrent load.

## Locating the Configuration Constants

The rate limiter is not controlled via external configuration files. Instead, behavior is hardcoded in the source file [`internal/client/socks_ratelimit.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/client/socks_ratelimit.go) at lines 19‑44.

Key tunables include:

- `socksRateLimitWindow` – Duration of the observation window
- `socksRateLimitMaxFailures` – Failure count that triggers a ban
- `socksRateLimitBaseBan` – Initial ban duration
- `socksRateLimitMaxBanDuration` – Maximum allowable ban time
- `socksRateLimitBanDecayAfter` – Clean‑slate period for resetting escalation
- `socksRateLimitPurgeInterval` – Garbage collection frequency for old entries

## Modifying Rate Limit Parameters

To configure custom limits, you must edit the constants and rebuild the binary.

1. Open [`internal/client/socks_ratelimit.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/client/socks_ratelimit.go).

2. Adjust the constant block (lines 19‑44):

```go
const (
    // Sliding window duration (default 2 min)
    socksRateLimitWindow = 2 * time.Minute

    // Max failures before a ban (default 10)
    socksRateLimitMaxFailures = 10

    // Base ban duration (default 1 min)
    socksRateLimitBaseBan = 1 * time.Minute

    // Maximum ban (default 15 min)
    socksRateLimitMaxBanDuration = 15 * time.Minute

    // Time after which escalation counter resets (default 10 min)
    socksRateLimitBanDecayAfter = 10 * time.Minute

    // How often stale entries are cleaned up (default 60 s)
    socksRateLimitPurgeInterval = 60 * time.Second
)

```

3. Rebuild the client binary:

```bash
go build ./cmd/client

```

The new limits take effect immediately when the updated binary starts. If you require runtime‑adjustable limits without recompilation, you would need to expose these constants through a wrapper in [`internal/client/client.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/client/client.go) and wire them to the existing TOML configuration parser or command‑line flags.

## Runtime Integration Examples

According to the MasterDnsVPN source code, the limiter exposes four primary methods. These are typically invoked inside the SOCKS5 handshake logic found in [`internal/client/client.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/client/client.go).

**Checking ban status before processing authentication:**

```go
ip := extractIP(conn) // helper logic from socks_ratelimit.go
if client.socksRateLimiter.IsBlocked(ip) {
    log.Warnf("SOCKS5 request from %s blocked by rate limiter", ip)
    // Send AUTH_FAILURE and close connection
    return
}

```

**Recording failures and detecting new bans:**

```go
if authFailed {
    if client.socksRateLimiter.RecordFailure(ip) {
        log.Infof("IP %s banned due to repeated failures", ip)
        // Trigger alert or metrics increment
    }
}

```

**Clearing state after successful authentication:**

```go
if authSucceeded {
    client.socksRateLimiter.RecordSuccess(ip)
}

```

**Administrative reset of all rate‑limit data:**

```go
client.socksRateLimiter.Reset()
log.Info("All SOCKS5 rate-limit data cleared")

```

## Summary

- MasterDnsVPN SOCKS5 proxy rate limiting is compile‑time configurable via constants in [`internal/client/socks_ratelimit.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/client/socks_ratelimit.go).
- The default policy blocks IPs for 1 minute after 10 failures within a 2‑minute window, with exponential escalation up to 15 minutes.
- Loopback traffic is automatically exempt, and thread‑safe operations are enforced by a `sync.Mutex`.
- To apply changes, edit lines 19‑44, rebuild with `go build ./cmd/client`, and restart the service.
- Runtime integration relies on four methods: `IsBlocked()`, `RecordFailure()`, `RecordSuccess()`, and `Reset()`.

## Frequently Asked Questions

### Can I configure SOCKS5 rate limiting without rebuilding the binary?

No. As implemented in the MasterDnsVPN repository, the rate limits are hardcoded constants. To adjust thresholds or windows, you must modify [`internal/client/socks_ratelimit.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/client/socks_ratelimit.go) and recompile. For runtime changes, you would need to fork the repository and add TOML or flag‑based configuration parsing in [`internal/client/client.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/client/client.go).

### How long does an IP remain banned after repeated failures?

The first ban lasts 1 minute (`socksRateLimitBaseBan`). Each subsequent ban doubles in duration until it hits the 15‑minute ceiling (`socksRateLimitMaxBanDuration`). If the IP avoids authentication failures for 10 minutes after a ban expires, the escalation counter resets to the base 1‑minute duration.

### Does the rate limiter affect local development on localhost?

No. Loopback addresses—specifically IPv4 `127.0.0.1` and IPv6 `::1`—are explicitly whitelisted and will never be blocked, regardless of failure count. This exemption is hardcoded in the `IsBlocked()` logic within [`internal/client/socks_ratelimit.go`](https://github.com/masterking32/MasterDnsVPN/blob/main/internal/client/socks_ratelimit.go).

### What happens if the rate limiter state grows too large?

The implementation automatically purges stale entries every 60 seconds (`socksRateLimitPurgeInterval`). This cleanup removes IPs that have not seen activity within the relevant time windows, preventing unbounded memory growth in long‑running deployments.