TCP Keepalive - Configuration Guide

sysctl net.ipv4.tcp_keepalive_time \
       net.ipv4.tcp_keepalive_intvl \
       net.ipv4.tcp_keepalive_probes

sudo sysctl -w net.ipv4.tcp_keepalive_time=10
sudo sysctl -w net.ipv4.tcp_keepalive_intvl=5
sudo sysctl -w net.ipv4.tcp_keepalive_probes=3

net.ipv4.tcp_keepalive_time = 120
net.ipv4.tcp_keepalive_intvl = 15
net.ipv4.tcp_keepalive_probes = 9

sudo tcpdump -i eth0 -w keepalive_3306.pcap 'tcp port 3306'

sudo tcpdump -i eth0 -nn \
  'tcp port 3306 and (tcp[tcpflags] & tcp-ack != 0) and \
  (ip[2:2] - ((ip[0] & 0xf)<<2) - ((tcp[12] & 0xf0)>>2)) == 0'

tcpdump -nn -r keepalive_3306.pcap

14:23:01.123456 IP 10.0.0.1.54321 > 10.0.0.2.3306: Flags [.], seq 999:999, ack 1000, win 512, length 0
14:23:01.124100 IP 10.0.0.2.3306 > 10.0.0.1.54321: Flags [.], seq 1000:1000, ack 1000, win 512, length 0

tshark -r keepalive_3306.pcap \
  -Y 'tcp.analysis.keep_alive or tcp.analysis.keep_alive_ack' \
  -T fields \
  -e frame.time \
  -e ip.src \
  -e ip.dst \
  -e tcp.srcport \
  -e tcp.dstport \
  -e tcp.seq \
  -e tcp.ack \
  -E header=y \
  -E separator=$'\t'

tshark -i eth0 \
  -Y 'tcp.analysis.keep_alive or tcp.analysis.keep_alive_ack' \
  -T fields \
  -e frame.time -e ip.src -e ip.dst \
  -e tcp.srcport -e tcp.dstport -e tcp.seq -e tcp.ack \
  -E header=y -E separator=$'\t'

frame.time              ip.src      ip.dst      srcport  dstport  seq   ack
Apr 29, 2026 14:23:01   10.0.0.1    10.0.0.2    54321    3306     999   1000
Apr 29, 2026 14:23:01   10.0.0.2    10.0.0.1    3306     54321    1000  1000
Apr 29, 2026 14:23:11   10.0.0.1    10.0.0.2    54321    3306     999   1000

ss -tnop | grep 3306 | grep timer

watch -n 1 'ss -tnop | grep 3306 | grep timer'

ESTAB 0 0 10.0.0.1:54321 10.0.0.2:3306 users:(("app",pid=1234,fd=7)) timer:(keepalive,58s,0)

timer:(  keepalive,   58s,   0  )
         ^            ^      ^
         type         |      unacknowledged probe count
                      countdown to next probe

package main

import (
	"context"
	"database/sql"
	"fmt"
	"log"
	"net"
	"net/url"
	"os"
	"strconv"
	"strings"
	"time"

	"github.com/go-sql-driver/mysql"
)

