Skip to main content
Mole configuring SOCKS5

SOCKS5 Configuration

The SOCKS5 section configures the ingress proxy server.

Configuration​

socks5:
  enabled: true
  address: "127.0.0.1:1080"
  auth:
    enabled: false
    users: []
  max_connections: 1000

Options​

OptionTypeDefaultDescription
enabledboolfalseEnable SOCKS5 server
addressstring"127.0.0.1:1080"Bind address
auth.enabledboolfalseRequire authentication
auth.usersarray[]User credentials
max_connectionsint1000Maximum concurrent connections

Basic Configuration​

Local Access Only​

socks5:
  enabled: true
  address: "127.0.0.1:1080"

Network Access​

socks5:
  enabled: true
  address: "0.0.0.0:1080"    # Accept from any IPv4 interface
warning

Exposing SOCKS5 on 0.0.0.0 without authentication allows anyone to use your proxy.

IPv6 Access​

socks5:
  enabled: true
  address: "[::1]:1080"      # IPv6 localhost only

Or accept from all IPv6 interfaces:

socks5:
  enabled: true
  address: "[::]:1080"       # All IPv6 interfaces
tip

SOCKS5 clients can connect to IPv6 destinations regardless of which address family the server binds to. The destination address family is independent of the listener address.

Authentication​

No Authentication​

socks5:
  enabled: true
  address: "127.0.0.1:1080"
  auth:
    enabled: false

Username/Password Authentication​

socks5:
  enabled: true
  address: "0.0.0.0:1080"
  auth:
    enabled: true
    users:
      - username: "user1"
        password_hash: "$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy"
      - username: "user2"
        password_hash: "$2a$10$..."

Generating Password Hash​

Use the built-in CLI command (recommended):

# Interactive (recommended - password hidden)
muti-metroo hash

# Or provide password as argument
muti-metroo hash "yourpassword"

# With custom cost factor
muti-metroo hash --cost 12

See CLI - hash for full documentation.

Alternative Methods​

Using htpasswd:

htpasswd -bnBC 10 "" yourpassword | tr -d ':\n'

Using Python:

import bcrypt
print(bcrypt.hashpw(b"yourpassword", bcrypt.gensalt(10)).decode())

Plaintext Passwords (Development Only)​

socks5:
  auth:
    users:
      - username: "dev"
        password: "devpass"    # NOT for production!
danger

Never use plaintext passwords in production. Always use bcrypt hashes.

Connection Limits​

socks5:
  max_connections: 1000       # Maximum concurrent SOCKS5 connections

When limit is reached:

  • New connections are rejected
  • Metric socks5_connections_rejected_total increments
  • Existing connections continue working

Client Configuration​

curl​

# No authentication
curl -x socks5://localhost:1080 https://example.com

# With authentication
curl -x socks5://user1:password@localhost:1080 https://example.com

# SOCKS5h (resolve DNS through proxy)
curl -x socks5h://localhost:1080 https://example.com

SSH​

ssh -o ProxyCommand='nc -x localhost:1080 %h %p' user@remote-host

Or in ~/.ssh/config:

Host remote-host
  ProxyCommand nc -x localhost:1080 %h %p
  User myuser

Firefox​

  1. Settings -> Network Settings
  2. Manual proxy configuration
  3. SOCKS Host: localhost, Port: 1080
  4. SOCKS v5
  5. If auth enabled, enter credentials when prompted

Chrome​

# Linux/macOS
google-chrome --proxy-server="socks5://localhost:1080"

# Windows
chrome.exe --proxy-server="socks5://localhost:1080"

Git​

git config --global http.proxy socks5://localhost:1080

SOCKS5 Protocol Support​

Muti Metroo supports:

FeatureSupported
CONNECT commandYes
BIND commandNo
UDP ASSOCIATENo
No AuthenticationYes
Username/PasswordYes
IPv4 addressesYes
IPv6 addressesYes
Domain namesYes

Examples​

Development​

socks5:
  enabled: true
  address: "127.0.0.1:1080"

Team Shared Proxy​

socks5:
  enabled: true
  address: "0.0.0.0:1080"
  auth:
    enabled: true
    users:
      - username: "team"
        password_hash: "$2a$10$..."
  max_connections: 5000

High-Security​

socks5:
  enabled: true
  address: "127.0.0.1:1080"    # Localhost only
  auth:
    enabled: true
    users:
      - username: "admin"
        password_hash: "$2a$12$..."    # Cost factor 12
  max_connections: 100

Metrics​

MetricTypeDescription
muti_metroo_socks5_connections_activeGaugeActive connections
muti_metroo_socks5_connections_totalCounterTotal connections
muti_metroo_socks5_auth_failures_totalCounterAuth failures
muti_metroo_socks5_connect_latency_secondsHistogramConnect latency

Troubleshooting​

Connection Refused​

# Check SOCKS5 is enabled
grep -A5 "socks5:" config.yaml

# Check process is listening
lsof -i :1080
netstat -tlnp | grep 1080

Authentication Failed​

# Verify password hash
# Hash should start with $2a$ or $2b$

# Try with curl
curl -v -x socks5://user:pass@localhost:1080 https://example.com

No Route to Host​

  • Check exit agent is connected
  • Verify routes are advertised
  • Check routing table: curl http://localhost:8080/healthz

See Troubleshooting for more help.