Troubleshooting Guide

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

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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# Add ServerName to Apache config
echo "ServerName example.com" >> /etc/apache2/apache2.conf

# OR in your VirtualHost
# <VirtualHost *:8080>
#     ServerName example.com
#     ...
# </VirtualHost>

# 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:

# 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:

# 1. Find what's using port 9443
lsof -i :9443

# 2. Kill the process
kill -9 <PID>

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

---

Troubleshooting Guide

Table of Contents

Service Issues

HAProxy Won't Start

Nginx/Apache Won't Start

PQC Demo Server Won't Start

Port and Connectivity Problems

Port 443 Not Accessible from Internet

Backend Ports Not Working

Certificate Errors

"Certificate Not Valid" in Browser

Certificate File Permissions Error

HAProxy Issues

HAProxy Not Routing Correctly

HAProxy Backend Health Check Failing

Web Server Problems

Nginx "Too Many Redirects"

Apache "AH00558: Could not reliably determine"

PQC Server Issues

BoringSSL Server Crashes on Start

PQC Server Port Already in Use

Browser and Client Issues

"This Site Can't Provide a Secure Connection"

Qromium Shows "NET::ERR_CERT_AUTHORITY_INVALID"

Performance Problems

Slow Response Times

High Memory Usage

Quick Diagnostic Commands

Getting Help

Related Documentation