Configure the web application servers supported for quick deployment - Certificate Management Service

If you use a deployment task to deploy a certificate to an Elastic Compute Service (ECS) instance for the first time, you must complete the configurations of the web application server to which you want to deploy the certificate, such as an NGINX server.

Important

Before you begin, make sure that you have known the deployment limits and prerequisites described in Deploy a certificate to an Alibaba Cloud ECS instance and completed the steps required before modifying the NGINX configuration file.

Supported web application servers and their versions

Only NGINX servers are supported.

For Alibaba Cloud Linux 3.x images, the NGINX version must be 1.18.0-2.1.al8 and later and earlier than 1.20.1-1.0.5.al8. If NGINX is installed on the ECS instance, you must check whether the NGINX version is supported before you perform quick deployment. If the existing NGINX version is not supported, you must roll back NGINX to an earlier version or reinstall NGINX.
For Ubuntu 22.04 UEFI images, NGINX must be installed by using apt.

Important

Alibaba Cloud Linux 3.x and Ubuntu 22.04 images do not support NGINX servers that are built by yourself. Only NGINX servers installed by using a package manager such as YUM or apt are supported.

Alibaba Cloud Linux 3.x images

Note

In this example, NGINX 1.20.1 is used. If you install NGINX by using YUM, NGINX is installed in the /etc/nginx/ directory by default. If you have changed this directory, replace /etc/nginx/ with the actual installation directory.

Supported web application servers and their versions:
NGINX: 1.18.0-2.1.al8 and later and earlier than 1.20.1-1.0.5.al8.
Important
If NGINX is installed on the ECS instance, you must check whether the NGINX version is supported before you perform quick deployment. If the existing NGINX version is not supported, you must roll back NGINX to an earlier version or reinstall NGINX.

Open the /etc/nginx/nginx.conf configuration file, find pid /run/nginx.pid;, and then add ssl_engine pkcs11; below this line to specify the SSL/TLS encryption library to be used.

The following content is added:
```
ssl_engine pkcs11;
```

The following code shows the location of the added content in the complete sample code.

# For more information on configuration, see:
#   * Official English Documentation: http://nginx.org/en/docs/
#   * Official Russian Documentation: http://nginx.org/ru/docs/

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

# Specify that the PKCS #11 library is used.
ssl_engine pkcs11;

Open the /etc/nginx/nginx.conf configuration file, uncomment Settings for a TLS enabled server, and then add include "/etc/acm/ssl/nginx-acm.conf"; to reference the SLL key configuration.

The following content is added:
```
include "/etc/acm/ssl/nginx-acm.conf";
```

The following code shows the location of the added content in the complete sample code.

