How to Interpret MasterDnsVPN Server Logs for Diagnosing Connection Issues

MasterDnsVPN emits structured, color-coded log entries that reveal exactly why clients fail to connect, from queue overflows in internal/udpserver/server_runtime.go to invalid cookie thresholds in server_session.go.

MasterDnsVPN is a UDP-based VPN server that outputs detailed diagnostic information during startup, connection handling, and error conditions. Learning how to interpret these server logs allows you to distinguish between network congestion, configuration limits, and stale session data without guessing. This guide walks through the specific log sources in the masterking32/MasterDnsVPN repository and explains how to correlate log patterns with configuration parameters to resolve connection failures.

Understanding the Logging Infrastructure

The logging system is implemented in internal/logger/logger.go and formats every entry with a timestamp, optional color tag, component name, and severity level.

The four log levels you will encounter are:

• Debugf – Detailed internal state messages, including invalid-session drops and packet parsing details
• Infof – Normal operational events such as startup banners and successful session creation
• Warnf – Abnormal but recoverable conditions like queue overloads or socket buffer failures
• Errorf – Fatal misconfigurations that prevent the server from operating, such as encryption key errors

When the server writes logs to a file, color tags are automatically stripped, leaving plain text that remains fully searchable with standard Unix tools like grep or awk.

Startup and Configuration Logs

Server Initialization Messages

When the binary launches, cmd/server/main.go emits a startup banner at lines 101-107 that confirms the process is healthy:

🚀 MasterDnsVPN Server starting …
GitHub: https://github.com/masterking32/MasterDnsVPN
Build Version: …

If you do not see this banner, the binary failed before reaching the logging initialization. Verify the log level in your configuration—if set higher than INFO, these messages are suppressed.

UDP Listener Configuration

After startup, internal/udpserver/server.go logs the UDP stack configuration at lines 309-316:

📡 UDP Listener Ready, Addr: …, Readers: N, Workers: M, Queue: Q, Sockets: S

This line reveals four critical tuning parameters:

• Readers – Goroutines reading from the UDP socket
• Workers – Goroutines processing packets (controlled by DNS_REQUEST_WORKERS in server_config.toml)
• Queue – Channel buffer capacity for incoming requests (defaults to MAX_CONCURRENT_REQUESTS)
• Sockets – Number of bound UDP sockets

If the Queue value reads at its maximum (e.g., 512/512), the server is already under load and approaching packet drops.

Connection Lifecycle Logs

Session Creation Success

Successful handshakes trigger a log entry in internal/udpserver/server_session.go at lines 179-229:

✅ Session Created, ID: 3, Mode: RAW, Upload Compression: ZLIB, …

This confirms the client completed the PACKET_SESSION_INIT handshake. If this log never appears but you see inbound packets, check:

• MAX_ALLOWED_CLIENT_ACTIVE_SESSIONS may be reached
• Domain filtering rules might block the client before session allocation

Session Validation Failures

When a packet fails session validation, logInvalidSessionDrop at lines 92-118 of server_session.go emits one of two patterns:

Unknown Session:

🔶 Sending Session Drop | Reason: unknown session | Session: 7 | Received: 12 | Mode: RAW

Invalid Cookie Threshold:

🔶 Sending Session Drop | Reason: invalid cookie threshold | Session: 7 | Expected: 8 | Received: 12 | Mode: BASE64

These indicate:

• The client reused an old session ID after a server restart
• Packet loss caused the cookie sequence to desynchronize
• An attacker is flooding random cookies, triggering INVALID_COOKIE_ERROR_THRESHOLD (default typically 5)

Session Teardown

Graceful disconnections appear as:

🛑 Session Closed By Client, Session: 3

If sessions accumulate without corresponding close logs, inspect SESSION_TIMEOUT_SECONDS and verify the cleanup ticker in internal/udpserver/server_runtime.go is running. Missing cleanup logs indicate the sessionCleanupLoop is disabled or the timeout interval is set too high.

Performance and Overload Indicators

Request Queue Overload

The most common cause of "connection timed out" complaints appears in internal/udpserver/server_runtime.go at lines 57-80:

⚠️ Request Queue Overloaded | Dropped: 123 | Queue: 512/512 | Remote: 1.2.3.4:12345

This warning fires when the inbound request channel reaches capacity. The server discards UDP packets immediately, before session logic processes them.

To resolve this bottleneck:

1. Increase MAX_CONCURRENT_REQUESTS in server_config.toml
2. Raise DROP_LOG_INTERVAL_SECONDS to reduce log noise while dropping
3. Verify OS-level socket buffer sizes (socket_buffers in the config) are sufficient for your network throughput

