SyncEngine TLS/HTTPS Setup Guide

Enable HTTPS for the SyncEngine UI web server using a self-signed certificate or your own CA-issued certificates.

Prerequisites

• SyncEngine UI RPM installed
• Root or sudo access
• The syncengine user/group exists (created by RPM installation)
• Firewall ports open: 8888 (HTTP) and 8443 (HTTPS) (could be 443 and 80 too)

Step 1: Create the SSL Directory

sudo mkdir -p /etc/ssl/syncengine
sudo chown root:syncengine /etc/ssl/syncengine
sudo chmod 750 /etc/ssl/syncengine

Step 2: Generate Self-Signed Certificate

sudo syncengine-cli tls generate --hostname $(hostname -f)

This creates:

• /etc/ssl/syncengine/server.crt -- Certificate file
• /etc/ssl/syncengine/server.key -- Private key file

Optional: Add Additional Hostnames

If users will access the UI via multiple hostnames or IP addresses:

sudo syncengine-cli tls generate \
  --hostname $(hostname -f) \
  --san "localhost,192.168.1.100,syncengine.example.com"

Step 3: Set Certificate Permissions

sudo chown root:syncengine /etc/ssl/syncengine/server.key
sudo chmod 640 /etc/ssl/syncengine/server.key
sudo chmod 644 /etc/ssl/syncengine/server.crt

Step 4: Configure TLS

Edit /etc/default/syncengine-cli to enable TLS:

sudo tee -a /etc/default/syncengine-cli << 'EOF'

# TLS Configuration
SYNCENGINE_CLI_TLS_ENABLED=true
SYNCENGINE_CLI_HTTPS_PORT=8443
EOF

Ensure the HTTP web port is also configured (if not already set):

# Check current configuration
cat /etc/default/syncengine-cli

# Add HTTP port if missing
echo "SYNCENGINE_CLI_WEB_PORT=8888" | sudo tee -a /etc/default/syncengine-cli

Port Configuration

When TLS is enabled, the server listens on two ports:

Both ports serve the same content. There is no automatic redirect from HTTP to HTTPS.

Verify Configuration

Your /etc/default/syncengine-cli should include:

SYNCENGINE_CLI_WEB_PORT=8888
SYNCENGINE_CLI_TLS_ENABLED=true
SYNCENGINE_CLI_HTTPS_PORT=8443

Step 5: Restart the Service

sudo systemctl daemon-reload
sudo systemctl restart syncengine-ui
sudo systemctl status syncengine-ui

You should see output indicating both HTTP and HTTPS are running:

Web UI started successfully!
   HTTP:   http://localhost:8888
   HTTPS:  https://localhost:8443
   Certificate expires in 365 days (2027-02-05)

Step 6: Verify TLS is Working

Check service logs

sudo journalctl -u syncengine-ui -n 50

Test HTTP endpoint

curl http://localhost:8888/api/webuihealth

Test HTTPS endpoint

curl -k https://localhost:8443/api/webuihealth

The -k flag is required for self-signed certificates.

Check TLS status

curl http://localhost:8888/api/tls/status

Expected response:

{
  "tls_enabled": true,
  "https_port": 8443,
  "certificate": {
    "subject": "your-hostname",
    "issuer": "Self-Signed",
    "days_remaining": 365,
    "status": "valid"
  }
}

Access in Browser

• HTTP: http://<hostname>:8888
• HTTPS: https://<hostname>:8443

When accessing via HTTPS with a self-signed certificate, your browser will display a security warning:

• Chrome: Click "Advanced" > "Proceed to <hostname> (unsafe)"
• Firefox: Click "Advanced" > "Accept the Risk and Continue"
• Edge: Click "Continue to <hostname> (unsafe)"

Using Existing CA Certificates

If you have certificates from a Certificate Authority, copy them to the SSL directory:

sudo cp your-certificate.crt /etc/ssl/syncengine/server.crt
sudo cp your-private-key.key /etc/ssl/syncengine/server.key
sudo chmod 644 /etc/ssl/syncengine/server.crt
sudo chmod 640 /etc/ssl/syncengine/server.key
sudo chown root:syncengine /etc/ssl/syncengine/server.key

Then restart the service:

sudo systemctl restart syncengine-ui

Configuration Reference

Troubleshooting

Service won't start

sudo journalctl -u syncengine-ui -n 100 --no-pager

"Certificate file not found"

Verify the certificate files exist:

ls -la /etc/ssl/syncengine/

If missing, regenerate them (Step 2).

"Private key is world-readable"

Fix permissions:

sudo chmod 640 /etc/ssl/syncengine/server.key
sudo chown root:syncengine /etc/ssl/syncengine/server.key

"HTTPS port already in use"

Check what's using port 8443:

sudo ss -tlnp | grep 8443

Either stop the conflicting service or change the HTTPS port:

echo "SYNCENGINE_CLI_HTTPS_PORT=8444" | sudo tee -a /etc/default/syncengine-cli
sudo systemctl restart syncengine-ui

Certificate expired

Check expiration:

syncengine-cli tls info /etc/ssl/syncengine/server.crt

Regenerate if expired:

sudo syncengine-cli tls generate --hostname $(hostname -f)
sudo systemctl restart syncengine-ui