release: improve Linux defaults and harden renewal workflow

certbro-public-snapshot: true
certbro-private-commit: ad4d3a36837bfe3f27b79a11c65f433a6db0020c
certbro-private-branch: main

Author: amallek

CHANGES.md

@@ -0,0 +1,28 @@
+# Changes
+
+This file summarizes notable changes from the most recent committed updates.
+
+## 2026-03-22
+
+- Added English and German validity-management guides and updated the existing renewal, issuing, quick-start, and Ubuntu example docs to describe the new lifetime rules and short-lifetime examples correctly.
+- Expanded regression coverage for schedule transitions, renewal timing validation, legacy lead-time normalization, and recent-issuance cooldown behavior.
+- Added a 48-hour cooldown after fresh issuance. Non-forced renewal runs now skip certificates that were issued less than 48 hours ago.
+- Added self-healing for legacy managed certificates with overly large lead times. During renewals, stored lead times are reduced to `validity_days - 1` when needed.
+- Added renewal timing validation to prevent immediate renewal or reissue loops. New and updated configurations now require `validity_days` to be greater than both `renew_before_days` and `reissue_lead_days`.
+- Added automatic normalization of stored `validity_days` during renewals. If an older managed certificate still stores a now-too-large value, `certbro renew` uses the current schedule-aware default and persists the adjusted value after a successful run.
+- Moved the schedule-aware CA/B validity handling one day earlier than the official transition dates, so `certbro` starts using the upcoming lower defaults on `2026-03-14`, `2027-03-14`, and `2029-03-14`.
+
+---
+
+- The Linux install check now passes an explicit certificates root to `certbro install`, keeping the smoke run self-contained and repeatable.
+- The smoke test now uses temporary values for `CERTBRO_CERTIFICATES_DIR` and `CERTBRO_RENEW_LOCK_FILE`, so it no longer touches `/etc/certbro`.
+- Hardened `scripts/test-smoke.sh` for the Linux default paths introduced in the previous commit.
+
+---
+
+- Cleaned up repository maintenance scripts and ignored local helper script copies in `.gitignore`.
+- Updated the English and German README/getting-started guides to document the Linux defaults and the system-wide deployment layout.
+- Added regression tests for the Linux default paths and for preserving verified API settings during renew discovery.
+- Fixed `renew` discovery so runs with a certificates directory preserve verified global API configuration, including `api_key_validated_at`.
+- Updated the CLI root defaults so `--state-file` and `--certificates-dir` follow those Linux system paths by default.
+- Switched the default Linux paths to `/etc/certbro/state.json` for the global state file and `/etc/certbro` for managed certificate directories.

README.de.md

@@ -83,9 +83,9 @@ sudo certbro --state-file /etc/certbro/state.json install \
 - Paralleler RSA- und ECDSA-Betrieb: `certbro issue-pair`
 - Bereits bestehende regfish-Bestellungen: Import per `certificate_id`
 - Sofortiger Ersatz: `certbro renew --name example-com --force`
-- Einmaliger Laufzeit-Override: `certbro renew --name example-com --force --validity-days 3`
+- Einmaliger Laufzeit-Override: `certbro renew --name example-com --force --validity-days 30`
 - Pending-Ausstellung nach Timeout: `certbro renew --name example-com` erneut ausführen, um denselben Request weiter zu beobachten
-- Wenn `--validity-days` fehlt, verwendet `certbro` einen datumsabhängigen Default gemäß CA/B-Forum-Zeitplan: `199` Tage ab 2026-03-15, `99` Tage ab 2027-03-15 und `46` Tage ab 2029-03-15
+- Wenn `--validity-days` fehlt, verwendet `certbro` einen datumsabhängigen Default mit einem Sicherheitspuffer von einem Tag vor jedem CA/B-Forum-Stichtag: `199` Tage ab 2026-03-14, `99` Tage ab 2027-03-14 und `46` Tage ab 2029-03-14
 - Ruhige Ausgabe für Automatisierung: `--quiet` bei `issue` oder `renew`
 
 ## Dokumentation

