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