### Deploy S5Core Server with Docker (Bash)

Source: https://context7.com/mazixs/s5core/llms.txt

Instructions for deploying the S5Core server using Docker. Examples cover basic server setup with authentication, enabling obfuscation with dual-port mode, and configuring user files via volume mounts. Environment variables are used for configuration, including ports, authentication credentials, obfuscation settings, and user file paths.

```bash
# Basic server with authentication
docker run -d \
  --name s5core \
  -p 1080:1080 \
  -p 8080:8080 \
  -e PROXY_USER=myuser \
  -e PROXY_PASSWORD=mypassword \
  -e MAX_CONNECTIONS=5000 \
  -e FAIL2BAN_RETRIES=3 \
  -e FAIL2BAN_TIME=15m \
  ghcr.io/mazixs/s5core:latest

# With obfuscation enabled (dual-port mode)
docker run -d \
  --name s5core \
  -p 1080:1080 \
  -p 1443:1443 \
  -p 8080:8080 \
  -e PROXY_USER=myuser \
  -e PROXY_PASSWORD=supersecure \
  -e OBFS_ENABLED=true \
  -e OBFS_PORT=1443 \
  -e OBFS_PSK=AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH \
  -e OBFS_MAX_PADDING=256 \
  -e OBFS_MTU=1400 \
  ghcr.io/mazixs/s5core:latest

# With multi-account user file
docker run -d \
  --name s5core \
  -p 1080:1080 \
  -v /path/to/users.json:/etc/s5core/users.json:rw \
  -e USERS_FILE=/etc/s5core/users.json \
  -e TRAFFIC_FLUSH_INTERVAL=30s \
  ghcr.io/mazixs/s5core:latest
```

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

### Test S5Core Proxy with s5client (Obfuscated)

Source: https://github.com/mazixs/s5core/blob/main/README.md

This two-terminal example shows how to test the S5Core proxy with obfuscation using the s5client. The first terminal starts the s5client, and the second terminal uses it as a local SOCKS5 proxy to make requests.

```bash
# Terminal 1: Start local client
SERVER_ADDR=<PROXY_IP>:1443 OBFS_PSK=AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH ./s5client

# Terminal 2: Use it as a regular SOCKS5 proxy
curl --socks5 127.0.0.1:1080 https://ipinfo.io
```

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

### Initialize and Start a SOCKS5 Server in Go

Source: https://github.com/mazixs/s5core/blob/main/internal/socks5/README.md

This snippet demonstrates how to configure and launch a basic SOCKS5 proxy server. It uses the socks5.Config struct to initialize the server and ListenAndServe to bind it to a local address.

```go
// Create a SOCKS5 server
conf := &socks5.Config{}
server, err := socks5.New(conf)
if err != nil {
  panic(err)
}

// Create SOCKS5 proxy on localhost port 8000
if err := server.ListenAndServe("tcp", "127.0.0.1:8000"); err != nil {
  panic(err)
}
```

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

### Embedding S5Core Server in a Go Application

Source: https://github.com/mazixs/s5core/blob/main/README.md

Demonstrates how to programmatically configure and start the S5Core server within a Go application using the S5Core SDK. It covers setting up ports, authentication, user store, obfuscation, and whitelisting.

```go
package main

import (
	"context"
	"log/slog"
	"time"

	"github.com/mazixs/S5Core/pkg/s5server"
)

func main() {
	cfg := s5server.DefaultConfig()
	cfg.Port = "1080"
	cfg.RequireAuth = true
	// Enable modern user store
	cfg.UsersFile = "users.json"
	cfg.TrafficFlushInterval = 30 * time.Second

	// Enable obfuscation
	cfg.ObfsEnabled = true
	cfg.ObfsPort = "1443"
	cfg.ObfsPSK = "AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH" // 32 bytes
	cfg.ObfsMaxPadding = 256
	cfg.ObfsMTU = 1400

	// Initialize the server
	srv, err := s5server.NewServer(cfg)
	if err != nil {
		panic(err)
	}

	// Update whitelisted IPs on the fly
	srv.UpdateWhitelist([]string{"192.168.1.100"})

	// Start the server (blocks until context is canceled)
	slog.Info("Starting S5Core SDK...")
	if err := srv.Start(context.Background()); err != nil {
		panic(err)
	}
}
```

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

### Start SOCKS5 Server with Graceful Shutdown