func main() {
	jdbcURL := os.Getenv("DB_URL")
	directDSN := os.Getenv("DB_DSN")

	var dsn string
	var err error

	switch {
	case jdbcURL != "":
		fmt.Println("[CLIENT] Input format: JDBC URL")
		dsn, err = jdbcToMySQLDSN(jdbcURL)
		if err != nil {
			log.Fatalf("Failed to parse JDBC URL: %v", err)
		}

	case directDSN != "":
		fmt.Println("[CLIENT] Input format: Direct DSN")
		dsn = directDSN

	default:
		log.Fatal("Set either DB_URL (JDBC) or DB_DSN (direct) environment variable")
	}

	registerKeepaliveDialer()
	dsn = strings.Replace(dsn, "@tcp(", "@tcp-keepalive(", 1)

	fmt.Printf("[CLIENT] DSN: %s
", maskPassword(dsn))

	db, err := sql.Open("mysql", dsn)
	if err != nil {
		log.Fatalf("Failed to open database: %v", err)
	}
	defer db.Close()

	db.SetMaxOpenConns(1)
	db.SetMaxIdleConns(1)
	db.SetConnMaxLifetime(0)

	if err := db.Ping(); err != nil {
		log.Fatalf("Failed to connect: %v", err)
	}

	fmt.Println("[CLIENT] Connected. Connection is now IDLE.")
	fmt.Println("[CLIENT] OS will send keepalive probes using sysctl values.")
	fmt.Println(strings.Repeat("=", 60))

	startTime := time.Now()
	ticker := time.NewTicker(30 * time.Second)
	defer ticker.Stop()

	for range ticker.C {
		fmt.Printf("[CLIENT] Idle for %ds — run: ss -tnop | grep 3306 | grep timer
",
			int(time.Since(startTime).Seconds()))
	}
}

// registerKeepaliveDialer enables SO_KEEPALIVE on every new MySQL connection.
//
// KeepAlive: -1 enables the socket option without overriding OS sysctl values.
// The kernel applies tcp_keepalive_time, tcp_keepalive_intvl, and tcp_keepalive_probes
// automatically — the application does not need to read or pass those values.
func registerKeepaliveDialer() {
	mysql.RegisterDialContext("tcp-keepalive", func(ctx context.Context, addr string) (net.Conn, error) {
		dialer := &net.Dialer{
			Timeout: 10 * time.Second,
			// -1 enables SO_KEEPALIVE and delegates all timing to OS sysctl.
			// Do not set a positive duration here — that overrides sysctl values
			// and prevents operators from tuning keepalive without a code change.
			KeepAlive: -1,
		}

		conn, err := dialer.DialContext(ctx, "tcp", addr)
		if err != nil {
			return nil, err
		}

		fmt.Println("[CLIENT] SO_KEEPALIVE enabled — OS sysctl values apply automatically")
		return conn, nil
	})
}

// jdbcToMySQLDSN converts a JDBC connection URL to a Go MySQL DSN.
//
// Input:
//
//	jdbc:mysql://host:port/database?param1=value1&param2=value2
//
// Output:
//
//	user:password@tcp(host:port)/database?param1=value1
//
// Credentials are read from DB_USER and DB_PASSWORD environment variables.
func jdbcToMySQLDSN(jdbcURL string) (string, error) {
	if !strings.HasPrefix(jdbcURL, "jdbc:mysql://") {
		return "", fmt.Errorf("invalid JDBC URL: must start with jdbc:mysql://")
	}

	raw := strings.TrimPrefix(jdbcURL, "jdbc:mysql://")
	parts := strings.SplitN(raw, "/", 2)
	if len(parts) != 2 {
		return "", fmt.Errorf("invalid JDBC URL: missing database path")
	}

	hostPort := parts[0]
	dbParts := strings.SplitN(parts[1], "?", 2)
	database := dbParts[0]

	params := url.Values{}
	params.Set("parseTime", "true")

	if len(dbParts) > 1 {
		for _, pair := range strings.Split(dbParts[1], "&") {
			kv := strings.SplitN(pair, "=", 2)
			if len(kv) != 2 {
				continue
			}
			key, value := kv[0], kv[1]

			switch key {
			case "useSSL":
				if value == "true" {
					params.Set("tls", "true")
				}
			case "requireSSL":
				if value == "true" {
					params.Set("tls", "skip-verify")
				}
			case "characterEncoding":
				params.Set("charset", value)
			case "connectTimeout":
				if ms, err := strconv.Atoi(value); err == nil {
					params.Set("timeout", fmt.Sprintf("%dms", ms))
				}
			case "socketTimeout":
				if ms, err := strconv.Atoi(value); err == nil {
					params.Set("readTimeout", fmt.Sprintf("%dms", ms))
					params.Set("writeTimeout", fmt.Sprintf("%dms", ms))
				}
			// Intentionally ignored — handled by registerKeepaliveDialer or not applicable in Go:
			// tcpKeepAlive, autoReconnect, cacheServerConfiguration, sessionVariables,
			// zeroDateTimeBehavior, scrollTolerantForwardOnly, jdbcCompliantTruncation
			}
		}
	}

	user := getEnv("DB_USER", "root")
	password := getEnv("DB_PASSWORD", "")

	return fmt.Sprintf("%s:%s@tcp(%s)/%s?%s", user, password, hostPort, database, params.Encode()), nil
}

func getEnv(key, defaultValue string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return defaultValue
}

func maskPassword(dsn string) string {
	at := strings.Index(dsn, "@")
	if at == -1 {
		return dsn
	}
	userPass := dsn[:at]
	colon := strings.Index(userPass, ":")
	if colon == -1 {
		return dsn
	}
	return userPass[:colon] + ":****@" + dsn[at+1:]
}

# Direct DSN (DB_DSN)
user:password@tcp(host:port)/database?param=value

# With TLS + charset
appuser:secret@tcp(mysql.internal:3306)/mydb?tls=skip-verify&parseTime=true&charset=utf8

# JDBC URL (DB_URL) — converted automatically by jdbcToMySQLDSN
jdbc:mysql://mysql.internal:3306/mydb?useSSL=true&requireSSL=true&characterEncoding=utf8&tcpKeepAlive=true

tcp_keepalive_time  =  LB_timeout × 0.5     (50% safety margin)
tcp_keepalive_intvl =  10 – 30s             (based on network latency)
tcp_keepalive_probes=  6 – 9                (balance detection speed vs tolerance)

ALB_ARN=$(aws elbv2 describe-load-balancers \
  --query 'LoadBalancers[?contains(LoadBalancerName, `k8s`)].LoadBalancerArn' \
  --output text)

aws elbv2 modify-load-balancer-attributes \
  --load-balancer-arn $ALB_ARN \
  --attributes Key=idle_timeout.timeout_seconds,Value=120

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-sku: "Standard"
    service.beta.kubernetes.io/azure-load-balancer-tcp-idle-timeout: "10"  # minutes, range: 4–30

spec:
  securityContext:
    sysctls:
    - name: net.ipv4.tcp_keepalive_time
      value: "120"
    - name: net.ipv4.tcp_keepalive_intvl
      value: "15"
    - name: net.ipv4.tcp_keepalive_probes
      value: "9"

apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
data:
  # Client-side: keep idle client connections open (must be < LB timeout)
  keep-alive: "120"
  keep-alive-requests: "1000"

  # Upstream: connection pool to backend pods
  upstream-keepalive-connections: "64"
  upstream-keepalive-timeout: "60"
  upstream-keepalive-requests: "1000"

  # Proxy timeouts
  proxy-connect-timeout: "10"
  proxy-read-timeout: "120"
  proxy-send-timeout: "120"

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "120"
    nginx.ingress.kubernetes.io/proxy-connect-timeout: "10"
    nginx.ingress.kubernetes.io/upstream-keepalive-timeout: "60"

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    nginx.ingress.kubernetes.io/websocket-services: "websocket-svc"

stream {
    upstream mysql_backend {
        server mysql.internal:3306;
    }

    server {
        listen 3306;
        proxy_pass mysql_backend;

        # Must be shorter than: DB wait_timeout, Cloud NAT timeout, firewall timeout
        proxy_timeout 300s;
        proxy_connect_timeout 10s;

        # Enables SO_KEEPALIVE using system sysctl values
        proxy_socket_keepalive on;
    }
}

# 1. Check OS values
sysctl net.ipv4.tcp_keepalive_time net.ipv4.tcp_keepalive_intvl net.ipv4.tcp_keepalive_probes

# 2. Lower for testing
sudo sysctl -w net.ipv4.tcp_keepalive_time=10
sudo sysctl -w net.ipv4.tcp_keepalive_intvl=5
sudo sysctl -w net.ipv4.tcp_keepalive_probes=3

# 3. Start full stream capture
sudo tcpdump -i eth0 -w keepalive_3306.pcap 'tcp port 3306'

# 4. In another terminal — watch timer countdown
watch -n 1 'ss -tnop | grep 3306 | grep timer'

# 5. Analyse pcap with tshark
tshark -r keepalive_3306.pcap \
  -Y 'tcp.analysis.keep_alive or tcp.analysis.keep_alive_ack' \
  -T fields -e frame.time -e ip.src -e ip.dst \
  -e tcp.srcport -e tcp.dstport -e tcp.seq -e tcp.ack \
  -E header=y -E separator='\t'

# 6. Quick raw read
tcpdump -nn -r keepalive_3306.pcap