From 3040951fc7f4441b3e8773f29e3bd4c01f3c6254 Mon Sep 17 00:00:00 2001 From: John Coffey Date: Fri, 13 Nov 2026 08:39:24 -0700 Subject: [PATCH] Add an inbuxa backup command for a single-machine install backup archives this machine's mail server -- its configuration and its data -- to /backups, whether the server runs in a container or on the host. It stops the server for a consistent archive and starts it again, a brief outage, so without --yes it only says what it would do. BackupKind, a pure classifier over the state, decides whether there is anything here to back up and refuses on a clustered node, whose real store lives in the cluster's PostgreSQL and S3 and is backed up there; a local archive would hold only its configuration. The container path reuses the existing read-only volume archiver; the host path tars the server directory. Each archive is verified as a readable, non-empty gzip tar before the command reports success. Restoring from a backup is deliberately left for later: it overwrites a live store, so it needs its own careful design and testing. --- cmd/inbuxa/main.go | 43 ++++++++++ internal/apply/backup.go | 143 ++++++++++++++++++++++++++++++++++ internal/apply/backup_test.go | 81 +++++++++++++++++++ 3 files changed, 267 insertions(+) create mode 100644 internal/apply/backup.go create mode 100644 internal/apply/backup_test.go diff --git a/cmd/inbuxa/main.go b/cmd/inbuxa/main.go index 0d02140..f7f9f53 100644 --- a/cmd/inbuxa/main.go +++ b/cmd/inbuxa/main.go @@ -56,6 +56,9 @@ const usage = `inbuxa -- install the inbuxa suite on this machine inbuxa doctor a read-only health check: services, the mail server's certificate, the ports answering, and the DNS a sender needs (exit 1 on a failure) + inbuxa backup [--yes] archive this machine's mail server, its + configuration and data, to /backups; it is + briefly stopped, so without --yes it only says so inbuxa upgrade [component…] move what is here to the releases this installer installs: --dry-run, --yes, --no-backup, --check (report only; exit 10 if @@ -214,6 +217,8 @@ func main() { os.Exit(statusCmd()) case "doctor": os.Exit(doctorCmd(os.Args[2:])) + case "backup": + os.Exit(backupCmd(os.Args[2:])) case "upgrade": os.Exit(upgradeCmd(os.Args[2:])) case "uninstall": @@ -1699,6 +1704,44 @@ func printDoctorReport(r doctor.Report) { } } +// backupCmd archives this machine's mail server. It stops the server, which +// is a brief outage, so without --yes it only says what it would do and why, +// and stops. apply.BackupKind decides whether there is anything here to back +// up, and refuses on a clustered node, whose real store lives elsewhere. +func backupCmd(args []string) int { + fs := flag.NewFlagSet("backup", flag.ContinueOnError) + fs.Usage = func() { fmt.Print(usage) } + yes := fs.Bool("yes", false, "") + if err := fs.Parse(args); err != nil { + return 2 + } + ctx := context.Background() + st, err := state.Load() + if err != nil { + fmt.Fprintln(os.Stderr, err.Error()) + return 1 + } + if _, refuse := apply.BackupKind(st); refuse != "" { + fmt.Println(refuse) + return 1 + } + where := filepath.Join(st.Dir, "backups") + if !*yes { + fmt.Printf("This briefly stops the mail server, archives its configuration and data under\n") + fmt.Printf("%s, and starts it again. Mail is not lost while it is stopped --\n", where) + fmt.Printf("other servers retry -- but it is unreachable for those few seconds.\n\n") + fmt.Println("Re-run with --yes to take the backup.") + return 1 + } + name, err := apply.Backup(ctx, st, host.Survey(ctx), &printer{}) + if err != nil { + fmt.Fprintln(os.Stderr, err.Error()) + return 1 + } + fmt.Printf("Backed up to %s\n", name) + return 0 +} + func machineNames(t *topology.Topology) []string { var out []string for _, m := range t.Machines { diff --git a/internal/apply/backup.go b/internal/apply/backup.go new file mode 100644 index 0000000..1b9c812 --- /dev/null +++ b/internal/apply/backup.go @@ -0,0 +1,143 @@ +// SPDX-FileCopyrightText: 2026 Coffey Labs LLC +// SPDX-License-Identifier: AGPL-3.0-or-later + +package apply + +import ( + "context" + "fmt" + "os" + "os/exec" + "path/filepath" + "strings" + "time" + + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/docker" + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/host" + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/plan" + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state" +) + +// BackupKind decides how, or whether, Backup would archive this machine's +// mail server. refuse is non-empty when there is nothing here to back up, or +// when a local archive would mislead; otherwise kind is "container" or +// "host". It reads only the state, so the command can say what would happen +// before anything does. +func BackupKind(st *state.State) (kind, refuse string) { + switch { + case st.Removed(): + return "", "the programs were uninstalled here and the data kept; nothing is running to back up" + case st.ServerURL != "": + return "", "the mail server runs on another machine; it is backed up where it runs, not here" + case st.Shapes["server"] == "" || strings.EqualFold(st.Shapes["server"], "skip"): + return "", "the mail server is not installed on this machine" + case st.Clustered: + return "", "this node keeps its mail in the cluster's shared store (PostgreSQL and S3), which is backed up there; a local archive would hold only its configuration, so this does not take one" + case strings.EqualFold(st.Shapes["server"], "host"): + return "host", "" + default: + return "container", "" + } +} + +// Backup archives the mail server's configuration and data on this machine to +// /backups and returns the archive's path. It stops the server for a +// consistent archive and starts it again -- a brief outage -- so the caller +// should have the operator's go-ahead. It is for a single-machine install; +// BackupKind says when it will not run, and why. +// +// It takes only what lives here: the server's own volumes or its directory. A +// store the server keeps elsewhere -- the cluster's PostgreSQL and S3 -- is +// backed up there, which is why BackupKind refuses on a clustered node rather +// than write a half archive. +func Backup(ctx context.Context, st *state.State, f host.Facts, log Log) (string, error) { + kind, refuse := BackupKind(st) + if refuse != "" { + return "", fmt.Errorf("%s", refuse) + } + var ( + name string + err error + ) + if kind == "host" { + name, err = backupHostServer(ctx, st.Dir, log) + } else { + name, err = backupServerContainer(ctx, st.Dir, f, log) + } + if err != nil { + return "", err + } + if err := verifyArchive(ctx, name); err != nil { + return "", fmt.Errorf("the archive was written to %s but did not verify: %w", name, err) + } + return name, nil +} + +func backupServerContainer(ctx context.Context, dir string, f host.Facts, log Log) (string, error) { + compose, err := os.ReadFile(filepath.Join(dir, "compose.yaml")) + if err != nil { + return "", err + } + ver := installedVersion(dir, plan.Server, plan.Container, string(compose)) + if ver == "" || ver == "unknown" { + return "", fmt.Errorf("could not tell the server's version from %s", filepath.Join(dir, "compose.yaml")) + } + docker.UseRuntime(f.Runtime) + cmp := docker.Compose{Dir: dir, Runtime: f.Runtime} + log.Info("stopping the server to archive its data") + if err := cmp.Run(ctx, "stop", "server"); err != nil { + return "", err + } + name, archErr := archiveVolumes(ctx, dir, ver) + // Start it again whatever happened; a backup must not leave it down. + if startErr := cmp.Run(ctx, "start", "server"); startErr != nil && archErr == nil { + archErr = fmt.Errorf("the archive %s was written, but starting the server again failed: %w", name, startErr) + } + if archErr != nil { + return "", archErr + } + log.Info("archived its configuration and data to %s", name) + return name, nil +} + +func backupHostServer(ctx context.Context, dir string, log Log) (string, error) { + backups := filepath.Join(dir, "backups") + if err := os.MkdirAll(backups, 0o700); err != nil { + return "", err + } + name := filepath.Join(backups, "server-host-"+time.Now().UTC().Format("20060102T150405Z")+".tar.gz") + log.Info("stopping the server to archive its data") + if err := runQuiet(ctx, "systemctl", "stop", HostServerUnit); err != nil { + return "", err + } + tarErr := runQuiet(ctx, "tar", "-czf", name, "-C", dir, "server") + if startErr := runQuiet(ctx, "systemctl", "start", HostServerUnit); startErr != nil && tarErr == nil { + tarErr = fmt.Errorf("the archive %s was written, but starting the server again failed: %w", name, startErr) + } + if tarErr != nil { + os.Remove(name) + return "", tarErr + } + log.Info("archived its configuration and data to %s", name) + return name, nil +} + +// verifyArchive confirms a backup is a readable, non-empty gzip tar. A backup +// that is quietly broken is worse than one that loudly failed. +func verifyArchive(ctx context.Context, name string) error { + fi, err := os.Stat(name) + if err != nil { + return err + } + if fi.Size() == 0 { + return fmt.Errorf("it is empty") + } + out, err := exec.CommandContext(ctx, "tar", "-tzf", name).Output() + if err != nil { + return fmt.Errorf("it is not a readable tar: %w", err) + } + if len(strings.TrimSpace(string(out))) == 0 { + return fmt.Errorf("it holds no files") + } + return nil +} diff --git a/internal/apply/backup_test.go b/internal/apply/backup_test.go new file mode 100644 index 0000000..77e319a --- /dev/null +++ b/internal/apply/backup_test.go @@ -0,0 +1,81 @@ +// SPDX-FileCopyrightText: 2026 Coffey Labs LLC +// SPDX-License-Identifier: AGPL-3.0-or-later + +package apply + +import ( + "strings" + "testing" + "time" + + "git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state" +) + +func TestBackupKind(t *testing.T) { + removed := time.Now() + cases := []struct { + name string + st *state.State + wantKind string + wantRefuse string // a substring the refusal must mention, "" if it should not refuse + }{ + { + name: "container server", + st: &state.State{Dir: "/var/lib/inbuxa", Shapes: map[string]string{"server": "container"}}, + wantKind: "container", + }, + { + name: "host server", + st: &state.State{Dir: "/var/lib/inbuxa", Shapes: map[string]string{"server": "host"}}, + wantKind: "host", + }, + { + name: "front ends only, server elsewhere", + st: &state.State{Shapes: map[string]string{"webmail": "container"}, ServerURL: "https://mail.example.org"}, + wantRefuse: "another machine", + }, + { + name: "no server here", + st: &state.State{Shapes: map[string]string{"webmail": "container"}}, + wantRefuse: "not installed", + }, + { + name: "server skipped", + st: &state.State{Shapes: map[string]string{"server": "skip"}}, + wantRefuse: "not installed", + }, + { + name: "uninstalled, data kept", + st: &state.State{Shapes: map[string]string{"server": "container"}, RemovedAt: &removed}, + wantRefuse: "nothing is running", + }, + { + name: "clustered node", + st: &state.State{Dir: "/var/lib/inbuxa", Shapes: map[string]string{"server": "container"}, Clustered: true}, + wantRefuse: "shared store", + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + kind, refuse := BackupKind(tc.st) + if tc.wantRefuse != "" { + if refuse == "" { + t.Fatalf("expected a refusal mentioning %q, got kind %q and no refusal", tc.wantRefuse, kind) + } + if kind != "" { + t.Errorf("a refusal should give no kind, got %q", kind) + } + if !strings.Contains(refuse, tc.wantRefuse) { + t.Errorf("refusal %q does not mention %q", refuse, tc.wantRefuse) + } + return + } + if refuse != "" { + t.Fatalf("did not expect a refusal, got %q", refuse) + } + if kind != tc.wantKind { + t.Errorf("kind = %q, want %q", kind, tc.wantKind) + } + }) + } +} -- 2.54.0