From 828931655cc9626cad2c7dc25cbf068eb3137547 Mon Sep 17 00:00:00 2001 From: Gino Naumann Date: Tue, 23 Jan 2024 00:56:09 +0100 Subject: [PATCH] docs: add state and module docs --- README.md | 57 ++++++++++++--- doc/module_acme_sh.md | 158 ++++++++++++++++++++++++++++++++++++++++++ doc/state_acme_sh.md | 64 +++++++++++++++++ 3 files changed, 271 insertions(+), 8 deletions(-) create mode 100644 doc/module_acme_sh.md create mode 100644 doc/state_acme_sh.md diff --git a/README.md b/README.md index a624d23..52b571d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,20 @@ # Salt acme.sh Formula -**:construction_worker: This formula is currently being developed :construction_worker:** +![GitHub release](https://img.shields.io/github/v/release/genaumann/salt-acme.sh-formula) +![lint][lint_badge] +![test][test_badge] + +Interacts with [acme.sh](https://acme.sh): + +- install acme.sh +- issue certificates +- renew certificates + +The following modes are supported: + +- standalone +- webroot +- dns ## General notes @@ -14,6 +28,33 @@ This formula is versioned according to [Semantic Versioning](http://semver.org/) ## Available states +- [`acme.sh`](acme.sh/init.sls) +- [`acme.sh.install`](acme.sh/install.sls) +- [`acme.sh.issue`](acme.sh/issue.sls) + +### `acme.sh` + +Includes the following states: + +- `acme.sh.install` +- `acme.sh.issue` + +### `acme.sh.install` + +Installs `acme.sh`. + +### `acme.sh.issue` + +Issues or renews certificate with `acme.sh`. + +## Available execution modules + +- [`acme.sh`](docs/module_acme_sh.md) + +## Available state modules + +- [`acme.sh`](docs/state_acme_sh.md) + ## Testing Linux testing is done with `kitchen-salt`. @@ -41,13 +82,13 @@ kitchen test This formula has been tested under the following operating systems and salt versions. -| OS | 3006.5 | -| ------------ | ------ | -| Debian 12 | :x: | -| Ubuntu 22.04 | :x: | -| Rocky 9 | :x: | -| Fedora 38 | :x: | -| OpenSUSE 15 | :x: | +| OS | 3006.0 | 3006.5 | +| ------------ | ------ | ------------ | +| Debian 12 | :x: | ✅ | +| Ubuntu 22.04 | :x: | ✅ | +| Rocky 9 | :x: | ✅ | +| Fedora 38 | :x: | ✅ | +| OpenSUSE 15 | ✅ | Not released | [install]: https://docs.saltproject.io/en/latest/topics/development/conventions/formulas.html [lint_badge]: https://github.com/genaumann/salt-acme.sh-formula/actions/workflows/lint.yml/badge.svg?branch=main diff --git a/doc/module_acme_sh.md b/doc/module_acme_sh.md new file mode 100644 index 0000000..05ef9d2 --- /dev/null +++ b/doc/module_acme_sh.md @@ -0,0 +1,158 @@ +# Execution Module acme_sh + +The `acme.sh` module provides an interface to [acme.sh](https://acme.sh). + +`acme.sh` is installed in the user's home directory. +You can specify a different user with the `user` parameter, but you are not able to specify a different install path. +Of course you can change the cert path with the `cert_path` parameter. + +## Available functions + +- [acme_sh.issue](#acme_shissue) +- [acme_sh.install](#acme_shinstall) +- [acme_sh.renew](#acme_shrenew) +- [acme_sh.info](#acme_shinfo) +- [acme.sh_version](#acmesh_version) + +### acme_sh.issue + +Issues a certificate with `acme.sh`. + +| Parameter | Type | Required | Default | Description | +| ----------------- | --------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------- | +| `name` | `str` | `True` | | Domain to issue certificate for. | +| `acme_mode` | `str` | `True` | | Mode to issue certificate with. (webroot, standalone, standalone-tls-alpn, dns) | +| `aliases` | `str,str` | `False` | `None` | List of aliases to issue certificate for. | +| `server` | `str` | `False` | `letsencrypt` | ACME server to use. | +| `keysize` | `str` | `False` | `4096` | Key size to use. | +| `dns_plugin` | `str` | `False`, `True` if acme_mode is dns | `None` | DNS plugin to use. | +| `dns_credentials` | `dict` | `False`, `True` if acme_mode is dns | `None` | DNS plugin credentials to use. | +| `webroot` | `str` | `False`, `True` if acme_mode is webroot | `None` | Webroot path to use. | +| `http_port` | `str` | `False` | `80` | HTTP port to use. | +| `user` | `str` | `False` | `root` | User to run acme.sh as. | +| `cert_path` | `str` | `False` | `$HOME/.acme.sh` | Path to store certificates in. | +| `force` | `bool` | `False` | `False` | Force issue certificate. | +| `valid_to` | `str` | `False` | `None` | Validity of certificate. | +| `valid_from` | `str` | `False` | `None` | Validity of certificate. | +| `insecure` | `bool` | `False` | `False` | Don't verify SSL-Cert of acme server | + +**Server** + +You can define a custom server, or use one of the following: + +https://github.com/acmesh-official/acme.sh/wiki/Server + +**DNS Plugins** + +You can use the following DNS plugins: + +https://github.com/acmesh-official/acme.sh/wiki/dnsapi + +**DNS Credentials** + +Credentials are defined as a dictionary: + +`{ "key": "value" }` + +If acme mode is `dns`, this parameter is required. + +**Keysize** + +The following key sizes are supported: + +https://github.com/acmesh-official/acme.sh#10-issue-ecc-certificates + +**Cert Path** + +The cert path default is `$HOME/.acme.sh`. +If you specify a different path, e.g. `/etc/acme`, your certificate will be stored `/etc/acme/example.com`. + +### acme_sh.install + +Installs `acme.sh`. + +| Parameter | Type | Required | Default | Description | +| --------- | ------ | -------- | ------- | -------------------------------------- | +| `email` | `str` | `True` | | Email address to use for registration. | +| `user` | `str` | `False` | `root` | User to run acme.sh as. | +| `upgrade` | `bool` | `False` | `False` | Upgrade acme.sh. | +| `force` | `bool` | `False` | `False` | Force install acme.sh. | + +The installation is done with `--nocron` parameter. + +### acme_sh.register + +Register account @ zeroSSL CA. + +| Parameter | Type | Required | Default | Description | +| --------- | ----- | -------- | ------- | ----------------------- | +| `email` | `str` | `True` | | Email address to use. | +| `user` | `str` | `False` | `root` | User to run acme.sh as. | + +### acme_sh.renew + +Renews a certificate with `acme.sh`. + +| Parameter | Type | Required | Default | Description | +| ----------- | ------ | -------- | ---------------- | ------------------------------------ | +| `name` | `str` | `True` | | Domain to renew certificate for. | +| `user` | `str` | `False` | `root` | User to run acme.sh as. | +| `cert_path` | `str` | `False` | `$HOME/.acme.sh` | Path to store certificates in. | +| `force` | `bool` | `False` | `False` | Force renew certificate. | +| `insecure` | `bool` | `False` | `False` | Don't verify SSL-Cert of acme server | + +### acme_sh.info + +Returns information about a certificate. + +| Parameter | Type | Required | Default | Description | +| ----------- | ----- | -------- | ---------------- | ------------------------------------- | +| `name` | `str` | `True` | | Domain name of certificate | +| `user` | `str` | `False` | `root` | User to run acme.sh as. | +| `cert_path` | `str` | `False` | `$HOME/.acme.sh` | Path where certificates are stored in | + +### acme.sh_version + +Returns the version of `acme.sh`. + +| Parameter | Type | Required | Default | Description | +| --------- | ----- | -------- | ------- | ----------------------- | +| `user` | `str` | `False` | `root` | User to run acme.sh as. | + +## Examples + +### Install acme.sh for user acme + +```bash +salt '*' acme_sh.install user=acme +``` + +### Upgrade acme.sh installation + +```bash +salt '*' acme_sh.install user=acme upgrade=True +``` + +### Issue certificate with webroot + +```bash +salt '*' acme_sh.issue example.com acme_mode=webroot webroot=/var/www +``` + +### Issue certificate with Hetzner dns + +```bash +salt '*' acme_sh.issue example.com acme_mode=dns dns_plugin=dns_hetzner dns_credentials='{"HETZNER_Token": "tokenxxxxx"}' +``` + +### Issue certificate with standalone and aliases + +```bash +salt '*' acme_sh.issue example.com acme_mode=standalone aliases=www.example.com,example.org +``` + +### Renew certificate + +```bash +salt '*' acme_sh.renew example.com +``` diff --git a/doc/state_acme_sh.md b/doc/state_acme_sh.md new file mode 100644 index 0000000..38bb0aa --- /dev/null +++ b/doc/state_acme_sh.md @@ -0,0 +1,64 @@ +# State Module acme_sh + +You can use this state module to issue or renew certificates with `acme.sh`. + +## Available state functions + +- [acme_sh.installed](#acme_shinstalled) +- [acme_sh.cert](#acme_shcert) + +### acme_sh.installed + +Installs `acme.sh`. + +| Parameter | Type | Required | Default | Description | +| --------- | ------ | -------- | ------- | -------------------------------------- | +| `email` | `str` | `True` | | Email address to use for registration. | +| `user` | `str` | `False` | `root` | User to run acme.sh as. | +| `upgrade` | `bool` | `False` | `False` | Upgrade acme.sh. | +| `force` | `bool` | `False` | `False` | Force install acme.sh. | + +### acme_sh.cert + +Ensures that a certificate is issued and valid with `acme.sh`. + +| Parameter | Type | Required | Default | Description | +| ----------------- | ------ | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------- | +| `name` | `str` | `True` | | Domain to issue certificate for. | +| `acme_mode` | `str` | `True` | | Mode to issue certificate with. (webroot, standalone, standalone-tls-alpn, dns) | +| `aliases` | `list` | `False` | `None` | List of aliases to issue certificate for. | +| `server` | `str` | `False` | `letsencrypt` | ACME server to use. | +| `keysize` | `str` | `False` | `4096` | Key size to use. | +| `dns_plugin` | `str` | `False`, `True` if acme_mode is dns | `None` | DNS plugin to use. | +| `dns_credentials` | `dict` | `False`, `True` if acme_mode is dns | `None` | DNS plugin credentials to use. | +| `webroot` | `str` | `False`, `True` if acme_mode is webroot | `None` | Webroot path to use. | +| `http_port` | `str` | `False` | `80` | HTTP port to use. | +| `user` | `str` | `False` | `root` | User to run acme.sh as. | +| `cert_path` | `str` | `False` | `$HOME/.acme.sh` | Path to store certificates in. | +| `force` | `bool` | `False` | `False` | Force issue certificate. | +| `valid_to` | `str` | `False` | `None` | Validity of certificate. | +| `valid_from` | `str` | `False` | `None` | Validity of certificate. | +| `insecure` | `bool` | `False` | `False` | Don't verify SSL-Cert of acme server | + +**DNS Credentials** + +Credentials are defined as a dictionary. +You are able to define the credentials by creating environment variables. +The environment variables must be prefixed with `ACMESH_` and have the following format: + +`ACMESH_{user}_{domain}_{key}`: `ACMESH_root_exampleCom_HETZNER_Token` + +Please note the camel case of the domain: + +`example.com` -> `exampleCom` +`example.co.uk` -> `exampleCoUk` + +A dash `-` in the domain is currently not supported. + +**Further information** + +[See execution module documentation](./module_acme_sh.md#acme_shissue) + +## Examples + +You can use the predefined salt states in combination with the pillar structure from [`example.yml`](../example.yml).