diff --git a/README.md b/README.md index 06a531b..d557bd1 100644 --- a/README.md +++ b/README.md @@ -171,6 +171,7 @@ vaultik [--config ] config get vaultik [--config ] config set vaultik [--config ] snapshot create [snapshot-names...] [--cron] [--prune] [--keep-newer-than ] vaultik [--config ] snapshot list [--json] # alias: ls +vaultik [--config ] snapshot files [path] [--json] vaultik [--config ] snapshot verify [--deep] [--json] vaultik [--config ] snapshot purge [--keep-latest | --older-than ] [--snapshot ...] [--force] vaultik [--config ] snapshot remove [--dry-run] [--force] [--local-only] [--json] # alias: rm @@ -223,12 +224,12 @@ the backup can delete it; the new snapshot then cannot be restored. `remote nuke` deletes everything regardless. To not depend on the grace period, give each host or user its own prefix (or directory) on the destination. -Read-only commands — `info`, `snapshot list`, `snapshot verify`, and -`remote info` — do not take the lock and are never blocked, so they run even -while a backup is in progress. `snapshot restore` does not take the lock either: -it writes only to the target directory you name, not the local index or the -destination store. `config`, `database delete`, `completion`, and `version` do -not take the lock. +Read-only commands — `info`, `snapshot list`, `snapshot files`, +`snapshot verify`, and `remote info` — do not take the lock and are never +blocked, so they run even while a backup is in progress. `snapshot restore` does +not take the lock either: it writes only to the target directory you name, not +the local index or the destination store. `config`, `database delete`, +`completion`, and `version` do not take the lock. ### stdout and stderr @@ -261,9 +262,9 @@ work as written. ### environment variables - `VAULTIK_AGE_SECRET_KEY`: Age private key for decryption (required for - `snapshot restore` and `snapshot verify --deep`). May hold the whole - `age-keygen` file — comments and every identity in it are accepted. Set it - from the file, e.g. + `snapshot restore`, `snapshot files` and `snapshot verify --deep`). May hold + the whole `age-keygen` file — comments and every identity in it are accepted. + Set it from the file, e.g. `export VAULTIK_AGE_SECRET_KEY="$(cat vaultik_backup_private_key.txt)"`, so the key is not typed into your shell history. - `VAULTIK_CONFIG`: Path to config file (overridden by `--config`) @@ -408,6 +409,17 @@ point behind. truncated listing all go to stderr through the logger, so stdout stays a single parseable document. +**`snapshot files`**: List the files in a snapshot without restoring it. Each +row of the table shows mode, size in bytes, modification time and path, sorted +by path. + +- Requires `VAULTIK_AGE_SECRET_KEY`: the file list is only in the snapshot's + encrypted database, which the command downloads and decrypts. +- Accepts the same identifiers as `snapshot restore`. +- An optional path limits the list to that path and what is under it. A path + that matches nothing in the snapshot is an error. +- `--json`: Output an array of objects with `path`, `size`, `mode` and `mtime`. + **`snapshot verify`**: Verify snapshot integrity. - Default (shallow): checks that every blob the manifest lists is present in @@ -722,7 +734,7 @@ annotated example also lives in | Field | Default | Description | | -------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `age_recipients` | (required by `snapshot create`) | Age public keys for encryption. Other commands run without one, so a machine that only restores can leave it empty | -| `age_secret_key` | (unset) | Age private key for decryption (`snapshot restore`, `snapshot verify --deep`). Setting it in the config file places the private key on the backed-up host, defeating the public-key-only design (see "why" above). Prefer the `VAULTIK_AGE_SECRET_KEY` environment variable, supplied only on the machine you restore from. | +| `age_secret_key` | (unset) | Age private key for decryption (`snapshot restore`, `snapshot files`, `snapshot verify --deep`). Setting it in the config file places the private key on the backed-up host, defeating the public-key-only design (see "why" above). Prefer the `VAULTIK_AGE_SECRET_KEY` environment variable, supplied only on the machine you restore from. | | `snapshots` | (required) | Named snapshot definitions with paths and excludes | | `storage_url` | | Storage backend URL (`s3://`, `file://`, `rclone://`) | | `s3.*` | | Legacy S3 configuration (endpoint, bucket, credentials) | @@ -840,14 +852,14 @@ environment variable is unset (https://no-color.org/). - **The data a command exists to produce** is written plain, with no marker and no color, because a marker would corrupt a table or a parsed document. This covers the `version`, `info`, `remote info` and `snapshot verify` reports, the - `snapshot list` table, `config get` values, and every `--json` document. - `--quiet` silences the human reports and tables (`version`, `info`, - `remote info`, `snapshot verify`, `snapshot list`) but never the - machine-consumed `config get` value or the `--json` documents, which a script - depends on. The confirmation prompts of `database delete`, `prune`, - `snapshot purge` and `snapshot remove`, each with what it asks to delete, are - also written this way and always shown: they are an interactive exchange the - operator must see. + `snapshot list` and `snapshot files` tables, `config get` values, and every + `--json` document. `--quiet` silences the human reports and tables (`version`, + `info`, `remote info`, `snapshot verify`, `snapshot list`, `snapshot files`) + but never the machine-consumed `config get` value or the `--json` documents, + which a script depends on. The confirmation prompts of `database delete`, + `prune`, `snapshot purge` and `snapshot remove`, each with what it asks to + delete, are also written this way and always shown: they are an interactive + exchange the operator must see. `internal/ui` writes to stdout; it is the output the user asked for. The exceptions are the startup banner and the error a failed command ends with, diff --git a/internal/cli/snapshot.go b/internal/cli/snapshot.go index 27056fc..5fb5278 100644 --- a/internal/cli/snapshot.go +++ b/internal/cli/snapshot.go @@ -9,6 +9,10 @@ import ( "sneak.berlin/go/vaultik/internal/vaultik" ) +// filesMaxArgs is the maximum positional argument count of +// `snapshot files [path]`. +const filesMaxArgs = 2 + var ( errSnapshotIDRequired = errors.New("snapshot ID required") errWrongArgCount = errors.New("wrong argument count") @@ -52,6 +56,7 @@ func NewSnapshotCommand() *cobra.Command { // Add subcommands cmd.AddCommand(newSnapshotCreateCommand()) cmd.AddCommand(newSnapshotListCommand()) + cmd.AddCommand(newSnapshotFilesCommand()) cmd.AddCommand(newSnapshotPurgeCommand()) cmd.AddCommand(newSnapshotVerifyCommand()) cmd.AddCommand(newSnapshotRemoveCommand()) @@ -172,6 +177,44 @@ func newSnapshotListCommand() *cobra.Command { return cmd } +// newSnapshotFilesCommand creates the 'snapshot files' subcommand +func newSnapshotFilesCommand() *cobra.Command { + var jsonOutput bool + + cmd := &cobra.Command{ + Use: "files [path]", + Short: "List the files in a snapshot", + Long: `Lists the path, size, mode and modification time of every file in a +snapshot, without restoring it. With a path, lists only that path and +what is under it; a path that matches nothing is an error. + +The snapshot may be named by its ID or, on a host with no local index, +by the remote key that 'snapshot list' prints for a remote-only snapshot +(an unambiguous leading part is enough). + +The file list is only in the snapshot's encrypted database, so this +downloads and decrypts it, and requires the age private key in the +VAULTIK_AGE_SECRET_KEY environment variable, as 'snapshot restore' does.`, + Args: cobra.RangeArgs(1, filesMaxArgs), + RunE: func(cmd *cobra.Command, args []string) error { + path := "" + if len(args) == filesMaxArgs { + path = args[1] + } + + return runVaultikApp(cmd, readOnly, jsonOutput, + "Failed to list snapshot files", + func(v *vaultik.Vaultik) error { + return v.ListSnapshotFiles(args[0], path, jsonOutput) + }) + }, + } + + cmd.Flags().BoolVar(&jsonOutput, "json", false, "Output in JSON format") + + return cmd +} + // newSnapshotPurgeCommand creates the 'snapshot purge' subcommand func newSnapshotPurgeCommand() *cobra.Command { opts := &vaultik.SnapshotPurgeOptions{} diff --git a/internal/vaultik/restore.go b/internal/vaultik/restore.go index 5f41d96..60946db 100644 --- a/internal/vaultik/restore.go +++ b/internal/vaultik/restore.go @@ -31,7 +31,7 @@ var ( errPathsNotInSnapshot = errors.New("requested path(s) not in the snapshot") errFilesFailedVerify = errors.New("files failed verification") errDecryptionKeyRequired = errors.New( - "decryption key required for restore\n\n" + + "decryption key required\n\n" + "Set the VAULTIK_AGE_SECRET_KEY environment variable to your " + "age private key file:\n" + " export VAULTIK_AGE_SECRET_KEY=\"$(cat vaultik_backup_private_key.txt)\"") @@ -153,18 +153,7 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error { return fmt.Errorf("downloading snapshot database: %w", err) } - defer func() { - err := tempDB.Close() - if err != nil { - log.Debug("Failed to close temp database", "error", err) - } - // Remove the whole private directory, so the decrypted database - // and any SQLite side files it produced are gone on every path. - err = v.Fs.RemoveAll(tempDir) - if err != nil { - log.Debug("Failed to remove temp database directory", "error", err) - } - }() + defer v.closeSnapshotDB(tempDB, tempDir) repos := database.NewRepositories(tempDB) diff --git a/internal/vaultik/snapshot_files.go b/internal/vaultik/snapshot_files.go new file mode 100644 index 0000000..88df405 --- /dev/null +++ b/internal/vaultik/snapshot_files.go @@ -0,0 +1,134 @@ +package vaultik + +import ( + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "text/tabwriter" + "time" + + "sneak.berlin/go/vaultik/internal/database" + "sneak.berlin/go/vaultik/internal/log" +) + +// errPathNotInSnapshot is returned when the path given to `snapshot files` +// matches nothing in the snapshot. +var errPathNotInSnapshot = errors.New("path matches nothing in the snapshot") + +// SnapshotFile is one entry printed by `snapshot files`. Mode is the Go +// file mode string, which shows the entry type and the permission bits +// (for example -rw-r--r-- or drwxr-xr-x). +type SnapshotFile struct { + Path string `json:"path"` + Size int64 `json:"size"` + Mode string `json:"mode"` + MTime time.Time `json:"mtime"` +} + +// ListSnapshotFiles prints the path, size, mode and modification time of +// every file the snapshot holds at or under path, or of every file when +// path is empty. The file list is only in the snapshot's encrypted +// database, so this downloads and decrypts it as restore does, and needs +// the private key. +func (v *Vaultik) ListSnapshotFiles(snapshotID, path string, jsonOutput bool) error { + identities, err := v.restoreIdentities() + if err != nil { + return err + } + + remoteKey, err := v.resolveSnapshotRemoteKey(snapshotID) + if err != nil { + return err + } + + db, tempDir, err := v.downloadSnapshotDB(snapshotID, remoteKey, identities) + if errors.Is(err, errWrongPrivateKey) { + return err + } + + if err != nil { + return fmt.Errorf("downloading snapshot database: %w", err) + } + + defer v.closeSnapshotDB(db, tempDir) + + repos := database.NewRepositories(db) + + var files []*database.File + + if path == "" { + files, err = repos.Files.ListAll(v.ctx) + } else { + files, err = repos.Files.ListUnderPath(v.ctx, filepath.Clean(path)) + } + + if err != nil { + return fmt.Errorf("listing files: %w", err) + } + + if path != "" && len(files) == 0 { + return fmt.Errorf("%w: %s", errPathNotInSnapshot, path) + } + + entries := make([]SnapshotFile, 0, len(files)) + + for _, file := range files { + entries = append(entries, SnapshotFile{ + Path: file.Path.String(), + Size: file.Size, + Mode: os.FileMode(file.Mode).String(), + MTime: file.MTime, + }) + } + + if jsonOutput { + encoder := json.NewEncoder(v.Stdout) + encoder.SetIndent("", " ") + + return encoder.Encode(entries) + } + + if v.UI.Quiet() { + return nil + } + + return v.printSnapshotFileTable(entries) +} + +// printSnapshotFileTable writes the entries as a plain table to stdout. +func (v *Vaultik) printSnapshotFileTable(entries []SnapshotFile) error { + w := tabwriter.NewWriter(v.Stdout, 0, 0, tabPadding, ' ', 0) + + _, err := fmt.Fprintln(w, "MODE\tSIZE\tMODIFIED\tPATH") + if err != nil { + return err + } + + for _, entry := range entries { + _, err = fmt.Fprintf(w, "%s\t%d\t%s\t%s\n", + entry.Mode, entry.Size, + entry.MTime.Format(time.RFC3339), entry.Path) + if err != nil { + return err + } + } + + return w.Flush() +} + +// closeSnapshotDB closes a database returned by downloadSnapshotDB and +// removes its private directory, so the decrypted database and any SQLite +// side files it produced are gone. +func (v *Vaultik) closeSnapshotDB(db *database.DB, tempDir string) { + err := db.Close() + if err != nil { + log.Debug("Failed to close temp database", "error", err) + } + + err = v.Fs.RemoveAll(tempDir) + if err != nil { + log.Debug("Failed to remove temp database directory", "error", err) + } +} diff --git a/internal/vaultik/snapshot_files_test.go b/internal/vaultik/snapshot_files_test.go new file mode 100644 index 0000000..cc66383 --- /dev/null +++ b/internal/vaultik/snapshot_files_test.go @@ -0,0 +1,140 @@ +package vaultik_test + +import ( + "bytes" + "context" + "encoding/json" + "path/filepath" + "strings" + "testing" + + "github.com/spf13/afero" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "sneak.berlin/go/vaultik/internal/database" + "sneak.berlin/go/vaultik/internal/log" + "sneak.berlin/go/vaultik/internal/storage" + "sneak.berlin/go/vaultik/internal/vaultik" +) + +// These tests cover https://git.eeqj.de/sneak/vaultik/issues/435: +// `snapshot files` lists what a snapshot holds without restoring it. + +// backUpForFileListing backs up the fault source tree and returns a +// reader whose stdout is out, the snapshot ID, and the source directory. +func backUpForFileListing( + t *testing.T, out *bytes.Buffer, +) (*vaultik.Vaultik, string, string) { + t.Helper() + + fs := afero.NewOsFs() + tempDir := t.TempDir() + dataDir := filepath.Join(tempDir, "src") + dbPath := filepath.Join(tempDir, "index.sqlite") + + ctx := context.Background() + cfg := faultTestConfig() + + writeFaultSourceTree(t, fs, dataDir) + + store, err := storage.NewFileStorer(t.TempDir()) + require.NoError(t, err) + + db, err := database.New(ctx, dbPath) + require.NoError(t, err) + + id := fullFaultBackup(ctx, t, fs, store, cfg, + database.NewRepositories(db), dataDir, dbPath, "files") + require.NoError(t, db.Close()) + + v := newReaderVaultik(ctx, cfg, store, nil, fs) + v.Stdout = out + + return v, id, dataDir +} + +func TestSnapshotFilesJSONListsEveryFileWithItsMetadata(t *testing.T) { + log.Initialize(log.Config{}) + t.Parallel() + + var out bytes.Buffer + + v, id, dataDir := backUpForFileListing(t, &out) + + require.NoError(t, v.ListSnapshotFiles(id, "", true)) + + var entries []vaultik.SnapshotFile + + require.NoError(t, json.Unmarshal(out.Bytes(), &entries)) + + byPath := make(map[string]vaultik.SnapshotFile, len(entries)) + for _, entry := range entries { + byPath[entry.Path] = entry + } + + for _, rel := range []string{"small.txt", "a.bin", "sub", "sub/b.bin", "sub/c.bin"} { + path := filepath.Join(dataDir, rel) + + entry, ok := byPath[path] + require.True(t, ok, "%s must be listed", path) + + info, err := afero.NewOsFs().Stat(path) + require.NoError(t, err) + + assert.Equal(t, info.Mode().String(), entry.Mode, path) + assert.True(t, info.ModTime().Equal(entry.MTime), + "%s: mtime %v, listed %v", path, info.ModTime(), entry.MTime) + + if !info.IsDir() { + assert.Equal(t, info.Size(), entry.Size, path) + } + } +} + +func TestSnapshotFilesListsOnlyWhatIsUnderThePath(t *testing.T) { + log.Initialize(log.Config{}) + t.Parallel() + + var out bytes.Buffer + + v, id, dataDir := backUpForFileListing(t, &out) + + require.NoError(t, v.ListSnapshotFiles(id, filepath.Join(dataDir, "sub"), false)) + + text := out.String() + assert.Contains(t, text, filepath.Join(dataDir, "sub", "b.bin")) + assert.Contains(t, text, filepath.Join(dataDir, "sub", "c.bin")) + assert.NotContains(t, text, filepath.Join(dataDir, "small.txt")) + assert.True(t, strings.HasPrefix(text, "MODE"), "the table must have a header") +} + +func TestSnapshotFilesFailsOnAPathThatMatchesNothing(t *testing.T) { + log.Initialize(log.Config{}) + t.Parallel() + + var out bytes.Buffer + + v, id, dataDir := backUpForFileListing(t, &out) + missing := filepath.Join(dataDir, "typo.txt") + + err := v.ListSnapshotFiles(id, missing, false) + + require.Error(t, err) + assert.Contains(t, err.Error(), missing, "the error must name the path") + assert.Empty(t, out.String(), "nothing must be printed") +} + +func TestSnapshotFilesRequiresThePrivateKey(t *testing.T) { + log.Initialize(log.Config{}) + t.Parallel() + + var out bytes.Buffer + + v, id, _ := backUpForFileListing(t, &out) + v.Config.AgeSecretKey = "" + + err := v.ListSnapshotFiles(id, "", false) + + require.Error(t, err) + assert.Contains(t, err.Error(), "VAULTIK_AGE_SECRET_KEY") +}