|
| 1 | +--- |
| 2 | +description: Automates SSL/TLS certificate lifecycle management by enabling direct communication between clients and certificate authorities. |
| 3 | +title: ACME |
| 4 | +toc: true |
| 5 | +weight: 100 |
| 6 | +type: |
| 7 | +- how-to |
| 8 | +--- |
| 9 | + |
| 10 | +The ACME protocol automates SSL/TLS certificate lifecycle management by enabling direct communication between clients and certificate authorities for issuance, installation, revocation, and replacement of SSL certificates. |
| 11 | + |
| 12 | +The `nginx-plus-module-acme` module is an [NGINX-authored]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md#nginx-authored-dynamic-modules" >}}) dynamic module that implements the automatic certificate management ([ACMEv2](https://www.rfc-editor.org/rfc/rfc8555.html)) protocol. |
| 13 | + |
| 14 | +The source code for the module is available in the official [GitHub repository](https://github.com/nginx/nginx-acme). The official documentation, including module reference and usage examples, is available on the [nginx.org](https://nginx.org/en/docs/http/ngx_http_acme_module.html) website. |
| 15 | + |
| 16 | + |
| 17 | +## Installation |
| 18 | + |
| 19 | +The installation process closely follows the [NGINX Plus installation procedure]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}). The module is available as the prebuilt `nginx-plus-module-acme` package for various Linux distributions and can be installed directly from the official NGINX Plus repository. Prior to installation, you need to add the NGINX Plus package repository for your distribution and update the repository metadata. |
| 20 | + |
| 21 | +1. Check the [Technical Specifications]({{< ref "/nginx/technical-specs.md" >}}) page to verify that the module is supported by your operating system. |
| 22 | + |
| 23 | +2. Make sure you have the latest version of NGINX Plus. In Terminal, run the command: |
| 24 | + |
| 25 | + ```shell |
| 26 | + nginx -v |
| 27 | + ``` |
| 28 | + |
| 29 | + Expected output of the command: |
| 30 | + |
| 31 | + ```shell |
| 32 | + nginx version: nginx/1.29.0 (nginx-plus-r35) |
| 33 | + ``` |
| 34 | + |
| 35 | +3. Ensure you have the **nginx-repo.crt** and **nginx-repo.key** files from [MyF5 Customer Portal](https://account.f5.com/myf5) in the **/etc/ssl/nginx/** directory. These files are required for accessing the NGINX Plus repository. |
| 36 | + |
| 37 | + ```shell |
| 38 | + sudo cp <downloaded-file-name>.crt /etc/ssl/nginx/nginx-repo.crt && \ |
| 39 | + sudo cp <downloaded-file-name>.key /etc/ssl/nginx/nginx-repo.key |
| 40 | + ``` |
| 41 | + |
| 42 | + For Alpine, the **nginx-repo.crt** to **/etc/apk/cert.pem** and **nginx-repo.key** files should be added to **/etc/apk/cert.key**. Ensure these files contain only the specific key and certificate as Alpine Linux does not support mixing client certificates for multiple repositories. |
| 43 | + |
| 44 | + For FreeBSD, the path to these files should also be added to the `/usr/local/etc/pkg.conf` file: |
| 45 | + |
| 46 | + ```shell |
| 47 | + PKG_ENV: { SSL_NO_VERIFY_PEER: "1", |
| 48 | + SSL_CLIENT_CERT_FILE: "/etc/ssl/nginx/nginx-repo.crt", |
| 49 | + SSL_CLIENT_KEY_FILE: "/etc/ssl/nginx/nginx-repo.key" } |
| 50 | + ``` |
| 51 | +
|
| 52 | +4. Ensure that all required dependencies for your operating system are installed. |
| 53 | +
|
| 54 | + For Amazon Linux 2023, AlmaLinux, CentOS, Oracle Linux, RHEL, and Rocky Linux: |
| 55 | +
|
| 56 | + ```shell |
| 57 | + sudo dnf update && \ |
| 58 | + sudo dnf install ca-certificates |
| 59 | + ``` |
| 60 | +
|
| 61 | + For Debian: |
| 62 | +
|
| 63 | + ```shell |
| 64 | + sudo apt update && \ |
| 65 | + sudo apt install apt-transport-https \ |
| 66 | + lsb-release \ |
| 67 | + ca-certificates \ |
| 68 | + wget \ |
| 69 | + gnupg2 \ |
| 70 | + debian-archive-keyring |
| 71 | + ``` |
| 72 | +
|
| 73 | + For Ubuntu: |
| 74 | +
|
| 75 | + ```shell |
| 76 | + sudo apt update && \ |
| 77 | + sudo apt install apt-transport-https \ |
| 78 | + lsb-release \ |
| 79 | + ca-certificates \ |
| 80 | + wget \ |
| 81 | + gnupg2 \ |
| 82 | + ubuntu-keyring |
| 83 | + ``` |
| 84 | +
|
| 85 | + For FreeBSD: |
| 86 | +
|
| 87 | + ```shell |
| 88 | + sudo pkg update && \ |
| 89 | + sudo pkg install ca_root_nss |
| 90 | + ``` |
| 91 | +
|
| 92 | +5. Ensure that the NGINX signing key has been added, if required by your operating system. |
| 93 | +
|
| 94 | + For Debian: |
| 95 | +
|
| 96 | + ```shell |
| 97 | + wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \ |
| 98 | + | gpg --dearmor \ |
| 99 | + | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null |
| 100 | + ``` |
| 101 | +
|
| 102 | + For Ubuntu: |
| 103 | +
|
| 104 | + ```shell |
| 105 | + printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ |
| 106 | + https://pkgs.nginx.com/plus/ubuntu `lsb_release -cs` nginx-plus\n" \ |
| 107 | + | sudo tee /etc/apt/sources.list.d/nginx-plus.list |
| 108 | + ``` |
| 109 | +
|
| 110 | + For Alpine: |
| 111 | +
|
| 112 | + ```shell |
| 113 | + sudo wget -O /etc/apk/keys/nginx_signing.rsa.pub https://cs.nginx.com/static/keys/nginx_signing.rsa.pub |
| 114 | + ``` |
| 115 | +
|
| 116 | +6. Ensure that your package management system is configured to pull packages from the NGINX Plus repository. See [Installing NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}) for details. |
| 117 | +
|
| 118 | +7. Update the repository information and install the `nginx-plus-module-acme` package. In a terminal, run the appropriate command for your operating system. |
| 119 | +
|
| 120 | + For CentOS, Oracle Linux, and RHEL: |
| 121 | +
|
| 122 | + ```shell |
| 123 | + sudo yum update && \ |
| 124 | + sudo yum install nginx-plus-module-acme |
| 125 | + ``` |
| 126 | +
|
| 127 | + For Amazon Linux 2023, AlmaLinux, Rocky Linux: |
| 128 | +
|
| 129 | + ```shell |
| 130 | + sudo dnf update && \ |
| 131 | + sudo dnf install nginx-plus-module-acme |
| 132 | + ``` |
| 133 | +
|
| 134 | + For Debian and Ubuntu: |
| 135 | +
|
| 136 | + ```shell |
| 137 | + sudo apt update && \ |
| 138 | + sudo apt install nginx-plus-module-acme |
| 139 | + ``` |
| 140 | +
|
| 141 | + For Alpine: |
| 142 | +
|
| 143 | + ```shell |
| 144 | + sudo apk update && \ |
| 145 | + sudo apk add nginx-plus-module-acme |
| 146 | + ``` |
| 147 | +
|
| 148 | + For FreeBSD: |
| 149 | +
|
| 150 | + ```shell |
| 151 | + sudo pkg update && \ |
| 152 | + sudo pkg install nginx-plus-module-acme |
| 153 | + ``` |
| 154 | +
|
| 155 | + The resulting `ngx_http_acme_module.so` dynamic module will be written to the following directory, depending on your operating system: |
| 156 | +
|
| 157 | + - `/usr/lib64/nginx/modules/` for most Linux distributions |
| 158 | + - `/usr/lib/nginx/modules` for Debian, Ubuntu, Alpine |
| 159 | + - `/usr/local/etc/nginx/modules` for FreeBSD |
| 160 | +
|
| 161 | +8. Enable dynamic loading of the module. |
| 162 | +
|
| 163 | + - In a text editor, open the NGINX Plus configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). |
| 164 | +
|
| 165 | + - On the top-level (or “`main`”) context, specify the path to the dynamic module with the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive: |
| 166 | +
|
| 167 | + ```nginx |
| 168 | + load_module modules/ngx_http_acme_module.so; |
| 169 | +
|
| 170 | + http { |
| 171 | + #... |
| 172 | + } |
| 173 | + ``` |
| 174 | + - Save the configuration file. |
| 175 | +
|
| 176 | +9. Test the NGINX Plus configuration. In a terminal, type-in the command: |
| 177 | +
|
| 178 | + ```shell |
| 179 | + nginx -t |
| 180 | + ``` |
| 181 | +
|
| 182 | + Expected output of the command: |
| 183 | +
|
| 184 | + ```shell |
| 185 | + nginx: the configuration file /etc/nginx/nginx.conf syntax is ok |
| 186 | + nginx: configuration file /etc/nginx/nginx.conf is successful |
| 187 | + ``` |
| 188 | +
|
| 189 | +10. Reload the NGINX Plus configuration to enable the module: |
| 190 | +
|
| 191 | + ```shell |
| 192 | + nginx -s reload |
| 193 | + ``` |
| 194 | +
|
| 195 | +## Configuration |
| 196 | +
|
| 197 | +In a text editor, open the NGINX Plus configuration file: |
| 198 | + - `/etc/nginx/nginx.conf` for Linux |
| 199 | + - `/usr/local/etc/nginx/nginx.conf` for FreeBSD |
| 200 | +
|
| 201 | +For a complete list of directives, embedded variables, default span attributes, refer to the `ngx_http_acme_module` official documentation. |
| 202 | +
|
| 203 | +List of directives: |
| 204 | +
|
| 205 | +[`https://nginx.org/en/docs/http/ngx_http_acme_module.html#directives`](https://nginx.org/en/docs/ngx_otel_module.html#directives) |
| 206 | +
|
| 207 | +List of variables: |
| 208 | +
|
| 209 | +[`https://nginx.org/en/docs/http/ngx_http_acme_module.html#variables`](https://nginx.org/en/docs/ngx_otel_module.html#variables) |
| 210 | +
|
| 211 | +
|
| 212 | +## Usage example |
| 213 | +
|
| 214 | +```shell |
| 215 | +resolver 127.0.0.1:53; |
| 216 | +
|
| 217 | +acme_issuer example { |
| 218 | + uri https://acme.example.com/directory; |
| 219 | + |
| 220 | + state_path /var/cache/nginx/acme-example; |
| 221 | + accept_terms_of_service; |
| 222 | +} |
| 223 | +
|
| 224 | +acme_shared_zone zone=ngx_acme_shared:1M; |
| 225 | +
|
| 226 | +server { |
| 227 | + listen 443 ssl; |
| 228 | + server_name .example.test; |
| 229 | +
|
| 230 | + acme_certificate example; |
| 231 | +
|
| 232 | + ssl_certificate $acme_certificate; |
| 233 | + ssl_certificate_key $acme_certificate_key; |
| 234 | +
|
| 235 | + # do not parse the certificate on each request |
| 236 | + ssl_certificate_cache max=2; |
| 237 | +} |
| 238 | +
|
| 239 | +server { |
| 240 | + # listener on port 80 is required to process ACME HTTP-01 challenges |
| 241 | + listen 80; |
| 242 | +
|
| 243 | + location / { |
| 244 | + return 404; |
| 245 | + } |
| 246 | +} |
| 247 | +``` |
| 248 | +
|
| 249 | +## More info |
| 250 | +
|
| 251 | +- [Native support for ACME blog post](https://blog.nginx.org/blog/native-support-for-acme-protocol) |
| 252 | +
|
| 253 | +- [NGINX ACME module GitHub project](https://github.com/nginx/nginx-acme) |
| 254 | +
|
| 255 | +- [Official documentation for the NGINX ACME module](https://nginx.org/en/docs/http/ngx_http_acme_module.html) |
| 256 | +
|
| 257 | +- [NGINX Plus technical specifications]({{< ref "/nginx/technical-specs.md" >}}) |
| 258 | +
|
| 259 | +- [NGINX dynamic modules]({{< ref "dynamic-modules.md" >}}) |
| 260 | +
|
| 261 | +- [Uninstalling a dynamic module]({{< ref "uninstall.md" >}}) |
0 commit comments