Source: https://context7.com/mazixs/s5core/llms.txt

Starts the SOCKS5 server and manages its lifecycle using context. It includes signal handling to ensure the server shuts down gracefully upon receiving interrupt signals.

```go
package main

import (
    "context"
    "log"
    "os"
    "os/signal"
    "syscall"

    "github.com/mazixs/S5Core/pkg/s5server"
)

func main() {
    cfg := s5server.DefaultConfig()
    cfg.Port = "1080"
    cfg.RequireAuth = true

    srv, err := s5server.NewServer(cfg)
    if err != nil {
        log.Fatal(err)
    }

    srv.AddUser("admin", "secure123")

    // Set up graceful shutdown
    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
    defer stop()

    log.Println("Starting SOCKS5 server on :1080")
    if err := srv.Start(ctx); err != nil {
        log.Printf("Server stopped: %v", err)
    }
}
```

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

### S5Core Go SDK Integration

Source: https://context7.com/mazixs/s5core/llms.txt

Full implementation example for embedding S5Core into a Go application. It demonstrates server configuration, telemetry initialization, graceful shutdown, and dynamic hot-reloading of user lists and whitelists.

```go
package main

import (
	"context"
	"log"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/prometheus/client_golang/prometheus/promhttp"
	"go.opentelemetry.io/otel/exporters/prometheus"
	"go.opentelemetry.io/otel/sdk/metric"

	"github.com/mazixs/S5Core/pkg/s5server"
)

func main() {
	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
	slog.SetDefault(logger)

	exporter, _ := prometheus.New()
	provider := metric.NewMeterProvider(metric.WithReader(exporter))
	telemetry, _ := s5server.InitTelemetry(provider)

	cfg := s5server.Config{
		Port:                 "1080",
		ListenIP:             "0.0.0.0",
		RequireAuth:          true,
		UsersFile:            "users.json",
		TrafficFlushInterval: 30 * time.Second,
		AllowedIPs:           []string{"192.168.1.0/24"},
		AllowedDestFqdn:      ".*",
		ReadTimeout:          60 * time.Second,
		WriteTimeout:         60 * time.Second,
		MaxConnections:       10000,
		Fail2BanRetries:      5,
		Fail2BanTime:         5 * time.Minute,
		Telemetry:            telemetry,
		ObfsEnabled:          true,
		ObfsPort:             "1443",
		ObfsPSK:              "AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH",
		ObfsMaxPadding:       256,
		ObfsMTU:              1400,
	}

	srv, err := s5server.NewServer(cfg)
	if err != nil {
		log.Fatal(err)
	}

	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	go func() {
		hupCh := make(chan os.Signal, 1)
		signal.Notify(hupCh, syscall.SIGHUP)
		for range hupCh {
			slog.Info("SIGHUP received, reloading...")
			srv.ReloadUsers()
			srv.UpdateWhitelist([]string{"192.168.1.0/24", "10.0.0.0/8"})
		}
	}()

	go func() {
		http.Handle("/metrics", promhttp.Handler())
		http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
			w.WriteHeader(http.StatusOK)
			w.Write([]byte("OK"))
		})
		http.ListenAndServe(":8080", nil)
	}()

	if err := srv.Start(ctx); err != nil {
		slog.Error("Server stopped", "error", err)
	}

	srv.Stop()
}
```

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

### Run s5client with Obfuscation and Domain Routing

Source: https://github.com/mazixs/s5core/blob/main/README.md

Starts the s5client locally, connecting to a remote obfuscated server with specific domain routing rules for split tunneling.

```bash
SERVER_ADDR=your-server-ip:1443 \
OBFS_PSK=AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH \
ROUTE_DOMAINS="*.google.com,*.youtube.com" \
./s5client
```

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

### Execute s5vpn-win.ps1 commands

Source: https://github.com/mazixs/s5core/blob/main/README.md

Standard commands to manage the VPN tunnel lifecycle, including starting, stopping, and checking the status of the connection.

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\s5vpn-win.ps1 start
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\s5vpn-win.ps1 status
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\s5vpn-win.ps1 test
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\s5vpn-win.ps1 stop
```

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

### Test S5Core Proxy with cURL (Bash)

Source: https://context7.com/mazixs/s5core/llms.txt

Demonstrates how to test the S5Core proxy functionality using the cURL command-line tool. Examples show testing a plain SOCKS5 connection to the server and testing traffic routed through the S5Client, which utilizes the obfuscation tunnel.

```bash
# Test plain SOCKS5 (no obfuscation)
curl --socks5 your-server-ip:1080 \
     -U myuser:mypassword \
     https://ipinfo.io

