Troubleshooting Guide

This guide covers common issues and their solutions when deploying PQC SSL certificates.

Table of Contents

1. Service Issues 2. Port and Connectivity Problems 3. Certificate Errors 4. HAProxy Issues 5. Web Server Problems 6. PQC Server Issues 7. Browser and Client Issues 8. Performance Problems

---

Service Issues

HAProxy Won't Start

Symptoms:

  • \systemctl start haproxy\ fails
  • Error: "Address already in use"

Solution: \\\bash

Check what's using port 443

ss -tlnp | grep :443

If another service is using it (like Nginx on 443):

1. Stop the conflicting service

systemctl stop nginx

2. Reconfigure it to use port 8080 (backend)

See Configuration Guide

3. Start HAProxy first

systemctl start haproxy

4. Then start the backend service

systemctl start nginx \\\

Check Configuration: \\\bash

Test HAProxy config for syntax errors

haproxy -c -f /etc/haproxy/haproxy.cfg

Check for typos in server names

grep -i "req_ssl_sni" /etc/haproxy/haproxy.cfg \\\

Nginx/Apache Won't Start

Symptoms:

  • Service fails to start
  • Error: "Port already in use"

Solution: \\\bash

Check if port 8080 is in use

ss -tlnp | grep :8080

Kill conflicting process if needed

lsof -ti:8080 | xargs kill -9

Restart service

systemctl restart nginx \\\

Check SSL Certificate Paths: \\\bash

Verify cert files exist

ls -l /etc/letsencrypt/live/*/fullchain.pem ls -l /etc/letsencrypt/live/*/privkey.pem

Nginx config test

nginx -t

Apache config test

apachectl configtest \\\

PQC Demo Server Won't Start

Symptoms:

  • \systemctl status pqc-demo\ shows failed
  • Binary not found or permission denied

Solution: \\\bash

Check if binary exists and is executable

ls -l /opt/pqc/bssl_https_server_pqc

Make executable if needed

chmod +x /opt/pqc/bssl_https_server_pqc

Check certificate files exist

ls -l /opt/pqc/certificates/

Check systemd service config

systemctl cat pqc-demo

View detailed errors

journalctl -u pqc-demo -n 50 --no-pager

Test running manually

cd /opt/pqc/certificates /opt/pqc/bssl_https_server_pqc demo.pqcnow.com-bundle.crt demo.pqcnow.com.key 9443 \\\

---

Port and Connectivity Problems

Port 443 Not Accessible from Internet

Symptoms:

  • \curl https://example.com\ works locally but not externally
  • Connection timeout from outside

Solution: \\\bash

1. Check if HAProxy is listening on all interfaces

ss -tlnp | grep :443

Should show: *:443 (not 127.0.0.1:443)

2. Check firewall rules

ufw status iptables -L -n | grep 443

3. Allow port 443 if blocked

ufw allow 443/tcp

OR

iptables -A INPUT -p tcp --dport 443 -j ACCEPT

4. Check cloud provider firewall

Some providers (AWS, GCP, Azure) have additional firewalls

You may need to add rules in the cloud console

\\\

Backend Ports Not Working

Symptoms:

  • \curl http://localhost:8080\ fails
  • HAProxy can't connect to backends

Solution: \\\bash

Check if backend is listening

ss -tlnp | grep -E ':(8080|9443)'

For Nginx on 8080

nginx -t && systemctl restart nginx

For PQC server on 9443

systemctl restart pqc-demo

Test backend directly

curl -k https://localhost:8080 # Traditional SSL curl -k https://localhost:9443 # PQC SSL \\\

---

Certificate Errors

"Certificate Not Valid" in Browser

For Traditional Site (example.com):

Symptoms:

  • Browser shows certificate error
  • Certificate is for wrong domain

Solution: \\\bash

1. Check certificate matches domain

openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -text | grep -A1 "Subject:"

2. Verify certificate chain

openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>&1 | grep "Verify return code"

Should show: "Verify return code: 0 (ok)"

3. Renew Let's Encrypt certificate if expired

certbot renew

4. Restart web server

systemctl restart nginx \\\

For PQC Site (pqc.example.com):

Symptoms:

  • Certificate error in standard browsers (Chrome, Firefox)

This is NORMAL! Standard browsers don't support PQC yet.