README.md

@@ -83,9 +83,9 @@ sudo certbro --state-file /etc/certbro/state.json install \
 - Dual RSA and ECDSA deployment: use `certbro issue-pair`
 - Existing regfish orders: import by `certificate_id`
 - Immediate replacement: `certbro renew --name example-com --force`
-- One-off renewal lifetime override: `certbro renew --name example-com --force --validity-days 3`
+- One-off renewal lifetime override: `certbro renew --name example-com --force --validity-days 30`
 - Pending issuance after a timeout: rerun `certbro renew --name example-com` to resume monitoring the existing request
-- If `--validity-days` is omitted, `certbro` uses a date-aware default aligned with the CA/B Forum validity schedule: `199` days from 2026-03-15, `99` days from 2027-03-15, and `46` days from 2029-03-15
+- If `--validity-days` is omitted, `certbro` uses a date-aware default with a one-day safety margin before each CA/B Forum transition: `199` days from 2026-03-14, `99` days from 2027-03-14, and `46` days from 2029-03-14
 - Quiet output for automation: add `--quiet` to `issue` or `renew`
 
 ## Documentation

docs/de/README.md

@@ -12,6 +12,7 @@ Dieses Verzeichnis enthält die deutschsprachigen Betriebs- und Nutzungshinweise
 ## Zertifikats-Workflows
 
 - [Zertifikate bestellen](issuing-certificates.md): Single-Domain, SANs, Produktauswahl, Key-Algorithmen, Laufzeitplan und leise Ausgabe
+- [Laufzeitverwaltung](validity-management.md): gespeicherte Laufzeiten manuell ändern und automatisch an künftige Limits anpassen
 - [Parallele RSA- und ECDSA-Zertifikate](dual-certificates.md): gleichzeitiger Betrieb für moderne und ältere TLS-Clients
 - [Renewals und Ersatz](renewals-and-replacement.md): reguläre Renewals, erzwungene Renewals, Laufzeit-Overrides, künftige CA/B-Forum-Limits und schneller Ersatz
 - [Bestehende Zertifikate importieren](import-existing-certificates.md): Zertifikate aus der regfish UI unter `certbro`-Verwaltung übernehmen

docs/de/examples/ubuntu-apache-certbro.md

@@ -35,6 +35,8 @@ export HOST_FQDN='example.certbro.com'
 export CERTBRO_NAME='example-certbro-com'
 export CERTBRO_PRODUCT='RapidSSL'
 export CERTBRO_VALIDITY_DAYS='3'
+export CERTBRO_RENEW_BEFORE_DAYS='2'
+export CERTBRO_REISSUE_LEAD_DAYS='2'
 export WEBROOT="/var/www/${HOST_FQDN}/html"
 export CERTBRO_DIR="/etc/certbro/${HOST_FQDN}"
 export CERTBRO_STATE_FILE='/etc/certbro/state.json'
@@ -222,6 +224,8 @@ sudo certbro --state-file "${CERTBRO_STATE_FILE}" issue \
   --common-name "${HOST_FQDN}" \
   --product "${CERTBRO_PRODUCT}" \
   --validity-days "${CERTBRO_VALIDITY_DAYS}" \
+  --renew-before-days "${CERTBRO_RENEW_BEFORE_DAYS}" \
+  --reissue-lead-days "${CERTBRO_REISSUE_LEAD_DAYS}" \
   --webserver apache \
   --output-dir "${CERTBRO_DIR}"
 ```
@@ -321,6 +325,8 @@ sudo certbro --state-file "${CERTBRO_STATE_FILE}" renew \
   --validity-days "${CERTBRO_VALIDITY_DAYS}"
 ```
 
+Das `3`-Tage-Beispiel funktioniert nur, weil die gespeicherten Lead-Tage auf `2` gesetzt wurden. `certbro` lehnt Laufzeiten ab, die nicht größer sind als die Renewal-Lead-Tage.
+
 `--force` nur verwenden, wenn bewusst ein echter Renewal- oder Reissue-Flow für Tests ausgelöst werden soll.
 
 Service-Logs prüfen:

docs/de/examples/ubuntu-nginx-certbro.md

@@ -34,6 +34,8 @@ export HOST_FQDN='example.certbro.com'
 export CERTBRO_NAME='example-certbro-com'
 export CERTBRO_PRODUCT='RapidSSL'
 export CERTBRO_VALIDITY_DAYS='3'
+export CERTBRO_RENEW_BEFORE_DAYS='2'
+export CERTBRO_REISSUE_LEAD_DAYS='2'
 export WEBROOT="/var/www/${HOST_FQDN}/html"
 export CERTBRO_DIR="/etc/certbro/${HOST_FQDN}"
 export CERTBRO_STATE_FILE='/etc/certbro/state.json'
@@ -230,6 +232,8 @@ sudo certbro --state-file "${CERTBRO_STATE_FILE}" issue \
   --common-name "${HOST_FQDN}" \
   --product "${CERTBRO_PRODUCT}" \
   --validity-days "${CERTBRO_VALIDITY_DAYS}" \
+  --renew-before-days "${CERTBRO_RENEW_BEFORE_DAYS}" \
+  --reissue-lead-days "${CERTBRO_REISSUE_LEAD_DAYS}" \
   --webserver nginx \
   --webserver-config /etc/nginx/nginx.conf \
   --key-type ecdsa \
@@ -338,6 +342,8 @@ sudo certbro --state-file "${CERTBRO_STATE_FILE}" renew \
   --validity-days "${CERTBRO_VALIDITY_DAYS}"
 ```
 
+Das `3`-Tage-Beispiel funktioniert nur, weil die gespeicherten Lead-Tage auf `2` gesetzt wurden. `certbro` lehnt Laufzeiten ab, die nicht größer sind als die Renewal-Lead-Tage.
+
 `--force` nur verwenden, wenn bewusst ein echter Renewal- oder Reissue-Flow für Tests ausgelöst werden soll.
 
 Service-Logs prüfen:

docs/de/getting-started.md

@@ -51,7 +51,7 @@ sudo certbro --state-file /etc/certbro/state.json issue \
   --output-dir /etc/certbro/example.com
 ```
 
-Wenn `--validity-days` nicht gesetzt ist, wählt `certbro` automatisch einen datumsabhängigen Default gemäß CA/B-Forum-Zeitplan. Die aktuellen Defaults sind `199` Tage ab `2026-03-15`, `99` Tage ab `2027-03-15` und `46` Tage ab `2029-03-15`.
+Wenn `--validity-days` nicht gesetzt ist, wählt `certbro` automatisch einen datumsabhängigen Default mit einem Sicherheitspuffer von einem Tag vor jedem CA/B-Forum-Stichtag. Die aktuellen Defaults sind `199` Tage ab `2026-03-14`, `99` Tage ab `2027-03-14` und `46` Tage ab `2029-03-14`.
 
 Nach erfolgreicher Bestellung schreibt `certbro` unter anderem:
 

docs/de/issuing-certificates.md

@@ -18,15 +18,17 @@ Wenn `--validity-days` nicht gesetzt ist, nutzt `certbro` einen datumsabhängige
 
 ## Laufzeit-Zeitplan
 
-`certbro` folgt dem CA/B-Forum-Zeitplan für öffentlich vertrauenswürdige TLS-Zertifikate.
+`certbro` folgt dem CA/B-Forum-Zeitplan für öffentlich vertrauenswürdige TLS-Zertifikate und beginnt aus Sicherheitsgründen jeweils einen Tag früher mit dem niedrigeren Default.
 