# Test via s5client (with obfuscation)
# Terminal 1: Start s5client
SERVER_ADDR=your-server-ip:1443 \
OBFS_PSK=AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH \
./s5client

# Terminal 2: Use curl via the local s5client proxy
# curl --socks5 127.0.0.1:1080 https://ipinfo.io

```

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

### Install tun2socks dependency

Source: https://github.com/mazixs/s5core/blob/main/README.md

Uses the Windows Package Manager (winget) to install the tun2socks utility required for the full-tunnel operation.

```powershell
winget install xjasonlyu.tun2socks
```

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

### Create and Configure SOCKS5 Server Instance

Source: https://context7.com/mazixs/s5core/llms.txt

Initializes a new SOCKS5 server using a custom configuration. This snippet demonstrates how to apply settings and register user credentials for authentication.

```go
package main

import (
    "context"
    "log"
    "time"

    "github.com/mazixs/S5Core/pkg/s5server"
)

func main() {
    cfg := s5server.DefaultConfig()
    cfg.Port = "1080"
    cfg.RequireAuth = true
    cfg.MaxConnections = 5000
    cfg.ReadTimeout = 60 * time.Second
    cfg.WriteTimeout = 60 * time.Second
    cfg.Fail2BanRetries = 3
    cfg.Fail2BanTime = 10 * time.Minute

    srv, err := s5server.NewServer(cfg)
    if err != nil {
        log.Fatalf("Failed to create server: %v", err)
    }

    // Add authentication credentials
    if err := srv.AddUser("myuser", "mypassword"); err != nil {
        log.Fatalf("Failed to add user: %v", err)
    }

    log.Println("Server configured successfully")
}
```

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

### Initialize Server Configuration with Go

Source: https://context7.com/mazixs/s5core/llms.txt

Retrieves a default configuration struct for the S5Core server. This provides sensible production defaults that can be customized before server initialization.

```go
package main

import (
    "fmt"
    "time"
    "github.com/mazixs/S5Core/pkg/s5server"
)

func main() {
    cfg := s5server.DefaultConfig()

    // Defaults:
    // Port:            "1080"
    // ListenIP:        "0.0.0.0"
    // RequireAuth:     true
    // ReadTimeout:     30 * time.Second
    // WriteTimeout:    30 * time.Second
    // MaxConnections:  10000
    // Fail2BanRetries: 5
    // Fail2BanTime:    5 * time.Minute

    fmt.Printf("Default config: Port=%s, MaxConn=%d, Auth=%v\n",
        cfg.Port, cfg.MaxConnections, cfg.RequireAuth)
}
```

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

### Run S5Client with Environment Variables (Bash)

Source: https://context7.com/mazixs/s5core/llms.txt

Instructions for running the S5Client, a local SOCKS5 proxy that tunnels traffic through an obfuscation layer to the S5Core server. It can be configured using environment variables for server address, authentication, obfuscation parameters, and domain-based split tunneling. Key variables include SERVER_ADDR, OBFS_PSK, PROXY_USER, PROXY_PASS, and ROUTE_DOMAINS.

```bash
# Basic usage - tunnel all traffic
SERVER_ADDR=your-server-ip:1443 \
OBFS_PSK=AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH \
PROXY_USER=myuser \
PROXY_PASS=mypassword \
./s5client

# With domain-based split tunneling
SERVER_ADDR=your-server-ip:1443 \
OBFS_PSK=AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH \
ROUTE_DOMAINS="*.google.com,*.youtube.com,netflix.com" \
./s5client

# Client environment variables:
# CLIENT_LISTEN_ADDR  - Local listen address (default: 127.0.0.1:1080)
# SERVER_ADDR         - Remote S5Core obfs address (required)
# PROXY_USER          - Username for server authentication
# PROXY_PASS          - Password for server authentication
# OBFS_PSK            - Pre-shared key (must match server, 32 bytes)
# OBFS_MAX_PADDING    - Must match server (default: 256)
# OBFS_MTU            - Must match server (default: 1400)
# ROUTE_DOMAINS       - Comma-separated domain patterns for split tunneling