Solution:

  • Use Qromium browser to test PQC sites
  • Verify it works in Qromium
  • Standard browser errors are expected

Certificate File Permissions Error

Symptoms:

  • "Permission denied" when reading certificate
  • Service fails with permission errors

Solution: \\\bash

Fix certificate permissions

chmod 644 /opt/pqc/certificates/*.crt chmod 644 /opt/pqc/certificates/*.pem chmod 600 /opt/pqc/certificates/*.key

For Let's Encrypt

chmod 644 /etc/letsencrypt/live/*/fullchain.pem chmod 600 /etc/letsencrypt/live/*/privkey.pem

Fix ownership if needed

chown root:root /opt/pqc/certificates/* \\\

---

HAProxy Issues

HAProxy Not Routing Correctly

Symptoms:

  • All traffic goes to main site
  • PQC site not accessible

Solution: \\\bash

1. Check HAProxy config for SNI matching

grep -A5 "req_ssl_sni" /etc/haproxy/haproxy.cfg

2. Verify domain name matches exactly (case-insensitive with -i)

Config should have:

use_backend pqc_demo if { req_ssl_sni -i pqc.example.com }

3. Test SNI routing

openssl s_client -connect localhost:443 -servername pqc.example.com < /dev/null

4. Check HAProxy logs for routing decisions

journalctl -u haproxy -f

Make a test request and watch logs

5. Restart HAProxy

systemctl restart haproxy \\\

HAProxy Backend Health Check Failing

Symptoms:

  • HAProxy logs show "Server is DOWN"
  • \systemctl status haproxy\ shows backend unreachable

Solution: \\\bash

1. Verify backend is actually running

systemctl status nginx systemctl status pqc-demo

2. Test backend connectivity

curl -k https://localhost:8080 # Main site backend curl -k https://localhost:9443 # PQC backend

3. Check HAProxy config for correct backend ports

grep "server" /etc/haproxy/haproxy.cfg

4. Temporarily disable health checks (for testing)

Edit /etc/haproxy/haproxy.cfg

Comment out: option tcp-check

5. Reload HAProxy

systemctl reload haproxy \\\

---

Web Server Problems

Nginx "Too Many Redirects"

Symptoms:

  • Browser error: "Too many redirects"
  • Infinite redirect loop

Solution: \\\bash

This happens when both HTTP (port 80) and HTTPS (port 8080)

configs have redirect rules

1. Check Nginx configs

nginx -T | grep -A10 "listen 80" nginx -T | grep -A10 "listen 8080"

2. Ensure ONLY port 80 has redirect:

Port 80: return 301 https://...

Port 8080: NO redirect (serve content)

3. Fix config and test

nginx -t

4. Reload

systemctl reload nginx \\\

Apache "AH00558: Could not reliably determine"

Symptoms:

  • Warning about ServerName
  • Apache starts but shows warning

Solution: \\\bash

Add ServerName to Apache config

echo "ServerName example.com" >> /etc/apache2/apache2.conf

OR in your VirtualHost

ServerName example.com

...

Restart Apache

systemctl restart apache2 \\\

---

PQC Server Issues

BoringSSL Server Crashes on Start

Symptoms:

  • PQC server starts then immediately stops
  • "Segmentation fault" in logs

Solution: \\\bash

1. Check if running manually works

cd /opt/pqc/certificates /opt/pqc/bssl_https_server_pqc demo.pqcnow.com-bundle.crt demo.pqcnow.com.key 9443 /var/www/html/demo

2. Verify certificate format

PQC cert should be PEM format

file /opt/pqc/certificates/demo.pqcnow.com.crt

Should show: "PEM certificate"

3. Check certificate and key match

openssl x509 -noout -modulus -in demo.pqcnow.com.crt | openssl md5 openssl rsa -noout -modulus -in demo.pqcnow.com.key | openssl md5

MD5 hashes should match

4. Verify web root exists

ls -ld /var/www/html/demo

Should be a directory

5. Check systemd service paths

systemctl cat pqc-demo \\\

PQC Server Port Already in Use

Symptoms:

  • "Address already in use" on port 9443

Solution: \\\bash

1. Find what's using port 9443

lsof -i :9443

2. Kill the process

kill -9

3. Or use different port

Edit /etc/systemd/system/pqc-demo.service

Change: ExecStart=... 9443

To: ExecStart=... 9444

Update HAProxy backend to match

Edit /etc/haproxy/haproxy.cfg

Change: server pqc 127.0.0.1:9443

To: server pqc 127.0.0.1:9444

4. Reload and restart

systemctl daemon-reload systemctl restart pqc-demo systemctl reload haproxy \\\

---

Browser and Client Issues

"This Site Can't Provide a Secure Connection"

Symptoms:

  • ERR_SSL_PROTOCOL_ERROR
  • Connection resets

Solution: \\\bash

1. Test SSL connection manually

openssl s_client -connect example.com:443 -servername example.com

2. Check if HAProxy is forwarding correctly

Should see SSL handshake, not HAProxy error

3. Verify backend is using SSL on port 8080

curl -k https://localhost:8080

4. Check for SSL protocol mismatch

Nginx config should have:

ssl_protocols TLSv1.2 TLSv1.3;

5. Restart all services in order

systemctl restart nginx systemctl restart pqc-demo systemctl restart haproxy \\\

Qromium Shows "NET::ERR_CERT_AUTHORITY_INVALID"

Symptoms:

  • Qromium browser shows certificate error for PQC site
  • Certificate chain issue

Solution: \\\bash

1. Ensure you're using the BUNDLE certificate

Not: demo.pqcnow.com.crt

Use: demo.pqcnow.com-bundle.crt (includes CA chain)

2. Check systemd service is using bundle

systemctl cat pqc-demo | grep ExecStart

Should show: ...bundle.crt

3. Update if needed

systemctl edit pqc-demo

Change certificate file to bundle version

4. Restart

systemctl daemon-reload systemctl restart pqc-demo \\\

---

Performance Problems

Slow Response Times

Symptoms:

  • Page loads slowly (>2 seconds)
  • Timeouts on some requests

Solution: \\\bash

1. Check server load

top htop

2. Check HAProxy stats

curl http://localhost:8404/stats

3. Increase HAProxy timeouts if needed

Edit /etc/haproxy/haproxy.cfg

timeout connect 10000 # 10 seconds

timeout client 60000 # 60 seconds

timeout server 60000 # 60 seconds

4. Check backend performance

time curl -I https://localhost:8080 time curl -k -I https://localhost:9443

5. Enable caching in Nginx

Add to server block:

location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {

expires 1y;

add_header Cache-Control "public, immutable";

}

\\\

High Memory Usage

Solution: \\\bash

1. Check memory usage

free -h

2. Identify memory hog

ps aux --sort=-%mem | head -20

3. Limit systemd service memory (if needed)

systemctl edit pqc-demo

Add:

[Service]

MemoryLimit=512M

4. Restart service

systemctl daemon-reload systemctl restart pqc-demo \\\

---

Quick Diagnostic Commands

Run these to quickly identify issues:

\\\bash

Check all services

systemctl status haproxy nginx pqc-demo

Check all ports

ss -tlnp | grep -E ':(80|443|8080|9443)'

Test traditional site

curl -IL https://example.com

Test PQC backend

curl -k -I https://localhost:9443

View recent errors

journalctl -p err -n 50 --no-pager

Check disk space (cert renewal fails if disk full)

df -h \\\

---

Getting Help

If you're still experiencing issues:

1. Collect Diagnostic Information: \\\bash

Create diagnostic report

cat > diagnostic-report.txt << EOF === System Info === \$(uname -a) \$(cat /etc/os-release)

=== Service Status === \$(systemctl status haproxy nginx pqc-demo)

=== Listening Ports === \$(ss -tlnp | grep -E ':(80|443|8080|9443)')

=== HAProxy Config === \$(cat /etc/haproxy/haproxy.cfg)

=== Recent Logs === \$(journalctl -u haproxy -n 20 --no-pager) \$(journalctl -u pqc-demo -n 20 --no-pager)

=== Test Results === \$(curl -IL http://example.com 2>&1) \$(curl -k -I https://localhost:9443 2>&1) EOF

cat diagnostic-report.txt \\\

2. Contact Support: - Email: support@pqcnow.com - Include: diagnostic-report.txt - Describe: What you were trying to do when the issue occurred

3. Check Documentation: - Installation Guide - Configuration Reference - Testing Guide - FAQ

---

Related Documentation