dyntls/README.md

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
• Installation
• Configuration
• Directory Layout
• CRON Job Example
• ACME Backend
• License
• Authors
• 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:

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

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

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:

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

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

See LICENSE for details and third-party licensing notes.

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