```

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

### Manage Users with userstore.Store (Go)

Source: https://context7.com/mazixs/s5core/llms.txt

Provides a thread-safe in-memory user store with atomic traffic counters, periodic flushing to disk, and hot-reloading capabilities. It supports loading users from a JSON file, looking up users, validating credentials against business rules (enabled, password, expiration, traffic limit), adding traffic usage, and periodic background flushing.

```go
package main

import (
    "fmt"
    "log"
    "log/slog"
    "time"

    "github.com/mazixs/S5Core/internal/userstore"
)

func main() {
    logger := slog.Default()
    store := userstore.NewStore(logger)

    // Load users from JSON file
    if err := store.LoadFromFile("users.json"); err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Loaded %d users\n", store.UserCount())

    // Lookup a user
    if user, found := store.Lookup("premium_user"); found {
        fmt.Printf("User: %s, Traffic Used: %d bytes\n",
            user.Username, user.TrafficUsedBytes)
    }

    // Validate credentials with business rules
    // Checks: enabled, password, expiration, traffic limit
    if store.IsValid("premium_user", "secure123") {
        fmt.Println("Authentication successful")
    }

    // Add traffic (lock-free atomic operation)
    store.AddTraffic("premium_user", 1024*1024) // 1MB

    // Start periodic flush to disk (background goroutine)
    store.StartPeriodicFlush("users.json", 30*time.Second)
    defer store.StopPeriodicFlush()

    // Hot-reload without losing traffic counters
    store.Reload("users.json")
}
```

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

### Deploy s5core Server with Authentication using Docker

Source: https://github.com/mazixs/s5core/blob/main/README.md

Deploys the s5core proxy server container with basic username and password authentication enabled on port 1080.

```bash
docker run -d \
  --name s5core \
  -p 1080:1080 \
  -e PROXY_USER=myuser \
  -e PROXY_PASSWORD=mypassword \
  ghcr.io/mazixs/s5core:latest
```

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

### Reload S5Core Configuration with SIGHUP Signal

Source: https://github.com/mazixs/s5core/blob/main/README.md

This demonstrates how to reload specific S5Core configuration parameters like ALLOWED_IPS, READ_TIMEOUT, and WRITE_TIMEOUT without restarting the process. It involves updating environment variables and sending a SIGHUP signal to the running process.

```bash
# If running directly on host:
kill -HUP $(pgrep s5core)

# If running in Docker:
docker kill -s HUP s5core
```

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

### Deploy s5core Server with Obfuscation using Docker

Source: https://github.com/mazixs/s5core/blob/main/README.md

Deploys the s5core proxy server with traffic obfuscation enabled, requiring a 32-byte pre-shared key and specific MTU/padding settings.

```bash
docker run -d \
  --name s5core \
  -p 1080:1080 \
  -p 1443:1443 \
  -e PROXY_USER=myuser \
  -e PROXY_PASSWORD=supersecure \
  -e OBFS_ENABLED=true \
  -e OBFS_PORT=1443 \
  -e OBFS_PSK=AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH \
  -e OBFS_MAX_PADDING=256 \
  -e OBFS_MTU=1400 \
  ghcr.io/mazixs/s5core:latest
```

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

### Manage Multi-Account with UsersFile in Go

Source: https://context7.com/mazixs/s5core/llms.txt

Loads user accounts from a JSON file, supporting expiration dates and traffic quotas. It also enables hot-reloading of user data via SIGHUP signals without requiring a server restart. The configuration includes specifying the path to the users JSON file and setting a traffic flush interval.

```go
package main

import (
    "context"
    "log"
    "time"

    "github.com/mazixs/S5Core/pkg/s5server"
)

func main() {
    cfg := s5server.DefaultConfig()
    cfg.RequireAuth = true
    cfg.UsersFile = "/etc/s5core/users.json"       // Path to users JSON file
    cfg.TrafficFlushInterval = 30 * time.Second   // Flush traffic counters to disk

    srv, err := s5server.NewServer(cfg)
    if err != nil {
        log.Fatal(err)
    }

    // users.json format:
    // {
    //   "users": [
    //     {
    //       "id": "u-001",
    //       "username": "premium_user",
    //       "password": "secure123",
    //       "comment": "100GB limit, expires 2027",
    //       "valid_until": "2027-01-01T00:00:00Z",
    //       "traffic_limit_bytes": 107374182400,
    //       "traffic_used_bytes": 0,
    //       "enabled": true
    //     }
    //   ]
    // }

    // Hot-reload users without restart:
    // kill -HUP $(pgrep s5core)

    srv.Start(context.Background())
}

