Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update ZeroSSL issuer for v2.8 #414

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: Update ZeroSSL issuer for v2.8 #414

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c2172dc
docs: Update ZeroSSL issuer for v2.8
kekalainen Sep 4, 2024
c797f47
docs: Restore previous issuer sections, disambiguate
kekalainen Sep 6, 2024
5c827fd
docs: Add fields for zerossl issuer module
kekalainen Sep 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs: Restore previous issuer sections, disambiguate
  • Loading branch information
@kekalainen
kekalainen authored Sep 6, 2024
commit c797f47e67e5282e2eee043a0348b1763d879e51
8 changes: 5 additions & 3 deletions src/docs/markdown/caddyfile/directives/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,15 +359,17 @@ Obtains certificates using the ACME protocol. Note that `acme` is a default issu

- **any_common_name** <span id="any_common_name"/> is a list of one or more common names; Caddy will choose the first chain that has an issuer that matches with at least one of the specified common names.

##### ZeroSSL
<aside class="tip">

Caddy will implicitly use [ZeroSSL's ACME endpoint](https://zerossl.com/documentation/acme/) (and generate EAB credentials) if you specify the the [`email` global option](/docs/caddyfile/options#email).
The `acme` issuer module will implicitly use [ZeroSSL's ACME endpoint](https://zerossl.com/documentation/acme/) (and generate EAB credentials) if you specify the the [`email` global option](/docs/caddyfile/options#email).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, this is only true if it's unspecified in the config. If you specify an issuer in the config, that overrides the defaults. Since this is docs describing how to override the defaults, maybe it's not the place to describe the default behavior which might be confusing.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. Removing the paragraph altogether would muddy the difference between the acme and zerossl issuer modules, though. Perhaps prefixing it with "When explicitly unconfigured" would do?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if instead, we add a sentence to the zerossl section that clarifies: "The ZeroSSL API is distinct from its ACME endpoint." or something like that.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While that'd cover the distinction more directly, the acme section still claims the module is "using Let's Encrypt" by default. For consistency either all or none of the possible implicit/default configuration should be mentioned IMO.

Especially since the release notes claim that when the email global is configured,

you don't have to make any changes and you'll still get Let's Encrypt and ZeroSSL automatically as defaults.

which, turns out, is arguably not true if acme is explicitly configured. That's not apparent (to me anyway) when said configuration is not providing a directory_url as an argument nor field value. (For context, I use the acme issuer directive to override the DNS resolvers used for challenges (since those aren't globally configurable AFAIK) and had the false intuition it'd leave the dirs intact.)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the acme section still claims the module is "using Let's Encrypt" by default. For consistency either all or none of the possible implicit/default configuration should be mentioned IMO.

Fair point, maybe that section needs to be tweaked to say "(using Let's Encrypt, and if an email is provided, ZeroSSL too)" or similar.

which, turns out, is arguably not true if acme is explicitly configured. That's not apparent (to me anyway) when said configuration is not providing a directory_url as an argument nor field value.

Perhaps verbiage clarifying that specifying any issuers wipes out implicit defaults.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the status on this at this point?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we're still waiting for a few tweaks to be made; but if not, I might try to wrap this up myself at some point. Although, I don't think I have push rights to the branch.


To provide your own EAB credentials for ZeroSSL, specify the `dir` and `eab` options.

</aside>

#### zerossl

Obtains certificates using the ZeroSSL API.
Obtains certificates using the [ZeroSSL API](https://zerossl.com/documentation/api/).

```caddy-d
... zerossl <api_key> {
Expand Down