ACME Client Accounts

An ACME client account is the server's registration with a certificate authority: the CA's directory URL, a key pair the panel registers there, and an optional contact address. The server holds one or more of them, and one is active: every certificate the panel orders, for the server's hosts, the accounts' hosts and the IP addresses, goes through the active account.

What a new server starts with

server:init, which install.sh runs, creates two accounts: Let's Encrypt (https://acme-v02.api.letsencrypt.org/directory) and Let's Encrypt Staging (https://acme-staging-v02.api.letsencrypt.org/directory). Production is active unless the install said otherwise:

Install option	Active account
none	Let's Encrypt
--staging	Let's Encrypt Staging
--acme <directory URL>	Custom ACME Account, a third account at that URL

The accounts are created with no key. The panel generates the key pair and registers it with the directory at the first order through the account, and the Key column shows Installed from then on.

Staging issues untrusted certificates

The staging directory is Let's Encrypt's test endpoint: orders there don't spend the production rate limits, and its certificates are not trusted by any browser. Install with --staging to test an installation, then set Let's Encrypt active. Certificates already issued by staging stay in service until their renewal; certificate:provision:manual <hostname> orders a replacement now.

The screen

System › ACME Client Accounts lists the server's accounts, with the Active one marked. For each: its Description, its Identity (the directory URL, plus the External Account Binding key id if it has one), whether a Key is Installed or Not yet, and how many Certificates it issued. An account's page lists those certificates and offers Edit, and, for an account that is not active, Set as active and Delete.

Add ACME Account asks for:

• Description, a name for you, e.g. "Let's Encrypt production".
• Endpoint: the ACME directory URL.
• Contact email, optional, sent to the CA at registration.
• External account key ID and External account HMAC key: the EAB credentials from the CA's portal, for a CA that issues them. Leave both empty for Let's Encrypt and any other CA that takes anonymous registrations. Paste the HMAC key exactly as the portal printed it.

Once a key pair is registered, the endpoint and the EAB credentials are locked and the edit form leaves them out: EAB is sent at registration and nowhere else, so changing it afterwards would do nothing. The description and the contact address stay editable. On the edit form an empty HMAC field keeps the stored key.

The active account

Exactly one account is active, and it is the only one that issues. Setting another one active takes effect for the next order; certificates already issued keep serving until their renewal, which the new account then issues.

The active account can't be deleted, in the screen or on the command line: set another one active first. Deleting an account that issued certificates doesn't touch them; they lose their Provider and nothing else.

One Let's Encrypt account per server

Let's Encrypt asks a provider to use one account for each machine, and limits new accounts per IP address; see its rate limits page. One server-owned account is the right shape; the panel's own rate limiter spaces the orders through it.

Accounts owned by account holders

An account holder can hold an ACME account of their own, for a commercial CA that issued them EAB credentials. You create it for them: open the account under Accounts, then its ACME tab, or give --account to the commands below. ACME Client Accounts says how many exist and links to the list, Owned by accounts.

Nothing selects them yet

An account-owned ACME account is stored, credentialed and listed, and issues nothing: every certificate still goes through the server's active account. Which account issues for which hostnames is open design work. Creating one that points at Let's Encrypt gets a warning for that reason: it would spend a registration slot the whole server shares, for nothing.

Commands

In a root shell on the server. Without --account, each command works on the server's accounts.

elpanctl certificate:acme:list [--account=<account>]
elpanctl certificate:acme:create <description> <directory URL> [--email=<address>] [--eab-kid=<id> --eab-hmac=<key>] [--account=<account>]
elpanctl certificate:acme:set-active <id>
elpanctl certificate:acme:delete <id> [--account=<account>]
elpanctl certificate:provider:list [--account=<account>]

certificate:acme:list prints each account's id, directory URL, contact address, whether it has a key, its EAB key id, and which one is active. certificate:acme:set-active takes the server's accounts only; an account holder's accounts have no active one. certificate:provider:list lists the same relationships whatever their protocol, with the type of each and whether it is ready for use.