```

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

### Dynamically Add/Remove Users in Go

Source: https://context7.com/mazixs/s5core/llms.txt

Allows adding and removing users at runtime using the `AddUser` and `RemoveUser` functions. This functionality operates with an in-memory credential store, enabling dynamic user management without server restarts. Error handling is included for both adding and removing users.

```go
package main

import (
    "fmt"
    "log"

    "github.com/mazixs/S5Core/pkg/s5server"
)

func main() {
    cfg := s5server.DefaultConfig()
    cfg.RequireAuth = true

    srv, err := s5server.NewServer(cfg)
    if err != nil {
        log.Fatal(err)
    }

    // Add users dynamically
    if err := srv.AddUser("user1", "password1"); err != nil {
        log.Printf("Failed to add user1: %v", err)
    }
    if err := srv.AddUser("user2", "password2"); err != nil {
        log.Printf("Failed to add user2: %v", err)
    }

    fmt.Println("Added users: user1, user2")

    // Remove a user
    if err := srv.RemoveUser("user1"); err != nil {
        log.Printf("Failed to remove user1: %v", err)
    }

    fmt.Println("Removed user: user1")
}

```

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

### Initialize OpenTelemetry Metrics in Go

Source: https://context7.com/mazixs/s5core/llms.txt

Initializes standard OpenTelemetry metrics for monitoring server activity, including connections, traffic, and authentication failures. It uses a Prometheus exporter and integrates with the S5Core telemetry system. The metrics can be accessed via an HTTP endpoint, and a health check endpoint is also provided.

```go
package main

import (
    "context"
    "log"
    "net/http"

    "github.com/prometheus/client_golang/prometheus/promhttp"
    "go.opentelemetry.io/otel/exporters/prometheus"
    "go.opentelemetry.io/otel/sdk/metric"

    "github.com/mazixs/S5Core/pkg/s5server"
)

func main() {
    // Initialize Prometheus exporter
    exporter, err := prometheus.New()
    if err != nil {
        log.Fatal(err)
    }
    provider := metric.NewMeterProvider(metric.WithReader(exporter))

    // Initialize S5Core telemetry
    telemetry, err := s5server.InitTelemetry(provider)
    if err != nil {
        log.Fatal(err)
    }

    // Available metrics:
    // - s5core_connections_active (UpDownCounter): Current active TCP sessions
    // - s5core_connections_total (Counter): Total connections since start
    // - s5core_auth_failures_total (Counter): Failed authentication attempts
    // - s5core_traffic_bytes_in (Counter): Incoming traffic bytes
    // - s5core_traffic_bytes_out (Counter): Outgoing traffic bytes

    cfg := s5server.DefaultConfig()
    cfg.Telemetry = telemetry

    srv, _ := s5server.NewServer(cfg)
    srv.AddUser("user", "pass")

    // Start metrics endpoint
    go func() {
        http.Handle("/metrics", promhttp.Handler())
        http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
            w.WriteHeader(http.StatusOK)
            w.Write([]byte("OK"))
        })
        log.Println("Metrics at http://localhost:8080/metrics")
        http.ListenAndServe(":8080", nil)
    }()

    srv.Start(context.Background())
}

```

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

### Run S5Core with Advanced Docker Configuration

Source: https://github.com/mazixs/s5core/blob/main/README.md

This command runs the S5Core Docker container with advanced configurations including user authentication, IP whitelisting, and rate limiting. It maps the necessary ports and sets environment variables for security and performance tuning.

```bash
docker run -d \
  --name s5core \
  -p 1080:1080 \
  -p 8080:8080 \
  -e PROXY_USER=myuser \
  -e PROXY_PASSWORD=supersecure \
  -e ALLOWED_IPS=192.168.1.10,10.0.0.5 \
  -e MAX_CONNECTIONS=5000 \
  -e FAIL2BAN_RETRIES=3 \
  -e FAIL2BAN_TIME=15m \
  ghcr.io/mazixs/s5core:latest
