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)
+ }
+ })
+ }
+}