certbot: certs/ links into /etc/letsencrypt, mounted at the same path; the backup follows them

C-A1, C-Q4, D-guide:258, :291, :722. certbot's live/<host>/*.pem are
relative links into ../../archive/<host>/ (eff-certbot docs, "Where are
my certificates?": point a server at them "or create symlinks"). The
guide had `ln -s /etc/letsencrypt/live/<host> certs` and the nginx
fragment mounted live/<host> alone: inside the container the links led
into a directory it did not have - postfix-config.sh's [ -f ] false, no
copy, Postfix without a certificate - and the panel's backup, reading
certs/ through /selfpost-deploy, skipped links silently.

Now certs/fullchain.pem and certs/privkey.pem are links to
/etc/letsencrypt/live/<host>/, and /etc/letsencrypt is mounted read-only
at the same path: a commented line in deploy/docker-compose.yml for the
Apache scenario, mounted in the nginx fragment (./nginx/certbot-etc). The
guide's steps add certbot's own commands for a server that is not root -
chmod 0755 live archive, chgrp 998 + chmod 0640 the key, which certbot
keeps on renewal - so the panel reads them (Health, backup). Postfix's
side follows links already ([ -f ], cp, cmp, openssl). The vhost comment
says the same. The backup table: links are followed by the panel's
backup; a stopped tar stores them as links unless -h (GNU tar).

internal/backup: addTree follows, for certs/ only, a link to a regular
file and archives that file under the link's name; a link to nothing
reachable is an error naming it and the mount.

Tests: TestCertsLinksAreFollowed (certs/ -> live/ -> archive/, the
archive holds the files; the tree gone, Check names the dangling link;
Linux). Stand (2026-10-15, make e2e, exit 0): the stand mounts
./letsencrypt at /etc/letsencrypt; new certbot_layout_followed puts a new
pair into letsencrypt/archive/, relative links in live/, absolute links
in certs/, recreates the container: 465 serves the new serial, Health
names no renewal waiting, and the full backup holds certs/*.pem as
regular files with the archive's bytes. go vet and go test ./... pass on
the server (24 packages); the Linux-only tests of this session run there
and pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/backup/backup.go

@@ -160,7 +160,7 @@ func Create(w io.Writer, p Params) error {
 		return err
 	}
 
-	if err := addTree(tw, p.DataDir, DataArchivePrefix, excludedFromArchive, skipQueue); err != nil {
+	if err := addTree(tw, p.DataDir, DataArchivePrefix, excludedFromArchive, skipQueue, false); err != nil {
 		return err
 	}
 
@@ -221,7 +221,7 @@ func Check(p Params) error {
 	if err := ValidateDeployRoot(p.DeployRoot); err != nil {
 		return err
 	}
-	if err := addTree(nil, p.DataDir, DataArchivePrefix, excludedFromArchive, skipQueue); err != nil {
+	if err := addTree(nil, p.DataDir, DataArchivePrefix, excludedFromArchive, skipQueue, false); err != nil {
 		return err
 	}
 	return addDeployFiles(nil, p.DeployRoot, nil)
@@ -267,7 +267,12 @@ func addDeployFiles(tw *tar.Writer, deployRoot string, onWarn func(string)) erro
 		}
 		return fmt.Errorf("backup: stat %s: %w", CertsDirName, err)
 	}
-	return addTree(tw, certsDir, CertsDirName+"/", nil, nil)
+	// certs/ may hold links rather than files: certbot's own advice is to
+	// point a server at its live/ files "(or create symlinks)", and those
+	// are links again, relative, into archive/ (eff-certbot docs, "Where are
+	// my certificates?"; assumptions C-Q4, C-A1). The archive carries the
+	// files they lead to, under the links' names.
+	return addTree(tw, certsDir, CertsDirName+"/", nil, nil, true)
 }
 
 // addTree walks root and adds every regular file (and directory, to preserve
@@ -275,8 +280,11 @@ func addDeployFiles(tw *tar.Writer, deployRoot string, onWarn func(string)) erro
 // When exclude is non-nil, top-level names relative to root are skipped; skip,
 // when non-nil, leaves out whatever it says. With a nil tw nothing is written:
 // every file is opened and closed, which is how Check finds what cannot be read.
-// Non-regular, non-directory entries (symlinks, sockets) are skipped.
-func addTree(tw *tar.Writer, root, archivePrefix string, exclude map[string]bool, skip skipFunc) error {
+// Non-regular, non-directory entries (symlinks, sockets) are skipped - except,
+// with follow, a symbolic link to a regular file, which is archived as that
+// file under the link's name; a link that leads nowhere this process can
+// reach is an error, as an unreadable file is.
+func addTree(tw *tar.Writer, root, archivePrefix string, exclude map[string]bool, skip skipFunc, follow bool) error {
 	return filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
 		if err != nil {
 			return err
@@ -330,6 +338,15 @@ func addTree(tw *tar.Writer, root, archivePrefix string, exclude map[string]bool
 				return nil
 			}
 			return err
+		case follow && info.Mode()&fs.ModeSymlink != 0:
+			target, err := os.Stat(path)
+			if err != nil {
+				return fmt.Errorf("backup: %s is a link to a file this container cannot reach - with certbot, /etc/letsencrypt is mounted at the same path (guide § Reverse proxy): %w", name, err)
+			}
+			if !target.Mode().IsRegular() {
+				return nil
+			}
+			return writeTarFile(tw, name, target.Mode().Perm(), path)
 		default:
 			return nil
 		}

internal/backup/backup_test.go

@@ -10,6 +10,7 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 
@@ -310,3 +311,51 @@ func TestCheckReportsWhatCannotBeRead(t *testing.T) {
 		t.Fatal("Check passed with .env missing from the deploy root")
 	}
 }
+
+// certs/ as certbot's advice leaves it: links into live/, which are relative
+// links into archive/ (C-Q4). The archive holds the files, under the links'
+// names; a link to nothing reachable stops the backup, naming it.
+func TestCertsLinksAreFollowed(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("symbolic links need privileges on Windows; the container is Linux")
+	}
+	dataDir, dbPath, deployRoot := seedDataDir(t)
+	le := t.TempDir()
+	writeFile(t, filepath.Join(le, "archive", "mail.example.com", "fullchain1.pem"), "CERT FROM CERTBOT")
+	writeFile(t, filepath.Join(le, "archive", "mail.example.com", "privkey1.pem"), "KEY FROM CERTBOT")
+	live := filepath.Join(le, "live", "mail.example.com")
+	if err := os.MkdirAll(live, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	certs := filepath.Join(deployRoot, CertsDirName)
+	for _, f := range []string{"fullchain", "privkey"} {
+		if err := os.Symlink("../../archive/mail.example.com/"+f+"1.pem", filepath.Join(live, f+".pem")); err != nil {
+			t.Fatal(err)
+		}
+		os.Remove(filepath.Join(certs, f+".pem"))
+		if err := os.Symlink(filepath.Join(live, f+".pem"), filepath.Join(certs, f+".pem")); err != nil {
+			t.Fatal(err)
+		}
+	}
+	p := Params{DataDir: dataDir, DBPath: dbPath, Version: "1.2.3", DeployRoot: deployRoot}
+	if err := Check(p); err != nil {
+		t.Fatalf("Check: %v", err)
+	}
+	var buf bytes.Buffer
+	if err := Create(&buf, p); err != nil {
+		t.Fatalf("Create: %v", err)
+	}
+	files := readArchive(t, buf.Bytes())
+	if files[CertsDirName+"/fullchain.pem"] != "CERT FROM CERTBOT" || files[CertsDirName+"/privkey.pem"] != "KEY FROM CERTBOT" {
+		t.Fatalf("certs in the archive: %q, %q", files[CertsDirName+"/fullchain.pem"], files[CertsDirName+"/privkey.pem"])
+	}
+
+	// /etc/letsencrypt not mounted: the link leads nowhere.
+	if err := os.RemoveAll(le); err != nil {
+		t.Fatal(err)
+	}
+	err := Check(p)
+	if err == nil || !strings.Contains(err.Error(), "certs/fullchain.pem is a link to a file this container cannot reach") {
+		t.Fatalf("Check with a dangling link: %v", err)
+	}
+}