CLI Guide

This guide describes the changes between the v4 and v5 versions of the command line.

Commands

The global flags have been moved to flags of the commands.

Example:

# Before
lego --dns foo -d '*.example.com' -d example.com run

# After
lego run --dns foo -d '*.example.com' -d example.com

The command renew has been removed because the command run is able to renew certificates.

The command list has been removed and replaced by accounts list and certificates list.

The command revoke has been removed and replaced by certificates revoke.

Flags

Some flags have been changed, renamed or removed:

Directory structure

The directory structure has been changed.

.
├── accounts
│   └── <server-name-1>
│       ├── <account-name-1>
│       │   ├── account.json
│       │   └── keys
│       │       └── <account-name-1>.key
│       └── <account-name-2>
│           ├── account.json
│           └── keys
│               └── <account-name-2>.key
└── certificates
    ├── example.com.crt
    ├── example.com.issuer.crt
    ├── example.com.json
    ├── example.com.key
    ├── example.org.crt
    ├── example.org.issuer.crt
    ├── example.org.json
    └── example.org.key

.
├── accounts
│   └── <server-name-1>
│       ├── <account-name-1>
│       │   ├── account.json
│       │   └── <account-name-1>.key
│       └── <account-name-2>
│           ├── account.json
│           └── <account-name-2>.key
└── certificates
    ├── example.com.crt
    ├── example.com.issuer.crt
    ├── example.com.json
    ├── example.com.key
    ├── example.org.crt
    ├── example.org.issuer.crt
    ├── example.org.json
    └── example.org.key

The directory structure has changed but also the content of the JSON files, so don’t migrate the files manually.

To migrate the directory structure and the files, run the command lego migrate.

If you need to do it manually, please open a discussion and we will help you.

Environment variables

The following environment variables have been removed without replacement:

• SELECTEL_BASE_URL
• VSCALE_BASE_URL

The following environment variables related to the hook have been renamed:

CommonName

The support of the common name is disabled by default.

PEM encoding

Lego uses PKCS#8 instead of PKCS#1 for PEM encoding.

Default resolver/nameserver fallbacks

The default resolver/nameserver fallbacks have been changed.

Library Guide

This guide describes the changes between the v4 and v5 versions of the library.

Context

Most of the functions and methods are now using a context.

Example:

// Before
client.Certificate.Obtain(request)

// After
client.Certificate.Obtain(context.TODO(), request)

Logger

The logger is now slog and can be set using the log.SetDefault(logger) function.

DNS core client

The function dns01.ParseNameservers() is removed.

The function dns01.RecursiveNSsPropagationRequirement() is removed and replaced by dns01.DisableAuthoritativeNssPropagationRequirement().

The function dns01.AddRecursiveNameservers() is removed and replaced by an option dns01.Options.RecursiveNameservers.

opts := &dns01.Options{RecursiveNameservers: []string{"8.8.8.8"}}

dns01.SetDefaultClient(dns01.NewClient(opts))

The function dns01.AddDNSTimeout() is removed and replaced by an option dns01.Options.DNSTimeout.

opts := &dns01.Options{Timeout: 2*time.Second}

dns01.SetDefaultClient(dns01.NewClient(opts))

Method and function changes

The functions and methods related to the private key are now using the crypto.Signer interface instead of the crypto.PrivateKey type.

The following methods now return an *acme.ExtendedAccount instead of an *registration.Ressouce.

• registration.Registrar.Register
• registration.Registrar.RegisterWithExternalAccountBinding
• registration.Registrar.QueryRegistration
• registration.Registrar.UpdateRegistration
• registration.Registrar.ResolveAccountByKey

The structure registration.Ressouce has been removed.

The method http01.ProviderServer.SetProxyHeader() is removed and replaced by an option http01.Options.ProxyHeaderName.

The function dns01.RecursiveNSsPropagationRequirement() is removed and replaced by dns01.DisableAuthoritativeNssPropagationRequirement().

Field changes

The field RetryAfter of acme.RateLimitedError and acme.ExtendedChallenge is now a time.Duration instead of a string.

CertifierOptions

CommonName

The support of the common name is disabled by default.

The field DisableCommonName of certificate.CertifierOptions has been removed.

The option is now determined by the EnableCommonName field of the certificate.ObtainRequest and certificate.ObtainForCSRRequest.

KeyType

The field KeyType of certificate.CertifierOptions has been removed.

The key type is now determined by the KeyType field of the certificate.ObtainRequest.

certcrypto.KeyType

The string values of the certcrypto.KeyType enum have been changed:

Removed elements

The following elements have been removed without replacements:

• selectel.Config.BaseURL
• selectel.EnvBaseURL
• SELECTEL_BASE_URL
• vscale.Config.BaseURL
• vscale.EnvBaseURL
• VSCALE_BASE_URL
• ipv64.Config.SequenceInterval
• netcup.Config.TTL
• netcup.EnvTTL
• vultr.Config.HTTPTimeout

Package changes

The package platform/config/env has been moved to platform/env.

The following packages have been removed:

• platform/tester
• platform/wait

PEM encoding

It uses PKCS#8 instead of PKCS#1 for PEM encoding.

Default resolver/nameserver fallbacks

The default resolver/nameserver fallbacks have been changed.