dyntls/README.md

🔐 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
2. Installation
3. Configuration
4. Directory Layout
5. CRON Job Example
6. ACME Backend
7. License
8. Authors
9. 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

   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:

   • bash
   • 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:

   sudo dnf install openssl bind-utils curl -y
   

3. Prepare configuration

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

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

   ./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:

./
├── 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:

   sudo crontab -e
   

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

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

   #!/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:

   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 (reference), unchanged or only minimally modified.
• 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.

Example configuration in vars:

# 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

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

Authors

CB-601 - the open tec Elevator

• Stephan Düsterhaupt
• Ivo Noack aka Insonic

Project Home

Project Home: https://dev.town-square.de/cb601/dyntls