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

Usage notes

Before you begin, make sure that you meet the following requirements:

Step 1: Download the SSL certificate

1. Go to the SSL Certificate Management page. In the Actions column of the target certificate, click Download Certificate. Then, on the Download tab, download the certificate for the Server Type JKS.

   Note

   Java Keystore (JKS) is a proprietary keystore format for Java environments.

2. The extracted files include a certificate file (with a .jks extension containing the complete certificate chain) and a password file (jks-password.txt).

Step 2: Configure the system and network environment

Ensure your security group and system firewall allow inbound traffic on the HTTPS port (443).

1. Run the following command in the server terminal to check whether port 443 is open:

   RHEL/CentOS

   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

   If the output is Ncat: Connected to <your_server_public_ip>:443, port 443 is open. Otherwise, open port 443 in the security group and firewall.

   Debian/Ubuntu

   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

   If the output is Connection to <your_server_public_ip> port [tcp/https] succeeded! or [<your_server_public_ip>] 443 (https) open, port 443 is open. Otherwise, open port 443 in the security group and firewall.

2. Open port 443 in your security group configuration.

   Important

   If your server is deployed on a cloud platform, make sure that its security group allows inbound traffic on TCP port 443. Otherwise, the service will be inaccessible. The following steps use Alibaba Cloud ECS as an example. For other cloud platforms, refer to their official documentation.

   Go to the Elastic Compute Service (ECS) instances page and click the target instance name to go to the instance details page. For more information, see Add a security group rule to add a rule in the Security Group section with Authorization Policy set to Allow, Protocol Type to TCP, Destination Port Range to HTTPS (443), and Authorization Object to Anywhere (0.0.0.0/0).

3. Open port 443 in your firewall.

   Run the following command to identify the active firewall service on your system:

   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 further action is required. Otherwise, run the corresponding command below based on the output (firewalld, ufw, nftables, or iptables) to open port 443:

   firewalld

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

   ufw

   sudo ufw allow 443/tcp

   nftables

   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

   iptables

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

   To make sure that the iptables rules persist after a system reboot, run the following commands:

   RHEL/CentOS

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

   Debian/Ubuntu

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

Step 3: Install the SSL certificate on the Jetty server

1. Create and go to the Jetty's base directory ($JETTY_BASE) and create a cert directory within it to store your certificate files.

   Important

   Separating the Jetty installation directory ($JETTY_HOME) from the base directory ($JETTY_BASE) simplifies future upgrades and maintenance.

   # Example: Assume Jetty is installed in /usr/local/jetty, and the application and configuration are in /var/www/my-app.
   export JETTY_HOME=/usr/local/jetty
   export JETTY_BASE=/var/www/my-app
   
   # Create the necessary directory structure for certificate files, website code resources, and so on.
   mkdir -p $JETTY_BASE/cert
   mkdir -p $JETTY_BASE/webapps
   
   # Perform the following operations in the $JETTY_BASE directory.
   cd $JETTY_BASE

2. Upload your certificate files to the cert directory you just created.

   Note

   Use the file upload feature of your remote access tool, such as PuTTY, Xshell, or WinSCP. If using an Alibaba Cloud ECS, see Upload or download files.

3. Enable Jetty's ssl module and specify the certificate information.

   1. In the $JETTY_BASE directory, run the following command to initialize the ssl module.

      # This command generates the ssl.ini and https.ini configuration files in the $JETTY_BASE/start.d/ directory.
      java -jar $JETTY_HOME/start.jar --add-to-start=ssl

   2. Edit the $JETTY_BASE/start.d/ssl.ini file to specify the certificate path and password.

      # Run the following command to enter edit mode and prepare to configure certificate information.
      vim $JETTY_BASE/start.d/ssl.ini

   3. Find and modify the following parameters, ensuring they are not commented out with #. For JKS certificates downloaded from Alibaba Cloud, use the same password for keyStorePassword and keyManagerPassword.

      # ---------------------------------------
      # SSL Context Factory KeyStore Configuration
      # ---------------------------------------
      # jetty.ssl.keystore.path is deprecated. Use jetty.ssl.keyStorePath instead.
      jetty.ssl.keyStorePath=cert/your_domain.jks
      
      # jetty.ssl.keystore.password is deprecated. Use jetty.ssl.keyStorePassword instead.
      jetty.ssl.keyStorePassword=[password from the jks-password.txt file]
      
      # jetty.ssl.keymanager.password is deprecated. Use jetty.ssl.keyManagerPassword instead.
      jetty.ssl.keyManagerPassword=[password from the jks-password.txt file]

Step 4: Restart the Jetty service

In the $JETTY_BASE directory, start the Jetty server.

# Change to the Jetty working directory.
cd $JETTY_BASE

# Restart the service.
sudo java -jar $JETTY_HOME/start.jar

Step 5: Verify the installation

Why is my certificate not working or HTTPS inaccessible after installation or update?

This issue is often caused by one of the following configuration problems. Check them in order:

• Port 443 blocked: The server's security group or firewall does not have port 443 open. See Configure the system and network environment.

• Domain mismatch: The domain you are accessing is not listed in the certificate's Bound Domains. See Domain name matching.

• Jetty not restarted: You did not restart the Jetty service after modifying its configuration files. See Restart the Jetty service.

• Incorrect certificate configuration: The certificate files were not replaced correctly, or the Jetty configuration does not point to the correct certificate path. Verify that the configuration and certificate files are the latest and valid.

• Missing certificate on other services: If your domain uses services such as a Content Delivery Network (CDN), Server Load Balancer (SLB), or Web Application Firewall (WAF), the certificate must also be installed on those services. See Certificate deployment locations when traffic passes through multiple Alibaba Cloud services to complete the setup.

• Incomplete deployment on multiple servers: If your domain's DNS resolves to multiple servers, the certificate must be installed on all of them.

How do I update or replace an SSL certificate in Jetty?

1. Back up old files: Back up the existing certificate files (.jks and .txt) on your server.

2. Get new files: Download the new certificate and private key files from your Certificate Management Service console.

3. Replace files: Upload the new files to your server, overwriting the old ones. Ensure the new files have the exact same path and filename as the ones specified in your Jetty configuration.

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

Why do I get an "Address already in use" or "Port is already occupied" error on startup?

This error indicates that port 443 is already being used by another process. Use the sudo ss -tlnp | grep :443 or sudo lsof -i:443 command to find the process occupying the port and stop it. Common culprits include Nginx, Apache, or a test command that was not shut down correctly.

Why do I get a "Permission denied" error on startup?

On Linux systems, binding to ports below 1024 requires root permissions. Use sudo to start Jetty. In a production environment, avoid running services directly as the root user. A more secure practice is to grant the Java executable permission to bind to low-numbered ports by using setcap (such as sudo setcap 'cap_net_bind_service=+ep' /path/to/your/java) or to place Jetty behind a reverse proxy such as Nginx.