{"id":30416602,"url":"https://github.com/nginx/nginx-acme","last_synced_at":"2025-09-03T11:02:09.098Z","repository":{"id":310524536,"uuid":"1017668897","full_name":"nginx/nginx-acme","owner":"nginx","description":"An NGINX module with the implementation of the automatic certificate management (ACMEv2) protocol","archived":false,"fork":false,"pushed_at":"2025-08-18T16:49:31.000Z","size":132,"stargazers_count":218,"open_issues_count":18,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-18T18:08:40.722Z","etag":null,"topics":["acme","acme-client","nginx"],"latest_commit_sha":null,"homepage":"https://nginx.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nginx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-10T22:59:50.000Z","updated_at":"2025-08-18T17:10:08.000Z","dependencies_parsed_at":"2025-08-18T18:08:49.900Z","dependency_job_id":null,"html_url":"https://github.com/nginx/nginx-acme","commit_stats":null,"previous_names":["nginx/nginx-acme"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nginx/nginx-acme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Fnginx-acme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Fnginx-acme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Fnginx-acme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Fnginx-acme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nginx","download_url":"https://codeload.github.com/nginx/nginx-acme/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx%2Fnginx-acme/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271588743,"owners_count":24785751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acme","acme-client","nginx"],"created_at":"2025-08-22T05:02:09.834Z","updated_at":"2025-09-03T11:02:09.073Z","avatar_url":"https://github.com/nginx.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n[![Community Support](https://badgen.net/badge/support/community/cyan?icon=awesome)](/SUPPORT.md)\n[![Community Forum](https://img.shields.io/badge/community-forum-009639?logo=discourse\u0026link=https%3A%2F%2Fcommunity.nginx.org)](https://community.nginx.org)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/license/apache-2-0)\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](/CODE_OF_CONDUCT.md)\n\n# nginx-acme\n\nnginx-acme is an [NGINX] module with the implementation of the automatic\ncertificate management (ACMEv2) protocol.\n\nThe module implements following specifications:\n\n * [RFC8555] (Automatic Certificate Management Environment) with limitations:\n     * Only HTTP-01 challenge type is supported\n\n[NGINX]: https://nginx.org/\n[RFC8555]: https://www.rfc-editor.org/rfc/rfc8555.html\n\n## Getting Started\n\n### Requirements\n\n- Regular NGINX build dependencies: C compiler, make, PCRE2, Zlib\n- System-wide installation of OpenSSL 1.1.1 or later\n- Rust toolchain (1.81.0 or later)\n- [libclang] for rust-bindgen\n\n[libclang]: https://rust-lang.github.io/rust-bindgen/requirements.html\n\n### Building\n\nOne way to build the module is to export a path to a configured NGINX source\ntree and run `cargo`.\n\n```sh\n# checkout, configure and build NGINX at ../nginx\ncd nginx-acme\nexport NGINX_BUILD_DIR=$(realpath ../nginx/objs)\ncargo build --release\n```\n\nThe result will be located at `target/release/libnginx_acme.so`.\n\nAnother way is to use the provided config script:\n\n```sh\n# in the NGINX source directory\nauto/configure \\\n    --with-compat \\\n    --with-http_ssl_module \\\n    --add-[dynamic-]module=/path/to/nginx-acme\n```\n\nThe result will be located at `objs/ngx_http_acme_module.so`.\n\nCurrently this method produces a slightly larger library, as we don't instruct\nthe linker to perform LTO and remove unused code.\n\n#### Build options\n\nAs there is no mechanism to add third-party module configuration options to\nauto/configure, all the module build-time options are set via environment\nvariables passed to the `cargo build` or `make` commands.\nCurrently accepted options are:\n\n - `NGX_ACME_STATE_PREFIX`: sets a default prefix for per-issuer state paths.\n   If unset, state paths are created relative to the NGINX prefix directory.\n   The prefix directory should exist and be readable to the worker processes.\n\nExample:\n\n```sh\nexport NGX_ACME_STATE_PREFIX=/var/cache/nginx\nauto/configure \\\n    ... \\\n    --with-compat \\\n    --with-http_ssl_module \\\n    --add-dynamic-module=/path/to/nginx-acme\nmake\n```\n\n### Testing\n\nThe repository contains an integration test suite based on the [nginx-tests].\nThe following command will build the module and run the tests:\n\n```sh\n# Path to the nginx source checkout, defaults to ../nginx if not specified.\nexport NGINX_SOURCE_DIR=$(realpath ../nginx)\n# Path to the nginx-tests checkout; defaults to ../nginx/tests if not specified.\nexport NGINX_TESTS_DIR=$(realpath ../nginx-tests)\n\nmake test\n```\n\nMost of the tests require [pebble] test server binary in the path, or in a\nlocation specified via `TEST_NGINX_PEBBLE_BINARY` environment variable.\n\n[nginx-tests]: https://github.com/nginx/nginx-tests\n[pebble]: https://github.com/letsencrypt/pebble\n\n## How to Use\n\nAdd the module to the NGINX configuration and configure as described below.\nNote that this module requires a [resolver] configuration in the `http` block.\n\n[resolver]: https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver\n\n## Example Configuration\n\n```nginx\nresolver 127.0.0.1:53;\n\nacme_issuer example {\n    uri         https://acme.example.com/directory;\n    # contact     admin@example.test;\n    state_path  /var/cache/nginx/acme-example;\n    accept_terms_of_service;\n}\n\nacme_shared_zone zone=ngx_acme_shared:1M;\n\nserver {\n    listen 443 ssl;\n    server_name  .example.test;\n\n    acme_certificate example;\n\n    ssl_certificate       $acme_certificate;\n    ssl_certificate_key   $acme_certificate_key;\n\n    # do not parse the certificate on each request\n    ssl_certificate_cache max=2;\n}\n\nserver {\n    # listener on port 80 is required to process ACME HTTP-01 challenges\n    listen 80;\n\n    location / {\n        return 404;\n    }\n}\n```\n\n## Directives\n\n### acme_issuer\n\n**Syntax:** acme_issuer `name` { ... }\n\n**Default:** -\n\n**Context:** http\n\nDefines an ACME certificate issuer object.\n\n### uri\n\n**Syntax:** uri `uri`\n\n**Default:** -\n\n**Context:** acme_issuer\n\nThe [directory URL](https://www.rfc-editor.org/rfc/rfc8555#section-7.1.1)\nof the ACME server. This is the only mandatory directive in the\n[acme_issuer](#acme_issuer) block.\n\n### account_key\n\n**Syntax:** account_key `alg[:size]` | `file`\n\n**Default:** -\n\n**Context:** acme_issuer\n\nThe account's private key used for request authentication.\n\nAccepted values:\n\n- `ecdsa:256/384/521` for `ES256`, `ES384` or `ES512` JSON Web Signature\n  algorithms\n- `rsa:2048/3072/4096` for `RS256`.\n- File path for an existing key, using one of the algorithms above.\n\nThe generated account keys are preserved across reloads, but will be lost on\nrestart unless [state_path](#state_path) is configured.\n\n### contact\n\n**Syntax:** contact `url`\n\n**Default:** -\n\n**Context:** acme_issuer\n\nSets an array of URLs that the ACME server can use to contact the client\nregarding account issues.\nThe `mailto:` scheme will be assumed unless specified\nexplicitly.\n\n### external_account_key\n\n**Syntax:** external_account_key `kid` `file`\n\n**Default:** -\n\n**Context:** acme_issuer\n\nA key identifier and a file with the MAC key for external account authorization\n([RFC8555 § 7.3.4](https://www.rfc-editor.org/rfc/rfc8555.html#section-7.3.4)).\n\nThe value `data:key` can be specified instead of the `file` to load the key\ndirectly from the configuration without using intermediate files.\n\nIn both cases, the key is expected to be encoded as base64url.\n\n### ssl_trusted_certificate\n\n**Syntax:** ssl_trusted_certificate `file`\n\n**Default:** system CA bundle\n\n**Context:** acme_issuer\n\nSpecifies a `file` with trusted CA certificates in the PEM format\nused to [verify](#ssl_verify)\nthe certificate of the ACME server.\n\n### ssl_verify\n\n**Syntax:** ssl_verify `on` | `off`\n\n**Default:** on\n\n**Context:** acme_issuer\n\nEnables or disables verification of the ACME server certificate.\n\n### state_path\n\n**Syntax:** state_path `path` | `off`\n\n**Default:** acme_`name` or `$NGX_ACME_STATE_PREFIX`/acme_`name`\n\n**Context:** acme_issuer\n\nDefines a directory for storing the module data that can be persisted across\nrestarts. This can significantly improve the time until the server is ready\nand help with rate-limiting ACME servers.\n\nThe directory contains sensitive content, such as the account key, issued\ncertificates, and private keys.\n\n### accept_terms_of_service\n\n**Syntax:** accept_terms_of_service\n\n**Default:** -\n\n**Context:** acme_issuer\n\nAgrees to the terms of service under which the ACME server will be used.\nSome servers require accepting the terms of service before account registration.\nThe terms are usually available on the ACME server's website and the URL will\nbe printed to the error log if necessary.\n\n### acme_shared_zone\n\n**Syntax:** acme_shared_zone `zone` = `name:size`\n\n**Default:** ngx_acme_shared:256k\n\n**Context:** http\n\nAllows increasing the size of in-memory storage of the module.\nThe shared memory zone will be used to store the issued certificates, keys and\nchallenge data for all the configured certificate issuers.\n\nThe default zone size is sufficient to hold ~50 ECDSA prime256v1 keys or\n~35 RSA 2048 keys.\n\n### acme_certificate\n\n**Syntax:** acme_certificate `issuer` [`identifier` ...] [ `key` = `alg[:size]` ]\n\n**Default:** -\n\n**Context:** server\n\nDefines a certificate with the list of `identifier`s requested from\nissuer `issuer`.\n\nThe explicit list of identifiers can be omitted. In this case, the identifiers\nwill be taken from the [server_name] directive in the same `server` block.\nNot all values accepted in the [server_name] are valid certificate identifiers:\nregular expressions and wildcards are not supported.\n\n[server_name]: https://nginx.org/en/docs/http/ngx_http_core_module.html#server_name\n\nThe `key` parameter sets the type of a generated private key.\nSupported key algorithms and sizes:\n`ecdsa:256` (default), `ecdsa:384`, `ecdsa:521`,\n`rsa:2048`, `rsa:3072`, `rsa:4096`.\n\n## Embedded Variables\n\nThe `ngx_http_acme_module` module defines following embedded\nvariables, valid in the `server` block with the\n[acme_certificate](#acme_certificate) directive:\n\n### `$acme_certificate`\n\nSSL certificate that can be passed to the\n[ssl_certificate](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate).\n\n### `$acme_certificate_key`\n\nSSL certificate private key that can be passed to the\n[ssl_certificate_key](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key).\n\n## Contributing\n\nPlease see the [contributing guide](/CONTRIBUTING.md) for guidelines on how to best contribute to this project.\n\n## License\n\n[Apache License, Version 2.0](/LICENSE)\n\n\u0026copy; [F5, Inc.](https://www.f5.com/) 2025\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnginx%2Fnginx-acme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnginx%2Fnginx-acme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnginx%2Fnginx-acme/lists"}