server {
        listen       443 ssl http2;
        listen       [::]:443 ssl http2;
       
        # Specify the server name or common name (CN).
        server_name  example.com;
        root         /usr/share/nginx/html;

        ssl_session_cache shared:SSL:1m;
        ssl_session_timeout  10m;
        ssl_prefer_server_ciphers on;
       
        # Reference the SSL key configuration.
        include "/etc/acm/ssl/nginx-acm.conf";
       
        # Load configuration files for the default server block.
        include /etc/nginx/default.d/*.conf;

        error_page 404 /404.html;
            location = /40x.html {
        }

        error_page 500 502 503 504 /50x.html;
            location = /50x.html {
        }
    }

Open the /usr/lib/systemd/system/nginx.service file and add P11_KIT_SERVER_ADDRESS=unix:path=/etc/acm/ssl/acm-p11-kit.sock and OPENSSL_CONF=/etc/acm/ssl/openssl-acm.cnf to configure the communication with the SSL key service.

The following content is added:

Environment="P11_KIT_SERVER_ADDRESS=unix:path=/etc/acm/ssl/acm-p11-kit.sock"
Environment="OPENSSL_CONF=/etc/acm/ssl/openssl-acm.cnf"

The following code shows the location of the added content in the complete sample code.

[Unit]
Description=A high performance web server and a reverse proxy server
Documentation=man:nginx(8)
After=network.target nss-lookup.target

[Service]
Type=forking
PIDFile=/run/nginx.pid
ExecStartPre=/usr/sbin/nginx -t -q -g 'daemon on; master_process on;'
ExecStart=/usr/sbin/nginx -g 'daemon on; master_process on;'
ExecReload=/usr/sbin/nginx -g 'daemon on; master_process on;' -s reload
ExecStop=-/sbin/start-stop-daemon --quiet --stop --retry QUIT/5 --pidfile /run/nginx.pid
TimeoutStopSec=5
KillMode=mixed

# Configure the communication with the SSL key service.
Environment="P11_KIT_SERVER_ADDRESS=unix:path=/etc/acm/ssl/acm-p11-kit.sock"
Environment="OPENSSL_CONF=/etc/acm/ssl/openssl-acm.cnf"

[Install]
WantedBy=multi-user.target

Note

To query the path of the NGINX systemd configuration file, run the sudo find / -name "nginx.service" command.

Run the following command to reload the NGINX systemd service configuration:
```
systemctl daemon-reload
```

Ubuntu 22.04 images

Note

In this example, NGINX 1.18.0 is used. If you install NGINX by using apt, NGINX is installed in the /etc/nginx directory by default. If you have changed this directory or installed NGINX by using other methods, replace /etc/nginx/ with the actual installation directory.

Open the /etc/nginx/nginx.conf configuration file, find pid /run/nginx.pid;, and then add ssl_engine pkcs11; below this line to specify the SSL/TLS encryption library to be used.
1. The following content is added:
```
ssl_engine pkcs11;
```
2. The following code shows the location of the added content in the complete sample code.
```
user www-data;
worker_processes auto;
pid /run/nginx.pid;

# Specify that the PKCS #11 library is used.
ssl_engine pkcs11;

include /etc/nginx/modules-enabled/*.conf;
```

Open the /etc/nginx/sites-enabled/default file, create a server block in the default file, and add include "/etc/acm/ssl/nginx-acm.conf";.

The following content is added:
```
include "/etc/acm/ssl/nginx-acm.conf";
```

The following code shows the location of the added content in the complete sample code.

server {
    listen 443 ssl;
    
    # Specify the server name or CN.
    server_name example.com;
    root /var/www/html;
    index index.html index.htm;
    access_log /var/log/nginx/access_6equj5.log;
    error_log /var/log/nginx/error_6equj5.log;
    ssl on;
    
    # Reference the SSL key configuration.
    include "/etc/acm/ssl/nginx-acm.conf";

    location / {
      try_files $uri $uri/ =404;
    }
}

Note

To query the path of the NGINX systemd configuration file, run the sudo find / -name "nginx.service" command.

The following content is added:

Environment="P11_KIT_SERVER_ADDRESS=unix:path=/etc/acm/ssl/acm-p11-kit.sock"
Environment="OPENSSL_CONF=/etc/acm/ssl/openssl-acm.cnf"

The following code shows the location of the added content in the complete sample code.

[Unit]
Description=A high performance web server and a reverse proxy server
Documentation=man:nginx(8)
After=network.target nss-lookup.target

[Service]
Type=forking
PIDFile=/run/nginx.pid
ExecStartPre=/usr/sbin/nginx -t -q -g 'daemon on; master_process on;'
ExecStart=/usr/sbin/nginx -g 'daemon on; master_process on;'
ExecReload=/usr/sbin/nginx -g 'daemon on; master_process on;' -s reload
ExecStop=-/sbin/start-stop-daemon --quiet --stop --retry QUIT/5 --pidfile /run/nginx.pid
TimeoutStopSec=5
KillMode=mixed

# Configure the communication with the SSL key service.
Environment="P11_KIT_SERVER_ADDRESS=unix:path=/etc/acm/ssl/acm-p11-kit.sock"
Environment="OPENSSL_CONF=/etc/acm/ssl/openssl-acm.cnf"

[Install]
WantedBy=multi-user.target

Run the following command to reload the NGINX systemd service configuration:
```
systemctl daemon-reload
```

References

Deploy a certificate to an Alibaba Cloud ECS instance