-
Notifications
You must be signed in to change notification settings - Fork 0
Command reference
- add-email
- authorize-domains
- deactivate-account
- deactivate-domain-authorization
- download-certificates
- download-challenges
- generate-certificate
- get-agreement-url
- register
- renew-certificate
- revoke-certificate
- update-agreement
- verify-domains
Add an e-mail address to your account or change the existing e-mail address on your account.
Required options: --account-key, --email
Example:
java -jar acme_client.jar --command add-email -a /path/to/account.key
-e [email protected]
Request authorization for the specified domains, i.e. request generation of challenges and download them. Challenges will only be created for domains that aren't authorized yet. For domains that already have a valid authorization, new authorizations won't be generated but instead previously created (and already verified) challenges will be returned.
Required options: --account-key, --domain
Optional options: --challenge-type, --dns-digests-dir, --one-dir-for-well-known,
--well-known-dir, --work-dir
In case of partial failure (PJAC failed to create/retrieve authorization for some domains but succeeded for other domains) the list of failed domains is written to the JSON return value, before the status object, i.e.
{"failed_domains":["example.com", "blog.example.com"],"status":"error"}.
During execution, PJAC stores information about the downloaded challenges in the file /path/to/workdir/authorization_uri_list. This information is used with subsequent operations that involve previously generated challenges: deactivate-domain-authorization, download-challenges and verify-domains.
ℹ️ Each domain name a certificate is requested for (i.e. the main domain name -aka common name- and alternative domain names) must be authorized and verified, otherwise generation of the certificate will fail. Hence, it's good practice to specify all domains which you use in the Certificate Signing Request (CSR) when executing this command, but -in case of a high amount of domains- take care to avoid hitting rate limits. For instance, when requesting a certificate from Let's Encrypt for more than 20 domains it is recommended to perform authorization (authorize command followed by verify command) in blocks of 20 domains each.
Example:
java -jar acme_client.jar --command authorize-domains -a /path/to/account.key
-w /path/to/workdir/ -d example.com -d www.example.com -d admin.example.com
-d www.admin.example.com --well-known-dir /path/to/wellknown
--one-dir-for-well-known
Deactivate the account associated with the specified user account key.
Required option: --account-key
With Let's Encrypt, currently there is no way to reactivate your account. However, you can register again using the same (or a new) user account key. In that case, you won't be able perform operations on previously generated authorizations and/or certificates (deactivate, download, revoke etc) but you can always generate new authorizations and certificates. Except for rate limits, there is no limit on the number of accounts, authorizations and certificates you can create.
Example:
java -jar acme_client.jar --command deactivate-account -a /path/to/account.key
Deactivate all domain authorizations for all or specific domains. Useful if you want to remove/sell one or more domains.
Required option: --account-key
Optional options: --domain, --work-dir
Needs: authorization_uri_list
In case of partial failure (PJAC failed to deactivate authorization for some domains but succeeded for other domains) the list of failed authorizations is written to the JSON return value, before the status object, i.e.
{"failed_authorizations":["https://acme-staging.api.letsencrypt.org/acme/authz/O9mvHapsXGnd7Lnt89p8uoEYdAGGFva1seAhp7-6w5k", "https://..."],"status":"error"}.
Examples:
Deactivate all authorizations for all domains:
java -jar acme_client.jar --command deactivate-domain-authorization
-a /path/to/account.key -w /path/to/workdir/
Deactivate all authorizations for domains admin.example.com and www.example.com:
java -jar acme_client.jar --command deactivate-domain-authorization
-a /path/to/account.key -w /path/to/workdir/ -d admin.example.com
-d www.example.com
Download previously generated certificates. By default, all existing certificates are downloaded, sorted ascending by expiration date (cert_0.pem being the most recent certificate). Use newest-only to download only the most recent certificate.
Required option: --account-key
Optional options: --cert-dir, --newest-only, --work-dir
Needs: certificate_uri_list
In case of partial failure (PJAC failed to download some certificates but succeeded for other certificates) the list of failed certificates is written to the JSON return value, before the status object, i.e.
{"failed_certificates":["https://acme-staging.api.letsencrypt.org/acme/cert/fa57a3c23a0792f75a15d42b45168fef27fa", "https://..."],"status":"error"}.
Examples:
Download most recent certificate:
java -jar acme_client.jar --command download-certificates -a /path/to/account.key
-w /path/to/workdir/ --cert-dir /path/to/certdir/ --newest-only
Download all certificates sorted by expiration date:
If this command downloads 5 certificates, cert_0_pem is the most recent and cert_4_pem the oldest certificate.
java -jar acme_client.jar --command download-certificates -a /path/to/account.key
-w /path/to/workdir/ --cert-dir /path/to/certdir/
Download challenges for previously generated authorizations.
Required options: --account-key
Optional options: --challenge-type, --dns-digests-dir, --domain, --one-dir-for-well-known, --well-known-dir, --work-dir
Needs: authorization_uri_list
In case of partial failure (PJAC failed to download challenges for some domains but succeeded for other domains) the list of failed domains is written to the JSON return value, before the status object, i.e.
{"failed_domains":["example.com", "blog.example.com"],"status":"error"}.
This can occur when you failed to verify a challenge, which resulted in the CA setting the state "Invalid" for the authorization.
Examples:
Download all HTTP01 challenges for all authorizations for all domains. The challenge for each domain will be placed in a corresponding directory, i.e.
/path/to/wellknown/${domain}/${challenge_token}:
java -jar acme_client.jar --command download-challenges -a /path/to/account.key
-w /path/to/workdir/ --well-known-dir /path/to/wellknown
Download all HTTP01 challenges for all authorizations for domains example.com, www.example.com and admin.example.com. As in the previous example, the challenges for each domain will be placed in a corresponding directory, i.e.
/path/to/wellknown/${domain}/${challenge_token}:
java -jar acme_client.jar --command download-challenges -a /path/to/account.key
-w /path/to/workdir/ -d example.com -d www.example.com -d admin.example.com
--well-known-dir /path/to/wellknown
Download all HTTP01 challenges for all authorizations for all domains and place them in one directory, i.e.
/path/to/wellknown/${challenge_token}:
java -jar acme_client.jar --command download-challenges -a /path/to/account.key
-w /path/to/workdir/ --well-known-dir /path/to/wellknown --one-dir-for-well-known
Download all DNS01 challenges for all authorizations for all domains:
java -jar acme_client.jar --command download-challenges -a /path/to/account.key
-w /path/to/workdir/ --well-known-dir /path/to/wellknown --challenge-type DNS01
Generate a new certificate and download it.
Required options: --account-key, --csr
Optional options: --cert-dir, --work-dir
During execution, PJAC stores information about the generated certificates in the file /path/to/workdir/certificate_uri_list. This information is used with subsequent operations that involve previously generated certificates: download-certificates and revoke-certificate.
Example:
java -jar acme_client.jar --command generate-certificate -a /path/to/account.key
-w /path/to/workdir/ --csr /path/to/example.com.csr --cert-dir /path/to/certdir/
Returns the URL to the most recent Subscriber Agreement.
Required option: --account-key
The URL is written to the JSON return value, before the status object, i.e {"agreement_url":"https://...","status":"ok"}.
Example:
java -jar acme_client.jar --command get-agreement-url -a /path/to/account.key
Create a new account with your CA which will be associated with the specified user account key.
Required option: --account-key
Optional option: --email
Example:
java -jar acme_client.jar --command register -a /path/to/account.key
--email [email protected] --with-agreement-update
Generate a new certificate and download it, either for an existing CSR or a new CSR. Only generates a new certificate if your most recent certificate will expire within <max-expiration-time>, specified in milliseconds. By default it is set to 2592000000 (30 days).
Required options: --account-key, --csr
Optional options: --cert-dir, --force, --max-expiration-time, --work-dir
If a new certificates was generated by this command, the status "true" is written to the JSON return value, before the status object, i.e. {"renewed":true,"status":"ok"}. Otherwise (most recent certificate still has a longer lifetime than <max-expiration-time>), the status "false" is written to the JSON return value, i.e {"renewed":false,"status":"ok"}.
During execution, PJAC stores information about the generated certificates in the file /path/to/workdir/certificate_uri_list. This information is used with subsequent operations that involve previously generated certificates: download-certificates and revoke-certificate.
ℹ️ renew-certificate with option --force produces the same result as generate-certificate.
Examples:
Generate a certificate only if all your existing certificates will be expired within 30 days (default):
java -jar acme_client.jar --command renew-certificate -a /path/to/account.key
-w /path/to/workdir/ --cert-dir /path/to/certdir/ --csr /path/to/example.com.csr
Generate a certificate only if all your existing certificates will be expired within 10 days:
java -jar acme_client.jar --command renew-certificate -a /path/to/account.key
-w /path/to/workdir/ --cert-dir /path/to/certdir/ --csr /path/to/example.com.csr
--max-expiration-time 864000000
Force to generate a new certificate:
java -jar acme_client.jar --command renew-certificate -a /path/to/account.key
-w /root/workdir/ --cert-dir /path/to/certdir/ --csr /path/to/example.com.csr
--force
Revoke certificates. You can revoke either all your certificates or by time criteria. All certificates will be removed which are generated after <from-time> and which will be expired by <to-time>.
Required option: --account-key
Optional options: --from-time, --to-time, --work-dir
Needs: certificate_uri_list
In case of partial failure (PJAC failed to revoke some certificates but succeeded for other certificates) the list of failed certificates is written to the JSON return value, before the status object, i.e.
{"failed_certificates":["https://acme-staging.api.letsencrypt.org/acme/cert/fa57a3c23a0792f75a15d42b45168fef27fa", "https://..."],"status":"error"}.
Examples:
Revoke all certificates:
java -jar acme_client.jar --command revoke-certificate -a /path/to/account.key
-w /path/to/workdir/
Revoke certificates generated after Mon Dec 05 2016 10:28:50:
java -jar acme_client.jar --command revoke-certificate -a /path/to/account.key
-w /path/to/workdir/ --from-time 1480933730000
Revoke certificates which will expire before Sun Mar 05 2017 11:06:00:
java -jar acme_client.jar --command revoke-certificate -a /path/to/account.key
-w /path/to/workdir/ --to-time 1488711960000
Revoke certificates which are generated after Mon Dec 05 2016 10:28:50 and will expire before Sun Mar 05 2017 11:06:00:
java -jar acme_client.jar --command revoke-certificate -a /path/to/account.key
-w /path/to/workdir/ --from-time 1480933730000 --to-time 1488711960000
Accept the Subscriber Agreement. If the option agreement-url is omitted you will automatically accept the most recent agreement.
Required option: --account-key
Optional option: --agreement-url
See also --with-agreement-update.
Example:
To agree to the latest Subscriber Agreement:
java -jar acme_client.jar --command update-agreement -a /path/to/account.key
To agree to a specific Subscriber Agreement:
java -jar acme_client.jar --command update-agreement -a /path/to/account.key
--agreement-url "https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf"
Validate pending authorizations for specified domains, i.e. verify challenges for pending authorizations. Only challenges for domains that aren't authorized yet are verified (retrieved from your webserver by the CA). For domains that already have a valid authorization (authorize-domains returned previously created and already verified challenges), challenge files won't be checked.
Required option: --account-key
Optional options: --domain, --work-dir
Needs: authorization_uri_list
In case of partial failure (PJAC failed to validate authorizations for some domains but succeeded for other domains) the list of failed domains is written to the JSON return value, before the status object, i.e.
{"failed_domains":["example.com", "blog.example.com"],"status":"error"}.
Note that a challenge cannot be verified twice. If you tried to verify a challenge and it failed, the CA sets the authorization to the state "Invalid". In this case you must generate a new challenge (generate authorization for the domain again).
Examples:
Verify all domains for which authorization is requested:
java -jar acme_client.jar --command verify-domains -a /path/to/account.key
-w /path/to/workdir/
Verify domains example.com, www.example.com and admin.example.com:
java -jar acme_client.jar --command verify-domains -a /path/to/account.key
-w /path/to/workdir/ -d example.com -d www.example.com -d admin.example.com