acme.sh: add page

[peterbabic]

No description provided.

[tldr-bot]

The build for this PR failed with the following error(s):

pages/common/acme.sh.md:
Error: Parse error on line 4:
...sh-official/acme.sh>- Issue a certific
-----------------------^
Expecting 'END_INFORMATION_LINK_URL', got 'NEWLINE'
pages/common/acme.sh.md:4: TLDR011 Page never contains more than a single empty line

Please fix the error(s) and push again.

[bl-ue]

@peterbabic what do you think about using example.com instead of domain.tld? While the latter is perfectly good, the former looks more like a url at first glance.

[peterbabic]

This would ideally contain a far longer code snippet, like:

acme.sh --install-cert -d {{domain.tld}}  \
  --key-file {{/etc/nginx/ssl/domain.tld.key}} \
  --fullchain-file {{/etc/nginx/ssl/domain.tld.cer}} \
  --reloadcmd {{"systemctl force-reload nginx"}}

But I am not sure how to proceed. All the parameters, except the --domain are optional. However, there are many parameters in a format --*-filehandling their respective certificate key files. Without a single *-file parameter, the whole command does literally nothing.

Additionally, --reloadcmd is also optional, but it is run without it only rarely (in the situations that the service restart is done completely manually, bypassing the whole point of automatic certificate renewal mechanism).

I am not entirely sure how to proceed, but this single code block is the only one I would've looked for when calling tldr acme.sh.

EDIT: the relevant docs are at https://github.com/acmesh-official/acme.sh#3-install-the-cert-to-apachenginx-etc

[peterbabic]

@bl-ue @marchersimon @sbrl please, can anyone provide any kind of feedback?

Should this stay as it is, or is there any way to display long command? I did not find anything "long" related in the contribution guide.

[bl-ue]

This seems a little long, but it might not be... 🤔

`acme.sh --install-cert -d {{example.com}} --key-file {{/path/to/example.com.key}} --fullchain-file {{/path/to/example.com.cer}} --reloadcmd {{"systemctl force-reload nginx"}}`

[marchersimon]

I also think we should try to stuff it into one line. Mainly because most clients don't support multiline code.

[peterbabic]

Guys please, I am not sure what to do here. Would appreciate some guidance, if I am expected to commit some changes.

UPDATE:
As far as I can tell right now, we have at least three options:

1. drop the example as it is too long (I am strongly opposed, but might be sufficient)
2. include relatively short example with generic values (would serve more as a reminder)
3. include full length example (most valuable, might break some clients without multiline code support)

[peterbabic]

4. add the subcommand-like page, detailing the most used --install-cert options, as there are quite a few of them and mention this page in See also section

[bl-ue]

Why not just stuff it into one line? It's a little long, but I don't really see any strong reason why not to. As for multiline, we can't do that, because that goes against the client spec (or at least the client spec will have to be updated).

[peterbabic]

Long option would serve the most basic information, I am also wiling to write the subcommand page for --install-cert option, as it has around 5-7 commonly used parameters.

Thinking about it further, the name of the file could probably be called acme.sh-install-cert.md similarly as for instance git-cat-file.md

Would this somehow break existing conventions?

[sbrl]

For some commands, it's unavoidable to have long commands - just do tldr whiptail and you'll see what I mean. It's not necessarily a bad thing. I say put it all on 1 line.

Edit: Those file paths have to be absolute too by the looks of things, so we can't save some character there either

[peterbabic]

@peterbabic what do you think about using example.com instead of domain.tld? While the latter is perfectly good, the former looks more like a url at first glance.

$ grep -o -i -R "example.com" | wc -l 
216

On the contrary:

$ grep -o -i -R "domain.tld" | wc -l 
0

I agree with example.com

[sbrl]

Perhaps a concrete example for dns_api would aid clarity here?

[peterbabic]

@sbrl sure.

EDIT: but how please?

Instead of {{dns_api}} would be one of the many available options specified here https://github.com/acmesh-official/acme.sh/wiki/dnsapi

So, for instance for CloudFlare DNS API it is {{dns_cf}}

Also, in example used {{dns_api}} is still perfectly valid for custom scripts, if there is a dns_api.sh script present in the .acme.sh/ root folder, more info acmesh-official/acme.sh#1571 (comment)

[peterbabic]

Maybe this would also deserved it's separate subcommand page?

[bl-ue]

But is it actually a subcommand? If so, then if should just be dns_api.sh.md (if we document it, which we probably will).

[peterbabic]

I believe it would be called more like acme.sh-dns.md, as the subcommand in question is named --dns {{ }}

[sbrl]

If we document it as a subcommand, we'd probably do something similar to pacman in #5268, for example.

[peterbabic]

@sbrl it is already open in #5852

[peterbabic]

So I have added specific examples according to valuable suggestions with the possibility to document subcommands and maybe even open "Lets Document: acme.sh" issue in the future.