Deferred Session Backpressure

DNS and SOCKS5 CONNECT packets are queued for deferred processing in internal/udpserver/deferred_session.go. When this queue saturates, you will see overload messages similar to the request queue warnings.

This indicates:

• Upstream DNS latency is causing backups
• SOCKS5 proxies are responding slowly

Mitigate by increasing DEFERRED_SESSION_WORKERS or DEFERRED_SESSION_QUEUE_LIMIT, or switch to faster upstream DNS endpoints.

Encryption and Security Errors

Before any UDP processing begins, cmd/server/main.go validates the AES encryption setup. Failures appear as:

❌ Encryption Key Setup Failed | …
❌ Encryption Codec Setup Failed | …

These Errorf level logs halt the server. Verify the file path specified in ENCRYPTION_KEY_PATH is readable by the process user, or check disk space if the server auto-generates keys.

Practical Log Analysis Examples

The following Go snippets demonstrate how to programmatically inspect server state using the same patterns found in the source code.

Detecting queue overload programmatically:

// Check if packets are being dropped
if s.droppedPackets.Load() > 0 {
    total := s.droppedPackets.Load()
    log.Warnf(
        "⚠️ %d packets dropped due to full request queue – check MAX_CONCURRENT_REQUESTS",
        total,
    )
}

Adjusting cookie tolerance at runtime:

// Raise threshold to tolerate out-of-order packets after network hiccups
s.invalidCookieThreshold = 10 // default is 5

Enabling debug output for deep inspection:

// Replace standard logger with DEBUG level
log := logger.New("MasterDnsVPN Server", "debug") // instead of "info"

Retrieving drop statistics for diagnostics:

func (s *Server) lastDropInfo() string {
    return fmt.Sprintf(
        "Last drop: %d packets, last log at %v",
        s.droppedPackets.Load(),
        time.Unix(0, s.lastDropLogUnix.Load()),
    )
}

Summary

• Startup confirmation appears in cmd/server/main.go with the rocket emoji banner—verify this first to ensure you are tailing logs from a running process
• Queue overload warnings in internal/udpserver/server_runtime.go directly explain client timeouts and require tuning MAX_CONCURRENT_REQUESTS or OS socket buffers
• Invalid cookie drops in internal/udpserver/server_session.go reveal desynchronized clients or potential attacks, adjustable via INVALID_COOKIE_ERROR_THRESHOLD
• Session creation logs confirm successful handshakes; their absence points to MAX_ALLOWED_CLIENT_ACTIVE_SESSIONS limits or domain filters
• Deferred session backpressure indicates slow upstream DNS or SOCKS5 proxies, resolvable by increasing DEFERRED_SESSION_WORKERS

Frequently Asked Questions

Why do I see "Request Queue Overloaded" errors butlow CPU usage?

This indicates the UDP receive buffer in the kernel or the application's request channel is the bottleneck, not processing power. According to internal/udpserver/server_runtime.go lines 57-80, packets are dropped when the MAX_CONCURRENT_REQUESTS channel fills before worker goroutines can drain it. Increase MAX_CONCURRENT_REQUESTS in server_config.toml and verify socket_buffers settings in the OS match your network throughput.

What does "invalid cookie threshold" mean in the logs?

This message from internal/udpserver/server_session.go lines 92-118 signifies the server received a packet with a cookie sequence number that deviates too far from the expected value. It commonly occurs when a client resumes after a network pause, causing out-of-order delivery, or during cookie-flood attacks. You can raise the tolerance by adjusting INVALID_COOKIE_ERROR_THRESHOLD in your configuration, or reduce client-side ping aggressiveness via CLIENT_MIN_PING_AGGRESSIVE_INTERVAL.

How do I enable DEBUG logging to see every dropped packet?

Initialize the logger with the debug level as shown in internal/logger/logger.go. Replace your existing logger initialization with logger.New("MasterDnsVPN Server", "debug") to receive Debugf output including granular session validation failures and packet handler traces. Remember to revert to info level in production to prevent disk exhaustion from high-volume UDP traffic.

Why aren't expired sessions being cleaned up?

If internal/udpserver/server_runtime.go shows the cleanup loop running but finding no sessions, verify SESSION_TIMEOUT_SECONDS is not set to an excessively high value. Additionally, ensure SESSION_CLEANUP_INTERVAL_SECONDS is greater than zero; if set to zero or if the cleanup ticker is disabled, zombie sessions accumulate indefinitely, consuming memory and preventing new connections under MAX_ALLOWED_CLIENT_ACTIVE_SESSIONS limits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}