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

acme.sh: add page #5823

Merged
merged 8 commits into from
Apr 27, 2021
Merged

acme.sh: add page #5823

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
90ec8e8
add page: acme.sh
peterbabic Apr 23, 2021
8244ad2
fix 825645081
peterbabic Apr 23, 2021
d6e1b85
replace domain.tld with example.com
peterbabic Apr 23, 2021
3a8b190
Update pages/common/acme.sh.md
peterbabic Apr 23, 2021
1802401
Update pages/common/acme.sh.md
peterbabic Apr 25, 2021
b063ae0
convert examples to more specific ones
peterbabic Apr 25, 2021
d2a4aeb
reword example description
peterbabic Apr 25, 2021
cd75f28
Update pages/common/acme.sh.md
peterbabic Apr 25, 2021
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
36 changes: 36 additions & 0 deletions pages/common/acme.sh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# acme.sh

> An ACME Shell script, an acme client alternative to certbot.
> More information: <https://github.com/acmesh-official/acme.sh>

- Issue a certificate using webroot mode:

`acme.sh --issue --domain {{domain.tld}} --webroot {{/path/to/webroot}}`

- Issue a certificate using standalone mode using port 80:

`acme.sh --issue --standalone --domain {{domain.tld}}`

- Issue a certificate using standalone TLS mode using port 443:

`acme.sh --issue --alpn --domain {{domain.tld}}`

- Issue a certificate using a working Nginx configuration:

`acme.sh --issue --nginx --domain {{domain.tld}}`

- Issue a certificate using a working Apache configuration:

`acme.sh --issue --apache --domain {{domain.tld}}`

- Issue a wildcard (\*) certificate using a manual DNS mode:

`acme.sh --issue --dns --domain {{*.domain.tld}}`

- Issue a certificate using an automatic DNS API mode:

`acme.sh --issue --dns {{dns_api}} --domain {{domain.tld}}`

- Install certificate file into location specified by its parameter (not displayed):

`acme.sh --install-cert --domain {{domain.tld}} --reloadcmd {{reload_commad}}`
Copy link
Contributor Author

@peterbabic peterbabic Apr 23, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

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

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@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.

Copy link
Contributor

Choose a reason for hiding this comment

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

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"}}`

Copy link
Collaborator

Choose a reason for hiding this comment

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

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

Copy link
Contributor Author

@peterbabic peterbabic Apr 25, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

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)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

  1. 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

Copy link
Contributor

Choose a reason for hiding this comment

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

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).

Copy link
Contributor Author

@peterbabic peterbabic Apr 25, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

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?

Copy link
Member

@sbrl sbrl Apr 25, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

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