```

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

### Proxy Server Operational Commands

Source: https://context7.com/mazixs/s5core/llms.txt

Standard CLI commands for testing proxy connectivity, verifying health and metrics endpoints, and performing hot-reloads of the server configuration.

```bash
curl --socks5 127.0.0.1:1080 https://ipinfo.io
proxychains4 dig @1.1.1.1 example.com
curl http://your-server-ip:8080/metrics
curl http://your-server-ip:8080/health
kill -HUP $(pgrep s5core)
docker kill -s HUP s5core
```

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

### Configure s5vpn-win.ps1 parameters

Source: https://github.com/mazixs/s5core/blob/main/README.md

The configuration block for the PowerShell script, defining server connection details, obfuscation settings, and network interface parameters.

```powershell
$Config = [ordered]@{
    ServerHost        = "YOUR_SERVER_IP"
    ServerPort        = 1443
    ObfsPsk           = "YOUR_32_BYTE_PSK_REPLACE_ME_1234"
    ObfsMaxPadding    = 256
    ObfsMtu           = 1400
    ProxyUser         = "YOUR_PROXY_USERNAME"
    ProxyPass         = "YOUR_PROXY_PASSWORD"
    ClientListenAddr  = "127.0.0.1:1080"
    TunName           = "wintun"
    TunIp             = "198.18.0.1"
    TunPrefixLength   = 15
    DnsServers        = @("1.1.1.1", "1.0.0.1")
    DisableIPv6       = $true
    RouteLanRanges    = $true
    AutoBuildS5Client = $true
    S5ClientExe       = (Join-Path $RepoRoot "build\s5client.exe")
    Tun2SocksExe      = ""
    WintunDll         = ""
}
```

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

### Test S5Core Proxy with cURL (No Obfuscation)

Source: https://github.com/mazixs/s5core/blob/main/README.md

This command uses cURL to test the S5Core proxy without obfuscation, providing authentication credentials and the target URL. It's a straightforward way to verify basic proxy functionality.

```bash
curl --socks5 <PROXY_IP>:1080 -U myuser:mypassword https://ipinfo.io
```

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

### Deploy S5Core and Application with Docker Compose

Source: https://github.com/mazixs/s5core/blob/main/README.md

This Docker Compose configuration sets up S5Core and another service (e.g., a curl client) to route traffic through S5Core. It demonstrates how to disable authentication for internal networks and configure applications to use the S5Core SOCKS5 proxy.

```yaml
services:
  s5core:
    # Image is automatically pulled from GitHub Packages
    image: ghcr.io/mazixs/s5core:latest
    restart: always
    ports:
      - "1080:1080"
    environment:
      - REQUIRE_AUTH=false # Disable auth for internal network, or use PROXY_USER/PROXY_PASSWORD
      - MAX_CONNECTIONS=5000

  my_app:
    image: curlimages/curl
    command: ["curl", "-s", "https://ipinfo.io"]
    environment:
      # Tell the application to use the S5Core SOCKS5 proxy
      - HTTP_PROXY=socks5://s5core:1080
      - HTTPS_PROXY=socks5://s5core:1080
      - ALL_PROXY=socks5://s5core:1080
    depends_on:
      - s5core
```

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

### Test UDP Relay (DNS over SOCKS5) with proxychains4

Source: https://github.com/mazixs/s5core/blob/main/README.md

This demonstrates testing UDP relay functionality, specifically for DNS queries over SOCKS5, using proxychains4. It shows two methods: tunneling DNS traffic through an encrypted TCP connection via s5client, and using direct UDP Associate without obfuscation.

```bash
# Via s5client — DNS traffic tunneled through encrypted TCP
proxychains4 dig @1.1.1.1 example.com

# Or with direct UDP Associate (no obfuscation)
proxychains4 -f /etc/proxychains-udp.conf dig @8.8.8.8 example.com
```

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

### Dynamically Update IP Whitelist in Go

Source: https://context7.com/mazixs/s5core/llms.txt

Enables runtime updates to the IP whitelist using the `UpdateWhitelist` function. This allows for dynamic modification of allowed client IP addresses without needing to restart the server. The function can also be used to clear the whitelist by passing an empty slice, effectively allowing all IPs.

```go
package main

import (
    "context"
    "log"
    "time"

    "github.com/mazixs/S5Core/pkg/s5server"
)