-- Vor `2026-03-15` ausgestellte Zertifikate: maximal `398` Tage, Default `397`
-- Ab `2026-03-15` und vor `2027-03-15`: maximal `200` Tage, Default `199`
-- Ab `2027-03-15` und vor `2029-03-15`: maximal `100` Tage, Default `99`
-- Ab `2029-03-15`: maximal `47` Tage, Default `46`
+- Vor `2026-03-14` ausgestellte Zertifikate: maximal `398` Tage, Default `397`
+- Ab `2026-03-14` und vor `2027-03-14`: maximal `200` Tage, Default `199`
+- Ab `2027-03-14` und vor `2029-03-14`: maximal `100` Tage, Default `99`
+- Ab `2029-03-14`: maximal `47` Tage, Default `46`
 
 Wenn `--validity-days` gesetzt wird, validiert `certbro` den Wert vor der Bestellung gegen das aktuell gültige Limit.
 
+Die gewünschte Laufzeit muss außerdem größer sein als `--renew-before-days` und `--reissue-lead-days`. So verhindert `certbro`, dass direkt nach der Ausstellung sofort wieder ein Renewal oder Reissue fällig wird.
+
 ## Subject Alternative Names
 
 `--dns-name` für jede SAN wiederholen:

docs/de/renewals-and-replacement.md

@@ -24,6 +24,8 @@ sudo certbro --state-file /etc/certbro/state.json --certificates-dir /etc/certbr
 
 Wenn eine Bestellung beim Erreichen des Wait-Timeouts noch `pending` ist, kann später einfach `certbro renew` erneut ausgeführt werden. `certbro` beobachtet dann denselben offenen Request weiter und startet keine doppelte Bestellung.
 
+Damit frisch ausgestellte Zertifikate nicht sofort wieder in den Renewal-Flow geraten, überspringt `certbro` außerdem Zertifikate, die jünger als `48` Stunden sind, solange `--force` nicht gesetzt ist.
+
 ## Renewal vs. Reissue
 
 `certbro` wählt automatisch den passenden regfish-API-Flow:
@@ -53,11 +55,13 @@ Wenn für einen erzwungenen Renewal-Lauf oder eine neue Renewal-Order eine ander
 sudo certbro --state-file /etc/certbro/state.json renew \
   --name example-com \
   --force \
-  --validity-days 3
+  --validity-days 30
 ```
 
 `--validity-days` gilt in diesem Lauf für Renewal-Orders und neue Orders. Für Reissues gilt der Wert nicht.
 
+Die gewünschte Laufzeit muss dabei größer bleiben als die gespeicherten Werte für `renew_before_days` und `reissue_lead_days`. Für sehr kurz laufende Zertifikate sollten diese Lead-Tage zuerst abgesenkt werden.
+
 Den gespeicherten Default für künftige Renewal-Orders ändern:
 
 ```sh
@@ -66,16 +70,23 @@ sudo certbro --state-file /etc/certbro/state.json update \
   --validity-days 90
 ```
 
-Wenn gespeicherte `validity_days` später über dem aktiven CA/B-Forum-Limit liegen, bricht `certbro` vor der Bestellung sauber ab, damit die Laufzeit explizit angepasst werden kann.
+Wenn gespeicherte `validity_days` später über dem aktiven schedule-aware Limit liegen, verwendet `certbro renew` automatisch den aktuellen schedule-aware Default und speichert den angepassten Wert nach erfolgreichem Renewal dauerhaft zurück.
 
-Die aktiven CA/B-Forum-Limits sind:
+Offizielle CA/B-Forum-Limits:
 
 - vor `2026-03-15`: maximal `398` Tage
 - ab `2026-03-15`: maximal `200` Tage
 - ab `2027-03-15`: maximal `100` Tage
 - ab `2029-03-15`: maximal `47` Tage
 
-Die dazugehörigen schedule-aware Defaults in `certbro` sind `397`, `199`, `99` und `46` Tage.
+`certbro` beginnt aus Sicherheitsgründen jeweils einen Tag früher mit dem niedrigeren Default. Die dazugehörigen schedule-aware Defaults sind:
+
+- vor `2026-03-14`: `397` Tage
+- ab `2026-03-14`: `199` Tage
+- ab `2027-03-14`: `99` Tage
+- ab `2029-03-14`: `46` Tage
+
+Für konkrete Beispiele siehe [Laufzeitverwaltung](validity-management.md).
 
 ## Aktives Zertifikat schnell ersetzen
 
@@ -92,7 +103,7 @@ Beispiel:
 sudo certbro --state-file /etc/certbro/state.json renew \
   --name example-com \
   --force \
-  --validity-days 3
+  --validity-days 30
 ```
 
 `certbro` hat aktuell noch keinen eigenen `revoke`-Befehl. Das Widerrufen des vorherigen Zertifikats erfolgt daher über die regfish Console oder die TLS API.

