# 🔐 dynTLS

**Granular Let's Encrypt certificate management for multi-service environments**  
Provides flexible ACME backend integration, DNS/http challenges and per-service certificate deployment.

This utility simplifies issuing and managing TLS certificates via Let’s Encrypt for multiple services and hosts (e.g. Postfix, Dovecot, web servers and others). It separates ACME handling from deployment logic, supports HTTP-01 and DNS-01 challenges and maps issued certificates cleanly to individual services.

Key features:

- 🔁 Automated issuance and renewal of Let’s Encrypt certificates
- 🌐 Support for HTTP-01 and DNS-01 challenges via external ACME client
- 🧩 Flexible ACME backend selection (e.g. customized `letsencrypt_master_local.sh`)
- 🎯 Per-host and per-service certificate mapping with backup handling
- 📜 Central configuration via `vars` file
- 📂 Plain repository layout with optional contrib scripts under `./contrib/acme`

---

## Outline

1. [Features](#features)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Directory Layout](#directory-layout)
5. [CRON Job Example](#cron-job-example)
6. [ACME Backend](#acme-backend)
7. [License](#license)
8. [Authors](#authors)
9. [Project Home](#project-home)

---

## Features

- Manages Let’s Encrypt certificates for multiple domains and services
- Uses a configurable ACME backend script (e.g. `letsencrypt_master_local.sh`)
- Supports HTTP-01 and DNS-01 challenges (e.g. via Bind/nsupdate, TSIG, `rndc`)
- Validates hostnames, SAN lists and certificate expiration before deployment
- Creates backups of replaced certificates and can prune old backups
- Logs operations with log levels and domain-set IDs for better traceability

## Installation

The following steps describe a simple, source-based installation.

1. Clone the repository

   ```bash
   git clone https://dev.town-square.de/cb601/dyntls.git /opt/dyntls
   
   cd /opt/dyntls
   ```
2. Install required packages

   Make sure you have at least:
   - openssl
   - nsupdate / bind-utils (for DNS-01 with Bind, if used)
   - curl or wget (depending on your ACME script)

   On RPM-based systems, for example:

   ```bash
   sudo dnf install openssl bind-utils curl -y
   ```
3. Prepare configuration

   Copy the example vars file and adapt it to your environment:

   ```bash
   sudo cp vars.example vars
   sudo chmod 640 vars
   ```
4. Test a dry run

   Before using dynTLS in production, run a dry or staging-mode test (example):

   ```bash
   ./dyntls.sh help
   ```

## Configuration

dynTLS is configured via a `vars` file (e.g. `vars` or `vars.example`) which defines:

- Base directories for PKI and HTTP token storage
- ACME backend script path (`DYNTLS_LE_PROGRAM`)
- Certificate renewal thresholds and backup behavior
- Domain lists and service mappings

Key options include, for example:

- `DYNTLS_LE_PROGRAM` – path to the external ACME client script
- `DYNTLS_PKI` – root PKI directory (certificates, keys, backups)
- `DYNTLS_PKI_CERT_EXPIRE` – minimum remaining validity (days) before renewal
- `DYNTLS_DOMAIN_LIST` – list of domains (CN + SANs) for a certificate
- `DYNTLS_DOMAINSERVICE_LIST` – mapping from certificate CN to service target(s)

You can keep `vars.example` under version control and use a separate, local `vars` file (ignored by Git) for host-specific secrets and paths.

## Directory Layout

Minimal plain layout in the repository:

```text
./
├── dyntls                 # main dynTLS script
├── vars.example           # example configuration
├── LICENSE.md             # project license
├── README.md              # this file
└── contrib/
    └── acme/
        ├── letsencrypt_master.sh
        └── letsencrypt_master_local.sh
```

Suggested runtime layout on a host (example):

| Path                        | Purpose                         |
|-----------------------------|---------------------------------|
| /opt/dyntls/dyntls.sh       | Main script                     |
| /opt/dyntls/vars.example    | Example config (reference)      |
| /opt/dyntls/vars            | User config (never overwritten) |
| /etc/pki/httpd/certs        | Issued certificates             |
| /etc/pki/httpd/private      | Private keys                    |
| /etc/pki/httpd/certs/backup | Certificate backups             |
| /var/log/dyntls/dyntls.log  | dynTLS log file                 |
| /etc/cron.daily/dyntls      | Cron job script (optional)      |

Adjust these paths in your `vars` file according to your distribution and service layout.

## CRON Job Example

To run the key generator daily, you have two options:

1. Crontab

   You can add a daily cron job directly to the root user's crontab:

   Open the root crontab for editing:

   ```bash
   sudo crontab -e
   ```

   Add the following line to run the script daily at 3:30 AM:

   ```bash
   # Staging mode
   30 3 * * * /opt/dyntls/dyntls.sh update-cert
   
   # Productive mode
   #30 3 * * * /opt/dyntls/dyntls.sh -P update-cert
   ```

   *(Adjust the schedule as needed. This example runs the script daily.)*
2. System Cron Daily Directory

   Create a script as `/etc/cron.daily/dyntls`:

   ```bash
   #!/bin/sh
   
   # Staging mode
   /opt/dyntls/dyntls.sh update-cert
   
   # Productive mode
   #/opt/dyntls/dyntls.sh -P update-cert
   
   exit 0
   ```

   Ensure the script is executable:

   ```bash
   sudo chmod 750 /etc/cron.daily/dyntls
   ```

## ACME Backend

dynTLS does not implement the ACME protocol itself. Instead, it delegates all ACME communication to an external client script configured via `DYNTLS_LE_PROGRAM`.

In this repository, ACME-related scripts are placed under:

- `contrib/acme/letsencrypt_master.sh`
  Upstream ACME client script, unchanged.
- `contrib/acme/letsencrypt_master_local.sh`
  Local variant with customized `dns-01` challenge handling, for example using Bind/nsupdate, TSIG and `rndc` to manage internal DNS zones.

Both scripts are based on the upstream `ght-acme.sh` client (<https://github.com/bruncsak/ght-acme.sh>) and are licensed under the GNU GPLv2-or-later; see `LICENSE.md` and the script headers for details.
  
Example configuration in `vars`:

```bash
# Use local ACME backend
setvar DYNTLS_LE_PROGRAM "contrib/acme/letsencrypt_master_local.sh"

# Pass DNS parameters to the ACME script (exported to its environment)
set_var DYNTLS_DNS_SERVER "root-dns.example365.tld"
set_var DYNTLS_DNS_TSIG   "/opt/dyntls/private/tsig.key"
```

You can replace this with other ACME clients (e.g. acme.sh, lego) by pointing `DYNTLS_LE_PROGRAM` to your preferred script and ensuring its CLI options match your setup.

## License

[MIT](https://dev.town-square.de/cb601/dyntls/src/branch/main/LICENSE)

See `LICENSE.md` for details and third-party license information.

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