func main() {
    cfg := s5server.DefaultConfig()
    cfg.AllowedIPs = []string{"192.168.1.100", "10.0.0.5"} // Initial whitelist

    srv, err := s5server.NewServer(cfg)
    if err != nil {
        log.Fatal(err)
    }

    // Update whitelist at runtime
    newIPs := []string{"192.168.1.100", "192.168.1.101", "10.0.0.0/24"}
    if err := srv.UpdateWhitelist(newIPs); err != nil {
        log.Printf("Failed to update whitelist: %v", err)
    }

    // Clear whitelist (allow all IPs)
    srv.UpdateWhitelist([]string{})

    log.Println("Whitelist updated successfully")
}

```

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

### Obfuscate Network Connections with obfs.NewConn (Go)

Source: https://context7.com/mazixs/s5core/llms.txt

Wraps a standard net.Conn with AES-256-GCM encryption and random padding for secure communication. It requires a 32-byte Pre-Shared Key (PSK) and allows configuration of maximum padding and MTU. The encrypted frames include frame size, nonce, and ciphertext, with the ciphertext containing payload length, payload, padding length, and random padding.

```go
package main

import (
    "fmt"
    "log"
    "net"

    "github.com/mazixs/S5Core/pkg/obfs"
)

func main() {
    // Example: Wrap a client connection with obfuscation
    conn, err := net.Dial("tcp", "server.example.com:1443")
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    cfg := obfs.Config{
        PSK:        []byte("AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH"), // Exactly 32 bytes
        MaxPadding: 256,   // Random padding 0-256 bytes per frame
        MTU:        1400,  // Maximum frame size
    }

    obfsConn, err := obfs.NewConn(conn, cfg)
    if err != nil {
        log.Fatal(err)
    }

    // Wire protocol per frame:
    // [Frame Size (4B)] [Nonce (12B)] [AES-256-GCM Ciphertext]
    //                                  └─ [PayloadLen (2B)] [Payload] [PadLen (2B)] [Random Padding]

    // Use like any net.Conn - encryption is transparent
    obfsConn.Write([]byte("Hello, encrypted world!"))

    buf := make([]byte, 1024)
    n, _ := obfsConn.Read(buf)
    fmt.Printf("Received: %s\n", buf[:n])
}
```

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

### JSON User Store Configuration for S5Core

Source: https://github.com/mazixs/s5core/blob/main/README.md

Defines the structure for a JSON file to manage multiple user accounts, including authentication, traffic limits, and expiration dates. This enables multi-account support and per-user traffic tracking.

```json
{
  "users": [
    {
      "id": "u-001",
      "username": "premium_user",
      "password": "secure123",
      "comment": "100GB limit, expires in 2027",
      "valid_until": "2027-01-01T00:00:00Z",
      "traffic_limit_bytes": 107374182400,
      "traffic_used_bytes": 0,
      "enabled": true
    },
    {
      "id": "u-002",
      "username": "unlimited_user",
      "password": "anotherpassword",
      "enabled": true
    }
  ]
}
```

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

### Enable Traffic Obfuscation

Source: https://context7.com/mazixs/s5core/llms.txt

Configures the server to support AES-256-GCM traffic obfuscation on a secondary port. This helps bypass DPI by making proxy traffic appear as random noise.

```go
package main

import (
    "context"
    "log"
    "os"
    "os/signal"
    "syscall"
    "time"

    "github.com/mazixs/S5Core/pkg/s5server"
)

func main() {
    cfg := s5server.DefaultConfig()
    cfg.Port = "1080"                              // Plain SOCKS5 port
    cfg.RequireAuth = true

    // Enable obfuscation on separate port
    cfg.ObfsEnabled = true
    cfg.ObfsPort = "1443"                          // Obfuscated connections port
    cfg.ObfsPSK = "AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH" // Exactly 32 bytes
    cfg.ObfsMaxPadding = 256                       // Max random padding per frame
    cfg.ObfsMTU = 1400                             // Frame MTU (avoid fragmentation)

    srv, err := s5server.NewServer(cfg)
    if err != nil {
        log.Fatal(err)
    }
    srv.AddUser("tunneluser", "secretpass")

    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
    defer stop()

    // Server now listens on:
    // - :1080 for plain SOCKS5
    // - :1443 for obfuscated connections (s5client only)
    log.Println("Starting dual-port server (plain:1080, obfs:1443)")
    srv.Start(ctx)
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.