docs/de/validity-management.md

@@ -0,0 +1,77 @@
+# Laufzeitverwaltung
+
+English version: [../en/validity-management.md](../en/validity-management.md)
+
+## Überblick
+
+`certbro` speichert die gewünschte Laufzeit pro verwaltetem Zertifikat und verwendet sie für künftige Renewal-Orders und neue Orders weiter.
+
+Für `example.com` kann diese gespeicherte Laufzeit jederzeit geändert werden. `certbro` verwendet dann bei späteren Renewals den neuen Wert, solange er innerhalb des aktuell gültigen schedule-aware Limits liegt.
+
+## Gespeicherte Laufzeit manuell ändern
+
+Beispiel: `example.com` wurde ursprünglich mit `3` Tagen bestellt und soll künftig `30` Tage verwenden.
+
+Gespeicherten Wert aktualisieren:
+
+```sh
+sudo certbro update --name example-com --validity-days 30
+```
+
+Danach das nächste Renewal normal ausführen:
+
+```sh
+sudo certbro renew --name example-com
+```
+
+Wenn das aktuell deployte Zertifikat sofort mit der neuen gewünschten Laufzeit ersetzt werden soll:
+
+```sh
+sudo certbro renew --name example-com --force --validity-days 30
+```
+
+Für sehr kurz laufende Zertifikate müssen die Lead-Tage unter der gewünschten Laufzeit bleiben. Beispiel für ein Zertifikat mit `3` Tagen:
+
+```sh
+sudo certbro issue \
+  --name example-com \
+  --common-name example.com \
+  --output-dir /etc/certbro/example.com \
+  --validity-days 3 \
+  --renew-before-days 2 \
+  --reissue-lead-days 2
+```
+
+## Automatische Laufzeit-Anpassung
+
+`certbro` folgt dem CA/B-Forum-Zeitplan für Zertifikatslaufzeiten, nutzt dabei aber einen Sicherheitspuffer von einem Tag. Das heißt: `certbro` beginnt einen Tag vor dem offiziellen Stichtag mit dem jeweils niedrigeren Limit.
+
+Offizielle maximale CA/B-Forum-Laufzeiten:
+
+- ab `2026-03-15`: `200` Tage
+- ab `2027-03-15`: `100` Tage
+- ab `2029-03-15`: `47` Tage
+
+Die schedule-aware Defaults in `certbro`:
+
+- ab `2026-03-14`: `199` Tage
+- ab `2027-03-14`: `99` Tage
+- ab `2029-03-14`: `46` Tage
+
+## Was mit älteren gespeicherten Werten passiert
+
+Wenn ein verwaltetes Zertifikat noch einen inzwischen zu hohen Wert gespeichert hat, passt `certbro renew` ihn vor der Bestellung automatisch an.
+
+Beispiel:
+
+- für `example.com` sind noch `199` Tage gespeichert
+- das Renewal läuft am oder nach `2027-03-14`
+- `certbro` bestellt automatisch mit `99` Tagen
+- nach erfolgreichem Renewal wird auch der gespeicherte `validity_days`-Wert aktualisiert
+
+Diese automatische Anpassung gilt für gespeicherte Werte während der Renewal-Verarbeitung. Explizite CLI-Eingaben bleiben weiterhin strikt:
+
+- `certbro issue --validity-days ...` wird sofort validiert
+- `certbro update --validity-days ...` wird sofort validiert
+
+So bleiben bestehende verwaltete Zertifikate auch bei künftigen Schedule-Änderungen lauffähig, während bewusst gesetzte ungültige neue Werte weiterhin sauber abgelehnt werden.