165 lines
5.5 KiB
Markdown
165 lines
5.5 KiB
Markdown
# dynTLS
|
|
|
|
Granular Let's Encrypt certificate management for multi-service environments.
|
|
|
|
This repository provides the backend components for issuing, renewing and deploying TLS certificates in self-hosted, multi-service environments. It separates ACME handling from deployment logic, supports HTTP-01 and DNS-01 challenge workflows and maps issued certificates cleanly to individual services and hosts.
|
|
|
|
## Outline
|
|
|
|
- [Features](#features)
|
|
- [Installation](#installation)
|
|
- [Configuration](#configuration)
|
|
- [Directory Layout](#directory-layout)
|
|
- [CRON Job Example](#cron-job-example)
|
|
- [ACME Backend](#acme-backend)
|
|
- [License](#license)
|
|
- [Authors](#authors)
|
|
- [Project Home](#project-home)
|
|
|
|
## Features
|
|
|
|
- Certificate management for multiple domains and services
|
|
- Configurable external ACME backend integration
|
|
- HTTP-01 and DNS-01 challenge support
|
|
- Per-host and per-service certificate mapping
|
|
- Backup creation and optional backup pruning
|
|
- Central configuration through a separate `vars` file
|
|
- Log output with domain-set context for traceability
|
|
- Designed for self-hosted Linux environments
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository.
|
|
2. Install the required packages for your platform.
|
|
3. Copy `vars.example` to a local `vars` file.
|
|
4. Adjust paths, ACME backend settings and domain/service mappings.
|
|
5. Run the script manually once before enabling automation.
|
|
|
|
Example:
|
|
|
|
```sh
|
|
sudo groupadd --system dyntls
|
|
sudo install -d -m 0750 -o root -g dyntls /opt/dyntls
|
|
git clone https://dev.town-square.de/cb601/dyntls.git /opt/dyntls
|
|
|
|
cd /opt/dyntls
|
|
|
|
sudo cp vars.example vars
|
|
sudo chown root:dyntls /opt/dyntls/dyntls.sh /opt/dyntls/vars
|
|
sudo chmod 0750 /opt/dyntls/dyntls.sh
|
|
sudo chmod 0640 /opt/dyntls/vars
|
|
|
|
sudo /opt/dyntls/dyntls.sh help
|
|
```
|
|
|
|
For DNS-01 workflows with BIND, ensure the required tools such as `nsupdate` and `rndc` are available and that the configured TSIG key and zone permissions are valid.
|
|
|
|
## Configuration
|
|
|
|
The backend is configured through a separate configuration file derived from `vars.example`.
|
|
|
|
Typical settings include:
|
|
|
|
- Base directories for PKI data and HTTP token storage
|
|
- Path to the external ACME backend script via `DYNTLS_LE_PROGRAM`
|
|
- Renewal thresholds and backup retention settings
|
|
- Domain definitions, including CN and SAN sets
|
|
- Service mapping definitions for certificate deployment targets
|
|
- Optional DNS parameters for DNS-01 automation
|
|
|
|
Recommended workflow:
|
|
|
|
1. Start from `vars.example`.
|
|
2. Create an environment-specific copy, for example `vars`.
|
|
3. Keep secrets and local overrides out of version control.
|
|
4. Validate ACME execution, challenge handling and deployment paths before enabling cron-based automation.
|
|
|
|
## Directory Layout
|
|
|
|
```text
|
|
.
|
|
├── dyntls.sh
|
|
├── vars.example
|
|
├── README.md
|
|
├── LICENSE
|
|
└── contrib/
|
|
└── acme/
|
|
├── letsencrypt_master.sh
|
|
└── letsencrypt_master_local.sh
|
|
```
|
|
|
|
Suggested runtime layout on a host:
|
|
|
|
| Path | Purpose |
|
|
|------------------------------|-------------------------------------------------|
|
|
| `/opt/dyntls/dyntls.sh` | Main script |
|
|
| `/opt/dyntls/vars.example` | Reference configuration |
|
|
| `/opt/dyntls/vars` | Local configuration with host-specific settings |
|
|
| `/etc/pki/...` | Certificate and key deployment targets |
|
|
| `/var/log/dyntls/dyntls.log` | dynTLS log file |
|
|
| `/etc/cron.daily/dyntls` | Optional cron wrapper |
|
|
|
|
Adjust all runtime paths in the `vars` file to match your distribution, PKI layout and service-specific deployment targets.
|
|
|
|
## CRON Job Example
|
|
|
|
The following examples show two common ways to automate certificate checks and renewals.
|
|
|
|
Crontab example:
|
|
|
|
```sh
|
|
30 3 * * * /opt/dyntls/dyntls.sh update-cert
|
|
#30 3 * * * /opt/dyntls/dyntls.sh -P update-cert
|
|
```
|
|
|
|
Running the job once per night at 03:30 is a reasonable default for typical `dynTLS` use cases.
|
|
|
|
System cron directory example:
|
|
|
|
```sh
|
|
#!/bin/sh
|
|
|
|
/opt/dyntls/dyntls.sh update-cert
|
|
#/opt/dyntls/dyntls.sh -P update-cert
|
|
|
|
exit 0
|
|
```
|
|
|
|
The commented lines illustrate a productive mode variant. Use a staging or non-productive mode first until ACME validation, deployment hooks and rollback behavior are verified.
|
|
|
|
## ACME Backend
|
|
|
|
dynTLS does not implement the ACME protocol itself. Instead, it delegates ACME communication to an external client script configured through `DYNTLS_LE_PROGRAM`.
|
|
|
|
In this repository, ACME-related helper scripts are located under `contrib/acme`:
|
|
|
|
- `letsencrypt_master.sh` for the upstream-oriented ACME helper
|
|
- `letsencrypt_master_local.sh` for a locally adapted variant, for example with customized DNS-01 handling via BIND, `nsupdate`, TSIG and `rndc`
|
|
|
|
Example configuration:
|
|
|
|
```sh
|
|
set_var DYNTLS_LE_PROGRAM "contrib/acme/letsencrypt_master_local.sh"
|
|
set_var DYNTLS_DNS_SERVER "root-dns.example365.tld"
|
|
set_var DYNTLS_DNS_TSIG "/opt/dyntls/private/tsig.key"
|
|
```
|
|
|
|
You can replace the bundled backend helper with another ACME client integration if its invocation and parameter handling match your deployment workflow.
|
|
|
|
## License
|
|
|
|
[MIT](https://dev.town-square.de/cb601/dyntls/src/branch/main/LICENSE)
|
|
|
|
See `LICENSE` for details and third-party licensing notes.
|
|
|
|
## Authors
|
|
|
|
CB-601 - the open tec Elevator
|
|
|
|
- [Stephan Düsterhaupt](xmpp:me@jabber.stephanduesterhaupt.de)
|
|
- [Ivo Noack](xmpp:me@jabber.ivonoack.de) aka Insonic
|
|
|
|
## Project Home
|
|
|
|
Project Home: [https://dev.town-square.de/cb601/dyntls](https://dev.town-square.de/cb601/dyntls)
|