Skip to content

Commit

Permalink
Merge pull request #8 from genaumann/docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@genaumann
genaumann authored Oct 14, 2024
2 parents 6ea5aa0 + b169a82 commit 300fae9
Show file tree
Hide file tree
Showing 3 changed files with 33 additions and 42 deletions.
32 changes: 10 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,32 +28,32 @@ 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`](acme_sh/init.sls)
- [`acme_sh.install`](acme_sh/install.sls)
- [`acme_sh.issue`](acme_sh/issue.sls)

### `acme.sh`
### `acme_sh`

Includes the following states:

- `acme.sh.install`
- `acme.sh.issue`
- `acme_sh.install`
- `acme_sh.issue`

### `acme.sh.install`
### `acme_sh.install`

Installs `acme.sh`.

### `acme.sh.issue`
### `acme_sh.issue`

Issues or renews certificate with `acme.sh`.

## Available execution modules

- [`acme.sh`](docs/module_acme_sh.md)
- [`acme_sh`](docs/module_acme_sh.md)

## Available state modules

- [`acme.sh`](docs/state_acme_sh.md)
- [`acmesh`](docs/state_acme_sh.md)

## Testing

Expand All @@ -78,18 +78,6 @@ kitchen list # list all available test instances
kitchen test <instance>
```

## OS support matrix

This formula has been tested under the following operating systems and salt versions.

| 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
[test_badge]: https://github.com/genaumann/salt-acme.sh-formula/actions/workflows/salt-kitchen.yml/badge.svg?branch=main
6 changes: 3 additions & 3 deletions doc/module_acme_sh.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Execution Module acme_sh

The `acme.sh` module provides an interface to [acme.sh](https://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.
Expand All @@ -12,7 +12,7 @@ Of course you can change the cert path with the `cert_path` parameter.
- [acme_sh.install](#acme_shinstall)
- [acme_sh.renew](#acme_shrenew)
- [acme_sh.info](#acme_shinfo)
- [acme.sh_version](#acmesh_version)
- [acme_shl.version](#acmesh_version)

### acme_sh.issue

Expand Down Expand Up @@ -111,7 +111,7 @@ Returns information about a 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
### acme_sh.version

Returns the version of `acme.sh`.

Expand Down
37 changes: 20 additions & 17 deletions doc/state_acme_sh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,23 +22,24 @@ Installs `acme.sh`.

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 |
| 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 |
| `retry` | `dicts` | `False` | `None` | Set state retry - see [State Retry docs][1] |

**DNS Credentials**

Expand All @@ -62,3 +63,5 @@ A dash `-` in the domain is currently not supported.
## Examples

You can use the predefined salt states in combination with the pillar structure from [`example.yml`](../example.yml).

[1]: https://docs.saltproject.io/en/latest/ref/states/requisites.html#retrying-states

0 comments on commit 300fae9

Please sign in to comment.