Show pageOld revisionsBacklinksBack to top This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong. ====== ACME (Let's Encrypt) Certificates ====== AstLinux now supports generating [[https://letsencrypt.org|Let's Encrypt]] certificates using the [[wp>Automated_Certificate_Management_Environment|ACME]] protocol. AstLinux uses the ''acme-client'' command as a front-end to the core ''acme.sh'' script provided by the [[https://github.com/acmesh-official/acme.sh|acme.sh]] project. The ''acme-client'' command limits issued certificates to only use DNS challenge validation, as such you need a supported DNS provider, of which there are well over 20 as of this writing. The Command Line Interface (CLI) must be used to initially issue and deploy ACME certificates. !!Note: AstLinux 1.3.0 or later is required!! \\ !!Note:!! From June 2025 on Let's-Encrypt doesn't send expiration/renewal emails anymore automatically. You can use a 3rd party service [[https://redsift.com/pulse-platform/certificates-lite|Red Sift Certificates Lite]] free for up to 250 certs. \\ ===== ACME Configuration ===== The generation of a Let's Encrypt Certificate does not require any special setup, but deployment options can be defined via the web interface: Select the Network Tab in the web interface.\\ {{:userdoc:ipv6-tunnel-network-tab.jpg?nolink|Network Tab}} {{:userdoc:acme-certificates-configure.png?nolink|ACME Configuration}} When the certificates are deployed the "ACME Deploy Service" services will receive the issued/renewed certificates and automatically restarted to make them active. The "ACME Account Email Address" registration email address is used for expiry notifications, while optional it seems like a good idea to specify. !!Note -> AstLinux 1.4.0!! or later, the "ACME Account Email Address" can be used for renewal notifications, more info: **[[userdoc:tt_acme_certificates#additional_cli_commands|Additional CLI Commands]]**. !!Tip ->!! Clicking on the blue ''(i)'' icon will display topic information text similar to this documentation page. !!Tip ->!! The "HTTPS Server" ACME Deploy Service also creates a ''/mnt/kd/ssl/https_stunnel_server.pem'' PEM file containing the ACME private key and full certificate chain, automatically used with the HTTPS Stunnel server and can be configured to be used with the FOP2 server for **[[userdoc:tt_asterisk-fop2-ssl|SSL/HTTPS with FOP2]]**. In order to apply web interface settings changes, use the CLI command: gen-rc-conf \\ ===== Issuing Certificates ===== This example on host ''pbx4'' uses the ''acme-client'' wrapper around the core ''acme.sh'' script, the core version can be obtained by the command: pbx4 ~ # acme-client --version https://github.com/acmesh-official/acme.sh v2.8.7 Only DNS challenge validation is supported within AstLinux, as such you need a supported DNS provider, in this example we are using Cloudflare. We need to export the ''CF_Key'' and ''CF_Email'' variables, adjust to match your credentials ... pbx4 ~ # export CF_Key="sdfdxxxxxxxosdfgje" pbx4 ~ # export CF_Email="email@example.com" Other DNS providers require different exported variables, see the [[https://github.com/acmesh-official/acme.sh/wiki/dnsapi|DNS API]] documentation for the details.\\ !!Tip ->!! Mentally replace ''acme.sh'' with ''acme-client'' when referencing the acme.sh documentation. Now for the fundamental CLI command, where we issue a new certificate for the single domain "pbx4.example.org" ... pbx4 ~ # acme-client --issue --dns dns_cf -d pbx4.example.org [Sat Jul 1 10:08:04 CDT 2017] Registering account [Sat Jul 1 10:08:06 CDT 2017] Registered [Sat Jul 1 10:08:06 CDT 2017] Update success. [Sat Jul 1 10:08:06 CDT 2017] ACCOUNT_THUMBPRINT='...' [Sat Jul 1 10:08:06 CDT 2017] Creating domain key [Sat Jul 1 10:08:07 CDT 2017] The domain key is here: /mnt/kd/acme/pbx4.example.org/pbx4.example.org.key [Sat Jul 1 10:08:07 CDT 2017] Single domain='pbx4.example.org' [Sat Jul 1 10:08:07 CDT 2017] Getting domain auth token for each domain [Sat Jul 1 10:08:07 CDT 2017] Getting webroot for domain='pbx4.example.org' [Sat Jul 1 10:08:07 CDT 2017] Getting new-authz for domain='pbx4.example.org' [Sat Jul 1 10:08:07 CDT 2017] The new-authz request is ok. [Sat Jul 1 10:08:08 CDT 2017] Found domain api file: /stat/etc/acme/dnsapi/dns_cf.sh [Sat Jul 1 10:08:09 CDT 2017] Adding record [Sat Jul 1 10:08:09 CDT 2017] Added, OK [Sat Jul 1 10:08:09 CDT 2017] Sleep 120 seconds for the txt records to take effect [Sat Jul 1 10:10:11 CDT 2017] Verifying:pbx4.example.org [Sat Jul 1 10:10:14 CDT 2017] Success [Sat Jul 1 10:10:16 CDT 2017] Verify finished, start to sign. [Sat Jul 1 10:10:16 CDT 2017] Cert success. -----BEGIN CERTIFICATE----- ... snip ... -----END CERTIFICATE----- [Sat Jul 1 10:10:16 CDT 2017] Your cert is in /mnt/kd/acme/pbx4.example.org/pbx4.example.org.cer [Sat Jul 1 10:10:16 CDT 2017] Your cert key is in /mnt/kd/acme/pbx4.example.org/pbx4.example.org.key [Sat Jul 1 10:10:17 CDT 2017] The intermediate CA cert is in /mnt/kd/acme/pbx4.example.org/ca.cer [Sat Jul 1 10:10:17 CDT 2017] And the full chain certs is there: /mnt/kd/acme/pbx4.example.org/fullchain.cer After the certificates are issued, they need to be deployed to the various services that can utilize them. In this example only "HTTPS Server" is checked after "ACME Deploy Service:" in the web interface. pbx4 ~ # acme-client --deploy --deploy-hook astlinux -d pbx4.example.org Stopping lighttpd... Starting lighttpd... acme-client: New ACME certificates deployed for HTTPS and 'lighttpd' restarted [Sat Jul 1 10:14:10 CDT 2017] Success While not required, it is a good idea to ''unset'' the exported variables above that contain the DNS challenge validation credentials. pbx4 ~ # unset CF_Key pbx4 ~ # unset CF_Email !!Note ->!! The DNS challenge validation credentials remain stored in the ''/mnt/kd/acme/account.conf'' file so auto-renewals can be performed via ''cron''. !!Special Note ->!! Depending on the acme.sh DNS provider script, some scripts store the exported credentials variable names exactly in ''/mnt/kd/acme/account.conf'' and others prepend ''SAVED_'' to the variable names. When the credentials variable names are stored exactly any later changes to the credentials must be done by editing ''/mnt/kd/acme/account.conf''. When the credentials variable names have ''SAVED_'' prepended you may use ''export ...'' later to change the saved credentials. \\ ===== Auto-Renewing Certificates ===== Let's Encrypt certificates are only valid for 90 days, renewable after 60 days from the issue date. As such it is important to automate the process of renewing the certificate, this can be done by installing a ''cron'' entry using the command: pbx4 ~ # acme-client --install-cronjob acme-client: Successfully added cron entry. \\ ===== Multiple Domain Certificates ===== In the example above only one domain ''pbx4.example.org'' was specified. Let's Encrypt allows multiple domains to be specified with valid "Subject Alternative Name" entries in a single certificate. This assumes the DNS ''A'' and/or ''AAAA'' and/or ''SRV'' record of each domain points to the server with the issued certificate. As an additional example let's say both ''example.org'' and subdomain ''pbx4.example.org'' are valid DNS entries you want to include in the "Subject Alternative Name" of the issued certificate. Proceed as above, but simply include ''-d example.org'' when issuing the certificate, (specify the more general domain first) ... pbx4 ~ # acme-client --issue --dns dns_cf -d example.org -d pbx4.example.org Likewise, when deploying the certificate, though you only need to specify the first ''-d example.org'' domain ... pbx4 ~ # acme-client --deploy --deploy-hook astlinux -d example.org \\ ===== Additional CLI Commands ===== Some additional commands that may be useful to know ... List the issued certificate(s): pbx4 ~ # acme-client --list Revoke an issued certificate by domain: pbx4 ~ # acme-client --revoke -d pbx4.example.org Remove a certificate by domain: pbx4 ~ # acme-client --remove -d pbx4.example.org Enable renewal notifications via email, (AstLinux 1.4.0 or later) pbx4 ~ # acme-client --set-notify --notify-hook mail --notify-level 2 !!Tip ->!! As above, with ''--notify-level 1'' only email errors and ''--notify-level 0'' disables email notifications \\ ===== Advanced Options ===== For advanced users there may be situations where it would be useful to add special options for every occurrence of the ''acme-client'' command. Increasing the log-level and defining a log file would be one such example. The ''/mnt/kd/acme/account.opts'' file does not exist by default, and needs to be manually created to enable this feature. Example ''/mnt/kd/acme/account.opts'' file with persistent options added by ''acme-client'' to the ''acme.sh'' script: ## acme.sh options log-level 3 log /var/log/acme-client.log !!Tip ->!! Most users will not need to create a ''/mnt/kd/acme/account.opts'' file. \\ userdoc/tt_acme_certificates.txt Last modified: 2025/02/05 05:16by mkeuter