e

7 Ways to Secure Your Connections with Stunnel

Written by

adm

in

Troubleshooting Common Stunnel Errors and Fixes

Stunnel is a lightweight tool that adds SSL/TLS encryption to existing TCP services. When misconfigured or when system-level issues occur, connections can fail or behave unpredictably. This article walks through common stunnel errors, their causes, and concrete fixes.

1. Stunnel won’t start — “Configuration error” or exits immediately

  • Cause: Syntax error, duplicate options, invalid file paths, or missing certificates in stunnel.conf.
  • Fixes:
    1. Validate config syntax: Run stunnel in foreground with verbose logging: 
      Code
      stunnel -n your_service -f -d 7 -o stunnel.log /etc/stunnel/stunnel.conf
    2. Check file paths and permissions: Ensure cert/key files exist and are readable by the stunnel user:
      • ls -l /etc/stunnel/*.pem
      • Adjust with chmod 640 and chown root:stunnel (or appropriate user).
    3. Remove duplicate or invalid options: Compare against stunnel documentation for your version.

2. “SSLaccept: error” or TLS handshake failures

  • Cause: Certificate/key mismatch, wrong cipher settings, unsupported TLS version, or client/server protocol mismatch.
  • Fixes:
    1. Confirm cert and key match: 
      Code
      openssl x509 -noout -modulus -in server.crt | openssl md5 openssl rsa -noout -modulus -in server.key | openssl md5

      Both outputs must match.

    2. Enable compatible TLS versions/ciphers: In stunnel.conf, set: 
      Code
      sslVersion = TLSv1.2 ciphers = HIGH:!aNULL:!MD5
    3. Test handshake with openssl sclient: 
      Code
      openssl sclient -connect localhost:443 -servername example.com

      Check protocol and cipher in response.

3. “Connection reset by peer” or immediate disconnects

  • Cause: Backend service refusing connections, stunnel unable to connect to target, or MTU/packet issues.
  • Fixes:
    1. Verify backend reachable from stunnel host: 
      Code
      telnet 127.0.0.1 8080
    2. Check stunnel’s connect setting: Ensure correct host:port in service section: 
      Code
      [service] accept = 443 connect = 127.0.0.1:8080
    3. Inspect logs for backend errors and increase stunnel debug level.

4. “Certificate has expired” or “self-signed certificate” warnings

  • Cause: Expired cert, incorrect trust store, or client rejecting self-signed cert.
  • Fixes:
    1. Check expiry: 
      Code
      openssl x509 -in server.crt -noout -dates
    2. Replace or renew certificate with a valid CA-signed cert or update expiry.
    3. For self-signed certs, distribute the CA cert to clients or enable verifyChain = no only for testing (not recommended in production).

5. Permission denied when binding to low ports (<1024)

  • Cause: Non-root stunnel user trying to bind privileged port.
  • Fixes:
    1. Use port redirection with firewall (iptables/nft) to forward traffic to a higher port.
    2. Run stunnel as root (not recommended) or use capabilities: 
      Code
      setcap ‘cap_net_bind_service=+ep’ /usr/bin/stunnel

6. High latency or throughput issues

  • Cause: TLS overhead, TCP windowing, small buffer sizes, or CPU limits on encryption.
  • Fixes:
    1. Enable session reuse and tune options (if available) to reduce handshakes.
    2. Increase socket buffer sizes (OS-level or stunnel options).
    3. Offload TLS using hardware or dedicate CPU for stunnel; profile CPU usage.

7. Problems after systemd migration (stunnel service fails to stay up)

  • Cause: Mismatch between stunnel unit file and stunnel configuration or incorrect ExecStart flags.
  • Fixes:
    1. Inspect systemd unit: systemctl status stunnel and journalctl -u stunnel.
    2. Use correct ExecStart for foreground mode (-f) if unit expects it.
    3. Ensure proper PID or user settings in unit file align with stunnel.conf.

Debugging checklist

  • Increase stunnel debug level (e.g., -d 7) and monitor logs.
  • Verify certificate/key correctness and permissions.
  • Test connectivity to backend services independently.
  • Use openssl sclient for TLS diagnostics.
  • Confirm firewall and SELinux/AppArmor aren’t blocking traffic.
  • Reproduce with minimal config to isolate variables.

Example minimal stunnel.conf for testing

Code
pid = /var/run/stunnel.pid output = /var/log/stunnel.log foreground = yes [https] accept= 443 connect = 127.0.0.1:8443 cert = /etc/stunnel/server.pem sslVersion = TLSv1.2

If you share the exact error messages or stunnel log excerpts, I can provide targeted fixes.

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts