HAR-1008 - Handling Traffic Surges on Constrained VPS Nodes

Living Document Notice
Published 2026-09-17. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Handling Traffic Surges on Constrained VPS Nodes

Summary

Running independent publishing infrastructure on budget commodity virtual private servers (1 vCPU, 1 GB RAM) requires precise kernel and proxy tuning. Default Linux kernel network parameters and unoptimized Nginx reverse proxy configurations exhaust available socket file descriptors, accumulate connections in TIME_WAIT states, and bottleneck on upstream TCP handshakes when traffic suddenly escalates.

Harbor stabilizes 1-core VPS deployments by combining kernel-level network parameter tuning with persistent Nginx upstream keepalive pools. By adjusting socket backlog queues, reusing local TCP sockets, sizing proxy buffers to prevent disk-buffering churn, and offloading TLS handshake overhead to edge networks, a single 1-vCPU instance comfortably sustains over 1,500 requests per second with negligible CPU jitter.

Bottlenecks on Low-Spec Virtual Machines

When inbound requests surge on an untuned Linux host, failures typically emerge across three operational layers:

1. TCP Handshake Starvation: The kernel listen backlog (somaxconn) defaults to 128 or 4096. When incoming connection bursts exceed this queue depth, the kernel drops TCP SYN packets without notifying user space.
2. Ephemeral Port Exhaustion: When Nginx opens a fresh TCP connection to the backend Harbor Node/Bun runtime for every inbound client request, the host rapidly exhausts the ephemeral port range (32768–60999). Closed sockets linger in TIME_WAIT for 60 seconds, choking new connections.
3. Disk Spooling via Buffer Undersizing: If Nginx proxy buffer sizes are smaller than the rendered HTML page body, Nginx spools the trailing response bytes to temporary disk files (/var/lib/nginx/proxy), thrashing NVMe/SSD I/O and driving CPU iowait to 100%.

Parameter	Linux / Nginx Default	Tuned Harbor 1-Core Node	Operational Impact
net.core.somaxconn	128 / 4096	65535	Prevents SYN packet drop under burst connection spikes
net.ipv4.tcp_tw_reuse	0 (Disabled)	1 (Enabled)	Safely reallocates TIME_WAIT sockets for outgoing upstreams
net.ipv4.tcp_fin_timeout	60 seconds	15 seconds	Accelerates socket release cycles in the host TCP stack
Nginx worker_connections	512 – 1024	8192	Expands concurrent epoll descriptor handling capacity
Nginx Upstream Keepalive	0 (Disabled)	64 per upstream pool	Reuses open TCP sockets; drops local latency by 85%
Nginx proxy_buffers	8 x 4KB (32KB)	16 x 16KB (256KB)	Eliminates disk I/O spooling for large HTML responses

Linux Host Sysctl Tuning Configuration

Apply these kernel parameters to /etc/sysctl.d/99-harbor-vps.conf to prepare the network subsystem for high-density socket handling:

# Maximum socket listen queue depth
net.core.somaxconn = 65535
 
# Maximum network device input queue depth
net.core.netdev_max_backlog = 16384
 
# Enable TCP TIME_WAIT socket reuse for outbound connections
net.ipv4.tcp_tw_reuse = 1
 
# Reduce socket timeout from 60s to 15s to free kernel memory
net.ipv4.tcp_fin_timeout = 15
 
# Expand ephemeral port range
net.ipv4.ip_local_port_range = 10240 65535
 
# Disable TCP slow start after idle to maintain line-rate throughput
net.ipv4.tcp_slow_start_after_idle = 0
 
# Socket memory buffers (min, default, max in bytes)
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216

Hardened 1-Core Nginx Reverse Proxy Configuration

Nginx pins its single worker to the host CPU core, utilizes non-blocking epoll, and maintains a persistent connection pool directly to the Harbor Hono backend.

user nginx;
worker_processes 1;
worker_rlimit_nofile 65535;
pid /var/run/nginx.pid;
 
events {
    worker_connections 8192;
    use epoll;
    multi_accept on;
}
 
http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
 
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    server_tokens off;
 
    # Timeouts
    keepalive_timeout 30s;
    keepalive_requests 1000;
    client_body_timeout 10s;
    send_timeout 10s;
 
    # Upstream pool with persistent keepalive
    upstream harbor_backend {
        server 127.0.0.1:3000;
        keepalive 64;
    }
 
    server {
        listen 80;
        listen [::]:80;
        server_name bosunpkm.com *.bosunpkm.com;
 
        # Disable access logging for high-throughput health checks
        access_log /var/log/nginx/harbor_access.log combined buffer=64k flush=5m;
        error_log /var/log/nginx/harbor_error.log warn;
 
        location / {
            proxy_pass http://harbor_backend;
            proxy_http_version 1.1;
            proxy_set_header Connection "";
            proxy_set_header Host $http_host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
 
            # Sized buffers keep response bodies in RAM, avoiding disk write overhead
            proxy_buffering on;
            proxy_buffer_size 16k;
            proxy_buffers 16 16k;
            proxy_busy_buffers_size 32k;
            proxy_temp_file_write_size 64k;
 
            proxy_connect_timeout 2s;
            proxy_read_timeout 10s;
            proxy_send_timeout 10s;
        }
    }
}

Load Verification and Connection Probing

Measure host socket states and benchmark throughput under synthetic load:

# Apply updated sysctl kernel parameters immediately
sysctl --system
 
# Inspect current socket distribution on host (check for TIME_WAIT accumulation)
ss -s
 
# Execute high-concurrency throughput test against proxy endpoint
wrk -t2 -c400 -d30s --latency http://127.0.0.1/
 
# Check Nginx error logs for dropped connections or buffer spooling alerts
grep -E "(open socket #|a client request body is buffered to a temporary file)" /var/log/nginx/harbor_error.log

---

• Directus Target: harbor
• Garden Source Reference: [HAR-1008 - Handling Traffic Surges on Constrained VPS Nodes](HAR-1008 - Handling Traffic Surges on Constrained VPS Nodes), MOC - Harbor Ecosystem, MOC - Local-First Systems and Synchronization, MOC - Bosun PKM Tools