## File: README.md # Lego [ACME](https://www.rfc-editor.org/rfc/rfc8555.html) client and library for Let's Encrypt and other ACME CAs written in Go. [](https://pkg.go.dev/github.com/go-acme/lego/v5) [](https://github.com//go-acme/lego/actions) [](https://hub.docker.com/r/goacme/lego/) lego is an independent, free, and open-source project, if you value it, consider [supporting it](https://donate.ldez.dev)! ❤️ Everybody thinks that the others will donate, but in the end, nobody does. So if you think that lego is worth it, please consider [donating](https://donate.ldez.dev). ## Features - ACME v2 [RFC 8555](https://www.rfc-editor.org/rfc/rfc8555.html) - Support [RFC 8737](https://www.rfc-editor.org/rfc/rfc8737.html): TLS Application‑Layer Protocol Negotiation (ALPN) Challenge Extension - Support [RFC 8738](https://www.rfc-editor.org/rfc/rfc8738.html): certificates for IP addresses - Support [RFC 9773](https://www.rfc-editor.org/rfc/rfc9773.html): Renewal Information (ARI) Extension - Support [draft-ietf-acme-profiles-00](https://datatracker.ietf.org/doc/draft-ietf-acme-profiles/): Profiles Extension - Support [draft-ietf-acme-dns-persist-01](https://datatracker.ietf.org/doc/draft-ietf-acme-dns-persist/): Challenge for Persistent DNS TXT Record Validation - Comes with more than [200 DNS providers](https://go-acme.github.io/lego/dns) - Register with CA - Obtain certificates, both from scratch or with an existing CSR - Renew certificates - Revoke certificates - Robust implementation of ACME challenges: - HTTP (http-01) - DNS (dns-01) - TLS (tls-alpn-01) - SAN certificate support - [CNAME support](https://letsencrypt.org/2019/10/09/onboarding-your-customers-with-lets-encrypt-and-acme.html) by default - [Custom challenge solvers](https://go-acme.github.io/lego/usage/library/writing-a-challenge-solver/) - Certificate bundling - OCSP helper function ## Installation How to [install](https://go-acme.github.io/lego/install/). ## Usage - as a [CLI](https://go-acme.github.io/lego/obtain) - as a [library](https://go-acme.github.io/lego/library) ## Documentation Documentation is hosted live at https://go-acme.github.io/lego/. ## DNS providers Detailed documentation is available [here](https://go-acme.github.io/lego/dns). If your DNS provider is not supported, please open an [issue](https://github.com/go-acme/lego/issues/new?assignees=&labels=enhancement%2C+new-provider&template=new_dns_provider.yml). | [1cloud.ru](https://go-acme.github.io/lego/dns/onecloudru/) | [35.com/三五互联](https://go-acme.github.io/lego/dns/com35/) | [51DNS](https://go-acme.github.io/lego/dns/dns51/) | [Abion](https://go-acme.github.io/lego/dns/abion/) | | --- | --- | --- | --- | | [Active24](https://go-acme.github.io/lego/dns/active24/) | [Akamai EdgeDNS](https://go-acme.github.io/lego/dns/edgedns/) | [Alibaba Cloud DNS](https://go-acme.github.io/lego/dns/alidns/) | [AlibabaCloud ESA](https://go-acme.github.io/lego/dns/aliesa/) | | [all-inkl](https://go-acme.github.io/lego/dns/allinkl/) | [Alwaysdata](https://go-acme.github.io/lego/dns/alwaysdata/) | [Amazon Lightsail](https://go-acme.github.io/lego/dns/lightsail/) | [Amazon Route 53](https://go-acme.github.io/lego/dns/route53/) | | [Anexia CloudDNS](https://go-acme.github.io/lego/dns/anexia/) | [ANS SafeDNS](https://go-acme.github.io/lego/dns/safedns/) | [ArtFiles](https://go-acme.github.io/lego/dns/artfiles/) | [ArvanCloud](https://go-acme.github.io/lego/dns/arvancloud/) | | [Aurora DNS](https://go-acme.github.io/lego/dns/auroradns/) | [Autodns](https://go-acme.github.io/lego/dns/autodns/) | [Axelname](https://go-acme.github.io/lego/dns/axelname/) | [Azion](https://go-acme.github.io/lego/dns/azion/) | | [Azure DNS](https://go-acme.github.io/lego/dns/azuredns/) | [Baidu Cloud](https://go-acme.github.io/lego/dns/baiducloud/) | [Beget.com](https://go-acme.github.io/lego/dns/beget/) | [Binary Lane](https://go-acme.github.io/lego/dns/binarylane/) | | [Bindman](https://go-acme.github.io/lego/dns/bindman/) | [Bluecat](https://go-acme.github.io/lego/dns/bluecat/) | [Bluecat v2](https://go-acme.github.io/lego/dns/bluecatv2/) | [BookMyName](https://go-acme.github.io/lego/dns/bookmyname/) | | [Bunny](https://go-acme.github.io/lego/dns/bunny/) | [Checkdomain](https://go-acme.github.io/lego/dns/checkdomain/) | [Civo](https://go-acme.github.io/lego/dns/civo/) | [Cloud.ru](https://go-acme.github.io/lego/dns/cloudru/) | | [CloudDNS](https://go-acme.github.io/lego/dns/clouddns/) | [Cloudflare](https://go-acme.github.io/lego/dns/cloudflare/) | [ClouDNS](https://go-acme.github.io/lego/dns/cloudns/) | [Connbyte](https://go-acme.github.io/lego/dns/connbyte/) | | [ConoHa v2](https://go-acme.github.io/lego/dns/conoha/) | [ConoHa v3](https://go-acme.github.io/lego/dns/conohav3/) | [Constellix](https://go-acme.github.io/lego/dns/constellix/) | [Core-Networks](https://go-acme.github.io/lego/dns/corenetworks/) | | [CPanel/WHM](https://go-acme.github.io/lego/dns/cpanel/) | [Curanet](https://go-acme.github.io/lego/dns/curanet/) | [Czechia](https://go-acme.github.io/lego/dns/czechia/) | [DanDomain](https://go-acme.github.io/lego/dns/dandomain/) | | [DDnss (DynDNS Service)](https://go-acme.github.io/lego/dns/ddnss/) | [Derak Cloud](https://go-acme.github.io/lego/dns/derak/) | [deSEC.io](https://go-acme.github.io/lego/dns/desec/) | [Designate DNSaaS for Openstack](https://go-acme.github.io/lego/dns/designate/) | | [Digital Ocean](https://go-acme.github.io/lego/dns/digitalocean/) | [Dinahosting](https://go-acme.github.io/lego/dns/dinahosting/) | [DirectAdmin](https://go-acme.github.io/lego/dns/directadmin/) | [DNS Made Easy](https://go-acme.github.io/lego/dns/dnsmadeeasy/) | | [DNS Update (RFC2136)](https://go-acme.github.io/lego/dns/dnsupdate/) | [dns.la](https://go-acme.github.io/lego/dns/dnsla/) | [DNS.services](https://go-acme.github.io/lego/dns/dnsservices/) | [DNScale](https://go-acme.github.io/lego/dns/dnscale/) | | [DNSExit](https://go-acme.github.io/lego/dns/dnsexit/) | [dnsHome.de](https://go-acme.github.io/lego/dns/dnshomede/) | [DNSimple](https://go-acme.github.io/lego/dns/dnsimple/) | [Domain Offensive (do.de)](https://go-acme.github.io/lego/dns/dode/) | | [Domeneshop](https://go-acme.github.io/lego/dns/domeneshop/) | [DreamHost](https://go-acme.github.io/lego/dns/dreamhost/) | [Duck DNS](https://go-acme.github.io/lego/dns/duckdns/) | [Dyn](https://go-acme.github.io/lego/dns/dyn/) | | [Dynadot](https://go-acme.github.io/lego/dns/dynadot/) | [DynDnsFree.de](https://go-acme.github.io/lego/dns/dyndnsfree/) | [Dynu](https://go-acme.github.io/lego/dns/dynu/) | [EasyDNS](https://go-acme.github.io/lego/dns/easydns/) | | [EdgeCenter](https://go-acme.github.io/lego/dns/edgecenter/) | [Efficient IP](https://go-acme.github.io/lego/dns/efficientip/) | [Epik](https://go-acme.github.io/lego/dns/epik/) | [EuroDNS](https://go-acme.github.io/lego/dns/eurodns/) | | [EUserv](https://go-acme.github.io/lego/dns/euserv/) | [Excedo](https://go-acme.github.io/lego/dns/excedo/) | [Exoscale](https://go-acme.github.io/lego/dns/exoscale/) | [External program](https://go-acme.github.io/lego/dns/exec/) | | [F5 XC](https://go-acme.github.io/lego/dns/f5xc/) | [Fornex](https://go-acme.github.io/lego/dns/fornex/) | [freemyip.com](https://go-acme.github.io/lego/dns/freemyip/) | [FusionLayer NameSurfer](https://go-acme.github.io/lego/dns/namesurfer/) | | [G-Core](https://go-acme.github.io/lego/dns/gcore/) | [Gandi](https://go-acme.github.io/lego/dns/gandi/) | [Gandi Live DNS (v5)](https://go-acme.github.io/lego/dns/gandiv5/) | [Gehirn](https://go-acme.github.io/lego/dns/gehirn/) | | [Gigahost.no](https://go-acme.github.io/lego/dns/gigahostno/) | [Glesys](https://go-acme.github.io/lego/dns/glesys/) | [Gname](https://go-acme.github.io/lego/dns/gname/) | [Go Daddy](https://go-acme.github.io/lego/dns/godaddy/) | | [Google Cloud](https://go-acme.github.io/lego/dns/gcloud/) | [Gravity](https://go-acme.github.io/lego/dns/gravity/) | [Hetzner](https://go-acme.github.io/lego/dns/hetzner/) | [Hosting.de](https://go-acme.github.io/lego/dns/hostingde/) | | [Hosting.nl](https://go-acme.github.io/lego/dns/hostingnl/) | [Hostinger](https://go-acme.github.io/lego/dns/hostinger/) | [Hosttech](https://go-acme.github.io/lego/dns/hosttech/) | [HostUp](https://go-acme.github.io/lego/dns/hostup/) | | [HTTP request](https://go-acme.github.io/lego/dns/httpreq/) | [http.net](https://go-acme.github.io/lego/dns/httpnet/) | [Huawei Cloud](https://go-acme.github.io/lego/dns/huaweicloud/) | [Hurricane Electric DNS](https://go-acme.github.io/lego/dns/hurricane/) | | [HyperOne](https://go-acme.github.io/lego/dns/hyperone/) | [IBM Cloud (SoftLayer)](https://go-acme.github.io/lego/dns/ibmcloud/) | [IIJ DNS Platform Service](https://go-acme.github.io/lego/dns/iijdpf/) | [Infoblox](https://go-acme.github.io/lego/dns/infoblox/) | | [Infomaniak](https://go-acme.github.io/lego/dns/infomaniak/) | [Internet.bs](https://go-acme.github.io/lego/dns/internetbs/) | [INWX](https://go-acme.github.io/lego/dns/inwx/) | [Ionos](https://go-acme.github.io/lego/dns/ionos/) | | [Ionos Cloud](https://go-acme.github.io/lego/dns/ionoscloud/) | [IPv64](https://go-acme.github.io/lego/dns/ipv64/) | [ISPConfig 3](https://go-acme.github.io/lego/dns/ispconfig/) | [ISPConfig 3 - Dynamic DNS (DDNS) Module](https://go-acme.github.io/lego/dns/ispconfigddns/) | | [JD Cloud](https://go-acme.github.io/lego/dns/jdcloud/) | [Joker](https://go-acme.github.io/lego/dns/joker/) | [Joohoi's ACME-DNS](https://go-acme.github.io/lego/dns/acmedns/) | [Katapult](https://go-acme.github.io/lego/dns/katapult/) | | [KeyHelp](https://go-acme.github.io/lego/dns/keyhelp/) | [Leaseweb](https://go-acme.github.io/lego/dns/leaseweb/) | [Liara](https://go-acme.github.io/lego/dns/liara/) | [Lima-City](https://go-acme.github.io/lego/dns/limacity/) | | [Linode (v4)](https://go-acme.github.io/lego/dns/linode/) | [Liquid Web](https://go-acme.github.io/lego/dns/liquidweb/) | [Loopia](https://go-acme.github.io/lego/dns/loopia/) | [LuaDNS](https://go-acme.github.io/lego/dns/luadns/) | | [Mail-in-a-Box](https://go-acme.github.io/lego/dns/mailinabox/) | [ManageEngine CloudDNS](https://go-acme.github.io/lego/dns/manageengine/) | [Manual](https://go-acme.github.io/lego/dns/manual/) | [Metaname](https://go-acme.github.io/lego/dns/metaname/) | | [Metaregistrar](https://go-acme.github.io/lego/dns/metaregistrar/) | [mijn.host](https://go-acme.github.io/lego/dns/mijnhost/) | [Mittwald](https://go-acme.github.io/lego/dns/mittwald/) | [myaddr.{tools,dev,io}](https://go-acme.github.io/lego/dns/myaddr/) | | [MyDNS.jp](https://go-acme.github.io/lego/dns/mydnsjp/) | [MythicBeasts](https://go-acme.github.io/lego/dns/mythicbeasts/) | [Name.com](https://go-acme.github.io/lego/dns/namedotcom/) | [Namecheap](https://go-acme.github.io/lego/dns/namecheap/) | | [Namesilo](https://go-acme.github.io/lego/dns/namesilo/) | [NearlyFreeSpeech.NET](https://go-acme.github.io/lego/dns/nearlyfreespeech/) | [NederHost](https://go-acme.github.io/lego/dns/nederhost/) | [Neodigit](https://go-acme.github.io/lego/dns/neodigit/) | | [Netcup](https://go-acme.github.io/lego/dns/netcup/) | [Netlify](https://go-acme.github.io/lego/dns/netlify/) | [Netnod](https://go-acme.github.io/lego/dns/netnod/) | [NexDNS](https://go-acme.github.io/lego/dns/nexdns/) | | [Ngenix](https://go-acme.github.io/lego/dns/ngenix/) | [Nicmanager](https://go-acme.github.io/lego/dns/nicmanager/) | [NIFCloud](https://go-acme.github.io/lego/dns/nifcloud/) | [Njalla](https://go-acme.github.io/lego/dns/njalla/) | | [Nodion](https://go-acme.github.io/lego/dns/nodion/) | [NS1](https://go-acme.github.io/lego/dns/ns1/) | [Octenium](https://go-acme.github.io/lego/dns/octenium/) | [omg.lol](https://go-acme.github.io/lego/dns/omglol/) | | [Online.net](https://go-acme.github.io/lego/dns/onlinenet/) | [Open Telekom Cloud](https://go-acme.github.io/lego/dns/otc/) | [Openprovider](https://go-acme.github.io/lego/dns/openprovider/) | [OpusDNS](https://go-acme.github.io/lego/dns/opusdns/) | | [Oracle Cloud](https://go-acme.github.io/lego/dns/oraclecloud/) | [OVH](https://go-acme.github.io/lego/dns/ovh/) | [plesk.com](https://go-acme.github.io/lego/dns/plesk/) | [PointDNS/PointHQ](https://go-acme.github.io/lego/dns/pointdns/) | | [Porkbun](https://go-acme.github.io/lego/dns/porkbun/) | [Poweradmin](https://go-acme.github.io/lego/dns/poweradmin/) | [PowerDNS](https://go-acme.github.io/lego/dns/pdns/) | [Rackspace](https://go-acme.github.io/lego/dns/rackspace/) | | [Rage4](https://go-acme.github.io/lego/dns/rage4/) | [Rain Yun/雨云](https://go-acme.github.io/lego/dns/rainyun/) | [RcodeZero](https://go-acme.github.io/lego/dns/rcodezero/) | [reg.ru](https://go-acme.github.io/lego/dns/regru/) | | [Regfish](https://go-acme.github.io/lego/dns/regfish/) | [RimuHosting](https://go-acme.github.io/lego/dns/rimuhosting/) | [RU CENTER](https://go-acme.github.io/lego/dns/nicru/) | [Sakura Cloud](https://go-acme.github.io/lego/dns/sakuracloud/) | | [Scaleway](https://go-acme.github.io/lego/dns/scaleway/) | [ScanNet](https://go-acme.github.io/lego/dns/scannet/) | [Selectel](https://go-acme.github.io/lego/dns/selectel/) | [Selectel v2](https://go-acme.github.io/lego/dns/selectelv2/) | | [SelfHost.(de eu)](https://go-acme.github.io/lego/dns/selfhostde/) | [Servercow](https://go-acme.github.io/lego/dns/servercow/) | [Shellrent](https://go-acme.github.io/lego/dns/shellrent/) | [Simply.com](https://go-acme.github.io/lego/dns/simply/) | | [Sonic](https://go-acme.github.io/lego/dns/sonic/) | [Spaceship](https://go-acme.github.io/lego/dns/spaceship/) | [Stackpath (Deprecated)](https://go-acme.github.io/lego/dns/stackpath/) | [Syse](https://go-acme.github.io/lego/dns/syse/) | | [Technitium](https://go-acme.github.io/lego/dns/technitium/) | [Tele3](https://go-acme.github.io/lego/dns/tele3/) | [Tencent Cloud DNS](https://go-acme.github.io/lego/dns/tencentcloud/) | [Tencent EdgeOne](https://go-acme.github.io/lego/dns/edgeone/) | | [Timeweb Cloud](https://go-acme.github.io/lego/dns/timewebcloud/) | [TodayNIC/时代互联](https://go-acme.github.io/lego/dns/todaynic/) | [TransIP](https://go-acme.github.io/lego/dns/transip/) | [UCloud](https://go-acme.github.io/lego/dns/ucloud/) | | [Ultradns](https://go-acme.github.io/lego/dns/ultradns/) | [United-Domains](https://go-acme.github.io/lego/dns/uniteddomains/) | [Variomedia](https://go-acme.github.io/lego/dns/variomedia/) | [Veesp](https://go-acme.github.io/lego/dns/veesp/) | | [VegaDNS](https://go-acme.github.io/lego/dns/vegadns/) | [Vercel](https://go-acme.github.io/lego/dns/vercel/) | [Versio.[nl eu uk]](https://go-acme.github.io/lego/dns/versio/) | [VinylDNS](https://go-acme.github.io/lego/dns/vinyldns/) | | [Virtualname](https://go-acme.github.io/lego/dns/virtualname/) | [VK Cloud](https://go-acme.github.io/lego/dns/vkcloud/) | [Volcano Engine/火山引擎](https://go-acme.github.io/lego/dns/volcengine/) | [Vscale](https://go-acme.github.io/lego/dns/vscale/) | | [Vultr](https://go-acme.github.io/lego/dns/vultr/) | [Wannafind](https://go-acme.github.io/lego/dns/wannafind/) | [webnames.ca](https://go-acme.github.io/lego/dns/webnamesca/) | [webnames.ru](https://go-acme.github.io/lego/dns/webnamesru/) | | [Websupport](https://go-acme.github.io/lego/dns/websupport/) | [WEDOS](https://go-acme.github.io/lego/dns/wedos/) | [West.cn/西部数码](https://go-acme.github.io/lego/dns/westcn/) | [Xinnet](https://go-acme.github.io/lego/dns/xinnet/) | | [Yandex 360](https://go-acme.github.io/lego/dns/yandex360/) | [Yandex Cloud](https://go-acme.github.io/lego/dns/yandexcloud/) | [Yandex PDD](https://go-acme.github.io/lego/dns/yandex/) | [Zilore](https://go-acme.github.io/lego/dns/zilore/) | | [Zone.ee](https://go-acme.github.io/lego/dns/zoneee/) | [ZoneEdit](https://go-acme.github.io/lego/dns/zoneedit/) | [Zonomi](https://go-acme.github.io/lego/dns/zonomi/) | | If your DNS provider is not supported, please open an [issue](https://github.com/go-acme/lego/issues/new?assignees=&labels=enhancement%2C+new-provider&template=new_dns_provider.yml). --- ## File: docs/archetypes/default.md --- title: "{{ replace .Name "-" " " | title }}" date: {{ .Date }} draft: true --- --- ## File: docs/content/advanced/_index.md --- title: "Advanced usages" date: 2019-03-03T16:39:46+01:00 draft: false weight: 4 params: menuPre: ' ' --- {{% children type="card" description="true" %}} --- ## File: docs/content/advanced/accounts.md --- title: "Account Operations" date: 2019-03-03T16:39:46+01:00 draft: false weight: 2 --- This section describes account operations. ## List Accounts You can list all the accounts registered in your local storage: ```bash lego accounts list ``` Output: ``` Found the following accounts: noemail@example.com ├── Email: ├── Server: https://acme-v02.api.letsencrypt.org/directory ├── Key Type: EC256 └── Path: /path/to/.lego/accounts/acme-v02.api.letsencrypt.org/noemail@example.com/account.json ... ``` ## Register You can register a new account by using the following command: {{< tabs >}} {{% tab title="Simple Registration" %}} ```bash lego accounts register --account-id='myaccount' ``` {{% /tab %}} {{% tab title="With External Account Binding" %}} ```bash lego accounts register --account-id='myaccount' \ --server https://example.com/ca \ --eab \ --eab.kid xxx \ --eab.hmac yyy ``` {{% /tab %}} {{< /tabs >}} To know the available options, run: ```bash lego accounts register --help ``` Or read the [documentation]({{% ref "references/ref-flags/#lego-accounts-register" %}}). ## Key Rollover You can change the account private key (a key rollover) by using the following command: ```bash lego accounts keyrollover --account-id='myaccount' ``` To know the available options, run: ```bash lego accounts keyrollover --help ``` Or read the [documentation]({{% ref "references/ref-flags/#lego-accounts-keyrollover" %}}). ## Account Recovery You can recover/import an account, to do that, you need the private key of the account. ```bash lego accounts recover --account-id='myaccount' --private-key /path/to/private-key.pem ``` The account will be imported and added to `.lego/accounts/`. To know the available options, run: ```bash lego accounts recover --help ``` Or read the [documentation]({{% ref "references/ref-flags/#lego-accounts-recover" %}}). --- ## File: docs/content/advanced/archives.md --- title: "Archive Operations" date: 2019-03-03T16:39:46+01:00 draft: false weight: 7 --- This section describes operations on the archives. ## List You can list all the backuped accounts and certificates with the following command: ```bash lego archives list ``` To know the available options, run: ```bash lego archives list --help ``` Or read the [documentation]({{% ref "references/ref-flags/#lego-archives-list" %}}). ## Restore You can restore a backup of an account or a certificate with the following command: ```bash lego archives restore ``` The command will ask you for the backup file to restore. To know the available options, run: ```bash lego archives restore --help ``` Or read the [documentation]({{% ref "references/ref-flags/#lego-archives-restore" %}}). --- ## File: docs/content/advanced/certificates.md --- title: "Certificate Operations" date: 2019-03-03T16:39:46+01:00 draft: false weight: 1 --- This section describes certificate operations. ## List Certificates You can list all certificates managed by lego with: ```bash lego certificates list ``` Output: ``` Found the following certificates: _.example.com ├── Status: this certificate is expired. ├── Domains: *.example.com, example.com ├── Expiration Date: 2026-04-08 21:02:27 +0000 UTC ├── Issuer: CN=(STAGING) Puzzling Parsnip E7,O=(STAGING) Let's Encrypt,C=US └── Certificate Path: /path/to/.lego/certificates/_.example.com.crt ... ``` ## Revoke Certificates You can revoke existing certificates. {{< tabs groupid="usage-examples" >}} {{% tab title="Classic Way" %}} Execute the following command: ```bash lego certificates revoke --cert.name 'example.com' ``` {{% /tab %}} {{% tab title="With a Configuration File" %}} If you have the following `.lego.yml` configuration file: ```yaml certificates: foo: challenge: http-01 domains: - example.com ``` And execute: ```bash lego certificates revoke --cert.name foo ``` When using a configuration file, you can revoke all certificates at once: ```bash lego certificates revoke ``` {{% /tab %}} {{< /tabs >}} To know the available options, run: ```bash lego certificates revoke --help ``` Or read the [documentation]({{% ref "references/ref-flags/#lego-certificates-revoke" %}}). --- ## File: docs/content/advanced/file-configuration.md --- title: "File Configuration" date: 2019-03-03T16:39:46+01:00 draft: false weight: 5 --- The configuration file is a way to simplify the management of multiple certificates. ## Commands The configuration file is used by the following commands: - `lego` - `lego certificates revoke` - `lego certificates list` - `lego accounts list` - `lego archives list` - `lego archives restore` ## File Location and Format The configuration file is a YAML file named `.lego.yml` (or `.lego.yaml`) placed in the current working directory. lego will automatically find and use it when present. You can also pass a custom path with the `--config` flag. ## Configuration File Structure The configuration file is organized in a way that makes it easy to understand and modify. The four main sections (`servers`, `accounts`, `challenges`, and `certificates`) are named maps: each entry has a key (a name you choose) and a value (its configuration). Certificates reference accounts and challenges by their name, and accounts reference servers by their name. More information about the configuration file structure can be found in the [configuration file reference]({{% ref "references/ref-file" %}}). ## Smart Defaults The configuration file applies a number of defaults to reduce verbosity: | Setting | Description | |-----------------------------------|-------------------------------------------------------------------------------------------------------------| | Storage | Defaults to `.lego` in the current directory. | | Account server | Defaults to the Let's Encrypt production if not specified. | | Certificate key type | Inherits from its account if not specified. | | Certificate account | If there is only one account defined, it is used automatically. | | Certificate challenge | If there is only one challenge defined, it is used automatically. | | Certificate predefined challenges | `http-01`, `tls-alpn-01`, `dns-persist-01` can be used as a challenge name without dedicated configuration. | This means the minimal configuration to obtain a certificate is just a certificate entry (and a challenge for DNS-01): {{< tabs >}} {{% tab title="HTTP-01" %}} Minimal example for a certificate (Let's Encrypt). ```yaml # .lego.yml certificates: my-cert: challenge: http-01 domains: - example.com ``` {{% /tab %}} {{% tab title="TLS-ALPN-01" %}} Minimal example for a certificate (Let's Encrypt). ```yaml # .lego.yml certificates: my-cert: challenge: tls-alpn-01 domains: - example.com ``` {{% /tab %}} {{% tab title="DNS-01" %}} Minimal example for a wildcard certificate (Let's Encrypt and DNS-01 via Cloudflare). ```yaml # .lego.yml challenges: my-dns: dns: provider: cloudflare certificates: my-cert: domains: - example.com - '*.example.com' ``` {{% /tab %}} {{% tab title="DNS-PERSIST-01" %}} Please read the dedicated [documentation]({{% ref "obtain/dnspersist01" %}}). {{% /tab %}} {{< /tabs >}} ## Archive Behavior The configuration file drives lifecycle management: - When a certificate entry is removed, its files are archived. - When an account entry is removed, its files are archived. - When a server entry is removed, the server and its related accounts are archived. More information about commands related to archives can be found in the [archives section]({{% ref "advanced/archives" %}}). --- ## File: docs/content/advanced/hooks.md --- title: 'Hooks' date: 2019-03-03T16:39:46+01:00 draft: false weight: 3 --- This section describes how to use hooks. There are three hooks available: | Hook | When it runs | |----------------------------------------------------------|--------------------------------------------------------------------------------------| | [pre-hook]({{% ref "advanced/hooks/#pre-hook" %}}) | Before the certificate is created or renewed (only if a change will actually happen) | | [deploy-hook]({{% ref "advanced/hooks/#deploy-hook" %}}) | After the certificate is successfully created or renewed | | [post-hook]({{% ref "advanced/hooks/#post-hook" %}}) | After the operation completes, regardless of outcome | Don't hesitate to share your hook scripts with [the community](https://github.com/go-acme/lego/discussions/categories/ideas). ## Pre-Hook This hook is executed, before the creation or the renewal, in cases where a certificate will be effectively created/renewed. {{< tabs groupid="usage-examples" >}} {{% tab title="Classic Way" %}} Execute the following command: ```bash lego run -d 'example.com' --pre-hook='./my-pre-hook.sh' ``` {{% /tab %}} {{% tab title="With a Configuration File" %}} Define the following section in your `.lego.yaml` file: ```yaml hooks: pre: command: './my-pre-hook.sh' ``` {{% /tab %}} {{< /tabs >}} ## Deploy-Hook This hook is executed after the successful creation or the renewal of a certificate. {{< tabs groupid="usage-examples" >}} {{% tab title="Classic Way" %}} Execute the following command: ```bash lego run -d 'example.com' --deploy-hook='./my-deploy-hook.sh' ``` {{% /tab %}} {{% tab title="With a Configuration File" %}} Define the following section in your `.lego.yaml` file: ```yaml hooks: deploy: command: './my-deploy-hook.sh' ``` {{% /tab %}} {{< /tabs >}} ## Post-Hook This hook is executed, after the creation or the renewal, in cases where a certificate is created/renewed, regardless of whether any errors occurred. {{< tabs groupid="usage-examples" >}} {{% tab title="Classic Way" %}} Execute the following command: ```bash lego run -d 'example.com' --post-hook='./my-post-hook.sh' ``` {{% /tab %}} {{% tab title="With a Configuration File" %}} Define the following section in your `.lego.yaml` file: ```yaml hooks: post: command: './my-post-hook.sh' ``` {{% /tab %}} {{< /tabs >}} ## Environment Variables Some details are passed through environment variables to help you with your hooks: | Environment Variable | Description | |---------------------------------|------------------------------------------------------| | `LEGO_HOOK_ACCOUNT_ID` | The account ID. | | `LEGO_HOOK_ACCOUNT_EMAIL` | The account email (if available). | | `LEGO_HOOK_ACCOUNT_SERVER` | The server related to the account. | | `LEGO_HOOK_CERT_NAME` | The name/ID of the certificate. | | `LEGO_HOOK_CERT_NAME_SANITIZED` | The sanitized name/ID of the certificate. | | `LEGO_HOOK_CERT_KEY_TYPE` | The type of the certificate key. | | `LEGO_HOOK_CERT_DOMAINS` | The domains of the certificate. | | `LEGO_HOOK_CERT_PATH` | The path of the certificate. | | `LEGO_HOOK_CERT_KEY_PATH` | The path of the certificate key. | | `LEGO_HOOK_ISSUER_CERT_PATH` | The path of the issuer certificate. | | `LEGO_HOOK_CERT_PEM_PATH` | (only with `--pem`) The path to the PEM certificate. | | `LEGO_HOOK_CERT_PFX_PATH` | (only with `--pfx`) The path to the PFX certificate. | ## Use Case A typical use case is distributing the certificate for other services and reload them if necessary. Since many programs understand PEM-formatted TLS certificates, it is relatively simple to use certificates for more than a web server. This example script installs the new certificate for a mail server and reloads it. Beware: this is just a starting point, error checking is omitted for brevity. ```bash #!/bin/bash # copy certificates to a directory controlled by Postfix postfix_cert_dir="/etc/postfix/certificates" # our Postfix server only handles mail for @example.com domain if [ "$LEGO_HOOK_CERT_NAME" = "example.com" ]; then install -u postfix -g postfix -m 0644 "$LEGO_HOOK_CERT_PATH" "$postfix_cert_dir" install -u postfix -g postfix -m 0640 "$LEGO_HOOK_CERT_KEY_PATH" "$postfix_cert_dir" systemctl reload postfix@-service fi ``` Don't hesitate to share your hook scripts with [the community](https://github.com/go-acme/lego/discussions/categories/ideas). ## Notes The hooks must be a system-executable: binary or script with a proper shebang (e.g. `#!/bin/bash` and `chmod +x my-hook.sh`). There is neither subshell nor shell interpretation. Arguments are allowed, but there is no shell-escaping support (spaces inside arguments or paths are not supported). The hooks run in the same environment as lego, augmented with `LEGO_HOOK_*` variables. Both `stdout` and `stderr` used by the hooks are merged into a single pipe. The output is read line by line and printed to lego's own `stdout`. If the hook exits with a non-zero code (or times out), lego will surface it as a failure. --- ## File: docs/content/advanced/options.md --- title: "Options" date: 2019-03-03T16:39:46+01:00 draft: false weight: 6 aliases: - usage/cli/options --- This section describes advanced options that can be used to configure lego. ## LEGO_CA_CERTIFICATES The environment variable `LEGO_CA_CERTIFICATES` allows to specify the path to PEM-encoded CA certificates that can be used to authenticate an ACME server with an HTTPS certificate not issued by a CA in the system-wide trusted root list. Multiple file paths can be added by using `:` (unix) or `;` (Windows) as a separator. Example: ```bash # On Unix system LEGO_CA_CERTIFICATES=/foo/cert1.pem:/foo/cert2.pem ``` ## LEGO_CA_SYSTEM_CERT_POOL The environment variable `LEGO_CA_SYSTEM_CERT_POOL` can be used to define if the certificates pool must use a copy of the system cert pool. Example: ```bash LEGO_CA_SYSTEM_CERT_POOL=true ``` ## LEGO_CA_SERVER_NAME The environment variable `LEGO_CA_SERVER_NAME` allows to specify the CA server name used to authenticate an ACME server with an HTTPS certificate not issued by a CA in the system-wide trusted root list. Example: ```bash LEGO_CA_SERVER_NAME=foo ``` ## LEGO_DISABLE_CNAME_SUPPORT By default, lego follows CNAME, the environment variable `LEGO_DISABLE_CNAME_SUPPORT` allows to disable this support. Example: ```bash LEGO_DISABLE_CNAME_SUPPORT=true ``` There is a Let's Encrypt [blog post](https://letsencrypt.org/2019/10/09/onboarding-your-customers-with-lets-encrypt-and-acme.html) about the behavior of CNAMEs. ## LEGO_DEBUG_CLIENT_VERBOSE_ERROR The environment variable `LEGO_DEBUG_CLIENT_VERBOSE_ERROR` allows to enrich error messages from some of the DNS clients. Example: ```bash LEGO_DEBUG_CLIENT_VERBOSE_ERROR=true ``` ## LEGO_DEBUG_DNS_API_HTTP_CLIENT > **⚠️ WARNING: This will expose credentials in the log output! ⚠️** > > Do not run this in production environments, or if you can't be sure that logs aren't accessed by third parties or tools (like log collectors). > > You have been warned. Here be dragons. The environment variable `LEGO_DEBUG_DNS_API_HTTP_CLIENT` allows debugging the DNS API interaction. It will dump the full request and response to the log output. Some DNS providers don't support this option. Example: ```bash LEGO_DEBUG_DNS_API_HTTP_CLIENT=true ``` ## LEGO_DEBUG_ACME_HTTP_CLIENT The environment variable `LEGO_DEBUG_ACME_HTTP_CLIENT` allows debug the calls to the ACME server. Example: ```bash LEGO_DEBUG_ACME_HTTP_CLIENT=true ``` --- ## File: docs/content/advanced/tips.md --- title: "Tips" date: 2019-03-03T16:39:46+01:00 draft: false weight: 8 --- This section contains some tips and tricks for using lego. ## Automatic Renewal It is tempting to create a cron job (or systemd timer) to automatically renew all you certificates. When doing so, please note that some cron defaults will cause a measurable load on the ACME provider's infrastructure. Notably `@daily` jobs run at midnight. To both counteract load spikes (caused by all lego users) and reduce subsequent renewal failures, we were asked to implement a small random delay for non-interactive renewals.[^loadspikes] Since v4.8.0, lego will pause for up to 8 minutes to help spread the load. You can help further, by adjusting your crontab entry, like so: ```ruby # avoid: #@daily /usr/bin/lego ... #@midnight /usr/bin/lego ... #0 0 * * * /usr/bin/lego ... # instead, use a randomly chosen time: 35 3 * * * /usr/bin/lego ... ``` If you use systemd timers, consider doing something similar, and/or introduce a `RandomizedDelaySec`: ```ini [Unit] Description=Renew certificates [Timer] Persistent=true # avoid: #OnCalendar=*-*-* 00:00:00 #OnCalendar=daily # instead, use a randomly chosen time: OnCalendar=*-*-* 3:35 # add extra delay, here up to 1 hour: RandomizedDelaySec=1h [Install] WantedBy=timers.target ``` [^loadspikes]: See [GitHub issue #1656](https://github.com/go-acme/lego/issues/1656) for an excellent problem description. ## Running without root privileges The CLI does not require root permissions but needs to bind to port 80 and 443 for certain challenges. To run the CLI without `sudo`, you have four options: - Use `setcap 'cap_net_bind_service=+ep' /path/to/lego` (Linux only) - Pass the `--http.address` or/and the `--tls.address` option and specify a custom port to bind to. In this case you have to forward port 80/443 to these custom ports (see [Port Usage](#port-usage)). - Pass the `--http.webroot` option and specify the path to your webroot folder. In this case the challenge will be written in a file in `.well-known/acme-challenge/` inside your webroot. - Pass the `--dns` option and specify a DNS provider. ## Port Usage By default, lego assumes it is able to bind to ports 80 and 443 to solve challenges. If this is not possible in your environment, you can use the `--http.address` and `--tls.address` options to instruct lego to listen on that interface:port for any incoming challenges. If you are using either of these options, make sure you setup a proxy to redirect traffic to the chosen ports. **HTTP Port:** All plaintext HTTP requests to port **80** which begin with a request path of `/.well-known/acme-challenge/` for the HTTP challenge[^header]. **TLS Port:** All TLS handshakes on port **443** for the TLS-ALPN challenge. This traffic redirection is only needed as long as lego solves challenges. As soon as you have received your certificates you can deactivate the forwarding. [^header]: You must ensure that incoming validation requests contains the correct value for the HTTP `Host` header. If you operate lego behind a non-transparent reverse proxy (such as Apache or NGINX), you might need to alter the header field using `--http.proxy-header X-Forwarded-Host`. ## DNS Resolvers and Challenge Verification When using a DNS challenge provider (via `--dns `), Lego tries to ensure the ACME challenge token is properly setup before instructing the ACME provider to perform the validation. This involves a few DNS queries to different servers: 1. Determining the DNS zone and resolving CNAMEs. The DNS zone for a given domain is determined by the SOA record, which contains the authoritative name server for the domain and all its subdomains. For simple domains like `example.com`, this is usually `example.com` itself. For other domains (like `fra.eu.cdn.example.com`), this can get complicated, as `cdn.example.com` may be delegated to the CDN provider, which means for `cdn.example.com` must exist a different SOA record. To find the correct zone, Lego requests the SOA record for each DNS label (starting on the leaf domain, i.e. the left-most DNS label). If there is no SOA record, Lego requests the SOA record of the parent label, then for its parent, etc., until it reaches the apex domain[^apex]. Should any DNS label on the way be a CNAME, it is resolved as per usual. In the default configuration, Lego uses the system name servers for this, and falls back to Cloudflare's DNS servers, should they be absent. 2. Verifying the challenge token. The `_acme-challenge.` TXT record must be correctly installed. Lego verifies this by directly querying the authoritative name server for this record (as detected in the previous step). Strictly speaking, this verification step is not necessary, but helps to protect your ACME account. Remember that some ACME providers impose a rate limit on certain actions (at the time of writing, Let's Encrypt allows 300 new certificate orders per account per 3 hours). There are also situations where this verification step doesn't work as expected: - A "split DNS" setup gives different answers to clients on the internal network (Lego) vs. on the public internet (ACME server). - With "hidden master" setups, Lego may be able to directly talk to the primary DNS server, while the `_acme-challenge` record might not have fully propagated to the (public) secondary servers, yet. The effect is the same: Lego determined the challenge token to be installed correctly, while the ACME server has a different view and rejects the certificate order. In these cases, you can instruct Lego to use a different DNS resolver, using the `--dns.resolvers` flag. You should prefer one on the public internet, otherwise you might be susceptible to the same problem. [^apex]: The apex domain is the domain you have registered with your domain registrar. For gTLDs (`.com`, `.fyi`) this is the 2nd level domain, but for ccTLDs, this can either be the 2nd level (`.de`) or 3rd level domain (`.co.uk`).