Certificate Management Service:Install an SSL certificate on a Jetty server (Linux)

Open port 443 in the security group

If your server runs on Alibaba Cloud Elastic Compute Service (ECS), add an inbound rule to the security group:

1. Go to the Elastic Compute Service (ECS) instances page and click the target instance name.

2. In the Security Group Details section, add a rule with the following settings, then save. For detailed instructions, see Add a security group rule.

   Field	Value
   Action	Allow
   Protocol	Custom TCP
   Destination (Current Instance)	HTTPS (443)
   Source	0.0.0.0/0 (anywhere)

For other cloud platforms, refer to their documentation.

Check whether port 443 is already open

Run the following command to verify that port 443 is reachable. Replace <your_server_public_ip> with your server's public IP address.

command -v nc > /dev/null 2>&1 || sudo yum install -y nc
# Replace <your_server_public_ip> with the public IP address of your server.
sudo ss -tlnp | grep -q ':443 ' || sudo nc -l 443 & sleep 1; nc -w 3 -vz <your_server_public_ip> 443

command -v nc > /dev/null 2>&1 || sudo apt-get install -y netcat
# Replace <your_server_public_ip> with the public IP address of your server.
sudo ss -tlnp | grep -q ':443 ' || sudo nc -l -p 443 & sleep 1; nc -w 3 -vz <your_server_public_ip> 443

Open port 443 in the firewall

First, identify the active firewall service:

if command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet firewalld; then
    echo "firewalld"
elif command -v ufw >/dev/null 2>&1 && sudo ufw status | grep -qw active; then
    echo "ufw"
elif command -v nft >/dev/null 2>&1 && sudo nft list ruleset 2>/dev/null | grep -q 'table'; then
    echo "nftables"
elif command -v systemctl >/dev/null 2>&1 && systemctl is-active --quiet iptables; then
    echo "iptables"
elif command -v iptables >/dev/null 2>&1 && sudo iptables -L 2>/dev/null | grep -qE 'REJECT|DROP|ACCEPT'; then
    echo "iptables"
else
    echo "none"
fi

If the output is none, no firewall is active and no further action is needed. Otherwise, run the command for your firewall:

sudo firewall-cmd --permanent --add-port=443/tcp && sudo firewall-cmd --reload

sudo ufw allow 443/tcp

sudo nft add table inet filter 2>/dev/null
sudo nft add chain inet filter input '{ type filter hook input priority 0; }' 2>/dev/null
sudo nft add rule inet filter input tcp dport 443 counter accept 2>/dev/null

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

sudo yum install -y iptables-services
sudo service iptables save

sudo apt-get install -y iptables-persistent
sudo iptables-save | sudo tee /etc/iptables/rules.v4 >/dev/null

Set up the directory structure

Jetty separates the installation directory ($JETTY_HOME) from the working directory ($JETTY_BASE). Keep them separate to simplify future upgrades.

# Example: Jetty is installed in /usr/local/jetty; the application runs from /var/www/my-app.
export JETTY_HOME=/usr/local/jetty
export JETTY_BASE=/var/www/my-app

# Create directories for certificate files and web application resources.
mkdir -p $JETTY_BASE/cert
mkdir -p $JETTY_BASE/webapps

cd $JETTY_BASE

Upload the certificate files

Upload the .jks file and jks-password.txt to the $JETTY_BASE/cert/ directory using a file transfer tool such as PuTTY, Xshell, or WinSCP. If your server is on Alibaba Cloud ECS, see Upload or download files.

Enable the SSL module

In the $JETTY_BASE directory, run the following command to initialize the ssl module. This generates ssl.ini and https.ini in $JETTY_BASE/start.d/.

java -jar $JETTY_HOME/start.jar --add-to-start=ssl

Configure the certificate path and password

Open $JETTY_BASE/start.d/ssl.ini for editing:

vim $JETTY_BASE/start.d/ssl.ini

Find and update the following parameters. Make sure none of them are commented out with #.

jetty.ssl.keyStorePath=cert/your_domain.jks
jetty.ssl.keyStorePassword=<password from jks-password.txt>
jetty.ssl.keyManagerPassword=<password from jks-password.txt>

The older parameter names jetty.ssl.keystore.path, jetty.ssl.keystore.password, and jetty.ssl.keymanager.password are deprecated. Use the camelCase names shown above.

HTTPS is not working after installation

Check the following in order:

• Port 443 is blocked: The security group or firewall is not allowing inbound traffic on port 443. See Open port 443.

• Domain mismatch: The domain you're accessing is not listed in the certificate's Bound Domains. See the Prerequisites section for wildcard and exact-match coverage rules.

• Jetty not restarted: Configuration changes take effect only after a restart. See Restart Jetty.

• Wrong certificate path or password: Verify that jetty.ssl.keyStorePath points to the correct .jks file and that the password in ssl.ini matches jks-password.txt.

• Certificate missing from upstream services: If your domain uses a Content Delivery Network (CDN), Server Load Balancer (SLB), or Web Application Firewall (WAF), install the certificate on those services as well. See Certificate deployment locations when traffic passes through multiple Alibaba Cloud services.

• Multiple servers: If DNS resolves to more than one server, install the certificate on all of them.

For further troubleshooting, see Resolve certificate deployment issues based on browser error messages and SSL certificate deployment troubleshooting guide.

How do I replace an SSL certificate in Jetty?

1. Back up old files: Save the existing .jks and jks-password.txt files from your server.

2. Get new files: Download the new certificate from the Certificate Management Service console.

3. Replace files: Upload the new files to the same path specified in ssl.ini, overwriting the old ones.

4. Restart Jetty: Restart the service to apply the new certificate.

Startup fails: "Address already in use" or "Port is already occupied"

Port 443 is already bound by another process. Run sudo ss -tlnp | grep :443 or sudo lsof -i:443 to identify the process and stop it. Common causes include Nginx, Apache, or a test listener that was not shut down.

Startup fails: "Permission denied"

On Linux, binding to ports below 1024 requires root permissions. Start Jetty with sudo. In production, avoid running services directly as root — use setcap to grant the Java binary the ability to bind to privileged ports:

sudo setcap 'cap_net_bind_service=+ep' /path/to/your/java

Alternatively, place Jetty behind a reverse proxy such as Nginx that listens on port 443 and forwards traffic to a non-privileged port.