Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 sneak
|
6c44b8aaff |
+389
-384
@@ -1,401 +1,406 @@
|
|||||||
# vaultik architecture
|
# Vaultik Architecture
|
||||||
|
|
||||||
This document describes how the `vaultik` code is organised. It covers three
|
This document describes the internal architecture of Vaultik, focusing on the data model, type instantiation, and the relationships between core modules.
|
||||||
things:
|
|
||||||
|
|
||||||
- the packages
|
## Overview
|
||||||
- how they are wired together
|
|
||||||
- what happens during a backup, a restore, a verify and a prune
|
|
||||||
|
|
||||||
Two other documents cover the stored data:
|
Vaultik is a backup system that uses content-defined chunking for deduplication and packs chunks into large, compressed, encrypted blobs for efficient cloud storage. The system is built around dependency injection using [uber-go/fx](https://github.com/uber-go/fx).
|
||||||
|
|
||||||
- [docs/DATAMODEL.md](docs/DATAMODEL.md) describes the local index.
|
## Data Flow
|
||||||
- [docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md) describes the layout of the
|
|
||||||
destination.
|
|
||||||
|
|
||||||
## Terms
|
|
||||||
|
|
||||||
- **Snapshot**: one backup of the paths listed under one name in the config.
|
|
||||||
- **Chunk**: a piece of a file's content. A chunk is named by the SHA-256 hash
|
|
||||||
of its content.
|
|
||||||
- **Blob**: one object at the destination. It holds many chunks, compressed and
|
|
||||||
then encrypted.
|
|
||||||
- **Local index**: the SQLite database on the backed-up machine.
|
|
||||||
- **Destination**: the place the backups are stored.
|
|
||||||
- **Manifest**: the unencrypted list of the blobs one snapshot uses.
|
|
||||||
- **Remote key**: a hash of the snapshot ID. It names the snapshot's directory
|
|
||||||
at the destination.
|
|
||||||
|
|
||||||
## How a backup moves data
|
|
||||||
|
|
||||||
```
|
```
|
||||||
source files
|
Source Files
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
Scanner walks the paths and finds the files that changed
|
┌─────────────────┐
|
||||||
│
|
│ Scanner │ Walks directories, detects changed files
|
||||||
▼
|
└────────┬────────┘
|
||||||
Chunker cuts each changed file into chunks
|
│
|
||||||
│
|
▼
|
||||||
▼
|
┌─────────────────┐
|
||||||
Packer packs new chunks into a blob, compressed and encrypted
|
│ Chunker │ Splits files into variable-size chunks (FastCDC)
|
||||||
│
|
└────────┬────────┘
|
||||||
▼
|
│
|
||||||
Storer uploads the blob to the destination
|
▼
|
||||||
|
┌─────────────────┐
|
||||||
|
│ Packer │ Accumulates chunks, compresses (zstd), encrypts (age)
|
||||||
|
└────────┬────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────┐
|
||||||
|
│ S3 Client │ Uploads blobs to remote storage
|
||||||
|
└─────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
## Packages
|
## Data Model
|
||||||
|
|
||||||
- `cmd/vaultik`: the `main` function. It starts optional profiling and calls
|
### Core Entities
|
||||||
`cli.Entry`.
|
|
||||||
- `internal/cli`: the commands, their flags and their help text. It builds the
|
|
||||||
application, takes the lock and handles interrupts.
|
|
||||||
- `internal/vaultik`: the code behind each command. `Vaultik` holds every
|
|
||||||
dependency a command uses.
|
|
||||||
- `internal/snapshot`: the `Scanner`, which backs up one path, and the
|
|
||||||
`SnapshotManager`, which creates snapshot records and uploads their metadata.
|
|
||||||
- `internal/chunker`: cuts a stream into chunks with the FastCDC algorithm.
|
|
||||||
- `internal/blob`: the `Packer`, which collects chunks into blobs.
|
|
||||||
- `internal/blobgen`: the writer that hashes, compresses and encrypts a blob,
|
|
||||||
and the reader that reverses it.
|
|
||||||
- `internal/database`: the local index. It holds the schema and the repository
|
|
||||||
types that read and write the tables.
|
|
||||||
[docs/DATAMODEL.md](docs/DATAMODEL.md#code) says which type serves which
|
|
||||||
table.
|
|
||||||
- `internal/storage`: the `Storer` interface and its three implementations, for
|
|
||||||
S3, a local directory and rclone.
|
|
||||||
- `internal/s3`: the S3 client that the S3 `Storer` uses.
|
|
||||||
- `internal/config`: loads and checks the config file.
|
|
||||||
- `internal/ui`: formats the status lines, warnings and errors a user sees.
|
|
||||||
- `internal/log`: the logger. It writes to stderr.
|
|
||||||
- `internal/pidlock`: the lock that keeps two data-changing commands from
|
|
||||||
running at once.
|
|
||||||
- `internal/globals`: the version, commit and commit date, set when the binary
|
|
||||||
is built.
|
|
||||||
- `internal/types`: distinct types for IDs, hashes and paths.
|
|
||||||
|
|
||||||
## Wiring
|
The database tracks five primary entities and their relationships:
|
||||||
|
|
||||||
The application is assembled with [uber-go/fx](https://github.com/uber-go/fx), a
|
```
|
||||||
dependency injection library. `cli.NewApp` lists the providers:
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||||
|
│ Snapshot │────▶│ File │────▶│ Chunk │
|
||||||
|
└──────────────┘ └──────────────┘ └──────────────┘
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌──────────────┐ ┌──────────────┐
|
||||||
|
│ Blob │◀─────────────────────────│ BlobChunk │
|
||||||
|
└──────────────┘ └──────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Entity Descriptions
|
||||||
|
|
||||||
|
#### File (`database.File`)
|
||||||
|
Represents a file, directory, or symlink in the backup system. Stores metadata needed for restoration:
|
||||||
|
- Path, mtime
|
||||||
|
- Size, mode, ownership (uid, gid)
|
||||||
|
- Symlink target (if applicable)
|
||||||
|
|
||||||
|
It also stores `source_path`, the source directory the scan found it under, made absolute and with symlinks resolved. Restore does not read it.
|
||||||
|
|
||||||
|
#### Chunk (`database.Chunk`)
|
||||||
|
A content-addressed unit of data. Files are split into variable-size chunks using the FastCDC algorithm:
|
||||||
|
- `ChunkHash`: SHA256 hash of chunk content (primary key)
|
||||||
|
- `Size`: Chunk size in bytes
|
||||||
|
|
||||||
|
Chunk sizes vary between `avgChunkSize/4` and `avgChunkSize*4` (2.5MB-40MB for the 10MB default average).
|
||||||
|
|
||||||
|
#### FileChunk (`database.FileChunk`)
|
||||||
|
Maps files to their constituent chunks:
|
||||||
|
- `FileID`: Reference to the file
|
||||||
|
- `Idx`: Position of this chunk within the file (0-indexed)
|
||||||
|
- `ChunkHash`: Reference to the chunk
|
||||||
|
|
||||||
|
#### Blob (`database.Blob`)
|
||||||
|
The final storage unit uploaded to S3. Contains many compressed and encrypted chunks:
|
||||||
|
- `ID`: UUID assigned at creation
|
||||||
|
- `Hash`: `hex(SHA256(SHA256(uncompressed blob contents)))`, computed before compression and encryption (see [docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#blobs-directory-blobs))
|
||||||
|
- `UncompressedSize`: Total raw chunk data before compression
|
||||||
|
- `CompressedSize`: Size after zstd compression and age encryption
|
||||||
|
- `CreatedTS`, `FinishedTS`, `UploadedTS`: Lifecycle timestamps
|
||||||
|
|
||||||
|
Blob creation process:
|
||||||
|
1. Chunks are accumulated (up to MaxBlobSize, typically 10GB)
|
||||||
|
2. As each chunk is added, its uncompressed bytes are fed to a running SHA-256
|
||||||
|
3. Concurrently, the same bytes are compressed with zstd, then encrypted with age (recipients configured in config), and written to a temporary file
|
||||||
|
4. On finalize, the blob's name is the double SHA-256 of the uncompressed contents — `hex(SHA256(SHA256(...)))` — not a hash of the compressed, encrypted bytes
|
||||||
|
5. The finished file is uploaded to `blobs/{hash[0:2]}/{hash[2:4]}/{hash}` and then deleted
|
||||||
|
|
||||||
|
A backup needs free temporary space, because each blob is written whole to a temporary file before it is uploaded (up to about `blob_size_limit`; an rclone destination that cannot stream uploads needs about twice that) and the metadata export writes copies of the local index. Temporary files go to `$TMPDIR` (default `/tmp`); with `TMPDIR` unset, SQLite writes one of those copies to `/var/tmp`.
|
||||||
|
|
||||||
|
#### BlobChunk (`database.BlobChunk`)
|
||||||
|
Maps chunks to their position within blobs:
|
||||||
|
- `BlobID`: Reference to the blob
|
||||||
|
- `ChunkHash`: Reference to the chunk
|
||||||
|
- `Offset`: Byte offset within the uncompressed blob
|
||||||
|
- `Length`: Chunk size
|
||||||
|
|
||||||
|
#### Snapshot (`database.Snapshot`)
|
||||||
|
Represents a point-in-time backup:
|
||||||
|
- `ID`: Format is `{hostname}_{snapshot-name}_{RFC3339}` (e.g. `server1_home_2025-06-01T12:00:00Z`)
|
||||||
|
- Tracks file count, chunk count, blob count, sizes, compression ratio
|
||||||
|
- `CompletedAt`: Null until snapshot finishes successfully
|
||||||
|
|
||||||
|
#### SnapshotFile / SnapshotBlob
|
||||||
|
Join tables linking snapshots to their files and blobs.
|
||||||
|
|
||||||
|
### Relationship Summary
|
||||||
|
|
||||||
|
```
|
||||||
|
Snapshot 1──────────▶ N SnapshotFile N ◀────────── 1 File
|
||||||
|
Snapshot 1──────────▶ N SnapshotBlob N ◀────────── 1 Blob
|
||||||
|
File 1──────────▶ N FileChunk N ◀────────── 1 Chunk
|
||||||
|
Blob 1──────────▶ N BlobChunk N ◀────────── 1 Chunk
|
||||||
|
```
|
||||||
|
|
||||||
|
## Type Instantiation
|
||||||
|
|
||||||
|
### Application Startup
|
||||||
|
|
||||||
|
The CLI uses fx for dependency injection. Here's the instantiation order:
|
||||||
|
|
||||||
```go
|
```go
|
||||||
fx.Supply(config.Path(opts.ConfigPath)),
|
// cli/app.go: NewApp()
|
||||||
fx.Supply(opts.LogOptions),
|
fx.New(
|
||||||
fx.Provide(globals.New),
|
fx.Supply(config.Path(opts.ConfigPath)), // 1. Config path
|
||||||
fx.Provide(log.New),
|
fx.Supply(opts.LogOptions), // 2. Log options
|
||||||
config.Module,
|
fx.Provide(globals.New), // 3. Globals
|
||||||
database.Module,
|
fx.Provide(log.New), // 4. Logger config
|
||||||
log.Module,
|
config.Module, // 5. Config
|
||||||
storage.Module,
|
database.Module, // 6. Database + Repositories
|
||||||
snapshot.Module,
|
log.Module, // 7. Logger initialization
|
||||||
fx.Provide(vaultik.New),
|
storage.Module, // 8. Storage backend (S3/file/rclone)
|
||||||
fx.Invoke(setupGlobals),
|
snapshot.Module, // 9. SnapshotManager + ScannerFactory
|
||||||
fx.NopLogger,
|
fx.Provide(vaultik.New), // 10. Vaultik orchestrator
|
||||||
|
)
|
||||||
```
|
```
|
||||||
|
|
||||||
Each module provides these:
|
### Key Type Instantiation Points
|
||||||
|
|
||||||
- `config.Module` provides `*config.Config`, from `config.Load`.
|
#### 1. Config (`config.Config`)
|
||||||
- `database.Module` provides `*database.DB` and `*database.Repositories`. It
|
- **Created by**: `config.Module` via `config.LoadConfig()`
|
||||||
creates the index file with mode `0600` when it does not exist.
|
- **When**: Application startup (fx DI)
|
||||||
- `storage.Module` provides the `storage.Storer` that the config selects.
|
- **Contains**: All configuration from YAML file (S3 credentials, encryption keys, paths, etc.)
|
||||||
- `snapshot.Module` provides the `snapshot.ScannerFactory` and the
|
|
||||||
`*snapshot.SnapshotManager`.
|
#### 2. Database (`database.DB`)
|
||||||
- `vaultik.New` provides `*vaultik.Vaultik`.
|
- **Created by**: `database.Module` via `database.New()`
|
||||||
|
- **When**: Application startup (fx DI)
|
||||||
A command runs through `cli.RunOperation`. It works like this:
|
- **Contains**: SQLite connection, path reference
|
||||||
|
|
||||||
- `RunWithApp` takes the lock when the command changes data, and then starts the
|
#### 3. Repositories (`database.Repositories`)
|
||||||
application.
|
- **Created by**: `database.Module` via `database.NewRepositories()`
|
||||||
- The command's function runs in its own goroutine.
|
- **When**: Application startup (fx DI)
|
||||||
- When the function returns, it asks the application to shut down.
|
- **Contains**: All repository interfaces (Files, Chunks, Blobs, Snapshots, etc.)
|
||||||
- On `SIGINT` or `SIGTERM`, the stop hook cancels the `Vaultik` context. It then
|
|
||||||
waits for the function to return, so that its temporary files are removed.
|
#### 4. Vaultik (`vaultik.Vaultik`)
|
||||||
- The wait ends after 30 seconds at most.
|
- **Created by**: `vaultik.New(VaultikParams)`
|
||||||
|
- **When**: Application startup (fx DI)
|
||||||
The `config` commands, `database delete`, `completion` and `version` do not
|
- **Contains**: All dependencies for backup operations
|
||||||
build the application.
|
|
||||||
|
```go
|
||||||
## Backup
|
type Vaultik struct {
|
||||||
|
Globals *globals.Globals
|
||||||
`Vaultik.CreateSnapshot` runs a backup. It does these steps in order:
|
Config *config.Config
|
||||||
|
DB *database.DB
|
||||||
- `EnsureStorageBinding` checks that the local index belongs to the configured
|
Repositories *database.Repositories
|
||||||
destination.
|
Storage storage.Storer
|
||||||
- `markDestination` checks the marker file and then writes it.
|
ScannerFactory snapshot.ScannerFactory
|
||||||
- `PruneDatabase` removes unfinished snapshots and unused records from the
|
SnapshotManager *snapshot.SnapshotManager
|
||||||
local index.
|
Shutdowner fx.Shutdowner
|
||||||
- `createNamedSnapshot` runs once for each snapshot name.
|
Fs afero.Fs
|
||||||
- With `--prune`, `runPostBackupPrune` removes old snapshots and unused data.
|
ctx context.Context
|
||||||
|
cancel context.CancelFunc
|
||||||
`CreateSnapshot` calls `skipPostBackupPrune` instead of `runPostBackupPrune` in
|
}
|
||||||
these cases:
|
```
|
||||||
|
|
||||||
- `--skip-errors` skipped a file or directory that could not be read.
|
#### 5. SnapshotManager (`snapshot.SnapshotManager`)
|
||||||
- A configured path held nothing.
|
- **Created by**: `snapshot.Module` via `snapshot.NewSnapshotManager()`
|
||||||
- An earlier snapshot of the same name found a mount point that this backup did
|
- **When**: Application startup (fx DI)
|
||||||
not find.
|
- **Responsibility**: Creates/completes snapshots, exports metadata to S3
|
||||||
|
|
||||||
`PruneDatabase` must succeed before anything is scanned. An unfinished snapshot
|
#### 6. Scanner (`snapshot.Scanner`)
|
||||||
left in the index would make the backup skip files that were never fully
|
- **Created by**: `ScannerFactory(ScannerParams)`
|
||||||
stored.
|
- **When**: Each `CreateSnapshot()` call
|
||||||
|
- **Contains**: Chunker, Packer, progress reporter
|
||||||
### One snapshot
|
|
||||||
|
```go
|
||||||
`createNamedSnapshot` does these steps:
|
// vaultik/snapshot.go: CreateSnapshot()
|
||||||
|
scanner := v.ScannerFactory(snapshot.ScannerParams{
|
||||||
- `resolveSnapshotPaths` makes each configured path absolute and resolves
|
EnableProgress: !opts.Cron,
|
||||||
symlinks.
|
Fs: v.Fs,
|
||||||
- `SnapshotManager.CreateSnapshotWithName` creates the snapshot record. The
|
})
|
||||||
record is not yet marked complete.
|
```
|
||||||
- `Scanner.Scan` backs up each path in turn.
|
|
||||||
- `finalizeSnapshotMetadata` uploads the snapshot's metadata and marks the
|
#### 7. Chunker (`chunker.Chunker`)
|
||||||
snapshot complete.
|
- **Created by**: `chunker.NewChunker(avgChunkSize)`
|
||||||
|
- **When**: Inside `snapshot.NewScanner()`
|
||||||
A new `Scanner` is created for each snapshot, from `ScannerFactory`. It owns a
|
- **Configuration**:
|
||||||
`Chunker` and a `Packer`.
|
- `avgChunkSize`: From config (default 10MB)
|
||||||
|
- `minChunkSize`: avgChunkSize / 4
|
||||||
### Scanning one path
|
- `maxChunkSize`: avgChunkSize * 4
|
||||||
|
|
||||||
`Scanner.Scan` works in these steps:
|
#### 8. Packer (`blob.Packer`)
|
||||||
|
- **Created by**: `blob.NewPacker(PackerConfig)`
|
||||||
- `repairInterruptedBlobs` deletes the records of blobs whose upload never
|
- **When**: Inside `snapshot.NewScanner()`
|
||||||
finished. Their data is then stored again.
|
- **Configuration**:
|
||||||
- `loadDatabaseState` loads the known files and chunks into memory.
|
- `MaxBlobSize`: Maximum blob size before finalization (typically 10GB)
|
||||||
- `scanPhase` walks the path. It sorts each entry into changed or unchanged.
|
- `CompressionLevel`: zstd level (1-19)
|
||||||
- `detectDeletedFiles` counts the files that the previous snapshot of this name
|
- `Recipients`: age public keys for encryption
|
||||||
had and that are now gone.
|
|
||||||
- `batchAddFilesToSnapshot` records the unchanged files in the new snapshot.
|
```go
|
||||||
- `recordDirectories` records every directory, and the mount points found.
|
// snapshot/scanner.go: NewScanner()
|
||||||
- `processPhase` reads each changed file and stores it.
|
packerCfg := blob.PackerConfig{
|
||||||
|
MaxBlobSize: cfg.MaxBlobSize,
|
||||||
The walk handles each kind of entry differently:
|
CompressionLevel: cfg.CompressionLevel,
|
||||||
|
Recipients: cfg.AgeRecipients,
|
||||||
- A regular file or a symlink is compared with its record in the index.
|
Repositories: cfg.Repositories,
|
||||||
- A directory is recorded with its metadata. It has no content to store.
|
Fs: cfg.FS,
|
||||||
- A device node, a named pipe or a socket is skipped.
|
}
|
||||||
- An entry that matches an exclude pattern is skipped. For a directory, so is
|
packer, err := blob.NewPacker(packerCfg)
|
||||||
everything in it.
|
```
|
||||||
|
|
||||||
### Deduplication
|
## Module Responsibilities
|
||||||
|
|
||||||
Data is stored once at two levels.
|
### `internal/cli`
|
||||||
|
Entry point for fx application. Combines all modules and handles signal interrupts.
|
||||||
- **Files.** A file is not read again when its record in the index still matches
|
|
||||||
it.
|
Key functions:
|
||||||
- **Chunks.** A chunk is named by the SHA-256 hash of its content. A chunk whose
|
- `NewApp(AppOptions)` → Creates fx.App with all modules
|
||||||
hash is already in the index is not stored again.
|
- `RunApp(ctx, app)` → Starts app, handles graceful shutdown
|
||||||
|
- `RunWithApp(ctx, opts)` → Convenience wrapper
|
||||||
A file's record matches when all of these are unchanged:
|
|
||||||
|
### `internal/vaultik`
|
||||||
- the size
|
Main orchestrator containing all dependencies and command implementations.
|
||||||
- the modification time
|
|
||||||
- the mode
|
Key methods:
|
||||||
- the owner and group
|
- `New(VaultikParams)` → Constructor (fx DI)
|
||||||
- the link target
|
- `CreateSnapshot(opts)` → Main backup operation
|
||||||
|
- `ListSnapshots(jsonOutput)` → List available snapshots
|
||||||
One case overrides the file check. A file is read again when it lists a chunk
|
- `VerifySnapshot(id, deep)` → Verify snapshot integrity
|
||||||
that no uploaded blob holds. This happens when the only snapshot that used the
|
- `PurgeSnapshots(...)` → Remove old snapshots
|
||||||
blob holding that chunk is removed. `loadFilesToRechunk` finds these files.
|
|
||||||
|
### `internal/chunker`
|
||||||
### Chunks
|
Content-defined chunking using FastCDC algorithm.
|
||||||
|
|
||||||
`chunker.Chunker` cuts a file with the FastCDC algorithm. The cut points depend
|
Key types:
|
||||||
on the content, so an insertion early in a file moves only nearby chunks.
|
- `Chunk` → Hash, Data, Offset, Size
|
||||||
|
- `Chunker` → avgChunkSize, minChunkSize, maxChunkSize
|
||||||
`chunk_size` sets the average chunk size. No chunk is larger than four times
|
|
||||||
this size. Only a file's last chunk can be smaller than a quarter of it. With
|
Key methods:
|
||||||
the default of 10 MB, those limits are 40 MB and 2.5 MB.
|
- `NewChunker(avgChunkSize)` → Constructor
|
||||||
|
- `ChunkReaderStreaming(reader, callback)` → Stream chunks with callback (preferred)
|
||||||
`ChunkReaderStreaming` passes each chunk to a callback as it is found. The whole
|
- `ChunkReader(reader)` → Return all chunks at once (memory-intensive)
|
||||||
file is never held in memory.
|
|
||||||
|
### `internal/blob`
|
||||||
### Blobs
|
Blob packing: accumulates chunks, compresses, encrypts, tracks metadata.
|
||||||
|
|
||||||
`blob.Packer` collects new chunks into a blob. For each blob it does this:
|
Key types:
|
||||||
|
- `Packer` → Thread-safe blob accumulator
|
||||||
- It gives the blob a UUID and creates a temporary file.
|
- `ChunkRef` → Hash + Data for adding to packer
|
||||||
- It adds each chunk's bytes to a running SHA-256 hash.
|
- `FinishedBlob` → Completed blob ready for upload
|
||||||
- In the same pass it compresses the bytes with zstd and encrypts them with
|
- `BlobWithReader` → FinishedBlob + io.Reader for streaming upload
|
||||||
age. The result goes to the temporary file.
|
|
||||||
- It records each chunk's offset and length within the blob.
|
Key methods:
|
||||||
- It closes the blob when the next chunk would pass `blob_size_limit`, and at
|
- `NewPacker(PackerConfig)` → Constructor
|
||||||
the end of each path.
|
- `AddChunk(ChunkRef)` → Add chunk to current blob
|
||||||
|
- `FinalizeBlob()` → Compress, encrypt, hash current blob
|
||||||
The blob's name is `hex(SHA256(SHA256(uncompressed contents)))`. It is computed
|
- `Flush()` → Finalize any in-progress blob
|
||||||
from the chunk data before compression and encryption.
|
- `SetBlobHandler(func)` → Set callback for upload
|
||||||
[docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#blobs) says what follows from
|
|
||||||
that.
|
### `internal/snapshot`
|
||||||
|
|
||||||
When a blob is closed, `Scanner.handleBlobReady` stores it:
|
#### Scanner
|
||||||
|
Orchestrates the backup process for a directory.
|
||||||
- It looks the blob up at the destination. A blob that is already there is not
|
|
||||||
uploaded again.
|
Key methods:
|
||||||
- Otherwise it uploads the temporary file to
|
- `NewScanner(ScannerConfig)` → Constructor (creates Chunker + Packer)
|
||||||
`blobs/<hash[0:2]>/<hash[2:4]>/<hash>`.
|
- `Scan(ctx, path, snapshotID)` → Main scan operation
|
||||||
- It records the upload in the index and links the blob to the snapshot.
|
|
||||||
- It deletes the temporary file.
|
Scan phases:
|
||||||
|
1. **Phase 1**: Walk directory, identify files needing processing
|
||||||
A file's record is written to the index only after every blob that holds its
|
2. **Phase 1b**: Count as deleted the files that the previous snapshot of the same name lists, the walk did not find, and are gone from disk; a file that is excluded, or inside an excluded directory, is not counted
|
||||||
chunks is uploaded.
|
3. **Phase 2**: Process files (chunk → pack → upload)
|
||||||
|
|
||||||
### Snapshot metadata
|
#### SnapshotManager
|
||||||
|
Manages snapshot lifecycle and metadata export.
|
||||||
`finalizeSnapshotMetadata` does these steps in order:
|
|
||||||
|
Key methods:
|
||||||
- `PopulateSnapshotBlobs` records every blob the snapshot uses.
|
- `CreateSnapshot(ctx, hostname, version, commit)` → Create snapshot record
|
||||||
- `UpdateSnapshotStatsExtended` stores the snapshot's totals.
|
- `PopulateSnapshotBlobs(ctx, snapshotID)` → Record every blob the snapshot references
|
||||||
- `ExportSnapshotMetadata` uploads the metadata.
|
- `ExportSnapshotMetadata(ctx, dbPath, snapshotID)` → Export to S3
|
||||||
- `MarkSnapshotComplete` marks the snapshot complete.
|
- `MarkSnapshotComplete(ctx, snapshotID)` → Record completion, only after a successful export
|
||||||
|
- `CompleteSnapshot(ctx, snapshotID)` → Convenience: populate blobs, then mark complete (no export between)
|
||||||
Completion is recorded last on purpose. A backup that stops during the upload
|
|
||||||
leaves the snapshot unfinished, and the next backup removes it and stores its
|
### `internal/database`
|
||||||
data again.
|
SQLite database for local index. Single-writer mode for thread safety.
|
||||||
|
|
||||||
`ExportSnapshotMetadata` works on a copy of the index, never on the index
|
Key types:
|
||||||
itself:
|
- `DB` → Database connection wrapper
|
||||||
|
- `Repositories` → Collection of all repository interfaces
|
||||||
- It copies the index into a temporary directory with `VACUUM INTO`.
|
|
||||||
- It deletes the rows of every other snapshot from the copy. It also deletes the
|
Repository interfaces:
|
||||||
files and blobs that this snapshot does not use. It then deletes each chunk
|
- `FilesRepository` → CRUD for File records
|
||||||
that no remaining file and no remaining blob uses.
|
- `ChunksRepository` → CRUD for Chunk records
|
||||||
- It keeps the `local_meta` and `schema_migrations` tables as they are. The
|
- `BlobsRepository` → CRUD for Blob records
|
||||||
uploaded database therefore names the destination, and lists the migrations
|
- `SnapshotsRepository` → CRUD for Snapshot records
|
||||||
that have run.
|
- Plus join table repositories (FileChunks, BlobChunks, etc.)
|
||||||
- It runs `VACUUM`, so that no deleted row is left in the file.
|
|
||||||
- It compresses the copy with zstd and encrypts it with age.
|
## Snapshot Creation Flow
|
||||||
- It builds the manifest from the copy.
|
|
||||||
- It uploads `metadata/<remote-key>/db.zst.age`, and then
|
```
|
||||||
`metadata/<remote-key>/manifest.json.zst`.
|
CreateSnapshot(opts)
|
||||||
|
│
|
||||||
The manifest is uploaded last. A directory under `metadata/` with no manifest
|
├─► markDestination() // Refuse a destination without the marker, then write it
|
||||||
therefore marks a backup that did not finish.
|
│
|
||||||
|
├─► PruneDatabase() // Critical: avoid dedup errors
|
||||||
## Restore
|
│
|
||||||
|
├─► SnapshotManager.CreateSnapshot() // Create DB record
|
||||||
`Vaultik.Restore` does these steps:
|
│
|
||||||
|
├─► For each source directory:
|
||||||
- `restoreIdentities` parses the age private key. A missing or malformed key
|
│ │
|
||||||
stops the restore before anything is downloaded.
|
│ ├─► scanner.Scan(ctx, path, snapshotID)
|
||||||
- `downloadSnapshotDB` downloads and decrypts the snapshot's database into a
|
│ │ │
|
||||||
temporary directory.
|
│ │ ├─► Phase 1: scanPhase()
|
||||||
- `getFilesToRestore` selects the files, from the paths given.
|
│ │ │ Walk directory
|
||||||
- `restoreAllFiles` downloads blobs and writes the files.
|
│ │ │ Check file metadata changes
|
||||||
- With `--verify`, `verifyRestoredFiles` reads each restored file and checks its
|
│ │ │ Build list of files to process
|
||||||
chunk hashes.
|
│ │ │
|
||||||
|
│ │ ├─► Phase 1b: detectDeletedFiles()
|
||||||
The restore does not read the local index or the manifest. It finds each file's
|
│ │ │
|
||||||
chunks and blobs through the downloaded database.
|
│ │ └─► Phase 2: processPhase()
|
||||||
|
│ │ For each file:
|
||||||
### Checks on the downloaded database
|
│ │ chunker.ChunkReaderStreaming()
|
||||||
|
│ │ For each chunk:
|
||||||
Decryption shows that a database is readable. It does not show that the
|
│ │ packer.AddChunk()
|
||||||
database is honest. The restore therefore checks it:
|
│ │ If blob full → FinalizeBlob()
|
||||||
|
│ │ → handleBlobReady()
|
||||||
- `database.OpenReadOnly` opens the file read-only. It refuses a file that has a
|
│ │ → s3Client.PutObjectWithProgress()
|
||||||
trigger, a view or a virtual table, or that lacks an expected table.
|
│ │ packer.Flush() // Final blob
|
||||||
- `verifySnapshotDBIdentity` checks that the snapshot in the database hashes to
|
│ │
|
||||||
the remote key that was asked for.
|
│ └─► Accumulate statistics
|
||||||
- `containedRestorePath` refuses a stored path that would leave the target
|
│
|
||||||
directory. It also refuses to write through a symlink below the target.
|
├─► SnapshotManager.PopulateSnapshotBlobs() // record referenced blobs
|
||||||
- A blob is not decompressed beyond the size that the database gives for it.
|
│
|
||||||
- Each downloaded blob is hashed. The hash must match the blob's name.
|
├─► SnapshotManager.UpdateSnapshotStatsExtended()
|
||||||
|
│
|
||||||
### Order of work
|
├─► SnapshotManager.ExportSnapshotMetadata()
|
||||||
|
│ │
|
||||||
`restorePlan` orders the files so that few blobs are on disk at once:
|
│ ├─► Copy database to temp file
|
||||||
|
│ ├─► Clean to only current snapshot data (VACUUM)
|
||||||
- Downloaded blobs are kept decrypted in a cache directory.
|
│ ├─► Compress binary SQLite with zstd
|
||||||
- A file is restored once every blob it needs is in the cache.
|
│ ├─► Encrypt with age
|
||||||
- When no file is ready, the restore downloads the blobs for the file that
|
│ ├─► Upload db.zst.age to storage
|
||||||
needs the fewest.
|
│ └─► Upload manifest.json.zst to storage
|
||||||
- `restoreSweeper` deletes a cached blob once no remaining file needs it.
|
│
|
||||||
|
└─► SnapshotManager.MarkSnapshotComplete() // only after the export succeeds
|
||||||
A regular file is created with mode `0600` and gets its stored mode after its
|
```
|
||||||
content is written. A directory gets its stored mode, owner and modification
|
|
||||||
time after the whole restore.
|
## Deduplication Strategy
|
||||||
|
|
||||||
## Verify
|
1. **File-level**: Files and symlinks unchanged since last backup are skipped (metadata comparison: size, mtime, mode, uid, gid, and a symlink's target), unless the file lists a chunk that no uploaded blob holds; such a file is re-chunked
|
||||||
|
|
||||||
`Vaultik.VerifySnapshotWithOptions` checks a snapshot without the private key:
|
2. **Chunk-level**: Chunks are content-addressed by SHA256 hash. If a chunk hash already exists in the database, the chunk data is not re-uploaded.
|
||||||
|
|
||||||
- It downloads the manifest.
|
3. **Blob-level**: Blobs contain only unique chunks. Duplicate chunks within a blob are skipped.
|
||||||
- It checks that the snapshot's encrypted database is present.
|
|
||||||
- It checks that each listed blob is present with the listed size.
|
## Storage Layout in S3
|
||||||
|
|
||||||
`Vaultik.RunDeepVerify` needs the private key. It does these steps:
|
```
|
||||||
|
bucket/
|
||||||
- It downloads the manifest and the database. It checks the database as a
|
├── vaultik-destination.txt # Marker written by every backup
|
||||||
restore does.
|
│
|
||||||
- `verifyManifestAgainstDatabase` checks that both list the same blobs with the
|
├── blobs/
|
||||||
same sizes.
|
│ └── {hash[0:2]}/
|
||||||
- `verifyBlobExistenceFromDB` checks that every blob is present with the
|
│ └── {hash[2:4]}/
|
||||||
recorded size.
|
│ └── {full-hash} # Compressed+encrypted blob
|
||||||
- `verifyBlob` downloads each blob, checks the hash of each chunk in it, and
|
│
|
||||||
checks the hash that names the blob.
|
└── metadata/
|
||||||
|
└── {remote-key}/
|
||||||
## Prune
|
├── db.zst.age # Encrypted binary SQLite database
|
||||||
|
└── manifest.json.zst # Blob list (for pruning/verification)
|
||||||
`Vaultik.Prune` does three steps:
|
```
|
||||||
|
|
||||||
- `CleanupLocalSnapshots` drops from the local index each snapshot whose
|
A destination without `vaultik-destination.txt` is treated as not present
|
||||||
manifest is gone from the destination.
|
while the local index holds snapshots stored there (`checkDestinationMarker`
|
||||||
- `PruneDatabase` removes unfinished snapshots and unused records from the
|
in `internal/vaultik/destination_marker.go`): `snapshot create` refuses to
|
||||||
local index.
|
write to it, `prune`, `snapshot purge` and `remote nuke` fail, and
|
||||||
- `PruneBlobs` deletes unused data at the destination.
|
`snapshot list` and `snapshot remove` behave as for a destination that cannot
|
||||||
|
be listed. This keeps those commands from taking an unplugged volume's empty
|
||||||
`PruneBlobs` reads every manifest at the destination. It then deletes two kinds
|
mount point for a destination whose snapshots are all gone. The `file://`
|
||||||
of object, once they are older than `prune_grace_period`:
|
backend never creates its destination directory, so a write to a missing one
|
||||||
|
fails.
|
||||||
- a blob that no manifest lists
|
|
||||||
- a directory under `metadata/` that has no manifest, and whose snapshot is not
|
The `{remote-key}` directory name is a one-way double SHA-256 hash of the human
|
||||||
in the local index
|
snapshot ID, so the human ID (hostname, snapshot name, timestamp) is never
|
||||||
|
written to the store as a directory name. See
|
||||||
It deletes nothing when any manifest cannot be read.
|
[docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#remote-key-derivation) for the
|
||||||
[docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#pruning) explains why this is
|
derivation and a worked example.
|
||||||
safe, and where it is not.
|
|
||||||
|
## Thread Safety
|
||||||
## The destination
|
|
||||||
|
- `Packer`: Thread-safe via mutex. Multiple goroutines can call `AddChunk()`.
|
||||||
`storage.Storer` is the only way the code reaches the destination. It has these
|
- `Scanner`: Uses `packerMu` mutex to coordinate blob finalization.
|
||||||
methods:
|
- `Database`: Single-writer mode (`MaxOpenConns=1`) ensures SQLite thread safety.
|
||||||
|
- `Repositories.WithTx()`: Handles transaction lifecycle automatically.
|
||||||
- `Put` and `PutWithProgress` store an object.
|
|
||||||
- `Get` reads an object.
|
|
||||||
- `Stat` reports an object's size.
|
|
||||||
- `Delete` removes an object.
|
|
||||||
- `List` and `ListStream` list the objects under a prefix.
|
|
||||||
- `DeletePartialUploads` removes what an interrupted upload left behind.
|
|
||||||
- `Info` describes the destination.
|
|
||||||
|
|
||||||
`storage.NewStorer` picks the implementation from `storage_url`:
|
|
||||||
|
|
||||||
- `s3://` gives the S3 implementation.
|
|
||||||
- `file://` gives the local directory implementation.
|
|
||||||
- `rclone://` gives the rclone implementation.
|
|
||||||
|
|
||||||
With no `storage_url`, it builds the S3 implementation from the `s3` settings.
|
|
||||||
|
|
||||||
## The marker file and the destination binding
|
|
||||||
|
|
||||||
Two checks keep the local index and the destination in step.
|
|
||||||
|
|
||||||
- `checkDestinationMarker` looks for `vaultik-destination.txt`. It fails when
|
|
||||||
the file is reported missing while the local index holds snapshots.
|
|
||||||
- `EnsureStorageBinding` records the configured destination in the local index
|
|
||||||
on first use. Later it fails when the config names a different destination.
|
|
||||||
|
|
||||||
Every command that changes data calls `EnsureStorageBinding` first.
|
|
||||||
|
|
||||||
## Concurrency
|
|
||||||
|
|
||||||
- The local index is opened with one connection, so its queries run one at a
|
|
||||||
time.
|
|
||||||
- The index runs in SQLite's WAL mode. A second process can therefore read it
|
|
||||||
while a backup writes to it.
|
|
||||||
- `Packer` guards its state with a mutex.
|
|
||||||
- `Scanner` holds `packerMu` while a chunk is added to the packer and while a
|
|
||||||
blob is closed.
|
|
||||||
- `Repositories.WithTx` runs a function in one transaction. It commits when the
|
|
||||||
function succeeds and rolls back when it fails.
|
|
||||||
|
|||||||
@@ -24,23 +24,6 @@ owner's; a `v*` tag runs the release build in
|
|||||||
|
|
||||||
# Completed Steps
|
# Completed Steps
|
||||||
|
|
||||||
- 2026-10-15: Stopped `snapshot create --prune` pruning after a backup
|
|
||||||
in which a volume mounted below a configured path in an earlier
|
|
||||||
snapshot of the same name was not mounted
|
|
||||||
([issue #395](https://git.eeqj.de/sneak/vaultik/issues/395)). Such a
|
|
||||||
prune could delete every snapshot still holding the volume's files.
|
|
||||||
Each snapshot now records in the local index the directories it found
|
|
||||||
on a different filesystem from their parent and found an entry in that
|
|
||||||
the backup does not exclude.
|
|
||||||
|
|
||||||
- 2026-10-14: Stopped `snapshot create --prune` pruning after a backup
|
|
||||||
that found nothing in a configured path
|
|
||||||
([issue #388](https://git.eeqj.de/sneak/vaultik/issues/388)), as in
|
|
||||||
the mount point of a volume that is not mounted. Such a prune could
|
|
||||||
delete every snapshot still holding that path's files. A configured
|
|
||||||
path that is a symlink whose target is gone, as one into such a
|
|
||||||
volume, now fails the backup, with or without `--prune`.
|
|
||||||
|
|
||||||
- 2026-10-14: Stopped `snapshot create --prune` pruning after a backup
|
- 2026-10-14: Stopped `snapshot create --prune` pruning after a backup
|
||||||
that skipped files it could not read
|
that skipped files it could not read
|
||||||
([issue #382](https://git.eeqj.de/sneak/vaultik/issues/382)). Such a
|
([issue #382](https://git.eeqj.de/sneak/vaultik/issues/382)). Such a
|
||||||
@@ -1316,64 +1299,5 @@ owner's; a `v*` tag runs the release build in
|
|||||||
|
|
||||||
# Future Steps
|
# Future Steps
|
||||||
|
|
||||||
Work planned after 1.0, loosely ordered by priority.
|
Work planned after 1.0 is listed in the README
|
||||||
|
[roadmap](README.md#roadmap).
|
||||||
## Correctness and operability
|
|
||||||
|
|
||||||
- **Outside security audit.** Before 1.0 the encryption and
|
|
||||||
blob-generation code was reviewed. Every bug the review found was
|
|
||||||
fixed. The risks it accepted are listed in
|
|
||||||
[Accepted risks](docs/REPOSTRUCTURE.md#accepted-risks). No outside
|
|
||||||
audit has been done. age, zstd and content-defined chunking are mostly
|
|
||||||
off-the-shelf pieces. The code that joins them needs an outside read:
|
|
||||||
- key handling
|
|
||||||
- recipient parsing
|
|
||||||
- manifest trust boundary
|
|
||||||
- restore-time identity validation
|
|
||||||
- **Verify restored content end-to-end in CI.** The current integration
|
|
||||||
test does this for a small synthetic snapshot but not at scale. A
|
|
||||||
nightly job against a multi-GB representative snapshot would catch
|
|
||||||
silent regressions in the chunker, packer, or restore planner.
|
|
||||||
|
|
||||||
## Performance
|
|
||||||
|
|
||||||
- **Parallel blob downloads during restore.** A restore downloads one
|
|
||||||
blob at a time now. With a fast S3 endpoint and a multi-core machine,
|
|
||||||
restore speed is bound by the fetch, decryption and decompression of
|
|
||||||
each blob. Running several of those in parallel against the disk
|
|
||||||
cache would close most of the remaining gap. This needs to interact
|
|
||||||
correctly with the locality planner and the sweeper.
|
|
||||||
- **Bandwidth limiting (`--bwlimit`).** For both upload and download.
|
|
||||||
It is useful for backing up over a shared link. It is tricky to make
|
|
||||||
work correctly with parallel downloads.
|
|
||||||
- **Restart of interrupted restore.** Today a restore can be started
|
|
||||||
again, and it then overwrites the partial output. It does not resume
|
|
||||||
from where it stopped, and it does not skip files that are already
|
|
||||||
present. A `--resume` mode that checks targets before fetching blobs
|
|
||||||
would matter for very large restores.
|
|
||||||
- **Daemon mode.** A long-running mode that watches for file changes,
|
|
||||||
so that frequent backups, such as hourly ones, skip the full scan. It
|
|
||||||
adds little for the usual backups from cron every 12 to 36 hours. See
|
|
||||||
[issue #204](https://git.eeqj.de/sneak/vaultik/issues/204).
|
|
||||||
|
|
||||||
## Usability
|
|
||||||
|
|
||||||
- **Man pages and richer `--help` examples.** Cobra generates basic
|
|
||||||
help. Man pages would be a separate target.
|
|
||||||
- **`vaultik snapshot diff <a> <b>`.** Show which files changed between
|
|
||||||
two snapshots, without restoring either.
|
|
||||||
- **Status reporting hook for `--cron`.** When a backup fails silently
|
|
||||||
in cron, the user has no idea. A configurable hook on completion, for
|
|
||||||
both success and failure, would close the loop. It could be a
|
|
||||||
webhook, an email or `notify-send`.
|
|
||||||
|
|
||||||
## Infrastructure
|
|
||||||
|
|
||||||
- **Schema migrations after 1.0.** Migrations are supported, but none
|
|
||||||
are added before 1.0 because there is no installed base yet. After
|
|
||||||
1.0, each schema change is a new migration, so an existing local
|
|
||||||
index is migrated when `vaultik` is updated. See
|
|
||||||
[`docs/DATAMODEL.md`](docs/DATAMODEL.md#schema-migrations).
|
|
||||||
- **Storage backend coverage tests.** S3, `file://` and `rclone://` all
|
|
||||||
share the `Storer` interface, but the rclone path is the least
|
|
||||||
exercised in CI.
|
|
||||||
|
|||||||
+7
-30
@@ -1,31 +1,16 @@
|
|||||||
# vaultik configuration file example
|
# vaultik configuration file example
|
||||||
# This file shows every configuration option. The values are examples, not
|
# This file shows all available configuration options with their default values
|
||||||
# defaults; where an option has a default, its comment gives it.
|
# Copy this file and uncomment/modify the values you need
|
||||||
# Copy this file and change the values you need
|
|
||||||
|
|
||||||
# Age recipient public keys for encryption
|
# Age recipient public keys for encryption
|
||||||
# Backups are encrypted to these public keys. snapshot create needs at least
|
# Backups are encrypted to these public keys. snapshot create needs at least
|
||||||
# one; listing, verifying and restoring do not
|
# one; listing, verifying and restoring do not
|
||||||
# Generate a key pair, and show its public key, with:
|
# Generate with: age-keygen | grep "public key"
|
||||||
# age-keygen -o vaultik_backup_private_key.txt
|
|
||||||
# grep 'public key' vaultik_backup_private_key.txt
|
|
||||||
# Keep the private key file: restoring needs it. Do not pipe age-keygen
|
|
||||||
# straight into grep, which would discard the private key
|
|
||||||
age_recipients:
|
age_recipients:
|
||||||
- age1cj2k2addawy294f6k2gr2mf9gps9r3syplryxca3nvxj3daqm96qfp84tz
|
- age1cj2k2addawy294f6k2gr2mf9gps9r3syplryxca3nvxj3daqm96qfp84tz
|
||||||
|
|
||||||
# Age private key for decryption
|
|
||||||
# Only snapshot restore and snapshot verify --deep need it. The
|
|
||||||
# VAULTIK_AGE_SECRET_KEY environment variable overrides this setting
|
|
||||||
# Do not set it on a machine you back up: prefer the environment variable,
|
|
||||||
# supplied only on the machine you restore on
|
|
||||||
# Default: not set
|
|
||||||
#age_secret_key: YOUR_AGE_PRIVATE_KEY
|
|
||||||
|
|
||||||
# Named snapshots - each snapshot can contain multiple paths
|
# Named snapshots - each snapshot can contain multiple paths
|
||||||
# Each snapshot gets its own ID and can have snapshot-specific excludes
|
# Each snapshot gets its own ID and can have snapshot-specific excludes
|
||||||
# Required: at least one snapshot with at least one path. Only the config
|
|
||||||
# commands, version and completion run without one
|
|
||||||
snapshots:
|
snapshots:
|
||||||
testing:
|
testing:
|
||||||
paths:
|
paths:
|
||||||
@@ -273,11 +258,6 @@ exclude:
|
|||||||
|
|
||||||
# Storage URL - use either this OR the s3 section below
|
# Storage URL - use either this OR the s3 section below
|
||||||
# Supports: s3://bucket/prefix, file:///path, rclone://remote/path
|
# Supports: s3://bucket/prefix, file:///path, rclone://remote/path
|
||||||
# An s3:// URL also needs s3.access_key_id and s3.secret_access_key below
|
|
||||||
# A file:// path must be absolute, and the directory must already exist:
|
|
||||||
# vaultik never creates it
|
|
||||||
# An rclone:// URL needs the remote to be defined in rclone's own config
|
|
||||||
# (rclone config)
|
|
||||||
storage_url: "rclone://myremote/path/to/backups"
|
storage_url: "rclone://myremote/path/to/backups"
|
||||||
|
|
||||||
# S3-compatible storage configuration
|
# S3-compatible storage configuration
|
||||||
@@ -303,8 +283,6 @@ storage_url: "rclone://myremote/path/to/backups"
|
|||||||
# #region: us-east-1
|
# #region: us-east-1
|
||||||
#
|
#
|
||||||
# # Use SSL/TLS for S3 connections
|
# # Use SSL/TLS for S3 connections
|
||||||
# # Only read when storage_url is not set and the endpoint has no scheme;
|
|
||||||
# # with an s3:// storage_url, use ?ssl=false in the URL instead
|
|
||||||
# # Default: true
|
# # Default: true
|
||||||
# #use_ssl: true
|
# #use_ssl: true
|
||||||
#
|
#
|
||||||
@@ -317,7 +295,6 @@ storage_url: "rclone://myremote/path/to/backups"
|
|||||||
|
|
||||||
# Path to local SQLite index database
|
# Path to local SQLite index database
|
||||||
# This database tracks file state for incremental backups
|
# This database tracks file state for incremental backups
|
||||||
# The VAULTIK_INDEX_PATH environment variable overrides this setting
|
|
||||||
# Default: the platform data directory, e.g.
|
# Default: the platform data directory, e.g.
|
||||||
# macOS: ~/Library/Application Support/vaultik/index.sqlite
|
# macOS: ~/Library/Application Support/vaultik/index.sqlite
|
||||||
# Linux: ~/.local/share/vaultik/index.sqlite
|
# Linux: ~/.local/share/vaultik/index.sqlite
|
||||||
@@ -355,13 +332,13 @@ compression_level: 5
|
|||||||
# How old a blob that no snapshot lists must be before prune deletes it, and
|
# How old a blob that no snapshot lists must be before prune deletes it, and
|
||||||
# how old every object in a directory under metadata/ with no manifest must
|
# how old every object in a directory under metadata/ with no manifest must
|
||||||
# be before prune deletes that directory
|
# be before prune deletes that directory
|
||||||
# A backup uploads its blobs and its db.zst.age before its manifest, so on a
|
# A backup uploads its blobs and its db.zst.age before the manifest that
|
||||||
# destination shared between hosts or users this must be longer than the
|
# lists them, so on a destination shared between hosts or users this must be
|
||||||
# longest backup run
|
# longer than the longest backup run
|
||||||
# It does not protect a blob a backup reuses from an earlier run that stopped
|
# It does not protect a blob a backup reuses from an earlier run that stopped
|
||||||
# before its manifest: that blob keeps the time of its first upload, so a
|
# before its manifest: that blob keeps the time of its first upload, so a
|
||||||
# prune can delete it
|
# prune can delete it
|
||||||
# Supports: 36h, 90m, etc.; 0s deletes such blobs and directories at once
|
# Supports: 36h, 90m, etc.; 0s deletes them at once
|
||||||
# Default: 24h
|
# Default: 24h
|
||||||
#prune_grace_period: 24h
|
#prune_grace_period: 24h
|
||||||
|
|
||||||
|
|||||||
+264
-385
@@ -1,418 +1,297 @@
|
|||||||
# vaultik data model
|
# Vaultik Data Model
|
||||||
|
|
||||||
`vaultik` keeps a SQLite database on the backed-up machine, called the local
|
## Overview
|
||||||
index. This document describes its tables and how each command uses them.
|
|
||||||
|
|
||||||
The local index has two jobs:
|
Vaultik uses a local SQLite database to track file metadata, chunk mappings, and blob associations during the backup process. This database serves as an index for incremental backups and enables efficient deduplication.
|
||||||
|
|
||||||
- It records which files, chunks and blobs are already stored. The next backup
|
**Important Notes:**
|
||||||
then does not store them again.
|
|
||||||
- It is the source of each snapshot's own database. A backup uploads a trimmed,
|
|
||||||
encrypted copy of the index with every snapshot.
|
|
||||||
|
|
||||||
A restore does not need the local index. It reads the copy that was uploaded
|
- **Version Compatibility**: In rare cases, you may need to use the same version
|
||||||
with the snapshot.
|
of Vaultik to restore a backup as was used to create it. This ensures
|
||||||
|
compatibility with the metadata format stored in S3.
|
||||||
|
|
||||||
## Terms
|
## Schema Migrations
|
||||||
|
|
||||||
- **Snapshot**: one backup of the paths listed under one name in the config.
|
Vaultik supports schema migrations. They are the numbered SQL files in
|
||||||
- **Chunk**: a piece of a file's content, named by the SHA-256 hash of that
|
`internal/database/schema/`, embedded in the binary: `000.sql` creates the
|
||||||
content.
|
`schema_migrations` table, which records each migration that has run, and
|
||||||
- **Blob**: one object at the destination. It holds many chunks, compressed and
|
`001.sql` creates the application tables. `database.New` opens a database and
|
||||||
then encrypted.
|
applies, in order, every migration that database has not yet recorded.
|
||||||
- **Destination**: the place the backups are stored.
|
|
||||||
- **Manifest**: the unencrypted list of the blobs one snapshot uses.
|
|
||||||
- **Remote key**: a hash of the snapshot ID. It names the snapshot's directory
|
|
||||||
at the destination.
|
|
||||||
|
|
||||||
## Where the index is
|
**Before 1.0** no migrations are added, because nothing is installed anywhere
|
||||||
|
yet. A schema change edits `001.sql` (and the code that uses the affected
|
||||||
|
tables) directly. A local database created before the change has already
|
||||||
|
recorded `001.sql` as run, so it keeps the old schema and can become unusable;
|
||||||
|
`vaultik database delete` followed by a full backup rebuilds it.
|
||||||
|
|
||||||
|
**After 1.0** each schema change is a new numbered file, so an existing local
|
||||||
|
database is migrated the first time an updated vaultik opens it. A file that
|
||||||
|
has shipped in a release is never edited.
|
||||||
|
|
||||||
|
## Database Tables
|
||||||
|
|
||||||
|
### 1. `files`
|
||||||
|
Stores metadata about files in the filesystem being backed up.
|
||||||
|
|
||||||
|
**Columns:**
|
||||||
|
- `id` (TEXT PRIMARY KEY) - UUID for the file record
|
||||||
|
- `path` (TEXT NOT NULL UNIQUE) - Absolute file path
|
||||||
|
- `mtime` (INTEGER NOT NULL) - Modification time, whole seconds since the Unix epoch
|
||||||
|
- `mtime_nsec` (INTEGER NOT NULL) - Nanoseconds within that second, 0 to 999999999
|
||||||
|
- `size` (INTEGER NOT NULL) - File size in bytes
|
||||||
|
- `mode` (INTEGER NOT NULL) - Unix file permissions and type
|
||||||
|
- `uid` (INTEGER NOT NULL) - User ID of file owner
|
||||||
|
- `gid` (INTEGER NOT NULL) - Group ID of file owner
|
||||||
|
- `link_target` (TEXT) - Symlink target path (NULL for regular files)
|
||||||
|
|
||||||
|
**Indexes:**
|
||||||
|
- `idx_files_path` on `path` for efficient lookups
|
||||||
|
|
||||||
|
**Purpose:** Tracks file metadata to detect changes between backup runs. Used for incremental backup decisions. The UUID primary key provides stable references that don't change if files are moved.
|
||||||
|
|
||||||
|
### 2. `chunks`
|
||||||
|
Stores information about content-defined chunks created from files.
|
||||||
|
|
||||||
|
**Columns:**
|
||||||
|
- `chunk_hash` (TEXT PRIMARY KEY) - SHA256 hash of chunk content
|
||||||
|
- `size` (INTEGER NOT NULL) - Chunk size in bytes
|
||||||
|
|
||||||
The index is the file `index.sqlite` in the platform data directory. That is
|
**Purpose:** Enables deduplication by tracking unique chunks across all files.
|
||||||
`~/.local/share/vaultik/` on Linux and `~/Library/Application Support/vaultik/`
|
|
||||||
on macOS. The `index_path` setting and the `VAULTIK_INDEX_PATH` environment
|
### 3. `file_chunks`
|
||||||
variable change the path.
|
Maps files to their constituent chunks in order.
|
||||||
|
|
||||||
|
**Columns:**
|
||||||
|
- `file_id` (TEXT) - File ID (FK to files.id)
|
||||||
|
- `idx` (INTEGER) - Chunk index within file (0-based)
|
||||||
|
- `chunk_hash` (TEXT) - Chunk hash (FK to chunks.chunk_hash)
|
||||||
|
- PRIMARY KEY (`file_id`, `idx`)
|
||||||
|
|
||||||
The file is readable only by its owner, because it lists every backed-up path.
|
**Purpose:** Allows reconstruction of files from chunks during restore.
|
||||||
`vaultik` sets that mode each time it opens the index.
|
|
||||||
|
|
||||||
## Schema migrations
|
### 4. `chunk_files`
|
||||||
|
Reverse mapping showing which files contain each chunk.
|
||||||
|
|
||||||
`vaultik` supports schema migrations. They are the numbered SQL files in
|
**Columns:**
|
||||||
`internal/database/schema/`, which are built into the binary.
|
- `chunk_hash` (TEXT) - Chunk hash (FK to chunks.chunk_hash)
|
||||||
|
- `file_id` (TEXT) - File ID (FK to files.id)
|
||||||
|
- `file_offset` (INTEGER) - Byte offset of chunk within file
|
||||||
|
- `length` (INTEGER) - Length of chunk in bytes
|
||||||
|
- PRIMARY KEY (`chunk_hash`, `file_id`)
|
||||||
|
|
||||||
- `000.sql` creates the `schema_migrations` table. That table records each
|
**Purpose:** Supports efficient queries for chunk usage and deduplication statistics.
|
||||||
migration that has run.
|
|
||||||
- `001.sql` creates every other table.
|
|
||||||
|
|
||||||
`database.New` opens the index. It then applies, in order, every migration that
|
### 5. `blobs`
|
||||||
the index has not recorded.
|
Stores information about packed, compressed, and encrypted blob files.
|
||||||
|
|
||||||
Before version 1.0, no migration is added, because nothing is installed anywhere
|
**Columns:**
|
||||||
yet. A schema change edits `001.sql` directly, with the code that uses the
|
- `id` (TEXT PRIMARY KEY) - UUID assigned when blob creation starts
|
||||||
changed tables.
|
- `blob_hash` (TEXT UNIQUE) - `hex(SHA256(SHA256(uncompressed blob contents)))`, computed before compression and encryption (NULL until finalized); see [REPOSTRUCTURE.md](REPOSTRUCTURE.md#blobs-directory-blobs)
|
||||||
|
- `created_ts` (INTEGER NOT NULL) - Creation timestamp
|
||||||
|
- `finished_ts` (INTEGER) - Finalization timestamp (NULL if in progress)
|
||||||
|
- `uncompressed_size` (INTEGER NOT NULL DEFAULT 0) - Total size of chunks before compression
|
||||||
|
- `compressed_size` (INTEGER NOT NULL DEFAULT 0) - Size after compression and encryption. Once uploaded, the size of the object in storage: when the blob was already stored, under another compression level or other recipients, this can differ from the size of the local copy
|
||||||
|
- `uploaded_ts` (INTEGER) - Upload completion timestamp (NULL if not uploaded)
|
||||||
|
|
||||||
This has one consequence. An index created before such a change has already
|
**Purpose:** Tracks blob lifecycle from creation through upload. The UUID primary key allows immediate association of chunks with blobs.
|
||||||
recorded `001.sql` as run, so it keeps the old schema and can become unusable.
|
|
||||||
To rebuild it, run `vaultik database delete` and then a full backup.
|
|
||||||
|
|
||||||
After version 1.0, each schema change is a new numbered file. An existing index
|
### 6. `blob_chunks`
|
||||||
is then migrated the first time an updated `vaultik` opens it. A file that was
|
Maps chunks to the blobs that contain them.
|
||||||
part of a release is never edited.
|
|
||||||
|
**Columns:**
|
||||||
|
- `blob_id` (TEXT) - Blob ID (FK to blobs.id)
|
||||||
|
- `chunk_hash` (TEXT) - Chunk hash (FK to chunks.chunk_hash)
|
||||||
|
- `offset` (INTEGER) - Byte offset of chunk within blob (before compression)
|
||||||
|
- `length` (INTEGER) - Length of chunk in bytes
|
||||||
|
- PRIMARY KEY (`blob_id`, `chunk_hash`)
|
||||||
|
|
||||||
|
**Purpose:** Enables chunk retrieval from blobs during restore operations.
|
||||||
|
|
||||||
|
### 7. `snapshots`
|
||||||
|
Tracks backup snapshots.
|
||||||
|
|
||||||
|
**Columns:**
|
||||||
|
- `id` (TEXT PRIMARY KEY) - Snapshot ID (format: `hostname_name_timestamp`, e.g. `server1_home_2025-06-01T12:00:00Z`: the hostname up to its first `.`, the snapshot name, and an RFC 3339 UTC timestamp)
|
||||||
|
- `hostname` (TEXT) - Hostname where backup was created
|
||||||
|
- `vaultik_version` (TEXT) - Version of Vaultik used
|
||||||
|
- `vaultik_git_revision` (TEXT) - Git revision of Vaultik used
|
||||||
|
- `started_at` (INTEGER) - Start timestamp
|
||||||
|
- `completed_at` (INTEGER) - Completion timestamp (NULL if in progress)
|
||||||
|
- `file_count` (INTEGER) - Number of files in snapshot
|
||||||
|
- `chunk_count` (INTEGER) - Number of chunks this snapshot stored that were not stored before
|
||||||
|
- `new_chunk_size` (INTEGER) - Total size of those chunks before compression; `snapshot list` shows it as NEW CHUNK SIZE
|
||||||
|
- `blob_count` (INTEGER) - Number of blobs this snapshot created
|
||||||
|
- `total_size` (INTEGER) - Total size of all files
|
||||||
|
- `uncompressed_chunk_size` (INTEGER) - Total size before compression of the distinct chunks the snapshot's files reference, recorded when its backup ran; `snapshot list` shows it as UNCOMPRESSED SIZE
|
||||||
|
- `blob_size` (INTEGER) - Total compressed size of all referenced blobs
|
||||||
|
- `blob_uncompressed_size` (INTEGER) - Total uncompressed size of all referenced blobs
|
||||||
|
- `compression_ratio` (REAL) - Compression ratio achieved
|
||||||
|
- `compression_level` (INTEGER) - Compression level used for this snapshot
|
||||||
|
- `upload_bytes` (INTEGER) - Total bytes uploaded during this snapshot
|
||||||
|
- `upload_duration_ms` (INTEGER) - Total milliseconds spent uploading to S3
|
||||||
|
|
||||||
|
**Purpose:** Provides snapshot metadata and statistics including version tracking for compatibility.
|
||||||
|
|
||||||
|
### 8. `snapshot_files`
|
||||||
|
Maps snapshots to the files they contain.
|
||||||
|
|
||||||
|
**Columns:**
|
||||||
|
- `snapshot_id` (TEXT) - Snapshot ID (FK to snapshots.id)
|
||||||
|
- `file_id` (TEXT) - File ID (FK to files.id)
|
||||||
|
- PRIMARY KEY (`snapshot_id`, `file_id`)
|
||||||
|
|
||||||
|
**Purpose:** Records which files are included in each snapshot.
|
||||||
|
|
||||||
|
### 9. `snapshot_blobs`
|
||||||
|
Maps snapshots to the blobs they reference.
|
||||||
|
|
||||||
|
**Columns:**
|
||||||
|
- `snapshot_id` (TEXT) - Snapshot ID (FK to snapshots.id)
|
||||||
|
- `blob_id` (TEXT) - Blob ID (FK to blobs.id)
|
||||||
|
- `blob_hash` (TEXT) - Denormalized blob hash for manifest generation
|
||||||
|
- PRIMARY KEY (`snapshot_id`, `blob_id`)
|
||||||
|
|
||||||
|
**Purpose:** Tracks blob dependencies for snapshots and enables manifest generation.
|
||||||
|
|
||||||
|
### 10. `uploads`
|
||||||
|
Tracks blob upload metrics.
|
||||||
|
|
||||||
|
**Columns:**
|
||||||
|
- `blob_hash` (TEXT PRIMARY KEY) - Hash of uploaded blob
|
||||||
|
- `snapshot_id` (TEXT NOT NULL) - The snapshot that triggered this upload (FK to snapshots.id)
|
||||||
|
- `uploaded_at` (INTEGER) - Upload timestamp
|
||||||
|
- `size` (INTEGER) - Size of uploaded blob
|
||||||
|
- `duration_ms` (INTEGER) - Upload duration in milliseconds
|
||||||
|
|
||||||
|
**Purpose:** Performance monitoring and tracking which blobs were newly created (uploaded) during each snapshot.
|
||||||
|
|
||||||
|
## Data Flow and Operations
|
||||||
|
|
||||||
|
### 1. Backup Process
|
||||||
|
|
||||||
|
1. **File Scanning**
|
||||||
|
- `INSERT OR REPLACE INTO files` - Update file metadata
|
||||||
|
- `SELECT * FROM files WHERE path = ?` - Check if file has changed
|
||||||
|
- `INSERT INTO snapshot_files` - Add file to current snapshot
|
||||||
|
|
||||||
|
2. **Chunking** (for changed files)
|
||||||
|
- `INSERT OR IGNORE INTO chunks` - Store new chunks
|
||||||
|
- `INSERT INTO file_chunks` - Map chunks to file
|
||||||
|
- `INSERT INTO chunk_files` - Create reverse mapping
|
||||||
|
|
||||||
|
3. **Blob Packing**
|
||||||
|
- `INSERT INTO blobs` - Create blob record with UUID (blob_hash NULL)
|
||||||
|
- `INSERT INTO blob_chunks` - Associate chunks with blob immediately
|
||||||
|
- `UPDATE blobs SET blob_hash = ?, finished_ts = ?` - Finalize blob after packing
|
||||||
|
|
||||||
|
4. **Upload**
|
||||||
|
- `UPDATE blobs SET uploaded_ts = ?, compressed_size = ?` - Mark blob as uploaded, with the size of the object in storage (the upload is skipped when the blob is already stored)
|
||||||
|
- `INSERT INTO uploads` - Record upload metrics with snapshot_id
|
||||||
|
- `INSERT INTO snapshot_blobs` - Associate blob with snapshot
|
||||||
|
|
||||||
|
5. **Snapshot Completion**
|
||||||
|
- `UPDATE snapshots SET completed_at = ?, stats...` - Finalize snapshot
|
||||||
|
- Generate and upload blob manifest from `snapshot_blobs`
|
||||||
|
|
||||||
|
### 2. Incremental Backup
|
||||||
|
|
||||||
|
1. **Change Detection**
|
||||||
|
- `SELECT * FROM files WHERE path = ?` - Get previous file metadata
|
||||||
|
- Compare mtime, size, mode to detect changes
|
||||||
|
- Re-chunk a file that lists a chunk no uploaded blob holds, even when its metadata is unchanged
|
||||||
|
- Skip unchanged files but still add to `snapshot_files`
|
||||||
|
|
||||||
|
2. **Chunk Reuse**
|
||||||
|
- `SELECT * FROM blob_chunks WHERE chunk_hash = ?` - Find existing chunks
|
||||||
|
- `INSERT INTO snapshot_blobs` - Reference existing blobs for unchanged files
|
||||||
|
|
||||||
|
### 3. Snapshot Metadata Export
|
||||||
|
|
||||||
|
After a snapshot is completed:
|
||||||
|
1. Copy database to temporary file
|
||||||
|
2. Clean temporary database to contain only current snapshot data
|
||||||
|
3. VACUUM the trimmed database so deleted rows leave no pages behind
|
||||||
|
4. Compress with zstd and encrypt with age
|
||||||
|
5. Upload to S3 as `metadata/{remote-key}/db.zst.age`
|
||||||
|
6. Generate blob manifest and upload as `metadata/{remote-key}/manifest.json.zst`
|
||||||
|
|
||||||
|
The `{remote-key}` directory name is a one-way hash of the human snapshot ID, so the ID is never written to the store in plaintext. The hash uses no secret, so a guessed hostname and snapshot name can still be confirmed against a listing; see [REPOSTRUCTURE.md](REPOSTRUCTURE.md#remote-key-derivation) and its [Accepted Risks](REPOSTRUCTURE.md#accepted-risks).
|
||||||
|
|
||||||
|
### 4. Restore Process
|
||||||
|
|
||||||
|
The restore process doesn't use the local database. Instead:
|
||||||
|
1. Downloads and decrypts the snapshot's metadata database (`db.zst.age`) from S3
|
||||||
|
2. Downloads the blobs holding the chunks of the files being restored, found through that database's `blob_chunks` table; the manifest is not read
|
||||||
|
3. Reconstructs files from decrypted and decompressed chunks
|
||||||
|
|
||||||
Migrations apply to the local index only. A snapshot's database at the
|
### 5. Pruning
|
||||||
destination is read as it was written. Each snapshot records the `vaultik`
|
|
||||||
version that wrote it.
|
|
||||||
|
|
||||||
## Tables
|
1. **Identify Unreferenced Blobs**
|
||||||
|
- Query blobs not referenced by any remaining snapshot
|
||||||
|
- Delete from S3, once older than `prune_grace_period`, and from the local
|
||||||
|
database
|
||||||
|
2. **Delete Metadata Directories With No Manifest**
|
||||||
|
- Delete each directory under `metadata/` that has no `manifest.json.zst`
|
||||||
|
and no local snapshot record, once every object in it is older than
|
||||||
|
`prune_grace_period`
|
||||||
|
|
||||||
Times are whole seconds since the Unix epoch, in UTC. The two exceptions are
|
### 6. Incomplete Snapshot Cleanup
|
||||||
noted at their columns.
|
|
||||||
|
|
||||||
### `files`
|
Before each backup:
|
||||||
|
1. Query incomplete snapshots (where `completed_at IS NULL`)
|
||||||
|
2. Delete each one and all its associations, without checking S3 for its metadata
|
||||||
|
3. Clean up orphaned files, chunks, and blobs
|
||||||
|
|
||||||
One row for each backed-up path: a regular file, a symlink or a directory.
|
## Repository Pattern
|
||||||
|
|
||||||
- `id`: a UUID. Primary key.
|
Vaultik uses a repository pattern for database access:
|
||||||
- `path`: the absolute path. Unique.
|
|
||||||
- `source_path`: the configured path that the scan found this entry under. A
|
- `FileRepository` - CRUD operations for files and file metadata
|
||||||
restore does not read it.
|
- `ChunkRepository` - CRUD operations for content chunks
|
||||||
- `mtime`: the modification time.
|
- `FileChunkRepository` - Manage file-to-chunk mappings
|
||||||
- `mtime_nsec`: the nanoseconds within that second.
|
- `ChunkFileRepository` - Manage chunk-to-file reverse mappings
|
||||||
- `size`: the size in bytes.
|
- `BlobRepository` - Manage blob lifecycle (creation, finalization, upload)
|
||||||
- `mode`: the permission bits and the file type.
|
- `BlobChunkRepository` - Manage blob-to-chunk associations
|
||||||
- `uid`: the owner's user ID.
|
- `SnapshotRepository` - Manage snapshots and their relationships
|
||||||
- `gid`: the owner's group ID.
|
- `UploadRepository` - Track blob upload metrics
|
||||||
- `link_target`: the target of a symlink. It is `NULL` for other entries.
|
|
||||||
|
|
||||||
`idx_files_path` indexes `path`.
|
Each repository provides methods like:
|
||||||
|
- `Create()` - Insert new record
|
||||||
|
- `GetByID()` / `GetByPath()` / `GetByHash()` - Retrieve records
|
||||||
|
- `Update()` - Update existing records
|
||||||
|
- `Delete()` - Remove records
|
||||||
|
- Specialized queries for each entity type (e.g., `DeleteOrphaned()`, `GetIncompleteByHostname()`)
|
||||||
|
|
||||||
There is one row for each path, and it is updated when the file changes. The
|
## Transaction Management
|
||||||
row is shared by every snapshot in the local index that lists the path. An
|
|
||||||
older snapshot's own view of the file is in that snapshot's database at the
|
|
||||||
destination.
|
|
||||||
|
|
||||||
### `chunks`
|
All database operations that modify multiple tables are wrapped in transactions:
|
||||||
|
|
||||||
One row for each distinct chunk.
|
|
||||||
|
|
||||||
- `chunk_hash`: the SHA-256 hash of the chunk's content, in hex. Primary key.
|
|
||||||
- `size`: the size in bytes.
|
|
||||||
|
|
||||||
### `file_chunks`
|
|
||||||
|
|
||||||
The chunks that make up each file, in order.
|
|
||||||
|
|
||||||
- `file_id`: the file. References `files.id`.
|
|
||||||
- `idx`: the position of the chunk within the file, counted from 0.
|
|
||||||
- `chunk_hash`: the chunk. References `chunks.chunk_hash`.
|
|
||||||
|
|
||||||
The primary key is (`file_id`, `idx`). `idx_file_chunks_chunk_hash` indexes
|
|
||||||
`chunk_hash`.
|
|
||||||
|
|
||||||
### `chunk_files`
|
|
||||||
|
|
||||||
The reverse of `file_chunks`: the files that contain each chunk.
|
|
||||||
|
|
||||||
- `chunk_hash`: the chunk. References `chunks.chunk_hash`.
|
|
||||||
- `file_id`: the file. References `files.id`.
|
|
||||||
- `file_offset`: the byte offset of the chunk within the file.
|
|
||||||
- `length`: the length of the chunk in bytes.
|
|
||||||
|
|
||||||
The primary key is (`chunk_hash`, `file_id`). `idx_chunk_files_file_id` indexes
|
|
||||||
`file_id`.
|
|
||||||
|
|
||||||
### `blobs`
|
|
||||||
|
|
||||||
One row for each blob.
|
|
||||||
|
|
||||||
- `id`: a UUID, given when packing of the blob starts. Primary key.
|
|
||||||
- `blob_hash`: the name of the blob at the destination. Unique. Until the blob
|
|
||||||
is closed, it holds a placeholder that starts with `temp-placeholder-`.
|
|
||||||
- `created_ts`: when packing started.
|
|
||||||
- `finished_ts`: when the blob was closed. It is `NULL` before that.
|
|
||||||
- `uncompressed_size`: the total size of the blob's chunks.
|
|
||||||
- `compressed_size`: the size after compression and encryption.
|
|
||||||
- `uploaded_ts`: when the upload finished. It is `NULL` before that.
|
|
||||||
|
|
||||||
`blob_hash` is `hex(SHA256(SHA256(uncompressed contents)))`. See
|
|
||||||
[REPOSTRUCTURE.md](REPOSTRUCTURE.md#blobs).
|
|
||||||
|
|
||||||
Once a blob is uploaded, `compressed_size` is the size of the object at the
|
|
||||||
destination. A blob that was already there can have a different size from the
|
|
||||||
local copy. That happens when it was written with another compression level or
|
|
||||||
other recipients.
|
|
||||||
|
|
||||||
### `blob_chunks`
|
|
||||||
|
|
||||||
The chunks that each blob holds.
|
|
||||||
|
|
||||||
- `blob_id`: the blob. References `blobs.id`.
|
|
||||||
- `chunk_hash`: the chunk. References `chunks.chunk_hash`.
|
|
||||||
- `offset`: the byte offset of the chunk within the uncompressed blob.
|
|
||||||
- `length`: the length of the chunk in bytes.
|
|
||||||
|
|
||||||
The primary key is (`blob_id`, `chunk_hash`). `idx_blob_chunks_chunk_hash`
|
|
||||||
indexes `chunk_hash`.
|
|
||||||
|
|
||||||
A restore finds the blob for each chunk through this table.
|
|
||||||
|
|
||||||
### `snapshots`
|
|
||||||
|
|
||||||
One row for each snapshot.
|
|
||||||
|
|
||||||
- `id`: the snapshot ID. Primary key.
|
|
||||||
- `hostname`: the hostname of the machine that made the backup.
|
|
||||||
- `vaultik_version`: the `vaultik` version that made it.
|
|
||||||
- `vaultik_git_revision`: the git commit of that version.
|
|
||||||
- `started_at`: when the backup started.
|
|
||||||
- `completed_at`: when the backup finished. It is `NULL` until then.
|
|
||||||
- `file_count`: the number of files and symlinks in the snapshot. Directories
|
|
||||||
are not counted.
|
|
||||||
- `chunk_count`: the number of chunks this snapshot stored that were not stored
|
|
||||||
before.
|
|
||||||
- `new_chunk_size`: the total size of those chunks before compression.
|
|
||||||
- `blob_count`: the number of blobs this snapshot created.
|
|
||||||
- `total_size`: the total size of all files in the snapshot.
|
|
||||||
- `uncompressed_chunk_size`: the total size, before compression, of the
|
|
||||||
distinct chunks the snapshot's files use.
|
|
||||||
- `blob_size`: the total compressed size of the blobs the snapshot uses.
|
|
||||||
- `blob_uncompressed_size`: the total uncompressed size of those blobs.
|
|
||||||
- `compression_ratio`: the compression ratio of those blobs.
|
|
||||||
- `compression_level`: the compression level the backup used.
|
|
||||||
- `upload_bytes`: the bytes uploaded during the backup.
|
|
||||||
- `upload_duration_ms`: the time spent uploading, in milliseconds.
|
|
||||||
|
|
||||||
The snapshot ID has the form `<hostname>_<snapshot-name>_<timestamp>`. An
|
|
||||||
example is `server1_home_2025-06-01T12:00:00Z`. It has three parts:
|
|
||||||
|
|
||||||
- the hostname, up to its first `.`
|
|
||||||
- the snapshot name
|
|
||||||
- the start time, in UTC
|
|
||||||
|
|
||||||
`snapshot list` shows `uncompressed_chunk_size` as `UNCOMPRESSED SIZE` and
|
|
||||||
`new_chunk_size` as `NEW CHUNK SIZE`.
|
|
||||||
|
|
||||||
A snapshot with `completed_at` set to `NULL` is unfinished. `snapshot list`
|
|
||||||
does not show it. The next backup deletes it, and so does `prune`.
|
|
||||||
|
|
||||||
### `snapshot_files`
|
|
||||||
|
|
||||||
The files in each snapshot.
|
|
||||||
|
|
||||||
- `snapshot_id`: the snapshot. References `snapshots.id`.
|
|
||||||
- `file_id`: the file. References `files.id`.
|
|
||||||
|
|
||||||
The primary key is (`snapshot_id`, `file_id`). `idx_snapshot_files_file_id`
|
|
||||||
indexes `file_id`.
|
|
||||||
|
|
||||||
### `snapshot_blobs`
|
|
||||||
|
|
||||||
The blobs that each snapshot uses.
|
|
||||||
|
|
||||||
- `snapshot_id`: the snapshot. References `snapshots.id`.
|
|
||||||
- `blob_id`: the blob. References `blobs.id`.
|
|
||||||
- `blob_hash`: a copy of the blob's hash.
|
|
||||||
|
|
||||||
The primary key is (`snapshot_id`, `blob_id`). `idx_snapshot_blobs_blob_id`
|
|
||||||
indexes `blob_id`.
|
|
||||||
|
|
||||||
The manifest is built from this table.
|
|
||||||
|
|
||||||
### `snapshot_mount_points`
|
|
||||||
|
|
||||||
The mount points that a snapshot's backup found.
|
|
||||||
|
|
||||||
- `snapshot_id`: the snapshot. References `snapshots.id`.
|
|
||||||
- `path`: the absolute path of the directory.
|
|
||||||
|
|
||||||
The primary key is (`snapshot_id`, `path`).
|
|
||||||
|
|
||||||
A directory is recorded here when all of these hold:
|
|
||||||
|
|
||||||
- It is at or below a configured path.
|
|
||||||
- The backup found an entry in it that is not excluded.
|
|
||||||
- It is on a different filesystem from its parent directory.
|
|
||||||
|
|
||||||
The device number is read after the directory has been listed. Listing an
|
|
||||||
automount point mounts its volume, so the number is that of the volume. An
|
|
||||||
automount point whose volume cannot be mounted is not recorded, because the
|
|
||||||
backup finds no entry in it.
|
|
||||||
|
|
||||||
`snapshot create --prune` reads this table. It skips the prune when an earlier
|
|
||||||
snapshot of the same name recorded a mount point that the new backup did not
|
|
||||||
find. That happens when the volume is not mounted.
|
|
||||||
|
|
||||||
### `uploads`
|
|
||||||
|
|
||||||
One row for each blob that a backup uploaded.
|
|
||||||
|
|
||||||
- `blob_hash`: the blob. References `blobs.blob_hash`. Primary key.
|
|
||||||
- `snapshot_id`: the snapshot whose backup uploaded it. References
|
|
||||||
`snapshots.id`.
|
|
||||||
- `uploaded_at`: when the upload started. It is written as a date and time, not
|
|
||||||
as seconds.
|
|
||||||
- `size`: the size of the uploaded blob.
|
|
||||||
- `duration_ms`: the duration of the upload, in milliseconds.
|
|
||||||
|
|
||||||
`idx_uploads_snapshot_id` indexes `snapshot_id`.
|
|
||||||
|
|
||||||
A blob that was already at the destination gets no row here.
|
|
||||||
|
|
||||||
### `local_meta`
|
|
||||||
|
|
||||||
Settings that belong to this copy of the index.
|
|
||||||
|
|
||||||
- `key`: the name of the setting. Primary key.
|
|
||||||
- `value`: its value.
|
|
||||||
|
|
||||||
The only key is `storage_url`. It holds the destination that the index was
|
|
||||||
first used with. A command that changes data refuses to run when the config
|
|
||||||
names a different destination.
|
|
||||||
|
|
||||||
### `schema_migrations`
|
|
||||||
|
|
||||||
The migrations that have run.
|
|
||||||
|
|
||||||
- `version`: the number of the migration. Primary key.
|
|
||||||
- `applied_at`: when it ran. It is written as a date and time, not as seconds.
|
|
||||||
|
|
||||||
## How commands use the tables
|
|
||||||
|
|
||||||
### Backup
|
|
||||||
|
|
||||||
A backup works on the tables in this order:
|
|
||||||
|
|
||||||
- It deletes unfinished snapshots, and the rows that no snapshot uses.
|
|
||||||
- It creates a row in `snapshots`, with `completed_at` set to `NULL`.
|
|
||||||
- It deletes the `blobs` rows that were never uploaded.
|
|
||||||
- It walks each path and compares every entry with its row in `files`.
|
|
||||||
- It links each unchanged file to the snapshot in `snapshot_files`.
|
|
||||||
- It records each mount point in `snapshot_mount_points`.
|
|
||||||
- It reads each changed file and stores it. See below.
|
|
||||||
- It fills `snapshot_blobs` with every blob the snapshot uses.
|
|
||||||
- It stores the snapshot's totals in `snapshots`.
|
|
||||||
- It uploads the snapshot's metadata.
|
|
||||||
- It sets `completed_at`.
|
|
||||||
|
|
||||||
A file counts as changed when its row in `files` differs from the file on disk
|
|
||||||
in any of these:
|
|
||||||
|
|
||||||
- size
|
|
||||||
- modification time
|
|
||||||
- mode
|
|
||||||
- owner or group
|
|
||||||
- link target
|
|
||||||
|
|
||||||
A file is also read again when it lists a chunk that no uploaded blob holds.
|
|
||||||
|
|
||||||
Storing a changed file writes these rows:
|
|
||||||
|
|
||||||
- A row in `blobs`, when packing of a blob starts.
|
|
||||||
- When the blob is closed, in one transaction:
|
|
||||||
- a row in `chunks` for each new chunk in the blob
|
|
||||||
- the blob's rows in `blob_chunks`
|
|
||||||
- the blob's `blob_hash`, sizes and `finished_ts`
|
|
||||||
- When the blob is stored at the destination, in one transaction:
|
|
||||||
- `uploaded_ts` and `compressed_size` in `blobs`
|
|
||||||
- a row in `snapshot_blobs`
|
|
||||||
- a row in `uploads`, unless the blob was already at the destination
|
|
||||||
- The row in `files`, with its `file_chunks`, `chunk_files` and
|
|
||||||
`snapshot_files` rows.
|
|
||||||
|
|
||||||
The row in `files` is written last. It is written only after every blob that
|
|
||||||
holds the file's new chunks is stored.
|
|
||||||
|
|
||||||
### Snapshot metadata
|
|
||||||
|
|
||||||
The metadata of a snapshot is made from a copy of the index:
|
|
||||||
|
|
||||||
- The index is copied into a temporary directory with `VACUUM INTO`.
|
|
||||||
- The rows of every other snapshot are deleted from the copy. So are the files
|
|
||||||
and blobs that this snapshot does not use. A chunk is then deleted when no
|
|
||||||
remaining file and no remaining blob uses it.
|
|
||||||
- The `local_meta` and `schema_migrations` tables are kept as they are. The
|
|
||||||
uploaded database therefore names the destination, and lists the migrations
|
|
||||||
that have run.
|
|
||||||
- `VACUUM` rewrites the copy, so that no deleted row is left in the file.
|
|
||||||
- The copy is compressed with zstd and encrypted with age.
|
|
||||||
- The manifest is built from the copy's `snapshot_blobs` table.
|
|
||||||
- The copy is uploaded as `metadata/<remote-key>/db.zst.age`.
|
|
||||||
- The manifest is uploaded as `metadata/<remote-key>/manifest.json.zst`.
|
|
||||||
|
|
||||||
The copy is made through SQLite, not by copying the file. The index runs in WAL
|
|
||||||
mode, so rows that are already committed can still be in the `-wal` file beside
|
|
||||||
it.
|
|
||||||
|
|
||||||
### Restore
|
|
||||||
|
|
||||||
A restore does not use the local index.
|
|
||||||
|
|
||||||
- It downloads and decrypts `db.zst.age` into a temporary directory.
|
|
||||||
- It opens that file read-only. It applies no migration to it.
|
|
||||||
- It reads the files to restore from `files`.
|
|
||||||
- It finds each file's chunks in `file_chunks`.
|
|
||||||
- It finds the blob and offset of each chunk in `blob_chunks`.
|
|
||||||
- It finds the name of each blob in `blobs`.
|
|
||||||
|
|
||||||
It does not read the manifest.
|
|
||||||
|
|
||||||
### Prune
|
|
||||||
|
|
||||||
`prune` changes the local index in two ways:
|
|
||||||
|
|
||||||
- It deletes each snapshot whose manifest is gone from the destination.
|
|
||||||
- It deletes unfinished snapshots, and the rows that no snapshot uses.
|
|
||||||
|
|
||||||
The second step removes unused rows in this order:
|
|
||||||
|
|
||||||
- files that are in no snapshot
|
|
||||||
- blobs that are in no snapshot
|
|
||||||
- `blob_chunks` rows whose chunk is gone
|
|
||||||
- chunks that no file and no blob uses
|
|
||||||
|
|
||||||
`prune` then deletes unused data at the destination. That step reads the
|
|
||||||
manifests, not the local index. It reads the local index only to keep a
|
|
||||||
directory under `metadata/` whose snapshot is still recorded there.
|
|
||||||
|
|
||||||
## Code
|
|
||||||
|
|
||||||
Each repository type in `internal/database` serves one or more tables:
|
|
||||||
|
|
||||||
- `FileRepository`: `files`
|
|
||||||
- `ChunkRepository`: `chunks`
|
|
||||||
- `FileChunkRepository`: `file_chunks`
|
|
||||||
- `ChunkFileRepository`: `chunk_files`
|
|
||||||
- `BlobRepository`: `blobs`
|
|
||||||
- `BlobChunkRepository`: `blob_chunks`
|
|
||||||
- `SnapshotRepository`:
|
|
||||||
- `snapshots`
|
|
||||||
- `snapshot_files`
|
|
||||||
- `snapshot_blobs`
|
|
||||||
- `snapshot_mount_points`
|
|
||||||
- `UploadRepository`: `uploads`
|
|
||||||
- `LocalMetaRepository`: `local_meta`
|
|
||||||
|
|
||||||
No repository type serves `schema_migrations`. The code that applies the
|
|
||||||
migrations reads and writes it.
|
|
||||||
|
|
||||||
`Repositories` holds one of each type.
|
|
||||||
|
|
||||||
`Repositories.WithTx` runs a function in one transaction:
|
|
||||||
|
|
||||||
```go
|
```go
|
||||||
err := repos.WithTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
|
err := repos.WithTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
|
||||||
// several repository calls that use tx
|
// Multiple repository operations using tx
|
||||||
})
|
})
|
||||||
```
|
```
|
||||||
|
|
||||||
The transaction commits when the function returns no error. Otherwise it is
|
This ensures consistency, especially important for operations like:
|
||||||
rolled back.
|
- Creating file-chunk mappings
|
||||||
|
- Associating chunks with blobs
|
||||||
|
- Updating snapshot statistics
|
||||||
|
|
||||||
## SQLite settings
|
## Performance Considerations
|
||||||
|
|
||||||
- The index runs in WAL mode. A command that only reads, such as
|
1. **Indexes**:
|
||||||
`snapshot list`, can read the index while a backup writes to it.
|
- Primary keys are automatically indexed
|
||||||
- A connection waits up to 10 seconds for a lock before it fails.
|
- `idx_files_path` on `files(path)` for efficient file lookups
|
||||||
- Foreign keys are enforced.
|
|
||||||
- Each open database uses one connection, so its queries run one at a time.
|
2. **Prepared Statements**: All queries use prepared statements for performance and security
|
||||||
- Queries pass their values as parameters.
|
|
||||||
|
3. **Batch Operations**: Where possible, operations are batched within transactions
|
||||||
|
|
||||||
|
4. **Write-Ahead Logging**: The local index runs in SQLite WAL mode with a 10-second busy timeout, so a read-only command such as `snapshot list` can read it while a backup writes to it. Committed rows can sit in the `-wal` file beside the index until a checkpoint, so the metadata export copies the index through SQLite (`VACUUM INTO`), not as a file
|
||||||
|
|
||||||
|
## Data Integrity
|
||||||
|
|
||||||
|
1. **Foreign Keys**: Enforced through CASCADE DELETE and application-level repository methods
|
||||||
|
2. **Unique Constraints**: Chunk hashes, file paths, and blob hashes are unique
|
||||||
|
3. **Null Handling**: Nullable fields clearly indicate in-progress operations
|
||||||
|
4. **Timestamp Tracking**: All major operations record timestamps for auditing
|
||||||
+142
-376
@@ -1,416 +1,182 @@
|
|||||||
# vaultik destination layout
|
# Vaultik S3 Repository Structure
|
||||||
|
|
||||||
This document describes what `vaultik` stores at the destination. It covers the
|
This document describes the structure and organization of data stored in the S3 bucket by Vaultik.
|
||||||
layout, what the layout protects, and the risks it accepts.
|
|
||||||
|
|
||||||
The destination is the place the backups are stored. It is an S3 bucket and
|
## Overview
|
||||||
prefix, a local directory or an rclone remote. The layout is the same on all
|
|
||||||
three.
|
|
||||||
|
|
||||||
## Terms
|
Vaultik stores all backup data in an S3-compatible object store. The repository consists of two main components, plus a marker file:
|
||||||
|
1. **Blobs** - The actual backup data (content-addressed, encrypted)
|
||||||
|
2. **Metadata** - Snapshot information and manifests (partially encrypted)
|
||||||
|
|
||||||
- **Snapshot**: one backup of the paths listed under one name in the config.
|
## Directory Structure
|
||||||
- **Snapshot ID**: the name of a snapshot, in the form
|
|
||||||
`<hostname>_<snapshot-name>_<timestamp>`.
|
|
||||||
- **Chunk**: a piece of a file's content, named by the SHA-256 hash of that
|
|
||||||
content.
|
|
||||||
- **Blob**: one object under `blobs/`. It holds many chunks.
|
|
||||||
- **Local index**: the SQLite database on the backed-up machine.
|
|
||||||
- **Recipient**: an age public key that backups are encrypted to.
|
|
||||||
|
|
||||||
## Layout
|
|
||||||
|
|
||||||
```
|
```
|
||||||
<destination>/
|
<bucket>/<prefix>/
|
||||||
├── vaultik-destination.txt
|
├── vaultik-destination.txt
|
||||||
├── blobs/
|
├── blobs/
|
||||||
│ └── <hash[0:2]>/
|
│ └── <hash[0:2]>/
|
||||||
│ └── <hash[2:4]>/
|
│ └── <hash[2:4]>/
|
||||||
│ └── <hash>
|
│ └── <full-hash>
|
||||||
└── metadata/
|
└── metadata/
|
||||||
└── <remote-key>/
|
└── <remote-key>/
|
||||||
├── db.zst.age
|
├── db.zst.age
|
||||||
└── manifest.json.zst
|
└── manifest.json.zst
|
||||||
```
|
```
|
||||||
|
|
||||||
The destination holds three things:
|
The metadata subdirectory is named with the **remote key**, a one-way hash of the snapshot ID, not with the human-readable snapshot ID itself. See [Remote Key Derivation](#remote-key-derivation).
|
||||||
|
|
||||||
- `vaultik-destination.txt`, the marker file
|
## Marker File (`vaultik-destination.txt`)
|
||||||
- `blobs/`, which holds the file contents
|
|
||||||
- `metadata/`, which holds one directory for each snapshot
|
|
||||||
|
|
||||||
## The marker file
|
Every backup writes this file at the root before it uploads anything. It holds one fixed line of plain text and names no host, path or time. A destination without it is treated as not present while the local index holds snapshots stored there: `snapshot create` refuses to write to it, and `prune`, `snapshot purge`, `snapshot remove`, `snapshot list` and `remote nuke` behave as for a destination that cannot be listed. An unplugged volume leaves an empty directory at its mount point, and without the marker that directory would read as a destination whose snapshots are all gone. `remote nuke` deletes the marker last.
|
||||||
|
|
||||||
Every backup writes `vaultik-destination.txt` before it uploads anything else.
|
## Blobs Directory (`blobs/`)
|
||||||
The file holds one fixed line of text. It names no host, path or time.
|
|
||||||
|
|
||||||
The marker tells an emptied or missing destination apart from a new one. An
|
### Structure
|
||||||
unplugged volume leaves an empty directory at its mount point. Without the
|
- **Path format**: `blobs/<first-2-chars>/<next-2-chars>/<full-hash>`
|
||||||
marker, that directory would look like a destination whose snapshots are all
|
- **Example**: `blobs/ca/fe/cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678`
|
||||||
gone.
|
- **Sharding**: The two-level directory structure (using the first 4 characters of the hash) prevents any single directory from containing too many objects
|
||||||
|
|
||||||
The check applies while the local index holds snapshots. When the destination
|
### Content
|
||||||
then answers that the marker does not exist, commands treat the destination as
|
- **What it contains**: Packed collections of content-defined chunks from files
|
||||||
not present:
|
- **Format**: Zstandard compressed, then Age encrypted
|
||||||
|
- **Encryption**: Always encrypted with Age using the configured recipients
|
||||||
|
- **Naming**: Content-addressed. The blob's name is `hex(SHA256(SHA256(uncompressed blob contents)))` — the double SHA-256 of the concatenated chunk data, computed before compression and encryption, not a hash of the stored (compressed, encrypted) bytes. One consequence: only a holder of the age private key can check a stored blob's integrity, because matching a blob to its name means decrypting and decompressing it first — which is what `restore` and `verify --deep` do. Implemented in `internal/blobgen` (`DoubleSHA256`). This is the canonical description of blob naming; other documents and comments point here.
|
||||||
|
|
||||||
- `snapshot create` refuses to write to it.
|
### Why Encrypted
|
||||||
- `prune`, `snapshot purge` and `remote nuke` fail.
|
Blobs contain the actual file data from backups and must be encrypted for security. The content-addressing ensures deduplication while the encryption ensures privacy.
|
||||||
- `snapshot list` shows the local index alone.
|
|
||||||
- `snapshot remove` deletes nothing at the destination.
|
|
||||||
|
|
||||||
The check is skipped when the look-up fails for any other reason. S3 refuses
|
## Metadata Directory (`metadata/`)
|
||||||
the look-up to credentials that can only write. A machine with such credentials
|
|
||||||
therefore does not notice an emptied destination. Its next backup would not
|
|
||||||
upload data that its local index says is stored. After a destination is emptied,
|
|
||||||
run `vaultik database delete` on such a machine before it backs up again.
|
|
||||||
|
|
||||||
`remote nuke` deletes the marker last.
|
Each snapshot has its own subdirectory. The directory is **not** named with the human-readable snapshot ID; it is named with the remote key — a one-way hash of that ID. The human ID is never written to the destination store as a directory name (see [Remote Key Derivation](#remote-key-derivation)).
|
||||||
|
|
||||||
## Blobs
|
### Snapshot ID Format
|
||||||
|
|
||||||
A blob holds the content of many chunks, one after another.
|
The human-readable snapshot ID is used in CLI arguments, log lines, and the local database. It is not written to the destination store.
|
||||||
|
- **Format**: `<hostname>_<snapshot-name>_<RFC3339>` (or `<hostname>_<RFC3339>` if no
|
||||||
|
name was specified)
|
||||||
|
- **Example**: `laptop_home_2024-01-15T14:30:52Z`
|
||||||
|
- **Components**:
|
||||||
|
- Short hostname (everything before the first dot is stripped from the FQDN)
|
||||||
|
- Snapshot name from the configured `snapshots:` map (optional)
|
||||||
|
- RFC3339 UTC timestamp
|
||||||
|
|
||||||
- **Path**: `blobs/<first 2 characters>/<next 2 characters>/<full hash>`.
|
This ID reveals the hostname, the configured snapshot name, and the backup time, so it is never used as the on-disk directory name — the remote key is used instead.
|
||||||
- **Example**:
|
|
||||||
`blobs/ca/fe/cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678`.
|
|
||||||
- **Format**: the chunk data, compressed with zstd and then encrypted with age.
|
|
||||||
- **Recipients**: the public keys in `age_recipients` when the blob was written.
|
|
||||||
|
|
||||||
The two directory levels keep any one directory from holding too many objects.
|
### Remote Key Derivation
|
||||||
|
|
||||||
### Blob names
|
The remote key is `hex(SHA256(SHA256("vaultik|" + snapshot-id)))`: a double SHA-256 over the snapshot ID, with a `vaultik|` domain-separation prefix. The result is a 64-character hex string. The hash is not reversible, but it uses no secret: an observer who guesses a candidate hostname and snapshot name can hash it the same way and confirm whether that snapshot is present. The remote key keeps names out of a plain listing; it does not hide them from a guess. Implemented in `internal/snapshot/remotekey.go`.
|
||||||
|
|
||||||
A blob's name is `hex(SHA256(SHA256(uncompressed contents)))`. The contents are
|
|
||||||
the chunk data, joined in order, before compression and encryption. The name is
|
|
||||||
not a hash of the stored bytes.
|
|
||||||
|
|
||||||
This has two consequences:
|
|
||||||
|
|
||||||
- Checking a blob against its name needs the private key. The blob must be
|
|
||||||
decrypted and decompressed first. `snapshot restore` and
|
|
||||||
`snapshot verify --deep` do this.
|
|
||||||
- Without the key, only a blob's presence and size can be checked.
|
|
||||||
`snapshot verify` does this.
|
|
||||||
|
|
||||||
`blobgen.DoubleSHA256` in `internal/blobgen` computes the name.
|
|
||||||
|
|
||||||
### Uploads
|
|
||||||
|
|
||||||
A backup looks a blob up by name before it uploads it. It does not upload a
|
|
||||||
blob that is already there.
|
|
||||||
|
|
||||||
When the destination refuses the look-up, the backup uploads the blob. An
|
|
||||||
object with that name is then replaced by one that holds the same chunk data.
|
|
||||||
|
|
||||||
## Metadata
|
|
||||||
|
|
||||||
Each snapshot has one directory under `metadata/`. The directory is named with
|
|
||||||
the snapshot's remote key, not with its snapshot ID.
|
|
||||||
|
|
||||||
### Snapshot IDs
|
|
||||||
|
|
||||||
A snapshot ID has the form `<hostname>_<snapshot-name>_<timestamp>`. An example
|
|
||||||
is `laptop_home_2024-01-15T14:30:52Z`. It has three parts:
|
|
||||||
|
|
||||||
- the hostname, up to its first `.`
|
|
||||||
- the snapshot name from the config
|
|
||||||
- the time the backup started, in UTC
|
|
||||||
|
|
||||||
The snapshot ID is used on the command line, in log records and in the local
|
|
||||||
index. It reveals the hostname, the snapshot name and the backup time. It is
|
|
||||||
therefore never written to the destination without encryption.
|
|
||||||
|
|
||||||
### Remote keys
|
|
||||||
|
|
||||||
The remote key is `hex(SHA256(SHA256("vaultik|" + snapshot ID)))`. It is 64 hex
|
|
||||||
characters long. `internal/snapshot/remotekey.go` computes it.
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
|
Worked example:
|
||||||
- Snapshot ID: `server1_home_2025-06-01T12:00:00Z`
|
- Snapshot ID: `server1_home_2025-06-01T12:00:00Z`
|
||||||
- Remote key: `17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa`
|
- Remote key: `17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa`
|
||||||
- Directory:
|
- Directory: `metadata/17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa/`
|
||||||
`metadata/17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa/`
|
|
||||||
|
|
||||||
A listing of the destination therefore shows no hostname and no snapshot name.
|
A plain listing of the destination store therefore shows only these hashes, not the hostname or snapshot name of any backup — but because the hash uses no secret, a guessed hostname and snapshot name can be hashed and confirmed against the listing. The same remote key is stored in the manifest's `snapshot_id` field.
|
||||||
|
|
||||||
The hash cannot be reversed, but it uses no secret. Someone who guesses a
|
### Files in Each Snapshot Directory
|
||||||
snapshot ID can hash it the same way and see whether that snapshot exists. The
|
|
||||||
remote key keeps names out of a listing. It does not hide them from a guess.
|
|
||||||
|
|
||||||
### `db.zst.age`
|
#### `db.zst.age` - Encrypted Database
|
||||||
|
- **What it contains**: Pruned binary SQLite database for this snapshot
|
||||||
The snapshot's database. A restore needs it.
|
- **Format**: Binary SQLite → Zstandard compressed → Age encrypted
|
||||||
|
- **Encryption**: Encrypted with Age
|
||||||
- **Contents**: a SQLite database. It is a copy of the local index without the
|
- **Purpose**: Contains full file metadata, chunk mappings, and all relationships
|
||||||
rows of other snapshots. It lists every file in the snapshot with its
|
- **Why encrypted**: Contains sensitive metadata like file paths, permissions, and ownership
|
||||||
metadata, its chunks, and the blob that holds each chunk.
|
|
||||||
- **Format**: the database file, compressed with zstd and then encrypted with
|
|
||||||
age.
|
|
||||||
|
|
||||||
It is encrypted because it holds file paths, permissions and owners.
|
|
||||||
[DATAMODEL.md](DATAMODEL.md) describes its tables.
|
|
||||||
|
|
||||||
### `manifest.json.zst`
|
|
||||||
|
|
||||||
The list of the blobs the snapshot uses.
|
|
||||||
|
|
||||||
- **Format**: JSON, compressed with zstd. It is not encrypted.
|
|
||||||
|
|
||||||
|
#### `manifest.json.zst` - Unencrypted Blob Manifest
|
||||||
|
- **What it contains**: JSON list of all blob hashes referenced by this snapshot
|
||||||
|
- **Format**: JSON → Zstandard compressed (NOT encrypted)
|
||||||
|
- **Encryption**: NOT encrypted
|
||||||
|
- **Purpose**: Enables pruning operations without requiring decryption keys
|
||||||
|
- **Structure**:
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"snapshot_id": "17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa",
|
"snapshot_id": "17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa",
|
||||||
"timestamp": "2025-06-01T12:04:31Z",
|
"timestamp": "2025-06-01T12:00:00Z",
|
||||||
"blob_count": 2,
|
"blob_count": 42,
|
||||||
"total_compressed_size": 57344,
|
"total_compressed_size": 1048576,
|
||||||
"blobs": [
|
"blobs": [
|
||||||
{
|
{ "hash": "cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678", "compressed_size": 24576 },
|
||||||
"hash": "cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678",
|
{ "hash": "deadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678", "compressed_size": 32768 }
|
||||||
"compressed_size": 24576
|
]
|
||||||
},
|
|
||||||
{
|
|
||||||
"hash": "deadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
|
|
||||||
"compressed_size": 32768
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
`snapshot_id` is the remote key (a hash), not the human ID; `timestamp` is written in the clear.
|
||||||
- `snapshot_id`: the remote key, not the snapshot ID.
|
|
||||||
- `timestamp`: when the manifest was written, at the end of the backup.
|
### Why Manifest is Unencrypted
|
||||||
- `blob_count`: the number of blobs.
|
The manifest must be readable without the private key to enable:
|
||||||
- `total_compressed_size`: the total size of those blobs, in bytes.
|
1. **Pruning operations** - Identifying unreferenced blobs for deletion
|
||||||
- `blobs`: the hash and the size of each blob.
|
2. **Storage analysis** - Understanding space usage without decryption
|
||||||
|
3. **Verification** - Checking blob existence without decryption
|
||||||
The manifest holds no file name and no path.
|
4. **Cross-snapshot deduplication analysis** - Finding shared blobs between snapshots
|
||||||
|
|
||||||
The manifest is not encrypted so that these commands work without the private
|
The manifest contains the remote key, the backup timestamp, the blob count and total compressed size, and each blob's hash and compressed size. It contains no file names, paths, or other decrypted metadata.
|
||||||
key:
|
|
||||||
|
## Security Considerations
|
||||||
- `prune`, which must know which blobs are still in use
|
|
||||||
- `snapshot verify`, which checks that each blob is present
|
### What's Encrypted
|
||||||
- `snapshot list` and `remote info`, which report what the destination holds
|
- **All file content** (in blobs)
|
||||||
|
- **All file metadata** (paths, permissions, timestamps, ownership in db.zst.age)
|
||||||
## What is protected
|
- **File-to-chunk mappings** (in db.zst.age)
|
||||||
|
|
||||||
These are encrypted:
|
### What's Not Encrypted
|
||||||
|
- **The remote key** — directory names and the manifest `snapshot_id`, a one-way hash of the snapshot ID (see [Remote Key Derivation](#remote-key-derivation))
|
||||||
- file contents, in the blobs
|
- **The backup timestamp** (in manifest.json.zst)
|
||||||
- in `db.zst.age`:
|
- **Blob hashes and their compressed sizes** (in manifest.json.zst)
|
||||||
- file names and paths
|
- **Blob count and total compressed size per snapshot** (in manifest.json.zst)
|
||||||
- permissions and owners
|
|
||||||
- modification times
|
### Privacy Implications
|
||||||
- which chunks make up which file
|
From the unencrypted data, an observer of the destination store can determine:
|
||||||
|
- **When each backup was taken** — not from the directory name, which is a one-way hash, but from the plaintext `timestamp` field in manifest.json.zst, which is published in the clear
|
||||||
These are not encrypted:
|
- How many blobs each snapshot references, and the total compressed size
|
||||||
|
- The compressed size of each blob, and which blobs are shared between snapshots (deduplication patterns)
|
||||||
- the remote key of each snapshot
|
- **Whether a guessed hostname and snapshot name are present** — the remote key is an unkeyed hash, so an observer holding candidate names can hash each one and match it against the directory listing. The human ID is never published, so it cannot be read off directly, but it can be confirmed by guessing.
|
||||||
- the time each backup finished, in the manifest
|
|
||||||
- the hash and the compressed size of each blob, in the manifest
|
Together these give an observer a timing-and-size profile of every snapshot. This is an accepted, documented property of the format, not a defect: the manifest is unencrypted so that pruning can run without the private key, and the timing channel could not be closed by encrypting it anyway — object creation times and per-object sizes stay visible at the storage layer on both `s3://` and `file://` destinations regardless.
|
||||||
- the number of blobs and their total size for each snapshot, in the manifest
|
|
||||||
|
An observer cannot determine:
|
||||||
Someone who can read the destination therefore learns these:
|
- The hostname or snapshot name of any backup by reading it off the store — the directory name and the manifest `snapshot_id` are unkeyed hashes of the human ID, so the text is never published (though a guessed name can be confirmed, as above)
|
||||||
|
- File names or paths
|
||||||
- when each backup finished
|
- File contents
|
||||||
- how many blobs each snapshot uses, and how large they are
|
- File permissions or ownership
|
||||||
- which blobs two snapshots share
|
- Directory structure
|
||||||
- whether a snapshot ID they guess exists
|
- Which chunks belong to which files
|
||||||
|
|
||||||
They do not learn these:
|
### Accepted Risks
|
||||||
|
|
||||||
- any hostname or snapshot name, unless they guess it
|
These are known, deliberate properties of the format and the tooling, recorded so an operator can weigh them rather than discover them.
|
||||||
- file names or paths
|
|
||||||
- file contents
|
1. **No proof of authorship.** Restore and `verify --deep` prove that data decrypts with the age private key and matches its unkeyed content hashes. They do not prove who wrote it: anyone who knows a recipient public key and can replace objects on the destination can substitute a snapshot they built. The recipient string is not stored at the destination, but a compromised backed-up host has it. Defences live on the destination side — bucket versioning or object lock, credentials for the source host that cannot delete or overwrite existing versions, and pruning from a trusted host. Note that S3 `PutObject` overwrites an existing key, so PUT permission alone is not append-only.
|
||||||
- permissions or owners
|
2. **Compression reveals sizes.** Blobs and `db.zst.age` are zstd-compressed then age-encrypted; the manifest is compressed only. age does not pad, so an object's size is the exact compressed length of its contents. All new chunks packed into one blob share a single zstd stream (8 MiB window, 4 MiB at compression levels 1-2), and a blob is closed at `blob_size_limit` and at the end of each configured path. Because a stored chunk is never packed again, someone who can write into a backed-up file and watch blob sizes learns something only when their controlled data and a secret land in the same chunk of a file that keeps changing. Advice: back up any outsider-writable directory as its own snapshot.
|
||||||
- the directory structure
|
3. **Chunking uses no secret.** The FastCDC parameters are fixed and public. The default 10 MB average yields chunks between 2.5 MB and 40 MB, and any file of 2.5 MB or less is a single chunk. At the default 10 GB `blob_size_limit` a blob holds hundreds of chunks, so individual chunk lengths are not visible in the blob's size; lowering the limit toward the chunk size begins to expose them.
|
||||||
- which chunks belong to which file
|
4. **Decrypted data on local disk.** Several commands stage plaintext under `$TMPDIR`: `snapshot restore` writes decrypted blobs under `vaultik-blobcache-*/` (no size cap) and the decrypted metadata database at `vaultik-restore-*/snapshot.db`; `verify --deep` writes that database at `vaultik-verify-*/snapshot.db`; `snapshot create` keeps a plaintext copy of the index at `vaultik-snapshot-*/snapshot.db`. These files are created `0600` and removed on success, but a `kill -9` or a power loss leaves them behind — delete any leftover `vaultik-*` directory under `$TMPDIR` by hand. `$TMPDIR` should be trusted to the same degree as the restore target.
|
||||||
|
5. **Store permissions differ per command.** The backed-up host needs only PUT to run `snapshot create`: it writes blobs and metadata and neither reads nor deletes them. Other commands need more — `snapshot verify`, `snapshot restore`, and `prune` list and read; `prune`, `snapshot purge`, `snapshot remove`, and `remote nuke` also delete. The recommended cron line uses `--prune`, which runs `prune` on the backed-up host, so granting that host `--prune` gives it credentials that can delete its own backups. To keep the source host to PUT only, prune from a separate trusted host instead.
|
||||||
The times and sizes could not be hidden by encrypting the manifest. The
|
6. **Changing recipients does not re-encrypt existing data.** Deduplicated chunks and same-named blobs already on the destination stay encrypted to the recipients in force when they were written. A new snapshot that reuses them cannot be restored with a newly added recipient's key alone, because those reused objects were never encrypted to it. To make everything readable by a new key, run `vaultik database delete` and take a full backup to a fresh destination or prefix.
|
||||||
destination itself shows when each object was written and how large it is.
|
7. **X25519 recipients only.** vaultik rejects age ssh and plugin recipients. Long-lived ciphertext held by a third party (the destination operator) has no fallback if X25519 is ever broken: there is no second recipient type and no post-quantum option.
|
||||||
|
|
||||||
## Accepted risks
|
## Consistency Guarantees
|
||||||
|
|
||||||
These are known properties of the format. They are written down so that you can
|
1. **Blobs are immutable** - Once written, a blob is never modified
|
||||||
weigh them.
|
2. **Blobs are written before metadata** - A snapshot's metadata is only written after all its blobs are successfully uploaded
|
||||||
|
3. **Metadata is written atomically** - Both db.zst.age and manifest.json.zst are written as complete files
|
||||||
### No proof of who wrote the data
|
4. **A snapshot is marked complete in the local DB only after its metadata is uploaded** - `finalizeSnapshotMetadata` runs `ExportSnapshotMetadata` first and records completion (`MarkSnapshotComplete`) only once the export succeeds (see the backup data flow in [ARCHITECTURE.md](../ARCHITECTURE.md)). A crash during the export therefore leaves the snapshot incomplete, so the next backup's `PruneDatabase` drops it and re-backs-up its data, rather than leaving a completed-looking row in the local index with no matching metadata on the destination store. (A crash in the brief moment after the export succeeds but before completion is recorded leaves a fully-restorable snapshot on the destination that the local index drops as incomplete on the next run; `snapshot list` then reports it honestly as remote-only, which is the safe direction: the destination copy stays restorable.)
|
||||||
|
|
||||||
A restore and `snapshot verify --deep` prove two things. The data decrypts with
|
## Pruning Safety
|
||||||
your private key, and it matches its hashes. They do not prove who wrote it.
|
|
||||||
|
The prune operation is safe because:
|
||||||
The hashes use no secret. Someone who knows a recipient's public key and can
|
1. It keeps every blob listed in any snapshot's manifest and deletes only blobs that no manifest references. Under `metadata/` it deletes only a directory that has no `manifest.json.zst`, whose name is a remote key, and that no local snapshot record claims
|
||||||
replace objects at the destination can put a snapshot of their own there. The
|
2. Manifests are unencrypted and can be read without keys
|
||||||
public key is not stored at the destination, but a backed-up machine that is
|
3. If any manifest cannot be downloaded or decoded, prune deletes nothing and exits with an error, rather than treating that snapshot's blobs as unreferenced
|
||||||
broken into has it.
|
4. It deletes an unreferenced blob only once the blob is older than `prune_grace_period` (default `24h`), and a directory under `metadata/` with no manifest only once every object in it is. A backup uploads its blobs and its `db.zst.age` before the manifest that lists them, so a prune running meanwhile, on this host or another sharing the destination, leaves them as long as no backup run takes longer than the grace period. The grace period does not protect a blob a backup reuses from an earlier run that stopped before its manifest: the backup skips the upload of a blob already on the destination, so that blob keeps the time of its first upload, and a prune before the backup's manifest is written can delete it; the new snapshot then cannot be restored. `remote nuke` has no such check
|
||||||
|
|
||||||
The defences are on the destination's side:
|
## Restoration Requirements
|
||||||
|
|
||||||
- object versioning or object lock on the bucket
|
To restore from a backup, you need:
|
||||||
- credentials for the backed-up machine that cannot delete or overwrite
|
1. **The Age private key** - To decrypt blobs and database
|
||||||
- running `prune` from a trusted machine
|
2. **The snapshot metadata** - Both files from the snapshot's metadata directory
|
||||||
|
3. **All referenced blobs** - As listed in the manifest
|
||||||
An S3 `PutObject` replaces an existing object. Permission to write alone
|
|
||||||
therefore does not stop overwrites.
|
The restoration process:
|
||||||
|
1. Download and decrypt the database dump to understand file structure
|
||||||
### Sizes are visible
|
2. Download and decrypt the required blobs
|
||||||
|
3. Reconstruct files from their chunks
|
||||||
An object's size follows exactly from the size of its compressed contents.
|
4. Restore file metadata (permissions, timestamps, etc.)
|
||||||
|
|
||||||
All the new chunks in one blob share one zstd stream. The stream looks back 8
|
|
||||||
MiB, or 4 MiB at compression levels 1 and 2. A blob is closed at
|
|
||||||
`blob_size_limit` and at the end of each configured path. A chunk that is
|
|
||||||
already stored is never packed again.
|
|
||||||
|
|
||||||
Data that an outsider writes compresses smaller when it matches a secret in the
|
|
||||||
same chunk, so the blob gets smaller. The blob's size therefore shows the
|
|
||||||
outsider whether their data matched the secret.
|
|
||||||
|
|
||||||
This works only when all of these hold:
|
|
||||||
|
|
||||||
- The outsider can write into a backed-up file.
|
|
||||||
- The outsider can see the blob sizes at the destination.
|
|
||||||
- The outsider's data and the secret land in the same chunk.
|
|
||||||
- The file keeps changing.
|
|
||||||
|
|
||||||
Back up a directory that outsiders can write to as a snapshot of its own.
|
|
||||||
|
|
||||||
### Chunk boundaries use no secret
|
|
||||||
|
|
||||||
The FastCDC parameters are fixed and public. `chunk_size` sets the average chunk
|
|
||||||
size. No chunk is larger than four times this size. Only a file's last chunk can
|
|
||||||
be smaller than a quarter of it. With the default of 10 MB, those limits are 40
|
|
||||||
MB and 2.5 MB. A file of 2.5 MB or less is one chunk.
|
|
||||||
|
|
||||||
At the default `blob_size_limit` of 10 GB, a blob holds hundreds of chunks. The
|
|
||||||
size of the blob then does not show the size of any one chunk. A limit close to
|
|
||||||
`chunk_size` begins to show chunk sizes.
|
|
||||||
|
|
||||||
### Decrypted data on the local disk
|
|
||||||
|
|
||||||
These commands write unencrypted data to the temporary directory:
|
|
||||||
|
|
||||||
- `snapshot restore` writes decrypted blobs under `vaultik-blobcache-*/`. There
|
|
||||||
is no limit on their total size.
|
|
||||||
- `snapshot restore` writes the decrypted database to
|
|
||||||
`vaultik-restore-*/snapshot.db`.
|
|
||||||
- `snapshot verify --deep` writes the decrypted database to
|
|
||||||
`vaultik-verify-*/snapshot.db`.
|
|
||||||
- `snapshot create` writes a copy of the local index to
|
|
||||||
`vaultik-snapshot-*/snapshot.db`.
|
|
||||||
|
|
||||||
These files are readable only by their owner, and are removed when the command
|
|
||||||
ends. A `kill -9` or a power loss leaves them behind. Delete any leftover
|
|
||||||
`vaultik-*` entry in the temporary directory yourself.
|
|
||||||
|
|
||||||
Trust the temporary directory as much as the directory you restore into.
|
|
||||||
|
|
||||||
### Commands need different permissions
|
|
||||||
|
|
||||||
`snapshot create` needs only permission to write objects. Other commands need
|
|
||||||
more:
|
|
||||||
|
|
||||||
- `snapshot list`, `snapshot verify`, `snapshot restore` and `remote info` list
|
|
||||||
and read.
|
|
||||||
- `snapshot purge`, `snapshot remove` and `remote nuke` list and delete.
|
|
||||||
- `prune` lists, reads and deletes.
|
|
||||||
|
|
||||||
`snapshot create --prune` runs a prune on the backed-up machine. That machine
|
|
||||||
then holds credentials that can delete its own backups. To keep it to
|
|
||||||
write-only credentials, run `prune` from a separate, trusted machine.
|
|
||||||
|
|
||||||
### New recipients cannot read old data
|
|
||||||
|
|
||||||
Changing `age_recipients` does not re-encrypt what is already stored. A chunk
|
|
||||||
that is already stored is not written again, so it stays encrypted to the
|
|
||||||
earlier recipients.
|
|
||||||
|
|
||||||
A new snapshot that uses such chunks cannot be restored with a new recipient's
|
|
||||||
key alone. To make everything readable by a new key, run
|
|
||||||
`vaultik database delete` and take a full backup to a new destination.
|
|
||||||
|
|
||||||
### X25519 recipients only
|
|
||||||
|
|
||||||
`vaultik` accepts age X25519 public keys only. It rejects age SSH and plugin
|
|
||||||
recipients.
|
|
||||||
|
|
||||||
The encrypted data is held by a third party for a long time. There is no second
|
|
||||||
kind of recipient to fall back on if X25519 is broken, and no post-quantum
|
|
||||||
option.
|
|
||||||
|
|
||||||
## Order of writes
|
|
||||||
|
|
||||||
A backup writes in a fixed order:
|
|
||||||
|
|
||||||
- the marker file
|
|
||||||
- the blobs
|
|
||||||
- `db.zst.age`
|
|
||||||
- `manifest.json.zst`
|
|
||||||
|
|
||||||
A snapshot's metadata is written only after all its blobs are uploaded. The
|
|
||||||
manifest is written last. A directory under `metadata/` that has no manifest
|
|
||||||
therefore belongs to a backup that did not finish.
|
|
||||||
|
|
||||||
The local index marks a snapshot complete only after both metadata files are
|
|
||||||
uploaded. A backup that stops during that upload leaves the snapshot
|
|
||||||
unfinished. The next backup removes it from the local index and stores its data
|
|
||||||
again.
|
|
||||||
|
|
||||||
One short gap remains. A backup can stop after the upload and before the
|
|
||||||
snapshot is marked complete. The destination then holds a snapshot that can be
|
|
||||||
restored, and the local index does not list it. `snapshot list` shows it as
|
|
||||||
remote only.
|
|
||||||
|
|
||||||
An upload that is cut off leaves no partial object under the final name on S3
|
|
||||||
or on a local directory. The same holds for an rclone remote that can move
|
|
||||||
objects. An rclone remote that cannot move objects can keep a partial object.
|
|
||||||
|
|
||||||
## Pruning
|
|
||||||
|
|
||||||
`prune` deletes two kinds of object at the destination:
|
|
||||||
|
|
||||||
- a blob that no manifest lists
|
|
||||||
- a directory under `metadata/` that has no manifest
|
|
||||||
|
|
||||||
It reads the manifests, which are not encrypted, so it needs no private key.
|
|
||||||
|
|
||||||
These rules keep it from deleting data that is in use:
|
|
||||||
|
|
||||||
- It keeps every blob that any manifest lists.
|
|
||||||
- It deletes nothing when any manifest cannot be downloaded or decoded.
|
|
||||||
- It deletes a blob only once the blob is older than `prune_grace_period`.
|
|
||||||
- It deletes a directory only once every object in it is that old.
|
|
||||||
- It keeps a directory whose snapshot is in the local index.
|
|
||||||
- It leaves alone a directory whose name is not a remote key.
|
|
||||||
|
|
||||||
`prune_grace_period` defaults to `24h`. It protects a backup that is still
|
|
||||||
running. Such a backup has uploaded blobs and perhaps `db.zst.age`, but not yet
|
|
||||||
its manifest. A prune from this machine or another keeps those objects, as long
|
|
||||||
as no backup takes longer than the grace period.
|
|
||||||
|
|
||||||
The grace period does not protect one case. A backup does not upload a blob
|
|
||||||
that is already at the destination, so that blob keeps the time of its first
|
|
||||||
upload. The blob can be left over from an earlier backup that stopped before
|
|
||||||
its manifest. A prune that runs before the new manifest is written can then
|
|
||||||
delete that blob. The new snapshot cannot be restored afterwards.
|
|
||||||
|
|
||||||
To avoid this case, give each machine and each user its own destination.
|
|
||||||
|
|
||||||
`remote nuke` applies none of these rules.
|
|
||||||
|
|
||||||
## What a restore needs
|
|
||||||
|
|
||||||
- the age private key
|
|
||||||
- the snapshot's `db.zst.age`
|
|
||||||
- the blobs that hold the files to restore
|
|
||||||
|
|
||||||
A restore does not read the manifest and does not need the local index.
|
|
||||||
|
|
||||||
It works in these steps:
|
|
||||||
|
|
||||||
- It downloads and decrypts `db.zst.age`.
|
|
||||||
- It checks that the database is the one for the snapshot that was asked for.
|
|
||||||
- It downloads and decrypts the blobs it needs. It checks each blob against its
|
|
||||||
name.
|
|
||||||
- It writes each file from its chunks.
|
|
||||||
- It sets each file's permissions and times, and its owner when it runs as
|
|
||||||
root.
|
|
||||||
+11
-13
@@ -242,12 +242,12 @@ storage_url: ""
|
|||||||
# How old a blob that no snapshot lists must be before prune deletes it,
|
# How old a blob that no snapshot lists must be before prune deletes it,
|
||||||
# and how old every object in a directory under metadata/ with no manifest
|
# and how old every object in a directory under metadata/ with no manifest
|
||||||
# must be before prune deletes that directory. A backup uploads its blobs
|
# must be before prune deletes that directory. A backup uploads its blobs
|
||||||
# and its db.zst.age before its manifest, so on a destination shared
|
# and its db.zst.age before the manifest that lists them, so on a
|
||||||
# between hosts or users this must be longer than the longest backup run.
|
# destination shared between hosts or users this must be longer than the
|
||||||
# It does not protect a blob a backup reuses from an earlier run that
|
# longest backup run. It does not protect a blob a backup reuses from an
|
||||||
# stopped before its manifest: that blob keeps the time of its first
|
# earlier run that stopped before its manifest: that blob keeps the time of
|
||||||
# upload, so a prune can delete it.
|
# its first upload, so a prune can delete it.
|
||||||
# Accepts: 36h, 90m, etc. 0s deletes such blobs and directories at once.
|
# Accepts: 36h, 90m, etc. 0s deletes them at once.
|
||||||
# Default: 24h
|
# Default: 24h
|
||||||
# prune_grace_period: 24h
|
# prune_grace_period: 24h
|
||||||
|
|
||||||
@@ -289,14 +289,12 @@ func newConfigInitCommand() *cobra.Command {
|
|||||||
Use: "init",
|
Use: "init",
|
||||||
Short: "Write a default config file",
|
Short: "Write a default config file",
|
||||||
Long: `Creates a default configuration file with commented explanations
|
Long: `Creates a default configuration file with commented explanations
|
||||||
for the settings it lists. If a config file already exists at the target
|
for every setting. If a config file already exists at the target path,
|
||||||
path, the command refuses to overwrite it. The file is created with mode
|
the command refuses to overwrite it.
|
||||||
0600, because it can hold credentials.
|
|
||||||
|
|
||||||
The config is written to the path from --config, $VAULTIK_CONFIG, or
|
The config is written to the path from --config, $VAULTIK_CONFIG, or
|
||||||
config.yml in the platform default config directory
|
the platform default config directory (e.g. ~/Library/Application Support/
|
||||||
(~/Library/Application Support/vaultik/ on macOS, ~/.config/vaultik/ on
|
on macOS, ~/.config/ on Linux, /etc/vaultik/ as root).`,
|
||||||
Linux, /etc/vaultik/ as root).`,
|
|
||||||
Args: cobra.NoArgs,
|
Args: cobra.NoArgs,
|
||||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||||
path := configPathForInit()
|
path := configPathForInit()
|
||||||
@@ -334,7 +332,7 @@ Linux, /etc/vaultik/ as root).`,
|
|||||||
func newConfigEditCommand() *cobra.Command {
|
func newConfigEditCommand() *cobra.Command {
|
||||||
return &cobra.Command{
|
return &cobra.Command{
|
||||||
Use: "edit",
|
Use: "edit",
|
||||||
Short: "Open the config file in $EDITOR (vi when it is not set)",
|
Short: "Open the config file in $EDITOR",
|
||||||
Args: cobra.NoArgs,
|
Args: cobra.NoArgs,
|
||||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||||
path, err := ResolveConfigPath()
|
path, err := ResolveConfigPath()
|
||||||
|
|||||||
@@ -61,8 +61,8 @@ func TestDefaultConfigTemplateParses(t *testing.T) {
|
|||||||
// testRecipient is a valid age public key.
|
// testRecipient is a valid age public key.
|
||||||
const testRecipient = "age1278m9q7dp3chsh2dcy82qk27v047zywyvtxwnj4cvt0z65jw6a7q5dqhfj"
|
const testRecipient = "age1278m9q7dp3chsh2dcy82qk27v047zywyvtxwnj4cvt0z65jw6a7q5dqhfj"
|
||||||
|
|
||||||
// TestConfigSetRecipientOnFreshConfig follows the README's getting started
|
// TestConfigSetRecipientOnFreshConfig follows the README quickstart: on the
|
||||||
// steps: on the file `config init` writes, `config set age_recipients.0` and
|
// file `config init` writes, `config set age_recipients.0` and
|
||||||
// `config set storage_url` give a config that loads with that recipient.
|
// `config set storage_url` give a config that loads with that recipient.
|
||||||
// Neither is refused, although the config does not load until both are set;
|
// Neither is refused, although the config does not load until both are set;
|
||||||
// once it loads, a recipient that is not a valid key is.
|
// once it loads, a recipient that is not a valid key is.
|
||||||
|
|||||||
@@ -134,7 +134,7 @@ func writeHermeticPruneConfig(t *testing.T, seedStale bool) string {
|
|||||||
seedStaleSnapshotRecord(t, indexPath)
|
seedStaleSnapshotRecord(t, indexPath)
|
||||||
|
|
||||||
// While the local index holds a snapshot, prune fails on a
|
// While the local index holds a snapshot, prune fails on a
|
||||||
// destination that answers that it has no marker.
|
// destination without the marker a backup writes.
|
||||||
require.NoError(t, os.WriteFile(
|
require.NoError(t, os.WriteFile(
|
||||||
filepath.Join(storeDir, "vaultik-destination.txt"), nil, 0o600))
|
filepath.Join(storeDir, "vaultik-destination.txt"), nil, 0o600))
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,7 +1,6 @@
|
|||||||
package cli //nolint:testpackage // shares runEntry and the hermetic config helpers
|
package cli //nolint:testpackage // shares runEntry and the hermetic config helpers
|
||||||
|
|
||||||
import (
|
import (
|
||||||
"context"
|
|
||||||
"os"
|
"os"
|
||||||
"path/filepath"
|
"path/filepath"
|
||||||
"strings"
|
"strings"
|
||||||
@@ -9,7 +8,6 @@ import (
|
|||||||
|
|
||||||
"github.com/stretchr/testify/assert"
|
"github.com/stretchr/testify/assert"
|
||||||
"github.com/stretchr/testify/require"
|
"github.com/stretchr/testify/require"
|
||||||
"sneak.berlin/go/vaultik/internal/database"
|
|
||||||
)
|
)
|
||||||
|
|
||||||
// Flags of `snapshot create` used to build argument vectors below.
|
// Flags of `snapshot create` used to build argument vectors below.
|
||||||
@@ -89,81 +87,6 @@ func TestEntrySnapshotCreateReportsPostBackupPruneFailure(t *testing.T) {
|
|||||||
"the new snapshot is on the store beside the planted one")
|
"the new snapshot is on the store beside the planted one")
|
||||||
}
|
}
|
||||||
|
|
||||||
// TestEntrySnapshotCreatePruneExitsNonZeroWhenSourceIsEmpty backs up,
|
|
||||||
// empties the source directory, as a volume that is not mounted leaves
|
|
||||||
// its mount point, and runs `snapshot create --prune`. The command exits
|
|
||||||
// non-zero and reports the backup as completed, not as a failed snapshot
|
|
||||||
// creation. See https://git.eeqj.de/sneak/vaultik/issues/388.
|
|
||||||
//
|
|
||||||
//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
|
|
||||||
func TestEntrySnapshotCreatePruneExitsNonZeroWhenSourceIsEmpty(t *testing.T) {
|
|
||||||
configPath, storeDir := writeBackupConfig(t)
|
|
||||||
|
|
||||||
code, _, _ := runEntry(t, flagConfig, configPath, cmdSnapshot, cmdCreate)
|
|
||||||
require.Equal(t, 0, code)
|
|
||||||
|
|
||||||
// writeBackupConfig puts the source directory beside the config file.
|
|
||||||
require.NoError(t, os.Remove(
|
|
||||||
filepath.Join(filepath.Dir(configPath), "source", "file.txt")))
|
|
||||||
|
|
||||||
code, _, stderr := runEntry(t,
|
|
||||||
flagConfig, configPath, cmdSnapshot, cmdCreate, flagPrune)
|
|
||||||
|
|
||||||
assert.Equal(t, 1, code)
|
|
||||||
assert.Contains(t, stderr,
|
|
||||||
"Backup completed, but 1 source path(s) were empty")
|
|
||||||
assert.NotContains(t, stderr, "Snapshot creation failed")
|
|
||||||
|
|
||||||
snapshots, err := os.ReadDir(filepath.Join(storeDir, "metadata"))
|
|
||||||
require.NoError(t, err)
|
|
||||||
assert.Len(t, snapshots, 2, "the older snapshot is kept")
|
|
||||||
}
|
|
||||||
|
|
||||||
// TestEntrySnapshotCreatePruneExitsNonZeroWhenMountPointIsMissing backs
|
|
||||||
// up, records in the local index that this backup found the source
|
|
||||||
// directory as a mount point, and runs `snapshot create --prune`, which
|
|
||||||
// does not find it as one. The command exits non-zero, reports the
|
|
||||||
// backup as completed, not as a failed snapshot creation, and keeps the
|
|
||||||
// older snapshot. See https://git.eeqj.de/sneak/vaultik/issues/395.
|
|
||||||
//
|
|
||||||
//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
|
|
||||||
func TestEntrySnapshotCreatePruneExitsNonZeroWhenMountPointIsMissing(
|
|
||||||
t *testing.T,
|
|
||||||
) {
|
|
||||||
configPath, storeDir := writeBackupConfig(t)
|
|
||||||
|
|
||||||
code, _, _ := runEntry(t, flagConfig, configPath, cmdSnapshot, cmdCreate)
|
|
||||||
require.Equal(t, 0, code)
|
|
||||||
|
|
||||||
// writeBackupConfig puts the source directory and the local index
|
|
||||||
// beside the config file.
|
|
||||||
dir := filepath.Dir(configPath)
|
|
||||||
ctx := context.Background()
|
|
||||||
|
|
||||||
db, err := database.New(ctx, filepath.Join(dir, "index.sqlite"))
|
|
||||||
require.NoError(t, err)
|
|
||||||
|
|
||||||
repos := database.NewRepositories(db)
|
|
||||||
|
|
||||||
backedUp, err := repos.Snapshots.GetOnlySnapshot(ctx)
|
|
||||||
require.NoError(t, err)
|
|
||||||
require.NoError(t, repos.Snapshots.AddMountPoint(ctx, nil,
|
|
||||||
backedUp.ID.String(), filepath.Join(dir, "source")))
|
|
||||||
require.NoError(t, db.Close())
|
|
||||||
|
|
||||||
code, _, stderr := runEntry(t,
|
|
||||||
flagConfig, configPath, cmdSnapshot, cmdCreate, flagPrune)
|
|
||||||
|
|
||||||
assert.Equal(t, 1, code)
|
|
||||||
assert.Contains(t, stderr, "Backup completed, but 1 mount point(s) "+
|
|
||||||
"an earlier snapshot recorded were not found")
|
|
||||||
assert.NotContains(t, stderr, "Snapshot creation failed")
|
|
||||||
|
|
||||||
snapshots, err := os.ReadDir(filepath.Join(storeDir, "metadata"))
|
|
||||||
require.NoError(t, err)
|
|
||||||
assert.Len(t, snapshots, 2, "the older snapshot is kept")
|
|
||||||
}
|
|
||||||
|
|
||||||
// writeBackupConfig builds a hermetic config with one small file in its
|
// writeBackupConfig builds a hermetic config with one small file in its
|
||||||
// source directory and an empty destination store directory. Returns the
|
// source directory and an empty destination store directory. Returns the
|
||||||
// config path and the store directory.
|
// config path and the store directory.
|
||||||
|
|||||||
@@ -42,7 +42,7 @@ func TestEntrySnapshotPurgeKeepsMetadataWhenLocalIndexDeleteFails(t *testing.T)
|
|||||||
seedStaleSnapshotRecord(t, indexPath)
|
seedStaleSnapshotRecord(t, indexPath)
|
||||||
|
|
||||||
// While the local index holds a snapshot, purge fails on a
|
// While the local index holds a snapshot, purge fails on a
|
||||||
// destination that answers that it has no marker.
|
// destination without the marker a backup writes.
|
||||||
require.NoError(t, os.WriteFile(
|
require.NoError(t, os.WriteFile(
|
||||||
filepath.Join(dir, "store", "vaultik-destination.txt"), nil, 0o600))
|
filepath.Join(dir, "store", "vaultik-destination.txt"), nil, 0o600))
|
||||||
|
|
||||||
|
|||||||
@@ -13,15 +13,10 @@ func NewPruneCommand() *cobra.Command {
|
|||||||
cmd := &cobra.Command{
|
cmd := &cobra.Command{
|
||||||
Use: "prune",
|
Use: "prune",
|
||||||
Short: "Tidy local database and remote storage",
|
Short: "Tidy local database and remote storage",
|
||||||
Long: `Removes orphaned data from the local index database, and
|
Long: `Removes orphaned data from both the local index database and
|
||||||
unreferenced blobs and directories under metadata/ with no manifest
|
unreferenced blobs from the backup destination store.
|
||||||
from the backup destination store.
|
|
||||||
|
|
||||||
Needs permission to list, read and delete objects on the destination
|
Local cleanup drops incomplete snapshots and any files, chunks, or
|
||||||
store. It does not need the age private key.
|
|
||||||
|
|
||||||
Local cleanup drops snapshots whose manifest is gone from the
|
|
||||||
destination store, incomplete snapshots, and any files, chunks, or
|
|
||||||
blobs no longer referenced by a completed snapshot. Remote cleanup
|
blobs no longer referenced by a completed snapshot. Remote cleanup
|
||||||
scans every snapshot manifest in the destination store, builds the
|
scans every snapshot manifest in the destination store, builds the
|
||||||
set of still-referenced blob hashes, and deletes any blob not in that
|
set of still-referenced blob hashes, and deletes any blob not in that
|
||||||
|
|||||||
+5
-10
@@ -40,13 +40,11 @@ func newRemoteNukeCommand() *cobra.Command {
|
|||||||
cmd := &cobra.Command{
|
cmd := &cobra.Command{
|
||||||
Use: "nuke",
|
Use: "nuke",
|
||||||
Short: "Delete ALL snapshot metadata and blobs from the backup destination store",
|
Short: "Delete ALL snapshot metadata and blobs from the backup destination store",
|
||||||
Long: `Removes every snapshot's metadata, every blob and the destination
|
Long: `Removes every snapshot's metadata and every blob from remote
|
||||||
marker from the backup destination store, and each removed snapshot from
|
storage. After this command completes successfully the bucket prefix is
|
||||||
the local index. After this command completes successfully the bucket
|
empty and the next backup starts from scratch.
|
||||||
prefix is empty and the next backup starts from scratch.
|
|
||||||
|
|
||||||
This is destructive and irreversible. Requires --force, and permission
|
This is destructive and irreversible. Requires --force.`,
|
||||||
to list and delete objects on the destination store.`,
|
|
||||||
Args: cobra.NoArgs,
|
Args: cobra.NoArgs,
|
||||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||||
if !force {
|
if !force {
|
||||||
@@ -77,10 +75,7 @@ func newRemoteInfoCommand() *cobra.Command {
|
|||||||
- Size of all snapshot metadata (per snapshot and total)
|
- Size of all snapshot metadata (per snapshot and total)
|
||||||
- Count and total size of all blobs
|
- Count and total size of all blobs
|
||||||
- Count and size of referenced blobs (from all manifests)
|
- Count and size of referenced blobs (from all manifests)
|
||||||
- Count and size of orphaned blobs (not referenced by any manifest)
|
- Count and size of orphaned blobs (not referenced by any manifest)`,
|
||||||
|
|
||||||
Needs permission to list and read the destination store. It does not
|
|
||||||
need the age private key.`,
|
|
||||||
Args: cobra.NoArgs,
|
Args: cobra.NoArgs,
|
||||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||||
// Use unified config resolution
|
// Use unified config resolution
|
||||||
|
|||||||
@@ -35,10 +35,9 @@ func NewRootCommand() *cobra.Command {
|
|||||||
cmd := &cobra.Command{
|
cmd := &cobra.Command{
|
||||||
Use: "vaultik",
|
Use: "vaultik",
|
||||||
Short: "Secure incremental backup tool with asymmetric encryption",
|
Short: "Secure incremental backup tool with asymmetric encryption",
|
||||||
Long: `vaultik is an incremental backup tool that encrypts data to age public
|
Long: `vaultik is a secure incremental backup tool that encrypts data using age
|
||||||
keys and uploads it to an S3-compatible object store, a local directory or
|
public keys and uploads to S3-compatible storage. No private keys are needed
|
||||||
an rclone remote. The backed-up machine needs no private key: only
|
on the source system.`,
|
||||||
'snapshot restore' and 'snapshot verify --deep' need one.`,
|
|
||||||
SilenceUsage: true,
|
SilenceUsage: true,
|
||||||
// Bare 'vaultik' (no subcommand): print help. The banner is
|
// Bare 'vaultik' (no subcommand): print help. The banner is
|
||||||
// printed once at process startup by Entry, before cobra
|
// printed once at process startup by Entry, before cobra
|
||||||
@@ -51,15 +50,13 @@ an rclone remote. The backed-up machine needs no private key: only
|
|||||||
|
|
||||||
// Add global flags
|
// Add global flags
|
||||||
cmd.PersistentFlags().StringVar(&rootFlags.ConfigPath, "config", "",
|
cmd.PersistentFlags().StringVar(&rootFlags.ConfigPath, "config", "",
|
||||||
"Path to config file (default: $VAULTIK_CONFIG, then the platform "+
|
"Path to config file (default: $VAULTIK_CONFIG or platform config dir)")
|
||||||
"config directory, then /etc/vaultik/config.yml)")
|
|
||||||
cmd.PersistentFlags().BoolVarP(&rootFlags.Verbose, "verbose", "v", false,
|
cmd.PersistentFlags().BoolVarP(&rootFlags.Verbose, "verbose", "v", false,
|
||||||
"Enable verbose output")
|
"Enable verbose output")
|
||||||
cmd.PersistentFlags().BoolVar(&rootFlags.Debug, "debug", false,
|
cmd.PersistentFlags().BoolVar(&rootFlags.Debug, "debug", false,
|
||||||
"Enable debug output")
|
"Enable debug output")
|
||||||
cmd.PersistentFlags().BoolVarP(&rootFlags.Quiet, "quiet", "q", false,
|
cmd.PersistentFlags().BoolVarP(&rootFlags.Quiet, "quiet", "q", false,
|
||||||
"Suppress status output (warnings, errors, JSON documents, "+
|
"Suppress non-error output")
|
||||||
"'config get' values and confirmation prompts are still printed)")
|
|
||||||
cmd.PersistentFlags().BoolVar(&rootFlags.SkipErrors, "skip-errors", false,
|
cmd.PersistentFlags().BoolVar(&rootFlags.SkipErrors, "skip-errors", false,
|
||||||
"Skip files that cannot be read when creating a snapshot, or "+
|
"Skip files that cannot be read when creating a snapshot, or "+
|
||||||
"that cannot be restored when restoring, instead of aborting "+
|
"that cannot be restored when restoring, instead of aborting "+
|
||||||
|
|||||||
+29
-75
@@ -60,21 +60,6 @@ func NewSnapshotCommand() *cobra.Command {
|
|||||||
return cmd
|
return cmd
|
||||||
}
|
}
|
||||||
|
|
||||||
// snapshotCreateLong is the long help text of 'snapshot create'.
|
|
||||||
const snapshotCreateLong = `Creates new snapshots of the configured directories.
|
|
||||||
|
|
||||||
If snapshot names are provided, only those snapshots are created.
|
|
||||||
If no names are provided, all configured snapshots are created.
|
|
||||||
|
|
||||||
Needs at least one public key in age_recipients, and permission to write
|
|
||||||
objects at the backup destination store. It does not need the age private
|
|
||||||
key. With --prune it also needs permission to list, read and delete objects
|
|
||||||
there.
|
|
||||||
|
|
||||||
The config is read from the path given by --config or VAULTIK_CONFIG;
|
|
||||||
otherwise from the platform config directory (~/.config/vaultik/config.yml
|
|
||||||
on Linux), then /etc/vaultik/config.yml.`
|
|
||||||
|
|
||||||
// newSnapshotCreateCommand creates the 'snapshot create' subcommand
|
// newSnapshotCreateCommand creates the 'snapshot create' subcommand
|
||||||
func newSnapshotCreateCommand() *cobra.Command {
|
func newSnapshotCreateCommand() *cobra.Command {
|
||||||
opts := &vaultik.SnapshotCreateOptions{}
|
opts := &vaultik.SnapshotCreateOptions{}
|
||||||
@@ -82,8 +67,15 @@ func newSnapshotCreateCommand() *cobra.Command {
|
|||||||
cmd := &cobra.Command{
|
cmd := &cobra.Command{
|
||||||
Use: "create [snapshot-names...]",
|
Use: "create [snapshot-names...]",
|
||||||
Short: "Create new snapshots",
|
Short: "Create new snapshots",
|
||||||
Long: snapshotCreateLong,
|
Long: `Creates new snapshots of the configured directories.
|
||||||
Args: cobra.ArbitraryArgs,
|
|
||||||
|
If snapshot names are provided, only those snapshots are created.
|
||||||
|
If no names are provided, all configured snapshots are created.
|
||||||
|
|
||||||
|
The config is read from the path given by --config or VAULTIK_CONFIG;
|
||||||
|
otherwise from the platform config directory (~/.config/vaultik/config.yml
|
||||||
|
on Linux), then /etc/vaultik/config.yml.`,
|
||||||
|
Args: cobra.ArbitraryArgs,
|
||||||
RunE: func(cmd *cobra.Command, args []string) error {
|
RunE: func(cmd *cobra.Command, args []string) error {
|
||||||
err := opts.Validate()
|
err := opts.Validate()
|
||||||
if err != nil {
|
if err != nil {
|
||||||
@@ -123,10 +115,8 @@ func newSnapshotCreateCommand() *cobra.Command {
|
|||||||
return
|
return
|
||||||
}
|
}
|
||||||
|
|
||||||
if errors.Is(err, vaultik.ErrFilesUnreadable) ||
|
if errors.Is(err, vaultik.ErrFilesUnreadable) {
|
||||||
errors.Is(err, vaultik.ErrSourcePathEmpty) ||
|
log.Error("Backup completed with unreadable files", "error", err)
|
||||||
errors.Is(err, vaultik.ErrVolumeNotMounted) {
|
|
||||||
log.Error("Backup completed with an error", "error", err)
|
|
||||||
ReportErrorf("Backup completed, but %v", err)
|
ReportErrorf("Backup completed, but %v", err)
|
||||||
|
|
||||||
return
|
return
|
||||||
@@ -146,8 +136,7 @@ func newSnapshotCreateCommand() *cobra.Command {
|
|||||||
"directory under metadata/ with no manifest once all its "+
|
"directory under metadata/ with no manifest once all its "+
|
||||||
"objects are older than prune_grace_period and its snapshot is "+
|
"objects are older than prune_grace_period and its snapshot is "+
|
||||||
"not in the local index (not after a backup that skipped "+
|
"not in the local index (not after a backup that skipped "+
|
||||||
"unreadable files, found a configured path empty, or did not "+
|
"unreadable files)")
|
||||||
"find a mount point an earlier snapshot found)")
|
|
||||||
cmd.Flags().StringVar(&opts.KeepNewerThan, "keep-newer-than", "",
|
cmd.Flags().StringVar(&opts.KeepNewerThan, "keep-newer-than", "",
|
||||||
"With --prune: keep snapshots newer than this duration "+
|
"With --prune: keep snapshots newer than this duration "+
|
||||||
"(e.g. 30d, 4w, 6mo, 1y; m is minutes, mo is months) "+
|
"(e.g. 30d, 4w, 6mo, 1y; m is minutes, mo is months) "+
|
||||||
@@ -164,15 +153,8 @@ func newSnapshotListCommand() *cobra.Command {
|
|||||||
Use: "list",
|
Use: "list",
|
||||||
Aliases: []string{"ls"},
|
Aliases: []string{"ls"},
|
||||||
Short: "List all snapshots",
|
Short: "List all snapshots",
|
||||||
Long: `Lists the snapshots in the local index and on the backup destination
|
Long: "Lists all snapshots with their ID, timestamp, and compressed size",
|
||||||
store, with their ID, timestamp, and sizes.
|
Args: cobra.NoArgs,
|
||||||
|
|
||||||
Needs permission to list and read the destination store. It does not need
|
|
||||||
the age private key. A snapshot found only on the destination store is
|
|
||||||
listed by its remote key, because its ID is stored only in the local index
|
|
||||||
and in the snapshot's encrypted database. If the destination store cannot
|
|
||||||
be listed, the command warns and lists the local index alone.`,
|
|
||||||
Args: cobra.NoArgs,
|
|
||||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||||
return runVaultikApp(cmd, readOnly, false,
|
return runVaultikApp(cmd, readOnly, false,
|
||||||
"Failed to list snapshots",
|
"Failed to list snapshots",
|
||||||
@@ -194,19 +176,11 @@ func newSnapshotPurgeCommand() *cobra.Command {
|
|||||||
cmd := &cobra.Command{
|
cmd := &cobra.Command{
|
||||||
Use: "purge",
|
Use: "purge",
|
||||||
Short: "Purge old snapshots",
|
Short: "Purge old snapshots",
|
||||||
Long: `Removes snapshots based on age or count criteria. Exactly one of
|
Long: `Removes snapshots based on age or count criteria.
|
||||||
--keep-latest and --older-than is required.
|
|
||||||
|
|
||||||
Retention is per-snapshot-name: --keep-latest keeps the latest snapshot of
|
Retention is per-snapshot-name: --keep-latest keeps the latest of each
|
||||||
each name, not the latest globally. Use --snapshot to restrict the
|
configured snapshot name, not the latest globally. Use --snapshot to
|
||||||
operation to specific snapshot names.
|
restrict the operation to specific snapshot names.`,
|
||||||
|
|
||||||
Only snapshots in the local index are removed. Each one is removed from
|
|
||||||
the local index and its metadata is deleted from the backup destination
|
|
||||||
store. Blobs are not touched: run 'vaultik prune' afterwards.
|
|
||||||
|
|
||||||
Needs permission to list and delete objects on the destination store. If
|
|
||||||
the destination store cannot be listed, nothing is removed.`,
|
|
||||||
Args: cobra.NoArgs,
|
Args: cobra.NoArgs,
|
||||||
RunE: func(cmd *cobra.Command, _ []string) error {
|
RunE: func(cmd *cobra.Command, _ []string) error {
|
||||||
// Validate flags
|
// Validate flags
|
||||||
@@ -245,29 +219,14 @@ func newSnapshotVerifyCommand() *cobra.Command {
|
|||||||
cmd := &cobra.Command{
|
cmd := &cobra.Command{
|
||||||
Use: "verify <snapshot-id>",
|
Use: "verify <snapshot-id>",
|
||||||
Short: "Check a snapshot's blobs are present with the listed size",
|
Short: "Check a snapshot's blobs are present with the listed size",
|
||||||
Long: `Checks that every blob the snapshot's manifest lists is present
|
Long: "Checks that every blob the snapshot's manifest lists is present\n" +
|
||||||
in storage with the size the manifest records, and that the
|
"in storage with the size the manifest records, and that the\n" +
|
||||||
snapshot's encrypted database is present. It does not read blob
|
"snapshot's encrypted database is present. It does not read blob\n" +
|
||||||
contents and does not need the age private key.
|
"contents; use --deep to download, decrypt, and re-hash every blob\n" +
|
||||||
|
"to detect corruption -- integrity, not who wrote it.\n\n" +
|
||||||
Needs permission to read the backup destination store, and to list it
|
"The snapshot may be named by its ID or, on a host with no local\n" +
|
||||||
when a remote key is given.
|
"index, by the remote key that 'snapshot list' prints for a\n" +
|
||||||
|
"remote-only snapshot (an unambiguous leading part is enough).",
|
||||||
Use --deep to download, decrypt, and re-hash every blob to detect
|
|
||||||
corruption -- integrity, not who wrote it.
|
|
||||||
|
|
||||||
--deep requires the age private key, in the VAULTIK_AGE_SECRET_KEY
|
|
||||||
environment variable or as age_secret_key in the config file; the
|
|
||||||
environment variable wins. The variable may hold the whole age-keygen
|
|
||||||
file, with its comments and all of its keys. Read the key from the
|
|
||||||
file rather than typing it, so that it does not land in your shell
|
|
||||||
history:
|
|
||||||
|
|
||||||
export VAULTIK_AGE_SECRET_KEY="$(cat vaultik_backup_private_key.txt)"
|
|
||||||
|
|
||||||
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).`,
|
|
||||||
Args: requireSnapshotIDArg,
|
Args: requireSnapshotIDArg,
|
||||||
RunE: func(cmd *cobra.Command, args []string) error {
|
RunE: func(cmd *cobra.Command, args []string) error {
|
||||||
snapshotID := args[0]
|
snapshotID := args[0]
|
||||||
@@ -302,10 +261,7 @@ remote-only snapshot (an unambiguous leading part is enough).`,
|
|||||||
},
|
},
|
||||||
}
|
}
|
||||||
|
|
||||||
cmd.Flags().BoolVar(&opts.Deep, "deep", false,
|
cmd.Flags().BoolVar(&opts.Deep, "deep", false, "Download and verify blob hashes")
|
||||||
"Download, decrypt and re-hash every blob; requires the age private "+
|
|
||||||
"key in VAULTIK_AGE_SECRET_KEY, or as age_secret_key in the config "+
|
|
||||||
"file")
|
|
||||||
cmd.Flags().BoolVar(&opts.JSON, "json", false, "Output verification results as JSON")
|
cmd.Flags().BoolVar(&opts.JSON, "json", false, "Output verification results as JSON")
|
||||||
|
|
||||||
return cmd
|
return cmd
|
||||||
@@ -329,10 +285,8 @@ know about), which is what 'vaultik prune' does. The command prints the
|
|||||||
'vaultik prune' invocation to run as a follow-up only when it removed the
|
'vaultik prune' invocation to run as a follow-up only when it removed the
|
||||||
snapshot's metadata from the destination store, and never under --json.
|
snapshot's metadata from the destination store, and never under --json.
|
||||||
|
|
||||||
The argument must be a snapshot ID: a remote key is not accepted. An ID
|
An ID that names no snapshot in the local index or on the destination
|
||||||
that names no snapshot in the local index or on the destination store is
|
store is an error.
|
||||||
an error. Needs permission to list and delete objects on the destination
|
|
||||||
store, unless --local-only is given.
|
|
||||||
|
|
||||||
Use --local-only to skip the remote half (e.g. when you want to forget a
|
Use --local-only to skip the remote half (e.g. when you want to forget a
|
||||||
snapshot locally without touching the destination store); the snapshot
|
snapshot locally without touching the destination store); the snapshot
|
||||||
|
|||||||
@@ -37,21 +37,13 @@ The snapshot may be named by its ID or, when restoring on a host with no
|
|||||||
local index, by the remote key that 'snapshot list' prints for a
|
local index, by the remote key that 'snapshot list' prints for a
|
||||||
remote-only snapshot (an unambiguous leading part is enough).
|
remote-only snapshot (an unambiguous leading part is enough).
|
||||||
|
|
||||||
Each file is restored under its original absolute path inside the target
|
Requires the age private key in the VAULTIK_AGE_SECRET_KEY environment
|
||||||
directory. File owners are restored only when the command runs as root.
|
variable. The variable may hold the whole age-keygen file (comments and
|
||||||
|
all of its identities are accepted); read it from the file rather than
|
||||||
Requires the age private key, in the VAULTIK_AGE_SECRET_KEY environment
|
typing the key, so it does not land in your shell history:
|
||||||
variable or as age_secret_key in the config file; the environment
|
|
||||||
variable wins. The variable may hold the whole age-keygen file, with its
|
|
||||||
comments and all of its keys. Read the key from the file rather than
|
|
||||||
typing it, so that it does not land in your shell history:
|
|
||||||
|
|
||||||
export VAULTIK_AGE_SECRET_KEY="$(cat vaultik_backup_private_key.txt)"
|
export VAULTIK_AGE_SECRET_KEY="$(cat vaultik_backup_private_key.txt)"
|
||||||
|
|
||||||
Also needs permission to read the backup destination store (and to list
|
|
||||||
it when a remote key is given), and free space in the temporary directory
|
|
||||||
for the decrypted blobs.
|
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
# Restore entire snapshot
|
# Restore entire snapshot
|
||||||
vaultik snapshot restore myhost_docs_2025-01-01T12:00:00Z /restore
|
vaultik snapshot restore myhost_docs_2025-01-01T12:00:00Z /restore
|
||||||
|
|||||||
@@ -415,8 +415,7 @@ func TestDocumentedSizeExamples(t *testing.T) {
|
|||||||
|
|
||||||
// TestValidatePruneGracePeriod checks that a negative prune_grace_period
|
// TestValidatePruneGracePeriod checks that a negative prune_grace_period
|
||||||
// is refused rather than acting like 0s, which deletes unreferenced blobs
|
// is refused rather than acting like 0s, which deletes unreferenced blobs
|
||||||
// and directories under metadata/ with no manifest at once, and that 0s
|
// at once, and that 0s and the documented examples are accepted.
|
||||||
// and the documented examples are accepted.
|
|
||||||
func TestValidatePruneGracePeriod(t *testing.T) {
|
func TestValidatePruneGracePeriod(t *testing.T) {
|
||||||
t.Parallel()
|
t.Parallel()
|
||||||
|
|
||||||
|
|||||||
@@ -123,16 +123,6 @@ CREATE TABLE IF NOT EXISTS snapshot_blobs (
|
|||||||
-- Index for efficient blob lookups (used in orphan detection)
|
-- Index for efficient blob lookups (used in orphan detection)
|
||||||
CREATE INDEX IF NOT EXISTS idx_snapshot_blobs_blob_id ON snapshot_blobs(blob_id);
|
CREATE INDEX IF NOT EXISTS idx_snapshot_blobs_blob_id ON snapshot_blobs(blob_id);
|
||||||
|
|
||||||
-- Snapshot mount points table: the directories at or below a configured
|
|
||||||
-- path that the snapshot's backup found on a different filesystem from
|
|
||||||
-- their parent directory, as a mount point is, and found an entry in
|
|
||||||
CREATE TABLE IF NOT EXISTS snapshot_mount_points (
|
|
||||||
snapshot_id TEXT NOT NULL,
|
|
||||||
path TEXT NOT NULL,
|
|
||||||
PRIMARY KEY (snapshot_id, path),
|
|
||||||
FOREIGN KEY (snapshot_id) REFERENCES snapshots(id) ON DELETE CASCADE
|
|
||||||
);
|
|
||||||
|
|
||||||
-- Uploads table: tracks blob upload metrics
|
-- Uploads table: tracks blob upload metrics
|
||||||
CREATE TABLE IF NOT EXISTS uploads (
|
CREATE TABLE IF NOT EXISTS uploads (
|
||||||
blob_hash TEXT PRIMARY KEY,
|
blob_hash TEXT PRIMARY KEY,
|
||||||
|
|||||||
@@ -24,8 +24,7 @@ var (
|
|||||||
)
|
)
|
||||||
|
|
||||||
// SnapshotRepository provides access to the snapshots table and its
|
// SnapshotRepository provides access to the snapshots table and its
|
||||||
// snapshot_files / snapshot_blobs association tables, and to the mount
|
// snapshot_files / snapshot_blobs association tables.
|
||||||
// points each snapshot's backup found (snapshot_mount_points).
|
|
||||||
type SnapshotRepository struct {
|
type SnapshotRepository struct {
|
||||||
db *DB
|
db *DB
|
||||||
}
|
}
|
||||||
@@ -495,63 +494,33 @@ func (r *SnapshotRepository) GetBlobHashes(
|
|||||||
ctx context.Context, snapshotID string,
|
ctx context.Context, snapshotID string,
|
||||||
) ([]string, error) {
|
) ([]string, error) {
|
||||||
query := `
|
query := `
|
||||||
SELECT sb.blob_hash
|
SELECT sb.blob_hash
|
||||||
FROM snapshot_blobs sb
|
FROM snapshot_blobs sb
|
||||||
WHERE sb.snapshot_id = ?
|
WHERE sb.snapshot_id = ?
|
||||||
ORDER BY sb.blob_hash
|
ORDER BY sb.blob_hash
|
||||||
`
|
`
|
||||||
|
|
||||||
blobs, err := r.queryStrings(ctx, query, snapshotID)
|
rows, err := r.db.conn.QueryContext(ctx, query, snapshotID)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return nil, fmt.Errorf("querying blob hashes: %w", err)
|
return nil, fmt.Errorf("querying blob hashes: %w", err)
|
||||||
}
|
}
|
||||||
|
|
||||||
return blobs, nil
|
defer func() { _ = rows.Close() }()
|
||||||
}
|
|
||||||
|
|
||||||
// AddMountPoint records dir as a directory that the backup of a snapshot
|
var blobs []string
|
||||||
// found on a different filesystem from its parent directory, as a mount
|
|
||||||
// point is, using tx when non-nil.
|
|
||||||
func (r *SnapshotRepository) AddMountPoint(
|
|
||||||
ctx context.Context, tx *sql.Tx, snapshotID string, dir string,
|
|
||||||
) error {
|
|
||||||
query := `
|
|
||||||
INSERT OR IGNORE INTO snapshot_mount_points (snapshot_id, path)
|
|
||||||
VALUES (?, ?)
|
|
||||||
`
|
|
||||||
|
|
||||||
var err error
|
for rows.Next() {
|
||||||
if tx != nil {
|
var blobHash string
|
||||||
_, err = tx.ExecContext(ctx, query, snapshotID, dir)
|
|
||||||
} else {
|
err := rows.Scan(&blobHash)
|
||||||
_, err = r.db.ExecWithLog(ctx, query, snapshotID, dir)
|
if err != nil {
|
||||||
|
return nil, fmt.Errorf("scanning blob hash: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
blobs = append(blobs, blobHash)
|
||||||
}
|
}
|
||||||
|
|
||||||
if err != nil {
|
return blobs, rows.Err()
|
||||||
return fmt.Errorf("adding mount point to snapshot: %w", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
return nil
|
|
||||||
}
|
|
||||||
|
|
||||||
// GetMountPoints returns the directories AddMountPoint recorded for a
|
|
||||||
// snapshot, sorted.
|
|
||||||
func (r *SnapshotRepository) GetMountPoints(
|
|
||||||
ctx context.Context, snapshotID string,
|
|
||||||
) ([]string, error) {
|
|
||||||
query := `
|
|
||||||
SELECT path
|
|
||||||
FROM snapshot_mount_points
|
|
||||||
WHERE snapshot_id = ?
|
|
||||||
ORDER BY path
|
|
||||||
`
|
|
||||||
|
|
||||||
dirs, err := r.queryStrings(ctx, query, snapshotID)
|
|
||||||
if err != nil {
|
|
||||||
return nil, fmt.Errorf("querying mount points: %w", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
return dirs, nil
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// GetSnapshotTotalCompressedSize returns the total compressed size of all
|
// GetSnapshotTotalCompressedSize returns the total compressed size of all
|
||||||
@@ -740,34 +709,6 @@ func (r *SnapshotRepository) DeleteSnapshotUploads(
|
|||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
|
|
||||||
// queryStrings runs query, which selects one text column, and returns
|
|
||||||
// its values in the order of the rows.
|
|
||||||
func (r *SnapshotRepository) queryStrings(
|
|
||||||
ctx context.Context, query string, args ...any,
|
|
||||||
) ([]string, error) {
|
|
||||||
rows, err := r.db.conn.QueryContext(ctx, query, args...)
|
|
||||||
if err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
|
|
||||||
defer func() { _ = rows.Close() }()
|
|
||||||
|
|
||||||
var values []string
|
|
||||||
|
|
||||||
for rows.Next() {
|
|
||||||
var value string
|
|
||||||
|
|
||||||
err := rows.Scan(&value)
|
|
||||||
if err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
|
|
||||||
values = append(values, value)
|
|
||||||
}
|
|
||||||
|
|
||||||
return values, rows.Err()
|
|
||||||
}
|
|
||||||
|
|
||||||
// extendedCompressionRatio computes the compression ratio for a snapshot
|
// extendedCompressionRatio computes the compression ratio for a snapshot
|
||||||
// from its stored blob_size and the given uncompressed size. Returns 1.0
|
// from its stored blob_size and the given uncompressed size. Returns 1.0
|
||||||
// when the uncompressed size is zero.
|
// when the uncompressed size is zero.
|
||||||
|
|||||||
@@ -4,7 +4,6 @@ import (
|
|||||||
"context"
|
"context"
|
||||||
"fmt"
|
"fmt"
|
||||||
"math"
|
"math"
|
||||||
"slices"
|
|
||||||
"testing"
|
"testing"
|
||||||
"time"
|
"time"
|
||||||
|
|
||||||
@@ -423,52 +422,3 @@ func TestSnapshotRepositoryDuplicate(t *testing.T) {
|
|||||||
t.Error("expected error for duplicate snapshot")
|
t.Error("expected error for duplicate snapshot")
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
// Deleting a snapshot from the local index deletes the mount points its
|
|
||||||
// backup recorded, and no other snapshot's. See
|
|
||||||
// https://git.eeqj.de/sneak/vaultik/issues/395.
|
|
||||||
func TestSnapshotRepositoryDeleteRemovesMountPoints(t *testing.T) {
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
db, cleanup := setupTestDB(t)
|
|
||||||
defer cleanup()
|
|
||||||
|
|
||||||
ctx := context.Background()
|
|
||||||
repo := database.NewSnapshotRepository(db)
|
|
||||||
|
|
||||||
for _, id := range []types.SnapshotID{"kept", "deleted"} {
|
|
||||||
err := repo.Create(ctx, nil, &database.Snapshot{
|
|
||||||
ID: id,
|
|
||||||
Hostname: testHostname,
|
|
||||||
VaultikVersion: testVersion,
|
|
||||||
StartedAt: time.Now().Truncate(time.Second),
|
|
||||||
})
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to create snapshot: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
err = repo.AddMountPoint(ctx, nil, id.String(), "/data/nas")
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to add mount point: %v", err)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
err := repo.Delete(ctx, "deleted")
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to delete snapshot: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
for id, want := range map[string][]string{
|
|
||||||
"kept": {"/data/nas"},
|
|
||||||
"deleted": nil,
|
|
||||||
} {
|
|
||||||
got, err := repo.GetMountPoints(ctx, id)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to read mount points: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
if !slices.Equal(got, want) {
|
|
||||||
t.Errorf("mount points of %s: got %v, want %v", id, got, want)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|||||||
@@ -1,40 +0,0 @@
|
|||||||
//nolint:testpackage // exercises the unexported deviceNumberFromStat
|
|
||||||
package snapshot
|
|
||||||
|
|
||||||
import (
|
|
||||||
"os"
|
|
||||||
"path/filepath"
|
|
||||||
"testing"
|
|
||||||
|
|
||||||
"github.com/stretchr/testify/assert"
|
|
||||||
"github.com/stretchr/testify/require"
|
|
||||||
)
|
|
||||||
|
|
||||||
// The device number a real backup reads is the same for a directory and
|
|
||||||
// a file in it, and differs between the temp directory and /dev.
|
|
||||||
// Without it no mount point is ever found. See
|
|
||||||
// https://git.eeqj.de/sneak/vaultik/issues/395.
|
|
||||||
func TestDeviceNumberFromStat(t *testing.T) {
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
dir := t.TempDir()
|
|
||||||
file := filepath.Join(dir, "file.txt")
|
|
||||||
require.NoError(t, os.WriteFile(file, nil, 0o600))
|
|
||||||
|
|
||||||
deviceOf := func(path string) uint64 {
|
|
||||||
t.Helper()
|
|
||||||
|
|
||||||
info, err := os.Stat(path)
|
|
||||||
require.NoError(t, err)
|
|
||||||
|
|
||||||
device, ok := deviceNumberFromStat(info)
|
|
||||||
require.True(t, ok, "no device number read for %s", path)
|
|
||||||
|
|
||||||
return device
|
|
||||||
}
|
|
||||||
|
|
||||||
assert.Equal(t, deviceOf(dir), deviceOf(file))
|
|
||||||
|
|
||||||
// /dev is a different filesystem from the temp dir on Linux, macOS and in Docker.
|
|
||||||
assert.NotEqual(t, deviceOf(dir), deviceOf("/dev"))
|
|
||||||
}
|
|
||||||
@@ -1,8 +1,6 @@
|
|||||||
package snapshot
|
package snapshot
|
||||||
|
|
||||||
import (
|
import (
|
||||||
"os"
|
|
||||||
|
|
||||||
"github.com/spf13/afero"
|
"github.com/spf13/afero"
|
||||||
"go.uber.org/fx"
|
"go.uber.org/fx"
|
||||||
"sneak.berlin/go/vaultik/internal/config"
|
"sneak.berlin/go/vaultik/internal/config"
|
||||||
@@ -21,9 +19,6 @@ type ScannerParams struct {
|
|||||||
// PreviousSnapshotID is the most recent completed snapshot of the
|
// PreviousSnapshotID is the most recent completed snapshot of the
|
||||||
// same name, "" for none.
|
// same name, "" for none.
|
||||||
PreviousSnapshotID string
|
PreviousSnapshotID string
|
||||||
// DeviceNumber is ScannerConfig.DeviceNumber; nil reads it from the
|
|
||||||
// file's stat.
|
|
||||||
DeviceNumber func(info os.FileInfo) (uint64, bool)
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// Module exports backup functionality as an fx module.
|
// Module exports backup functionality as an fx module.
|
||||||
@@ -64,7 +59,6 @@ func provideScannerFactory(
|
|||||||
Exclude: excludes,
|
Exclude: excludes,
|
||||||
SkipErrors: params.SkipErrors,
|
SkipErrors: params.SkipErrors,
|
||||||
PreviousSnapshotID: params.PreviousSnapshotID,
|
PreviousSnapshotID: params.PreviousSnapshotID,
|
||||||
DeviceNumber: params.DeviceNumber,
|
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,245 +0,0 @@
|
|||||||
package snapshot_test
|
|
||||||
|
|
||||||
import (
|
|
||||||
"context"
|
|
||||||
"os"
|
|
||||||
"path/filepath"
|
|
||||||
"slices"
|
|
||||||
"strings"
|
|
||||||
"syscall"
|
|
||||||
"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/snapshot"
|
|
||||||
)
|
|
||||||
|
|
||||||
// A scan records with the snapshot each directory on a different device
|
|
||||||
// from its parent directory that the walk found an entry in, as a mount
|
|
||||||
// point is, the scanned path included. A filesystem that gives no device
|
|
||||||
// numbers, as the in-memory one, records none. See
|
|
||||||
// https://git.eeqj.de/sneak/vaultik/issues/395.
|
|
||||||
func TestScanRecordsMountPoints(t *testing.T) {
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
const (
|
|
||||||
scannedPath = "/data/source"
|
|
||||||
snapshotID = "mount-points"
|
|
||||||
)
|
|
||||||
|
|
||||||
tests := []struct {
|
|
||||||
name string
|
|
||||||
// onVolume names the directories on the volume's device; every
|
|
||||||
// other directory is on another one. nil leaves the device
|
|
||||||
// numbers to the in-memory filesystem, which has none.
|
|
||||||
onVolume []string
|
|
||||||
want []string
|
|
||||||
}{
|
|
||||||
{
|
|
||||||
name: "volume below the scanned path",
|
|
||||||
onVolume: []string{"nas"},
|
|
||||||
want: []string{scannedPath + "/nas"},
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: "volume at the scanned path",
|
|
||||||
onVolume: []string{"source", "nas"},
|
|
||||||
want: []string{scannedPath},
|
|
||||||
},
|
|
||||||
{name: "no device numbers", want: nil},
|
|
||||||
}
|
|
||||||
|
|
||||||
for _, tt := range tests {
|
|
||||||
t.Run(tt.name, func(t *testing.T) {
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
ctx := context.Background()
|
|
||||||
fs := afero.NewMemMapFs()
|
|
||||||
|
|
||||||
for _, path := range []string{
|
|
||||||
scannedPath + "/notes.txt", scannedPath + "/nas/a.txt",
|
|
||||||
} {
|
|
||||||
require.NoError(t, fs.MkdirAll(filepath.Dir(path), 0o755))
|
|
||||||
require.NoError(t, afero.WriteFile(fs, path, []byte(path), 0o644))
|
|
||||||
}
|
|
||||||
|
|
||||||
db, err := database.NewTestDB()
|
|
||||||
require.NoError(t, err)
|
|
||||||
t.Cleanup(func() { _ = db.Close() })
|
|
||||||
|
|
||||||
repos := database.NewRepositories(db)
|
|
||||||
createTestSnapshotRecord(ctx, t, repos, snapshotID)
|
|
||||||
|
|
||||||
cfg := snapshot.ScannerConfig{
|
|
||||||
FS: fs,
|
|
||||||
ChunkSize: int64(1024 * 16),
|
|
||||||
Repositories: repos,
|
|
||||||
MaxBlobSize: int64(1024 * 1024),
|
|
||||||
CompressionLevel: 3,
|
|
||||||
AgeRecipients: []string{testAgePublicKey},
|
|
||||||
}
|
|
||||||
if tt.onVolume != nil {
|
|
||||||
cfg.DeviceNumber = func(info os.FileInfo) (uint64, bool) {
|
|
||||||
if slices.Contains(tt.onVolume, info.Name()) {
|
|
||||||
return 2, true
|
|
||||||
}
|
|
||||||
|
|
||||||
return 1, true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
_, err = snapshot.NewScanner(cfg).Scan(ctx, scannedPath, snapshotID)
|
|
||||||
require.NoError(t, err)
|
|
||||||
|
|
||||||
got, err := repos.Snapshots.GetMountPoints(ctx, snapshotID)
|
|
||||||
require.NoError(t, err)
|
|
||||||
assert.Equal(t, tt.want, got)
|
|
||||||
})
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// automountFs is an in-memory filesystem with a volume at mountPoint
|
|
||||||
// that is mounted on first access: opening mountPoint to list it mounts
|
|
||||||
// the volume or, if it cannot be mounted, fails with "no such file or
|
|
||||||
// directory", as with the autofs daemon. Stat records the device an
|
|
||||||
// entry is on at that moment, as a real stat does: unmountedDevice for
|
|
||||||
// mountPoint until the volume is mounted; the volume's, 2, for
|
|
||||||
// mountPoint once it is and for everything in it; 1 for everything else.
|
|
||||||
type automountFs struct {
|
|
||||||
afero.Fs
|
|
||||||
|
|
||||||
mountPoint string
|
|
||||||
unmountedDevice uint64
|
|
||||||
canMount bool
|
|
||||||
mounted bool
|
|
||||||
}
|
|
||||||
|
|
||||||
//nolint:ireturn // afero.Fs.Open is defined to return the interface.
|
|
||||||
func (fs *automountFs) Open(name string) (afero.File, error) {
|
|
||||||
if name == fs.mountPoint && !fs.canMount {
|
|
||||||
return nil, &os.PathError{Op: "open", Path: name, Err: syscall.ENOENT}
|
|
||||||
}
|
|
||||||
|
|
||||||
if name == fs.mountPoint {
|
|
||||||
fs.mounted = true
|
|
||||||
}
|
|
||||||
|
|
||||||
return fs.Fs.Open(name)
|
|
||||||
}
|
|
||||||
|
|
||||||
func (fs *automountFs) Stat(name string) (os.FileInfo, error) {
|
|
||||||
info, err := fs.Fs.Stat(name)
|
|
||||||
if err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
|
|
||||||
device := uint64(1)
|
|
||||||
|
|
||||||
switch {
|
|
||||||
case name == fs.mountPoint && !fs.mounted:
|
|
||||||
device = fs.unmountedDevice
|
|
||||||
case name == fs.mountPoint || strings.HasPrefix(name, fs.mountPoint+"/"):
|
|
||||||
device = 2
|
|
||||||
}
|
|
||||||
|
|
||||||
return statWithDevice{FileInfo: info, device: device}, nil
|
|
||||||
}
|
|
||||||
|
|
||||||
// statWithDevice is an entry automountFs.Stat looked up, with the device
|
|
||||||
// it was on then.
|
|
||||||
type statWithDevice struct {
|
|
||||||
os.FileInfo
|
|
||||||
|
|
||||||
device uint64
|
|
||||||
}
|
|
||||||
|
|
||||||
// deviceAtLookup returns the device automountFs.Stat recorded for info.
|
|
||||||
func deviceAtLookup(info os.FileInfo) (uint64, bool) {
|
|
||||||
stat, ok := info.(statWithDevice)
|
|
||||||
|
|
||||||
return stat.device, ok
|
|
||||||
}
|
|
||||||
|
|
||||||
// A volume mounted on first access is mounted when the walk lists its
|
|
||||||
// mount point. Until then the mount point is on the automounter's own
|
|
||||||
// device (a systemd automount) or on its parent's (an autofs map that
|
|
||||||
// shows its mount points before mounting them). Either way only the
|
|
||||||
// mount point is recorded, by the backup that mounts the volume and by a
|
|
||||||
// later one that finds it mounted. Listing an automount point whose
|
|
||||||
// volume cannot be mounted fails; it is not recorded, because the walk
|
|
||||||
// finds no entry in it. See https://git.eeqj.de/sneak/vaultik/issues/395.
|
|
||||||
func TestScanRecordsOnlyTheMountPointOfAnAutomountedVolume(t *testing.T) {
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
const scannedPath = "/data/source"
|
|
||||||
|
|
||||||
mountPoint := scannedPath + "/nas"
|
|
||||||
|
|
||||||
tests := []struct {
|
|
||||||
name string
|
|
||||||
unmountedDevice uint64
|
|
||||||
canMount bool
|
|
||||||
want []string
|
|
||||||
}{
|
|
||||||
{
|
|
||||||
name: "on the automounter's device until listed",
|
|
||||||
unmountedDevice: 3, canMount: true, want: []string{mountPoint},
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: "on its parent's device until listed",
|
|
||||||
unmountedDevice: 1, canMount: true, want: []string{mountPoint},
|
|
||||||
},
|
|
||||||
{
|
|
||||||
name: "volume that cannot be mounted",
|
|
||||||
unmountedDevice: 1, canMount: false, want: nil,
|
|
||||||
},
|
|
||||||
}
|
|
||||||
|
|
||||||
for _, tt := range tests {
|
|
||||||
t.Run(tt.name, func(t *testing.T) {
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
ctx := context.Background()
|
|
||||||
fs := &automountFs{
|
|
||||||
Fs: afero.NewMemMapFs(), mountPoint: mountPoint,
|
|
||||||
unmountedDevice: tt.unmountedDevice, canMount: tt.canMount,
|
|
||||||
}
|
|
||||||
|
|
||||||
require.NoError(t, fs.MkdirAll(mountPoint+"/photos", 0o755))
|
|
||||||
|
|
||||||
for _, path := range []string{
|
|
||||||
scannedPath + "/notes.txt", mountPoint + "/photos/a.jpg",
|
|
||||||
} {
|
|
||||||
require.NoError(t, afero.WriteFile(fs, path, []byte(path), 0o644))
|
|
||||||
}
|
|
||||||
|
|
||||||
db, err := database.NewTestDB()
|
|
||||||
require.NoError(t, err)
|
|
||||||
t.Cleanup(func() { _ = db.Close() })
|
|
||||||
|
|
||||||
repos := database.NewRepositories(db)
|
|
||||||
|
|
||||||
for _, snapshotID := range []string{"first", "later"} {
|
|
||||||
createTestSnapshotRecord(ctx, t, repos, snapshotID)
|
|
||||||
|
|
||||||
scanner := snapshot.NewScanner(snapshot.ScannerConfig{
|
|
||||||
FS: fs,
|
|
||||||
ChunkSize: int64(1024 * 16),
|
|
||||||
Repositories: repos,
|
|
||||||
MaxBlobSize: int64(1024 * 1024),
|
|
||||||
CompressionLevel: 3,
|
|
||||||
AgeRecipients: []string{testAgePublicKey},
|
|
||||||
DeviceNumber: deviceAtLookup,
|
|
||||||
})
|
|
||||||
|
|
||||||
_, err = scanner.Scan(ctx, scannedPath, snapshotID)
|
|
||||||
require.NoError(t, err)
|
|
||||||
|
|
||||||
got, err := repos.Snapshots.GetMountPoints(ctx, snapshotID)
|
|
||||||
require.NoError(t, err)
|
|
||||||
assert.Equal(t, tt.want, got, "mount points of the %s backup", snapshotID)
|
|
||||||
}
|
|
||||||
})
|
|
||||||
}
|
|
||||||
}
|
|
||||||
+20
-169
@@ -73,9 +73,6 @@ type Scanner struct {
|
|||||||
skipErrors bool
|
skipErrors bool
|
||||||
// ui is the user-facing output; never nil (defaults to a discarding writer).
|
// ui is the user-facing output; never nil (defaults to a discarding writer).
|
||||||
ui *ui.Writer
|
ui *ui.Writer
|
||||||
// deviceNumber returns the number of the device that holds a file;
|
|
||||||
// never nil (defaults to deviceNumberFromStat).
|
|
||||||
deviceNumber func(info os.FileInfo) (uint64, bool)
|
|
||||||
|
|
||||||
// In-memory cache of known chunk hashes for fast existence checks
|
// In-memory cache of known chunk hashes for fast existence checks
|
||||||
knownChunks map[string]struct{}
|
knownChunks map[string]struct{}
|
||||||
@@ -139,10 +136,6 @@ type ScannerConfig struct {
|
|||||||
// PreviousSnapshotID is the most recent completed snapshot of the
|
// PreviousSnapshotID is the most recent completed snapshot of the
|
||||||
// same name, "" for none.
|
// same name, "" for none.
|
||||||
PreviousSnapshotID string
|
PreviousSnapshotID string
|
||||||
// DeviceNumber returns the number of the device that holds a file,
|
|
||||||
// and false when there is none to read. nil reads it from the file's
|
|
||||||
// stat; tests replace it, since the in-memory test filesystem has none.
|
|
||||||
DeviceNumber func(info os.FileInfo) (uint64, bool)
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// ScanResult contains the results of a scan operation. Files and bytes
|
// ScanResult contains the results of a scan operation. Files and bytes
|
||||||
@@ -175,12 +168,6 @@ type ScanResult struct {
|
|||||||
// skipped because it could not be read or listed; the rest are files
|
// skipped because it could not be read or listed; the rest are files
|
||||||
// removed after the walk listed them.
|
// removed after the walk listed them.
|
||||||
FilesUnreadable int
|
FilesUnreadable int
|
||||||
|
|
||||||
// EntriesFound counts the entries the walk found and could look up
|
|
||||||
// that no exclude pattern matches, leaving out the scanned path
|
|
||||||
// itself when it is a directory. It is zero for an empty directory,
|
|
||||||
// such as the mount point of a volume that is not mounted.
|
|
||||||
EntriesFound int
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// NewScanner creates a new scanner instance
|
// NewScanner creates a new scanner instance
|
||||||
@@ -221,11 +208,6 @@ func NewScanner(cfg ScannerConfig) *Scanner {
|
|||||||
uiw = ui.NewWithColor(io.Discard, false)
|
uiw = ui.NewWithColor(io.Discard, false)
|
||||||
}
|
}
|
||||||
|
|
||||||
deviceNumber := cfg.DeviceNumber
|
|
||||||
if deviceNumber == nil {
|
|
||||||
deviceNumber = deviceNumberFromStat
|
|
||||||
}
|
|
||||||
|
|
||||||
return &Scanner{
|
return &Scanner{
|
||||||
fs: cfg.FS,
|
fs: cfg.FS,
|
||||||
chunker: chunker.NewChunker(cfg.ChunkSize),
|
chunker: chunker.NewChunker(cfg.ChunkSize),
|
||||||
@@ -241,7 +223,6 @@ func NewScanner(cfg ScannerConfig) *Scanner {
|
|||||||
skipErrors: cfg.SkipErrors,
|
skipErrors: cfg.SkipErrors,
|
||||||
previousSnapshotID: cfg.PreviousSnapshotID,
|
previousSnapshotID: cfg.PreviousSnapshotID,
|
||||||
ui: uiw,
|
ui: uiw,
|
||||||
deviceNumber: deviceNumber,
|
|
||||||
pendingChunkHashes: make(map[string]struct{}),
|
pendingChunkHashes: make(map[string]struct{}),
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -310,7 +291,7 @@ func (s *Scanner) Scan(
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
err = s.recordDirectories(ctx, scanResult)
|
err = s.recordDirectories(ctx, scanResult.Directories)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return nil, err
|
return nil, err
|
||||||
}
|
}
|
||||||
@@ -888,11 +869,6 @@ type ScanPhaseResult struct {
|
|||||||
FilesToProcess []*FileToProcess
|
FilesToProcess []*FileToProcess
|
||||||
UnchangedFileIDs []types.FileID // IDs of unchanged files to associate with snapshot
|
UnchangedFileIDs []types.FileID // IDs of unchanged files to associate with snapshot
|
||||||
Directories []*FileToProcess // Every directory found, to record
|
Directories []*FileToProcess // Every directory found, to record
|
||||||
// MountPoints are the directories, the scanned path included, that
|
|
||||||
// the walk found an entry in and, once it had listed them, on a
|
|
||||||
// different device from their parent directory (see
|
|
||||||
// recordIfMountPoint).
|
|
||||||
MountPoints []string
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// scanPhase performs the initial directory scan to identify files to process
|
// scanPhase performs the initial directory scan to identify files to process
|
||||||
@@ -912,7 +888,7 @@ func (s *Scanner) scanPhase(
|
|||||||
// estimate leaves them out.
|
// estimate leaves them out.
|
||||||
estimatedTotal := countNonDirectories(knownFiles)
|
estimatedTotal := countNonDirectories(knownFiles)
|
||||||
|
|
||||||
collector := &scanCollector{dirsWithEntries: make(map[string]struct{})}
|
collector := &scanCollector{}
|
||||||
|
|
||||||
// Set up periodic status output
|
// Set up periodic status output
|
||||||
startTime := time.Now()
|
startTime := time.Now()
|
||||||
@@ -952,13 +928,6 @@ func (s *Scanner) scanPhase(
|
|||||||
default:
|
default:
|
||||||
}
|
}
|
||||||
|
|
||||||
// The scanned directory itself is not an entry found in it.
|
|
||||||
if filePath != path || !info.IsDir() {
|
|
||||||
result.EntriesFound++
|
|
||||||
}
|
|
||||||
|
|
||||||
s.recordIfMountPoint(filePath, path, collector)
|
|
||||||
|
|
||||||
// Handle symlinks and directories
|
// Handle symlinks and directories
|
||||||
handled, err := s.recordSpecialEntry(
|
handled, err := s.recordSpecialEntry(
|
||||||
filePath, info, existingFiles, knownFiles, collector, result)
|
filePath, info, existingFiles, knownFiles, collector, result)
|
||||||
@@ -971,8 +940,18 @@ func (s *Scanner) scanPhase(
|
|||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
|
|
||||||
filesScanned, changedCount := s.recordRegularFile(
|
// Track this file as existing (for deletion detection)
|
||||||
filePath, info, existingFiles, knownFiles, collector, result)
|
existingFiles[filePath] = struct{}{}
|
||||||
|
|
||||||
|
// Check file against in-memory map (no DB query!)
|
||||||
|
file := s.buildRegularFileEntry(filePath, info)
|
||||||
|
needsProcessing := s.checkFileInMemory(file, knownFiles)
|
||||||
|
|
||||||
|
filesScanned, changedCount := collector.recordFile(
|
||||||
|
filePath, info, file, needsProcessing)
|
||||||
|
|
||||||
|
// Update result stats
|
||||||
|
s.updateScanEntryStats(result, needsProcessing, info)
|
||||||
|
|
||||||
// Output periodic status
|
// Output periodic status
|
||||||
if time.Since(lastStatusTime) >= scanStatusInterval {
|
if time.Since(lastStatusTime) >= scanStatusInterval {
|
||||||
@@ -993,7 +972,6 @@ func (s *Scanner) scanPhase(
|
|||||||
FilesToProcess: collector.filesToProcess,
|
FilesToProcess: collector.filesToProcess,
|
||||||
UnchangedFileIDs: collector.unchangedFileIDs,
|
UnchangedFileIDs: collector.unchangedFileIDs,
|
||||||
Directories: collector.directories,
|
Directories: collector.directories,
|
||||||
MountPoints: collector.mountPoints,
|
|
||||||
}, nil
|
}, nil
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -1049,30 +1027,6 @@ func (s *Scanner) recordSpecialEntry(
|
|||||||
return false, nil
|
return false, nil
|
||||||
}
|
}
|
||||||
|
|
||||||
// recordRegularFile records a regular file as recordSpecialEntry does a
|
|
||||||
// symlink and returns the running scanned and changed counts.
|
|
||||||
func (s *Scanner) recordRegularFile(
|
|
||||||
filePath string, info os.FileInfo,
|
|
||||||
existingFiles map[string]struct{},
|
|
||||||
knownFiles map[string]*database.File,
|
|
||||||
collector *scanCollector, result *ScanResult,
|
|
||||||
) (int64, int) {
|
|
||||||
// Track this file as existing (for deletion detection)
|
|
||||||
existingFiles[filePath] = struct{}{}
|
|
||||||
|
|
||||||
// Check file against in-memory map (no DB query!)
|
|
||||||
file := s.buildRegularFileEntry(filePath, info)
|
|
||||||
needsProcessing := s.checkFileInMemory(file, knownFiles)
|
|
||||||
|
|
||||||
filesScanned, changedCount := collector.recordFile(
|
|
||||||
filePath, info, file, needsProcessing)
|
|
||||||
|
|
||||||
// Update result stats
|
|
||||||
s.updateScanEntryStats(result, needsProcessing, info)
|
|
||||||
|
|
||||||
return filesScanned, changedCount
|
|
||||||
}
|
|
||||||
|
|
||||||
// countRemovedDuringWalk counts an entry that was in its directory's
|
// countRemovedDuringWalk counts an entry that was in its directory's
|
||||||
// listing but was gone when the walk looked it up, like a file removed
|
// listing but was gone when the walk looked it up, like a file removed
|
||||||
// before phase 2 reads it: as examined and failed, and not as an error,
|
// before phase 2 reads it: as examined and failed, and not as an error,
|
||||||
@@ -1120,29 +1074,6 @@ type scanCollector struct {
|
|||||||
unchangedFileIDs []types.FileID // Just IDs - no new records needed
|
unchangedFileIDs []types.FileID // Just IDs - no new records needed
|
||||||
directories []*FileToProcess
|
directories []*FileToProcess
|
||||||
filesScanned int64
|
filesScanned int64
|
||||||
// dirsWithEntries holds each directory the walk has found an entry in.
|
|
||||||
dirsWithEntries map[string]struct{}
|
|
||||||
mountPoints []string
|
|
||||||
}
|
|
||||||
|
|
||||||
// firstEntryIn notes that the walk found an entry in directory dir and
|
|
||||||
// reports whether it is the first one.
|
|
||||||
func (c *scanCollector) firstEntryIn(dir string) bool {
|
|
||||||
c.mu.Lock()
|
|
||||||
defer c.mu.Unlock()
|
|
||||||
|
|
||||||
_, seen := c.dirsWithEntries[dir]
|
|
||||||
c.dirsWithEntries[dir] = struct{}{}
|
|
||||||
|
|
||||||
return !seen
|
|
||||||
}
|
|
||||||
|
|
||||||
// addMountPoint sets a mount point aside to be recorded.
|
|
||||||
func (c *scanCollector) addMountPoint(dir string) {
|
|
||||||
c.mu.Lock()
|
|
||||||
defer c.mu.Unlock()
|
|
||||||
|
|
||||||
c.mountPoints = append(c.mountPoints, dir)
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// addDirectory sets a directory aside to be recorded. It is not counted
|
// addDirectory sets a directory aside to be recorded. It is not counted
|
||||||
@@ -1334,100 +1265,20 @@ func (s *Scanner) buildDirectoryEntry(path string, info os.FileInfo) *database.F
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
// recordDirectories records every directory the walk found, and its
|
// recordDirectories records every directory the walk found. A directory
|
||||||
// mount points (see recordMountPoints). A directory has no data to back
|
// has no data to back up, so it is not among the files counted and
|
||||||
// up, so it is not among the files counted and backed up.
|
// backed up.
|
||||||
func (s *Scanner) recordDirectories(
|
func (s *Scanner) recordDirectories(
|
||||||
ctx context.Context, scanned *ScanPhaseResult,
|
ctx context.Context, directories []*FileToProcess,
|
||||||
) error {
|
) error {
|
||||||
for _, dir := range scanned.Directories {
|
for _, dir := range directories {
|
||||||
err := s.recordNonRegularFile(ctx, dir)
|
err := s.recordNonRegularFile(ctx, dir)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return fmt.Errorf("recording directory %s: %w", dir.Path, err)
|
return fmt.Errorf("recording directory %s: %w", dir.Path, err)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
return s.recordMountPoints(ctx, scanned.MountPoints)
|
return nil
|
||||||
}
|
|
||||||
|
|
||||||
// recordMountPoints records with the snapshot the mount points the walk
|
|
||||||
// found (see ScanPhaseResult.MountPoints).
|
|
||||||
func (s *Scanner) recordMountPoints(
|
|
||||||
ctx context.Context, mountPoints []string,
|
|
||||||
) error {
|
|
||||||
return s.repos.WithTx(ctx, func(txCtx context.Context, tx *sql.Tx) error {
|
|
||||||
for _, dir := range mountPoints {
|
|
||||||
log.Info("Found a mount point", "path", dir)
|
|
||||||
|
|
||||||
err := s.repos.Snapshots.AddMountPoint(txCtx, tx, s.snapshotID, dir)
|
|
||||||
if err != nil {
|
|
||||||
return fmt.Errorf("recording mount point %s: %w", dir, err)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return nil
|
|
||||||
})
|
|
||||||
}
|
|
||||||
|
|
||||||
// recordIfMountPoint sets the directory that holds entry, a path the
|
|
||||||
// walk found, aside to be recorded as a mount point if it is on a
|
|
||||||
// different device from its parent directory. The walk calls it for each
|
|
||||||
// entry it finds, and it decides on the first entry in a directory, so a
|
|
||||||
// directory the walk found no entry in is never recorded. By then the
|
|
||||||
// walk has listed the directory, which mounts a volume mounted there on
|
|
||||||
// first access, so the directory and its parent are looked up again:
|
|
||||||
// before the listing, the directory can be on the automounter's own
|
|
||||||
// device (a systemd automount) or on its parent's (an autofs map that
|
|
||||||
// shows its mount points before mounting them). The scanned path is in
|
|
||||||
// no listing the walk made, so it is skipped as an entry. A directory
|
|
||||||
// that cannot be looked up then, or whose parent cannot, is not
|
|
||||||
// recorded, so this snapshot does not stop the prune of a later backup
|
|
||||||
// that misses its volume.
|
|
||||||
func (s *Scanner) recordIfMountPoint(
|
|
||||||
entry, scannedPath string, collector *scanCollector,
|
|
||||||
) {
|
|
||||||
dir := filepath.Dir(entry)
|
|
||||||
|
|
||||||
if entry == scannedPath || !collector.firstEntryIn(dir) {
|
|
||||||
return
|
|
||||||
}
|
|
||||||
|
|
||||||
dirDevice, ok := s.deviceNumberAt(dir)
|
|
||||||
if !ok {
|
|
||||||
return
|
|
||||||
}
|
|
||||||
|
|
||||||
parentDevice, ok := s.deviceNumberAt(filepath.Dir(dir))
|
|
||||||
if ok && dirDevice != parentDevice {
|
|
||||||
collector.addMountPoint(dir)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// deviceNumberAt looks path up now and returns the number of the device
|
|
||||||
// that holds it, and false when the lookup fails (logged) or gives no
|
|
||||||
// device number.
|
|
||||||
func (s *Scanner) deviceNumberAt(path string) (uint64, bool) {
|
|
||||||
info, err := s.fs.Stat(path)
|
|
||||||
if err != nil {
|
|
||||||
log.Warn("Could not look up a directory to check for a mount point",
|
|
||||||
"path", path, "error", err)
|
|
||||||
|
|
||||||
return 0, false
|
|
||||||
}
|
|
||||||
|
|
||||||
return s.deviceNumber(info)
|
|
||||||
}
|
|
||||||
|
|
||||||
// deviceNumberFromStat returns the number of the device that holds the
|
|
||||||
// file info describes, and false when info carries no stat, as from the
|
|
||||||
// in-memory test filesystem.
|
|
||||||
func deviceNumberFromStat(info os.FileInfo) (uint64, bool) {
|
|
||||||
stat, ok := info.Sys().(*syscall.Stat_t)
|
|
||||||
if !ok {
|
|
||||||
return 0, false
|
|
||||||
}
|
|
||||||
|
|
||||||
return uint64(stat.Dev), true //nolint:unconvert // Dev is an int32 on darwin
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// recordNonRegularFile writes a symlink or directory entry to the database
|
// recordNonRegularFile writes a symlink or directory entry to the database
|
||||||
|
|||||||
@@ -518,8 +518,8 @@ type CleanupStats struct {
|
|||||||
//
|
//
|
||||||
// The cleanup is performed in a specific order to maintain referential integrity:
|
// The cleanup is performed in a specific order to maintain referential integrity:
|
||||||
// 1. Delete other snapshots
|
// 1. Delete other snapshots
|
||||||
// 2. Delete orphaned snapshot associations (snapshot_files, snapshot_blobs,
|
// 2. Delete orphaned snapshot associations (snapshot_files, snapshot_blobs)
|
||||||
// snapshot_mount_points) for deleted snapshots
|
// for deleted snapshots
|
||||||
// 3. Delete orphaned files (not in the current snapshot)
|
// 3. Delete orphaned files (not in the current snapshot)
|
||||||
// 4. Delete orphaned chunk-to-file mappings (references to deleted files)
|
// 4. Delete orphaned chunk-to-file mappings (references to deleted files)
|
||||||
// 5. Delete orphaned blobs (not in the current snapshot)
|
// 5. Delete orphaned blobs (not in the current snapshot)
|
||||||
@@ -948,8 +948,8 @@ func (sm *SnapshotManager) deleteOtherSnapshots(
|
|||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
|
|
||||||
// deleteOrphanedSnapshotAssociations deletes snapshot_files,
|
// deleteOrphanedSnapshotAssociations deletes snapshot_files and
|
||||||
// snapshot_blobs and snapshot_mount_points for deleted snapshots
|
// snapshot_blobs for deleted snapshots
|
||||||
func (sm *SnapshotManager) deleteOrphanedSnapshotAssociations(
|
func (sm *SnapshotManager) deleteOrphanedSnapshotAssociations(
|
||||||
ctx context.Context, tx *sql.Tx, currentSnapshotID string,
|
ctx context.Context, tx *sql.Tx, currentSnapshotID string,
|
||||||
) error {
|
) error {
|
||||||
@@ -983,19 +983,6 @@ func (sm *SnapshotManager) deleteOrphanedSnapshotAssociations(
|
|||||||
log.Debug("[Temp DB Cleanup] Deleted snapshot_blobs associations",
|
log.Debug("[Temp DB Cleanup] Deleted snapshot_blobs associations",
|
||||||
"count", rowsAffected)
|
"count", rowsAffected)
|
||||||
|
|
||||||
// Delete the mount points other snapshots recorded
|
|
||||||
query := "DELETE FROM snapshot_mount_points WHERE snapshot_id != ?"
|
|
||||||
database.LogSQL("Execute", query, currentSnapshotID)
|
|
||||||
|
|
||||||
result, err = tx.ExecContext(ctx, query, currentSnapshotID)
|
|
||||||
if err != nil {
|
|
||||||
return fmt.Errorf("deleting orphaned snapshot_mount_points: %w", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
rowsAffected, _ = result.RowsAffected()
|
|
||||||
log.Debug("[Temp DB Cleanup] Deleted snapshot_mount_points rows",
|
|
||||||
"count", rowsAffected)
|
|
||||||
|
|
||||||
return nil
|
return nil
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -7,14 +7,12 @@ import (
|
|||||||
"database/sql"
|
"database/sql"
|
||||||
"io"
|
"io"
|
||||||
"path/filepath"
|
"path/filepath"
|
||||||
"slices"
|
|
||||||
"testing"
|
"testing"
|
||||||
|
|
||||||
"github.com/spf13/afero"
|
"github.com/spf13/afero"
|
||||||
"sneak.berlin/go/vaultik/internal/config"
|
"sneak.berlin/go/vaultik/internal/config"
|
||||||
"sneak.berlin/go/vaultik/internal/database"
|
"sneak.berlin/go/vaultik/internal/database"
|
||||||
"sneak.berlin/go/vaultik/internal/log"
|
"sneak.berlin/go/vaultik/internal/log"
|
||||||
"sneak.berlin/go/vaultik/internal/types"
|
|
||||||
)
|
)
|
||||||
|
|
||||||
const (
|
const (
|
||||||
@@ -389,77 +387,6 @@ func TestCleanSnapshotDBNonExistentSnapshot(t *testing.T) {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
// The exported metadata database keeps only the mount points that the
|
|
||||||
// exported snapshot recorded. See
|
|
||||||
// https://git.eeqj.de/sneak/vaultik/issues/395.
|
|
||||||
func TestCleanSnapshotDBKeepsOnlyTheSnapshotsMountPoints(t *testing.T) {
|
|
||||||
log.Initialize(log.Config{})
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
ctx := context.Background()
|
|
||||||
dbPath := filepath.Join(t.TempDir(), "export.db")
|
|
||||||
|
|
||||||
db, err := database.New(ctx, dbPath)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to create database: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
repos := database.NewRepositories(db)
|
|
||||||
|
|
||||||
for _, id := range []types.SnapshotID{"exported", "other"} {
|
|
||||||
err = repos.Snapshots.Create(ctx, nil, &database.Snapshot{ID: id})
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to create snapshot: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
err = repos.Snapshots.AddMountPoint(ctx, nil, id.String(), "/data/"+id.String())
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to add mount point: %v", err)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
err = db.Close()
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to close database: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
sm := &SnapshotManager{
|
|
||||||
config: &config.Config{
|
|
||||||
CompressionLevel: 3,
|
|
||||||
AgeRecipients: []string{testAgeRecipient},
|
|
||||||
},
|
|
||||||
fs: afero.NewOsFs(),
|
|
||||||
}
|
|
||||||
|
|
||||||
_, err = sm.cleanSnapshotDB(ctx, dbPath, "exported")
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to clean snapshot database: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
cleaned, err := database.New(ctx, dbPath)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to open cleaned database: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
defer func() { _ = cleaned.Close() }()
|
|
||||||
|
|
||||||
cleanedRepos := database.NewRepositories(cleaned)
|
|
||||||
|
|
||||||
for id, want := range map[string][]string{
|
|
||||||
"exported": {"/data/exported"},
|
|
||||||
"other": nil,
|
|
||||||
} {
|
|
||||||
got, err := cleanedRepos.Snapshots.GetMountPoints(ctx, id)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("failed to read mount points: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
if !slices.Equal(got, want) {
|
|
||||||
t.Errorf("mount points of %s: got %v, want %v", id, got, want)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Two creates of one snapshot name back to back start within one second,
|
// Two creates of one snapshot name back to back start within one second,
|
||||||
// the resolution of the timestamp in a snapshot ID. See
|
// the resolution of the timestamp in a snapshot ID. See
|
||||||
// https://git.eeqj.de/sneak/vaultik/issues/270.
|
// https://git.eeqj.de/sneak/vaultik/issues/270.
|
||||||
|
|||||||
@@ -2,17 +2,15 @@
|
|||||||
// faults on demand, so tests can reproduce the failure modes a real
|
// faults on demand, so tests can reproduce the failure modes a real
|
||||||
// backend exhibits: an upload that fails partway, a backend that reports
|
// backend exhibits: an upload that fails partway, a backend that reports
|
||||||
// success while storing nothing, reads that return corrupt or truncated
|
// success while storing nothing, reads that return corrupt or truncated
|
||||||
// bytes, and a delete or a stat the backend refuses. It is the seam
|
// bytes, and a delete the backend refuses. It is the seam called for by
|
||||||
// called for by the fault-injection tests (sneak/vaultik issue 72) and
|
// the fault-injection tests (sneak/vaultik issue 72) and is meant to be
|
||||||
// is meant to be reused by future tests rather than re-implemented per
|
// reused by future tests rather than re-implemented per case.
|
||||||
// case.
|
|
||||||
//
|
//
|
||||||
// The wrapper delegates every method to the inner Storer. Four hooks
|
// The wrapper delegates every method to the inner Storer. Three hooks
|
||||||
// change that: OnPut decides the fate of each write, OnGet decides how
|
// change that: OnPut decides the fate of each write, OnGet decides how
|
||||||
// each read's bytes are returned, OnDelete decides whether each delete
|
// each read's bytes are returned, and OnDelete decides whether each
|
||||||
// fails, and OnStat whether each stat fails. All are keyed by the object
|
// delete fails. All are keyed by the object key, so a test can fault
|
||||||
// key, so a test can fault only blobs, only metadata, or a single
|
// only blobs, only metadata, or a single object.
|
||||||
// object.
|
|
||||||
package faultstore
|
package faultstore
|
||||||
|
|
||||||
import (
|
import (
|
||||||
@@ -32,11 +30,6 @@ var ErrInjectedUpload = errors.New("faultstore: injected upload failure")
|
|||||||
// fail.
|
// fail.
|
||||||
var ErrInjectedDelete = errors.New("faultstore: injected delete failure")
|
var ErrInjectedDelete = errors.New("faultstore: injected delete failure")
|
||||||
|
|
||||||
// ErrInjectedStat is returned by a Stat the OnStat hook chose to fail.
|
|
||||||
// It is not storage.ErrNotFound: the backend refused the request, as S3
|
|
||||||
// refuses a HEAD to credentials that allow only PUT.
|
|
||||||
var ErrInjectedStat = errors.New("faultstore: injected stat failure")
|
|
||||||
|
|
||||||
// PutAction is the disposition OnPut assigns to a write.
|
// PutAction is the disposition OnPut assigns to a write.
|
||||||
type PutAction int
|
type PutAction int
|
||||||
|
|
||||||
@@ -83,10 +76,6 @@ type Storer struct {
|
|||||||
// object key. Returning true fails the delete and leaves the object
|
// object key. Returning true fails the delete and leaves the object
|
||||||
// in place.
|
// in place.
|
||||||
OnDelete func(key string) bool
|
OnDelete func(key string) bool
|
||||||
|
|
||||||
// OnStat, when set, is consulted before every Stat with the object
|
|
||||||
// key. Returning true fails the stat with ErrInjectedStat.
|
|
||||||
OnStat func(key string) bool
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// New wraps inner. inner must be non-nil.
|
// New wraps inner. inner must be non-nil.
|
||||||
@@ -170,12 +159,8 @@ func damage(fault GetFault, data []byte) []byte {
|
|||||||
return out
|
return out
|
||||||
}
|
}
|
||||||
|
|
||||||
// Stat returns the object's info unless OnStat fails the stat.
|
// Stat delegates unchanged.
|
||||||
func (f *Storer) Stat(ctx context.Context, key string) (*storage.ObjectInfo, error) {
|
func (f *Storer) Stat(ctx context.Context, key string) (*storage.ObjectInfo, error) {
|
||||||
if f.OnStat != nil && f.OnStat(key) {
|
|
||||||
return nil, fmt.Errorf("%w for %q", ErrInjectedStat, key)
|
|
||||||
}
|
|
||||||
|
|
||||||
return f.inner.Stat(ctx, key)
|
return f.inner.Stat(ctx, key)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -100,9 +100,8 @@ func TestS3StorerMissingKeyMapsToErrNotFound(t *testing.T) {
|
|||||||
// TestS3ListingCutShortIsAnError checks that List and ListStream fail on a
|
// TestS3ListingCutShortIsAnError checks that List and ListStream fail on a
|
||||||
// listing page marked truncated that carries no continuation token, as a
|
// listing page marked truncated that carries no continuation token, as a
|
||||||
// server answering V2 listings V1-style sends it. Taken as the last page,
|
// server answering V2 listings V1-style sends it. Taken as the last page,
|
||||||
// it would hide every later key: prune would treat the blobs of the
|
// it would hide every later key, and prune would treat the blobs of the
|
||||||
// snapshots listed there as unreferenced, and a directory under metadata/
|
// snapshots listed there as unreferenced.
|
||||||
// whose manifest is listed there as one with no manifest.
|
|
||||||
func TestS3ListingCutShortIsAnError(t *testing.T) {
|
func TestS3ListingCutShortIsAnError(t *testing.T) {
|
||||||
t.Parallel()
|
t.Parallel()
|
||||||
|
|
||||||
@@ -161,7 +160,7 @@ func TestS3ListingCutShortIsAnError(t *testing.T) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// TestS3URLPrefixKeyLayout pins the bucket keys an s3:// URL reads and
|
// TestS3URLPrefixKeyLayout pins the bucket keys an s3:// URL reads and
|
||||||
// writes: the layout in docs/REPOSTRUCTURE.md, with the prefix joined to
|
// writes: the README's remote storage layout, with the prefix joined to
|
||||||
// each key by one "/". s3://b/p and s3://b/p/ must be the same
|
// each key by one "/". s3://b/p and s3://b/p/ must be the same
|
||||||
// destination, or a host that writes the URL the other way finds no
|
// destination, or a host that writes the URL the other way finds no
|
||||||
// snapshots. The listed object is put straight into the bucket, as
|
// snapshots. The listed object is put straight into the bucket, as
|
||||||
|
|||||||
@@ -5,16 +5,14 @@ import (
|
|||||||
"fmt"
|
"fmt"
|
||||||
"strings"
|
"strings"
|
||||||
|
|
||||||
"sneak.berlin/go/vaultik/internal/log"
|
|
||||||
"sneak.berlin/go/vaultik/internal/storage"
|
"sneak.berlin/go/vaultik/internal/storage"
|
||||||
)
|
)
|
||||||
|
|
||||||
// destinationMarkerKey is the object every backup writes at the root of
|
// destinationMarkerKey is the object every backup writes at the root of
|
||||||
// the backup destination store. While the local index holds a snapshot
|
// the backup destination store. While the local index holds a snapshot
|
||||||
// stored there, a destination that answers a look-up of it with not
|
// stored there, a destination without it is treated as not present: an
|
||||||
// found is treated as not present: an unplugged volume leaves an empty
|
// unplugged volume leaves an empty directory at its mount point, which
|
||||||
// directory at its mount point, which would otherwise read as a store
|
// would otherwise read as a store whose snapshots are all gone.
|
||||||
// whose snapshots are all gone.
|
|
||||||
const destinationMarkerKey = "vaultik-destination.txt"
|
const destinationMarkerKey = "vaultik-destination.txt"
|
||||||
|
|
||||||
// destinationMarkerText is the whole content of the marker. It names no
|
// destinationMarkerText is the whole content of the marker. It names no
|
||||||
@@ -22,24 +20,16 @@ const destinationMarkerKey = "vaultik-destination.txt"
|
|||||||
const destinationMarkerText = "This is a vaultik backup destination store.\n"
|
const destinationMarkerText = "This is a vaultik backup destination store.\n"
|
||||||
|
|
||||||
// errDestinationNotPresent is returned when the local index holds a
|
// errDestinationNotPresent is returned when the local index holds a
|
||||||
// snapshot stored on the backup destination store and the store answers
|
// snapshot stored on the backup destination store and the store has no
|
||||||
// that it has no marker.
|
// marker.
|
||||||
var errDestinationNotPresent = errors.New("backup destination store is not present")
|
var errDestinationNotPresent = errors.New("backup destination store is not present")
|
||||||
|
|
||||||
// checkDestinationMarker returns errDestinationNotPresent when the local
|
// checkDestinationMarker returns errDestinationNotPresent when the local
|
||||||
// index holds a snapshot stored on the backup destination store and the
|
// index holds a snapshot stored on the backup destination store and the
|
||||||
// store answers that it has no marker. With no snapshot in the local
|
// store has no marker. With no snapshot in the local index, as on a
|
||||||
// index, as on a first backup or on another machine, there is nothing to
|
// first backup or on another machine, there is nothing to check; nor
|
||||||
// check; nor when the local index is bound to a different destination
|
// when the local index is bound to a different destination than the
|
||||||
// than the configured one, since its snapshots are stored there.
|
// configured one, since its snapshots are stored there.
|
||||||
//
|
|
||||||
// A look-up of the marker that fails for any other reason than not
|
|
||||||
// found is logged and otherwise ignored, because the check could not be
|
|
||||||
// made: S3 refuses it to credentials that allow only PUT, which is all
|
|
||||||
// a backup needs. The check exists for a file:// volume's empty mount
|
|
||||||
// point, which always answers not found, and a destination that cannot
|
|
||||||
// be reached fails on the next request made to it, such as the backup's
|
|
||||||
// PUT of the marker.
|
|
||||||
func (v *Vaultik) checkDestinationMarker() error {
|
func (v *Vaultik) checkDestinationMarker() error {
|
||||||
ids, err := v.localSnapshotIDs()
|
ids, err := v.localSnapshotIDs()
|
||||||
if err != nil {
|
if err != nil {
|
||||||
@@ -73,11 +63,8 @@ func (v *Vaultik) checkDestinationMarker() error {
|
|||||||
destinationMarkerKey)
|
destinationMarkerKey)
|
||||||
}
|
}
|
||||||
|
|
||||||
// Info, not a warning: --cron must stay silent on a successful
|
|
||||||
// backup from a host whose credentials allow only PUT.
|
|
||||||
if err != nil {
|
if err != nil {
|
||||||
log.Info("Could not check the backup destination store for its marker",
|
return fmt.Errorf("checking for %s: %w", destinationMarkerKey, err)
|
||||||
"key", destinationMarkerKey, "error", err)
|
|
||||||
}
|
}
|
||||||
|
|
||||||
return nil
|
return nil
|
||||||
|
|||||||
@@ -13,16 +13,15 @@ import (
|
|||||||
"sneak.berlin/go/vaultik/internal/database"
|
"sneak.berlin/go/vaultik/internal/database"
|
||||||
"sneak.berlin/go/vaultik/internal/log"
|
"sneak.berlin/go/vaultik/internal/log"
|
||||||
"sneak.berlin/go/vaultik/internal/storage"
|
"sneak.berlin/go/vaultik/internal/storage"
|
||||||
"sneak.berlin/go/vaultik/internal/storage/faultstore"
|
|
||||||
"sneak.berlin/go/vaultik/internal/vaultik"
|
"sneak.berlin/go/vaultik/internal/vaultik"
|
||||||
)
|
)
|
||||||
|
|
||||||
// These tests cover https://git.eeqj.de/sneak/vaultik/issues/239: a
|
// These tests cover https://git.eeqj.de/sneak/vaultik/issues/239: a
|
||||||
// file:// destination at a volume's mount point leaves an empty directory
|
// file:// destination at a volume's mount point leaves an empty directory
|
||||||
// behind when the volume is unplugged. While the local index holds
|
// behind when the volume is unplugged. While the local index holds
|
||||||
// snapshots, a destination that answers that it has no
|
// snapshots, a destination without vaultik-destination.txt is not present,
|
||||||
// vaultik-destination.txt is not present, so no command may write to it
|
// so no command may write to it or conclude from it that the local
|
||||||
// or conclude from it that the local snapshots are gone.
|
// snapshots are gone.
|
||||||
|
|
||||||
// markerFile is the name of the file a backup writes at the root of the
|
// markerFile is the name of the file a backup writes at the root of the
|
||||||
// destination.
|
// destination.
|
||||||
@@ -94,39 +93,6 @@ func TestBackupRefusesDestinationWithoutMarker(t *testing.T) {
|
|||||||
assertUntouched(ctx, t, repos, storeDir)
|
assertUntouched(ctx, t, repos, storeDir)
|
||||||
}
|
}
|
||||||
|
|
||||||
// TestBackupGoesOnWhenMarkerCannotBeChecked checks that a backup goes on
|
|
||||||
// and writes the marker when looking it up fails with an error other
|
|
||||||
// than not found, as S3 answers credentials that allow only PUT
|
|
||||||
// (https://git.eeqj.de/sneak/vaultik/issues/389), and that a marker
|
|
||||||
// that is not found still stops it.
|
|
||||||
func TestBackupGoesOnWhenMarkerCannotBeChecked(t *testing.T) {
|
|
||||||
log.Initialize(log.Config{})
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
ctx := context.Background()
|
|
||||||
storeDir := t.TempDir()
|
|
||||||
v, repos, _ := backUpToFileDestination(ctx, t, storeDir)
|
|
||||||
|
|
||||||
// Removed so the test sees the backup write it again: with the
|
|
||||||
// look-up failing, the backup cannot tell that it is gone.
|
|
||||||
markerPath := filepath.Join(storeDir, markerFile)
|
|
||||||
require.NoError(t, os.Remove(markerPath))
|
|
||||||
|
|
||||||
store := faultstore.New(v.Storage)
|
|
||||||
store.OnStat = func(key string) bool { return key == markerFile }
|
|
||||||
v.Storage = store
|
|
||||||
|
|
||||||
require.NoError(t, backUp(v, "second"))
|
|
||||||
localSnapshotID(ctx, t, repos, "second")
|
|
||||||
assert.FileExists(t, markerPath)
|
|
||||||
|
|
||||||
require.NoError(t, os.Remove(markerPath))
|
|
||||||
|
|
||||||
store.OnStat = nil
|
|
||||||
|
|
||||||
require.ErrorContains(t, backUp(v, "third"), markerFile)
|
|
||||||
}
|
|
||||||
|
|
||||||
// TestBackupChecksMarkerBeforeDroppingIncompleteSnapshots checks that
|
// TestBackupChecksMarkerBeforeDroppingIncompleteSnapshots checks that
|
||||||
// snapshot create writes nothing when the local index holds only an
|
// snapshot create writes nothing when the local index holds only an
|
||||||
// incomplete snapshot and the destination has no marker. The backup drops
|
// incomplete snapshot and the destination has no marker. The backup drops
|
||||||
|
|||||||
@@ -679,7 +679,6 @@ func faultScannerFactory(
|
|||||||
Exclude: params.Exclude,
|
Exclude: params.Exclude,
|
||||||
SkipErrors: params.SkipErrors,
|
SkipErrors: params.SkipErrors,
|
||||||
PreviousSnapshotID: params.PreviousSnapshotID,
|
PreviousSnapshotID: params.PreviousSnapshotID,
|
||||||
DeviceNumber: params.DeviceNumber,
|
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -76,7 +76,7 @@ func TestNukeRemoteLeavesNoFiles(t *testing.T) {
|
|||||||
// TestNukeRemoteFailsWhenADeleteFails checks that remote nuke returns an
|
// TestNukeRemoteFailsWhenADeleteFails checks that remote nuke returns an
|
||||||
// error when a snapshot's metadata or a blob cannot be deleted, does not
|
// error when a snapshot's metadata or a blob cannot be deleted, does not
|
||||||
// report the store empty, and advises running nuke again: prune deletes
|
// report the store empty, and advises running nuke again: prune deletes
|
||||||
// no snapshot metadata that has its manifest.
|
// no metadata.
|
||||||
func TestNukeRemoteFailsWhenADeleteFails(t *testing.T) {
|
func TestNukeRemoteFailsWhenADeleteFails(t *testing.T) {
|
||||||
log.Initialize(log.Config{})
|
log.Initialize(log.Config{})
|
||||||
t.Parallel()
|
t.Parallel()
|
||||||
|
|||||||
+11
-14
@@ -66,8 +66,8 @@ func (v *Vaultik) NukeRemote(force bool) error {
|
|||||||
|
|
||||||
// Checked before anything is deleted: running nuke again would fail
|
// Checked before anything is deleted: running nuke again would fail
|
||||||
// the same way, so the advice below must not follow these errors.
|
// the same way, so the advice below must not follow these errors.
|
||||||
// The listing also fails on a destination that answers that it has
|
// The listing also fails on a destination without the marker while
|
||||||
// no marker while the local index holds snapshots.
|
// the local index holds snapshots.
|
||||||
err := v.EnsureStorageBinding()
|
err := v.EnsureStorageBinding()
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return err
|
return err
|
||||||
@@ -184,13 +184,12 @@ type PruneBlobsResult struct {
|
|||||||
MetadataDirsFailed int `json:"metadata_dirs_failed,omitempty"`
|
MetadataDirsFailed int `json:"metadata_dirs_failed,omitempty"`
|
||||||
}
|
}
|
||||||
|
|
||||||
// Prune removes orphaned data from the local index database AND, from the
|
// Prune removes orphaned data from the local index database AND
|
||||||
// backup destination store, unreferenced blobs and the directories under
|
// unreferenced blobs from the backup destination store. This is the
|
||||||
// metadata/ with no manifest. This is the single user-facing prune entry
|
// single user-facing prune entry point — the split between local and
|
||||||
// point — the split between local and remote cleanup is an
|
// remote cleanup is an implementation detail. Calling code should
|
||||||
// implementation detail. Calling code should prefer this method over
|
// prefer this method over PruneDatabase or PruneBlobs individually
|
||||||
// PruneDatabase or PruneBlobs individually unless it specifically wants
|
// unless it specifically wants one half.
|
||||||
// one half.
|
|
||||||
func (v *Vaultik) Prune(opts *PruneOptions) error {
|
func (v *Vaultik) Prune(opts *PruneOptions) error {
|
||||||
err := v.EnsureStorageBinding()
|
err := v.EnsureStorageBinding()
|
||||||
if err != nil {
|
if err != nil {
|
||||||
@@ -297,11 +296,9 @@ func (v *Vaultik) PruneBlobs(opts *PruneOptions) error {
|
|||||||
return errors.Join(failures...)
|
return errors.Join(failures...)
|
||||||
}
|
}
|
||||||
|
|
||||||
// confirmPrune states what prune found to delete, unreferenced blobs and
|
// confirmPrune states what prune found to delete, naming each directory
|
||||||
// directories under metadata/ with no manifest, naming each directory by
|
// under metadata/ by its remote key, and, unless --force or --json is
|
||||||
// its remote key, and, unless --force is given, asks the operator to
|
// given, asks the operator to confirm. It reports whether to go ahead.
|
||||||
// confirm. Under --json it prints nothing and does not ask. It reports
|
|
||||||
// whether to go ahead.
|
|
||||||
func (v *Vaultik) confirmPrune(
|
func (v *Vaultik) confirmPrune(
|
||||||
opts *PruneOptions, blobCount int, blobsSize int64, dirs []string,
|
opts *PruneOptions, blobCount int, blobsSize int64, dirs []string,
|
||||||
) bool {
|
) bool {
|
||||||
|
|||||||
@@ -24,9 +24,8 @@ import (
|
|||||||
|
|
||||||
// TestPruneDuringBackupKeepsItsBlobs runs a prune from another host
|
// TestPruneDuringBackupKeepsItsBlobs runs a prune from another host
|
||||||
// sharing the destination store at the moment a backup has uploaded its
|
// sharing the destination store at the moment a backup has uploaded its
|
||||||
// blobs and its db.zst.age but not yet its manifest, so no manifest lists
|
// blobs but not yet its manifest, so no manifest lists those blobs. The
|
||||||
// those blobs. The prune must leave the blobs and the db.zst.age, and the
|
// prune must leave them, and the backup must then restore.
|
||||||
// backup must then restore.
|
|
||||||
func TestPruneDuringBackupKeepsItsBlobs(t *testing.T) {
|
func TestPruneDuringBackupKeepsItsBlobs(t *testing.T) {
|
||||||
log.Initialize(log.Config{})
|
log.Initialize(log.Config{})
|
||||||
t.Parallel()
|
t.Parallel()
|
||||||
@@ -80,8 +79,7 @@ func TestPruneDuringBackupKeepsItsBlobs(t *testing.T) {
|
|||||||
SnapshotID: id,
|
SnapshotID: id,
|
||||||
TargetDir: restoreDir,
|
TargetDir: restoreDir,
|
||||||
Verify: true,
|
Verify: true,
|
||||||
}), "a prune during the backup must not delete the backup's blobs "+
|
}), "a prune during the backup must not delete the backup's blobs")
|
||||||
"or its db.zst.age")
|
|
||||||
|
|
||||||
assertRestoredTree(t, fs, restoreDir, testFiles)
|
assertRestoredTree(t, fs, restoreDir, testFiles)
|
||||||
}
|
}
|
||||||
|
|||||||
+35
-189
@@ -7,7 +7,6 @@ import (
|
|||||||
"os"
|
"os"
|
||||||
"path/filepath"
|
"path/filepath"
|
||||||
"regexp"
|
"regexp"
|
||||||
"slices"
|
|
||||||
"sort"
|
"sort"
|
||||||
"strconv"
|
"strconv"
|
||||||
"strings"
|
"strings"
|
||||||
@@ -45,25 +44,6 @@ var ErrPostBackupPruneFailed = errors.New("post-backup prune failed")
|
|||||||
// kept, so the caller can report it apart from a failed backup.
|
// kept, so the caller can report it apart from a failed backup.
|
||||||
var ErrFilesUnreadable = errors.New("file(s) could not be read")
|
var ErrFilesUnreadable = errors.New("file(s) could not be read")
|
||||||
|
|
||||||
// ErrSourcePathEmpty is returned when --prune skipped the post-backup
|
|
||||||
// prune because the scan found nothing in a configured path of a
|
|
||||||
// snapshot, as in the mount point of a volume that is not mounted. The
|
|
||||||
// snapshots are complete and kept, so the caller can report it apart
|
|
||||||
// from a failed backup. A run that also skipped unreadable files
|
|
||||||
// returns ErrFilesUnreadable instead.
|
|
||||||
var ErrSourcePathEmpty = errors.New("source path(s) were empty")
|
|
||||||
|
|
||||||
// ErrVolumeNotMounted is returned when --prune skipped the post-backup
|
|
||||||
// prune because a directory that an earlier snapshot of the same name
|
|
||||||
// found as a mount point was not found as one in this run: the volume
|
|
||||||
// mounted there is not mounted, the run found no entry in it, or the
|
|
||||||
// directory is no longer backed up. The snapshots are complete and
|
|
||||||
// kept, so the caller can report it apart from a failed backup. A run
|
|
||||||
// that also skipped unreadable files or found a configured path empty
|
|
||||||
// returns ErrFilesUnreadable or ErrSourcePathEmpty instead.
|
|
||||||
var ErrVolumeNotMounted = errors.New(
|
|
||||||
"mount point(s) an earlier snapshot recorded were not found")
|
|
||||||
|
|
||||||
// listRecentLimit caps how many snapshot rows are fetched from the
|
// listRecentLimit caps how many snapshot rows are fetched from the
|
||||||
// local index for listing and purge operations.
|
// local index for listing and purge operations.
|
||||||
const listRecentLimit = 10000
|
const listRecentLimit = 10000
|
||||||
@@ -154,10 +134,17 @@ func (v *Vaultik) CreateSnapshot(opts *SnapshotCreateOptions) error {
|
|||||||
return err
|
return err
|
||||||
}
|
}
|
||||||
|
|
||||||
filesUnreadable, emptyPaths, unmountedPaths, err := v.createNamedSnapshots(
|
// Process each named snapshot
|
||||||
opts, hostname, snapshotNames)
|
filesUnreadable := 0
|
||||||
if err != nil {
|
|
||||||
return err
|
for snapIdx, snapName := range snapshotNames {
|
||||||
|
unreadable, err := v.createNamedSnapshot(
|
||||||
|
opts, hostname, snapName, snapIdx+1, len(snapshotNames))
|
||||||
|
if err != nil {
|
||||||
|
return err
|
||||||
|
}
|
||||||
|
|
||||||
|
filesUnreadable += unreadable
|
||||||
}
|
}
|
||||||
|
|
||||||
// Print overall summary if multiple snapshots
|
// Print overall summary if multiple snapshots
|
||||||
@@ -167,10 +154,13 @@ func (v *Vaultik) CreateSnapshot(opts *SnapshotCreateOptions) error {
|
|||||||
}
|
}
|
||||||
|
|
||||||
switch {
|
switch {
|
||||||
case opts.Prune && (filesUnreadable > 0 || len(emptyPaths) > 0 ||
|
case opts.Prune && filesUnreadable > 0:
|
||||||
len(unmountedPaths) > 0):
|
// An older snapshot may be the only one that still holds a file
|
||||||
return v.skipPostBackupPrune(
|
// this run could not read.
|
||||||
filesUnreadable, emptyPaths, unmountedPaths)
|
log.Warn("Skipping post-backup prune",
|
||||||
|
"files_unreadable", filesUnreadable)
|
||||||
|
v.UI.Warningf("Skipped the post-backup prune because %d file(s) "+
|
||||||
|
"could not be read; older snapshots are kept.", filesUnreadable)
|
||||||
case opts.Prune:
|
case opts.Prune:
|
||||||
err = v.runPostBackupPrune(snapshotNames, opts.KeepNewerThan)
|
err = v.runPostBackupPrune(snapshotNames, opts.KeepNewerThan)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
@@ -181,84 +171,6 @@ func (v *Vaultik) CreateSnapshot(opts *SnapshotCreateOptions) error {
|
|||||||
return v.finishCreateSnapshot(filesUnreadable)
|
return v.finishCreateSnapshot(filesUnreadable)
|
||||||
}
|
}
|
||||||
|
|
||||||
// createNamedSnapshots creates each named snapshot in turn. It returns
|
|
||||||
// the number of entries --skip-errors skipped because it could not read
|
|
||||||
// or list them, each configured path in which the scan found nothing,
|
|
||||||
// and, under --prune, each directory where an earlier snapshot found a
|
|
||||||
// volume mounted and this run did not, the paths named with their
|
|
||||||
// snapshot.
|
|
||||||
func (v *Vaultik) createNamedSnapshots(
|
|
||||||
opts *SnapshotCreateOptions, hostname string, snapshotNames []string,
|
|
||||||
) (int, []string, []string, error) {
|
|
||||||
filesUnreadable := 0
|
|
||||||
|
|
||||||
var emptyPaths, unmountedPaths []string
|
|
||||||
|
|
||||||
for snapIdx, snapName := range snapshotNames {
|
|
||||||
stats, err := v.createNamedSnapshot(
|
|
||||||
opts, hostname, snapName, snapIdx+1, len(snapshotNames))
|
|
||||||
if err != nil {
|
|
||||||
return 0, nil, nil, err
|
|
||||||
}
|
|
||||||
|
|
||||||
filesUnreadable += stats.totalFilesUnreadable
|
|
||||||
|
|
||||||
for _, dir := range stats.emptyPaths {
|
|
||||||
emptyPaths = append(emptyPaths, dir+" of snapshot "+snapName)
|
|
||||||
}
|
|
||||||
|
|
||||||
for _, dir := range stats.unmountedPaths {
|
|
||||||
unmountedPaths = append(unmountedPaths,
|
|
||||||
dir+" of snapshot "+snapName)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return filesUnreadable, emptyPaths, unmountedPaths, nil
|
|
||||||
}
|
|
||||||
|
|
||||||
// skipPostBackupPrune says why the post-backup prune does not run, naming
|
|
||||||
// every cause, and returns the error the run ends with. An older snapshot
|
|
||||||
// may be the only one that still holds a file this run could not read,
|
|
||||||
// or what an empty path or a volume that is not mounted held. The
|
|
||||||
// previous snapshot is no guide: after one such run it lacks them too.
|
|
||||||
func (v *Vaultik) skipPostBackupPrune(
|
|
||||||
filesUnreadable int, emptyPaths, unmountedPaths []string,
|
|
||||||
) error {
|
|
||||||
log.Warn("Skipping post-backup prune",
|
|
||||||
"files_unreadable", filesUnreadable, "empty_paths", emptyPaths,
|
|
||||||
"unmounted_paths", unmountedPaths)
|
|
||||||
|
|
||||||
if len(emptyPaths) > 0 {
|
|
||||||
v.UI.Warningf("Skipped the post-backup prune because nothing was "+
|
|
||||||
"found in %s; older snapshots are kept.",
|
|
||||||
strings.Join(emptyPaths, ", "))
|
|
||||||
}
|
|
||||||
|
|
||||||
if len(unmountedPaths) > 0 {
|
|
||||||
v.UI.Warningf("Skipped the post-backup prune because this backup "+
|
|
||||||
"did not find a mount point at %s, where an earlier snapshot "+
|
|
||||||
"found one: the volume is not mounted, this backup found no "+
|
|
||||||
"entry in it, or the directory is no longer backed up. Older "+
|
|
||||||
"snapshots are kept. Mount the volume again, or, if that is on "+
|
|
||||||
"purpose, remove the older snapshots by hand with "+
|
|
||||||
"'vaultik snapshot purge'.",
|
|
||||||
strings.Join(unmountedPaths, ", "))
|
|
||||||
}
|
|
||||||
|
|
||||||
if filesUnreadable > 0 {
|
|
||||||
v.UI.Warningf("Skipped the post-backup prune because %d file(s) "+
|
|
||||||
"could not be read; older snapshots are kept.", filesUnreadable)
|
|
||||||
|
|
||||||
return fmt.Errorf("%d %w", filesUnreadable, ErrFilesUnreadable)
|
|
||||||
}
|
|
||||||
|
|
||||||
if len(emptyPaths) > 0 {
|
|
||||||
return fmt.Errorf("%d %w", len(emptyPaths), ErrSourcePathEmpty)
|
|
||||||
}
|
|
||||||
|
|
||||||
return fmt.Errorf("%d %w", len(unmountedPaths), ErrVolumeNotMounted)
|
|
||||||
}
|
|
||||||
|
|
||||||
// finishCreateSnapshot ends a run whose snapshots are all complete and
|
// finishCreateSnapshot ends a run whose snapshots are all complete and
|
||||||
// kept. Like finishRestore, it returns an error when --skip-errors
|
// kept. Like finishRestore, it returns an error when --skip-errors
|
||||||
// skipped anything it could not read or list; otherwise it prints the
|
// skipped anything it could not read or list; otherwise it prints the
|
||||||
@@ -307,10 +219,9 @@ func (v *Vaultik) snapshotNamesToCreate(requested []string) ([]string, error) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// runPostBackupPrune drops older snapshots of the given names and removes
|
// runPostBackupPrune drops older snapshots of the given names and removes
|
||||||
// from remote storage the orphan blobs and the directories under
|
// orphan blobs from remote storage. If keepNewerThan is set (e.g. "4w"),
|
||||||
// metadata/ with no manifest, as PruneBlobs does. If keepNewerThan is set
|
// snapshots newer than that duration are kept. Otherwise only the latest
|
||||||
// (e.g. "4w"), snapshots newer than that duration are kept. Otherwise only
|
// snapshot of each name is kept.
|
||||||
// the latest snapshot of each name is kept.
|
|
||||||
func (v *Vaultik) runPostBackupPrune(
|
func (v *Vaultik) runPostBackupPrune(
|
||||||
snapshotNames []string, keepNewerThan string,
|
snapshotNames []string, keepNewerThan string,
|
||||||
) error {
|
) error {
|
||||||
@@ -337,7 +248,7 @@ func (v *Vaultik) runPostBackupPrune(
|
|||||||
|
|
||||||
err = v.PruneBlobs(&PruneOptions{Force: true})
|
err = v.PruneBlobs(&PruneOptions{Force: true})
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return fmt.Errorf("pruning the destination store: %w", err)
|
return fmt.Errorf("pruning orphaned blobs: %w", err)
|
||||||
}
|
}
|
||||||
|
|
||||||
return nil
|
return nil
|
||||||
@@ -363,13 +274,6 @@ type snapshotStats struct {
|
|||||||
// could not be read or listed.
|
// could not be read or listed.
|
||||||
totalFilesUnreadable int
|
totalFilesUnreadable int
|
||||||
|
|
||||||
// The configured paths in which the scan found nothing.
|
|
||||||
emptyPaths []string
|
|
||||||
|
|
||||||
// Under --prune, the directories where an earlier snapshot of the
|
|
||||||
// same name found a volume mounted and this one did not.
|
|
||||||
unmountedPaths []string
|
|
||||||
|
|
||||||
// The sizes of all blobs the snapshot references, set by
|
// The sizes of all blobs the snapshot references, set by
|
||||||
// finalizeSnapshotMetadata once snapshot_blobs is populated.
|
// finalizeSnapshotMetadata once snapshot_blobs is populated.
|
||||||
blobSize int64
|
blobSize int64
|
||||||
@@ -377,10 +281,11 @@ type snapshotStats struct {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// createNamedSnapshot creates a single named snapshot and returns the
|
// createNamedSnapshot creates a single named snapshot and returns the
|
||||||
// statistics of its scan.
|
// number of entries --skip-errors skipped because it could not read or
|
||||||
|
// list them.
|
||||||
func (v *Vaultik) createNamedSnapshot(
|
func (v *Vaultik) createNamedSnapshot(
|
||||||
opts *SnapshotCreateOptions, hostname, snapName string, idx, total int,
|
opts *SnapshotCreateOptions, hostname, snapName string, idx, total int,
|
||||||
) (*snapshotStats, error) {
|
) (int, error) {
|
||||||
snapshotStartTime := time.Now()
|
snapshotStartTime := time.Now()
|
||||||
|
|
||||||
if total > 1 {
|
if total > 1 {
|
||||||
@@ -389,12 +294,12 @@ func (v *Vaultik) createNamedSnapshot(
|
|||||||
|
|
||||||
resolvedDirs, err := v.resolveSnapshotPaths(snapName)
|
resolvedDirs, err := v.resolveSnapshotPaths(snapName)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return nil, err
|
return 0, err
|
||||||
}
|
}
|
||||||
|
|
||||||
previousSnapshotID, err := v.previousSnapshotID(snapName)
|
previousSnapshotID, err := v.previousSnapshotID(snapName)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return nil, err
|
return 0, err
|
||||||
}
|
}
|
||||||
|
|
||||||
scanner := v.ScannerFactory(snapshot.ScannerParams{
|
scanner := v.ScannerFactory(snapshot.ScannerParams{
|
||||||
@@ -409,7 +314,7 @@ func (v *Vaultik) createNamedSnapshot(
|
|||||||
snapshotID, err := v.SnapshotManager.CreateSnapshotWithName(
|
snapshotID, err := v.SnapshotManager.CreateSnapshotWithName(
|
||||||
v.ctx, hostname, snapName, v.Globals.Version, v.Globals.Commit)
|
v.ctx, hostname, snapName, v.Globals.Version, v.Globals.Commit)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return nil, fmt.Errorf("creating snapshot: %w", err)
|
return 0, fmt.Errorf("creating snapshot: %w", err)
|
||||||
}
|
}
|
||||||
|
|
||||||
log.Info("Beginning snapshot", "snapshot_id", snapshotID, "name", snapName)
|
log.Info("Beginning snapshot", "snapshot_id", snapshotID, "name", snapName)
|
||||||
@@ -417,12 +322,12 @@ func (v *Vaultik) createNamedSnapshot(
|
|||||||
|
|
||||||
stats, err := v.scanAllDirectories(scanner, resolvedDirs, snapshotID)
|
stats, err := v.scanAllDirectories(scanner, resolvedDirs, snapshotID)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return nil, err
|
return 0, err
|
||||||
}
|
}
|
||||||
|
|
||||||
err = v.finalizeSnapshotMetadata(snapshotID, stats)
|
err = v.finalizeSnapshotMetadata(snapshotID, stats)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return nil, err
|
return 0, err
|
||||||
}
|
}
|
||||||
|
|
||||||
log.Info("Snapshot complete",
|
log.Info("Snapshot complete",
|
||||||
@@ -435,55 +340,7 @@ func (v *Vaultik) createNamedSnapshot(
|
|||||||
|
|
||||||
v.printSnapshotSummary(snapshotID, snapshotStartTime, stats)
|
v.printSnapshotSummary(snapshotID, snapshotStartTime, stats)
|
||||||
|
|
||||||
if opts.Prune {
|
return stats.totalFilesUnreadable, nil
|
||||||
stats.unmountedPaths, err = v.findUnmountedPaths(snapName, snapshotID)
|
|
||||||
if err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return stats, nil
|
|
||||||
}
|
|
||||||
|
|
||||||
// findUnmountedPaths returns each directory that an earlier snapshot
|
|
||||||
// named snapName in the local index recorded as a mount point and
|
|
||||||
// snapshot snapshotID did not, as when the volume mounted there is not
|
|
||||||
// mounted.
|
|
||||||
func (v *Vaultik) findUnmountedPaths(
|
|
||||||
snapName, snapshotID string,
|
|
||||||
) ([]string, error) {
|
|
||||||
found, err := v.Repositories.Snapshots.GetMountPoints(v.ctx, snapshotID)
|
|
||||||
if err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
|
|
||||||
snapshots, err := v.Repositories.Snapshots.ListRecent(v.ctx, listRecentLimit)
|
|
||||||
if err != nil {
|
|
||||||
return nil, fmt.Errorf("listing snapshots: %w", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
var unmounted []string
|
|
||||||
|
|
||||||
for _, s := range snapshots {
|
|
||||||
if s.ID.String() == snapshotID ||
|
|
||||||
parseSnapshotName(s.ID.String(), s.Hostname.String()) != snapName {
|
|
||||||
continue
|
|
||||||
}
|
|
||||||
|
|
||||||
recorded, err := v.Repositories.Snapshots.GetMountPoints(
|
|
||||||
v.ctx, s.ID.String())
|
|
||||||
if err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
|
|
||||||
for _, dir := range recorded {
|
|
||||||
if !slices.Contains(found, dir) && !slices.Contains(unmounted, dir) {
|
|
||||||
unmounted = append(unmounted, dir)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return unmounted, nil
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// previousSnapshotID returns the ID of the most recent completed snapshot
|
// previousSnapshotID returns the ID of the most recent completed snapshot
|
||||||
@@ -505,8 +362,7 @@ func (v *Vaultik) previousSnapshotID(snapName string) (string, error) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// resolveSnapshotPaths resolves source directories to absolute paths
|
// resolveSnapshotPaths resolves source directories to absolute paths
|
||||||
// with symlink resolution. A path that is a symlink whose target does
|
// with symlink resolution.
|
||||||
// not exist is an error.
|
|
||||||
func (v *Vaultik) resolveSnapshotPaths(snapName string) ([]string, error) {
|
func (v *Vaultik) resolveSnapshotPaths(snapName string) ([]string, error) {
|
||||||
snapConfig := v.Config.Snapshots[snapName]
|
snapConfig := v.Config.Snapshots[snapName]
|
||||||
resolvedDirs := make([]string, 0, len(snapConfig.Paths))
|
resolvedDirs := make([]string, 0, len(snapConfig.Paths))
|
||||||
@@ -519,18 +375,12 @@ func (v *Vaultik) resolveSnapshotPaths(snapName string) ([]string, error) {
|
|||||||
|
|
||||||
resolvedPath, err := filepath.EvalSymlinks(absPath)
|
resolvedPath, err := filepath.EvalSymlinks(absPath)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
// A path that does not exist is left for the scan to report.
|
if os.IsNotExist(err) {
|
||||||
// One that exists is a symlink whose target is gone, as one
|
resolvedPath = absPath
|
||||||
// into a volume that is not mounted: the scan would record
|
} else {
|
||||||
// only the link, and --prune would then drop the older
|
|
||||||
// snapshots that hold the files.
|
|
||||||
_, lstatErr := os.Lstat(absPath)
|
|
||||||
if !os.IsNotExist(err) || lstatErr == nil {
|
|
||||||
return nil, fmt.Errorf(
|
return nil, fmt.Errorf(
|
||||||
"failed to resolve symlinks for %s: %w", absPath, err)
|
"failed to resolve symlinks for %s: %w", absPath, err)
|
||||||
}
|
}
|
||||||
|
|
||||||
resolvedPath = absPath
|
|
||||||
}
|
}
|
||||||
|
|
||||||
resolvedDirs = append(resolvedDirs, resolvedPath)
|
resolvedDirs = append(resolvedDirs, resolvedPath)
|
||||||
@@ -584,10 +434,6 @@ func (v *Vaultik) scanAllDirectories(
|
|||||||
stats.totalBytesUploaded += result.BytesUploaded
|
stats.totalBytesUploaded += result.BytesUploaded
|
||||||
stats.uploadDuration += result.UploadDuration
|
stats.uploadDuration += result.UploadDuration
|
||||||
|
|
||||||
if result.EntriesFound == 0 {
|
|
||||||
stats.emptyPaths = append(stats.emptyPaths, dir)
|
|
||||||
}
|
|
||||||
|
|
||||||
log.Info("Directory scan complete",
|
log.Info("Directory scan complete",
|
||||||
"path", dir,
|
"path", dir,
|
||||||
"files", result.FilesScanned,
|
"files", result.FilesScanned,
|
||||||
|
|||||||
@@ -1,18 +1,8 @@
|
|||||||
package vaultik_test
|
package vaultik_test
|
||||||
|
|
||||||
import (
|
import (
|
||||||
"context"
|
|
||||||
"os"
|
|
||||||
"path/filepath"
|
|
||||||
"syscall"
|
|
||||||
"testing"
|
"testing"
|
||||||
|
|
||||||
"github.com/spf13/afero"
|
|
||||||
"github.com/stretchr/testify/assert"
|
|
||||||
"github.com/stretchr/testify/require"
|
|
||||||
"sneak.berlin/go/vaultik/internal/config"
|
|
||||||
"sneak.berlin/go/vaultik/internal/log"
|
|
||||||
"sneak.berlin/go/vaultik/internal/snapshot"
|
|
||||||
"sneak.berlin/go/vaultik/internal/vaultik"
|
"sneak.berlin/go/vaultik/internal/vaultik"
|
||||||
)
|
)
|
||||||
|
|
||||||
@@ -35,379 +25,3 @@ func TestSnapshotCreateOptions_PruneFlag(t *testing.T) {
|
|||||||
t.Error("Expected Prune to be false")
|
t.Error("Expected Prune to be false")
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
// A backup under --prune that finds nothing in a configured path, as in
|
|
||||||
// the mount point of a volume that is not mounted, does not prune: run
|
|
||||||
// after run, the snapshot that holds the files is kept with everything
|
|
||||||
// it stored, and the run fails. That holds whether the empty path is the
|
|
||||||
// snapshot's only path or one of two. See
|
|
||||||
// https://git.eeqj.de/sneak/vaultik/issues/388.
|
|
||||||
func TestBackupWithEmptySourcePathDoesNotPrune(t *testing.T) {
|
|
||||||
log.Initialize(log.Config{})
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
// emptied is the path, relative to the source directory, that is
|
|
||||||
// emptied after the first backup.
|
|
||||||
const (
|
|
||||||
snapshotName = "media"
|
|
||||||
emptied = "music"
|
|
||||||
)
|
|
||||||
|
|
||||||
tests := []struct {
|
|
||||||
name string
|
|
||||||
paths []string // relative to the source directory
|
|
||||||
}{
|
|
||||||
{name: "only path", paths: []string{emptied}},
|
|
||||||
{name: "one of two paths", paths: []string{emptied, "docs"}},
|
|
||||||
}
|
|
||||||
|
|
||||||
for _, tt := range tests {
|
|
||||||
t.Run(tt.name, func(t *testing.T) {
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
ctx := context.Background()
|
|
||||||
env := newDeletedCountEnv(t, map[string][]byte{
|
|
||||||
emptied + "/a.mp3": []byte("song a"),
|
|
||||||
emptied + "/b.mp3": []byte("song b"),
|
|
||||||
"docs/notes.txt": []byte("notes"),
|
|
||||||
})
|
|
||||||
|
|
||||||
paths := make([]string, 0, len(tt.paths))
|
|
||||||
|
|
||||||
for _, rel := range tt.paths {
|
|
||||||
paths = append(paths, filepath.Join(env.src, rel))
|
|
||||||
}
|
|
||||||
|
|
||||||
env.v.Config.Snapshots[snapshotName] = config.SnapshotConfig{
|
|
||||||
Paths: paths,
|
|
||||||
}
|
|
||||||
env.backUp(t, snapshotName)
|
|
||||||
|
|
||||||
firstID := localSnapshotID(ctx, t, env.v.Repositories, snapshotName)
|
|
||||||
stored, err := env.v.Storage.List(ctx, "")
|
|
||||||
require.NoError(t, err)
|
|
||||||
|
|
||||||
// A volume that is not mounted leaves its mount point behind
|
|
||||||
// as an empty directory.
|
|
||||||
emptiedDir := filepath.Join(env.src, emptied)
|
|
||||||
require.NoError(t, os.RemoveAll(emptiedDir))
|
|
||||||
require.NoError(t, os.Mkdir(emptiedDir, 0o750))
|
|
||||||
|
|
||||||
for range 2 {
|
|
||||||
env.out.Reset()
|
|
||||||
|
|
||||||
err := env.v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
|
|
||||||
Prune: true,
|
|
||||||
Snapshots: []string{snapshotName},
|
|
||||||
})
|
|
||||||
require.ErrorIs(t, err, vaultik.ErrSourcePathEmpty)
|
|
||||||
assert.Contains(t, env.out.String(),
|
|
||||||
"Skipped the post-backup prune because nothing was found in ")
|
|
||||||
assert.Contains(t, env.out.String(),
|
|
||||||
emptied+" of snapshot "+snapshotName+";")
|
|
||||||
assert.NotContains(t, env.out.String(), "Running post-backup prune.")
|
|
||||||
}
|
|
||||||
|
|
||||||
snapshots, err := env.v.Repositories.Snapshots.ListRecent(
|
|
||||||
ctx, listRecentTestLimit)
|
|
||||||
require.NoError(t, err)
|
|
||||||
require.Len(t, snapshots, 3)
|
|
||||||
assert.Equal(t, firstID, snapshots[2].ID.String(),
|
|
||||||
"the snapshot that holds the files is kept")
|
|
||||||
|
|
||||||
for _, key := range stored {
|
|
||||||
_, err := env.v.Storage.Stat(ctx, key)
|
|
||||||
require.NoError(t, err, "%s is kept", key)
|
|
||||||
}
|
|
||||||
})
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// A backup under --prune of a configured path that is a symlink whose
|
|
||||||
// target is gone, as one into a volume that is not mounted, fails before
|
|
||||||
// anything is pruned: the snapshot that holds the files is kept with
|
|
||||||
// everything it stored. See https://git.eeqj.de/sneak/vaultik/issues/388.
|
|
||||||
func TestBackupThroughSymlinkWhoseTargetIsGoneDoesNotPrune(t *testing.T) {
|
|
||||||
log.Initialize(log.Config{})
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
const snapshotName = "photos"
|
|
||||||
|
|
||||||
ctx := context.Background()
|
|
||||||
env := newDeletedCountEnv(t, map[string][]byte{
|
|
||||||
"volume/a.jpg": []byte("photo a"),
|
|
||||||
"volume/b.jpg": []byte("photo b"),
|
|
||||||
})
|
|
||||||
|
|
||||||
target := filepath.Join(env.src, "volume")
|
|
||||||
link := filepath.Join(env.src, "photos")
|
|
||||||
require.NoError(t, os.Symlink(target, link))
|
|
||||||
env.setSnapshot(snapshotName, "photos")
|
|
||||||
env.backUp(t, snapshotName)
|
|
||||||
|
|
||||||
firstID := localSnapshotID(ctx, t, env.v.Repositories, snapshotName)
|
|
||||||
stored, err := env.v.Storage.List(ctx, "")
|
|
||||||
require.NoError(t, err)
|
|
||||||
|
|
||||||
// The volume is not mounted, so the symlink points at nothing.
|
|
||||||
require.NoError(t, os.RemoveAll(target))
|
|
||||||
|
|
||||||
env.out.Reset()
|
|
||||||
err = env.v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
|
|
||||||
Prune: true,
|
|
||||||
Snapshots: []string{snapshotName},
|
|
||||||
})
|
|
||||||
require.ErrorIs(t, err, os.ErrNotExist)
|
|
||||||
assert.Contains(t, err.Error(), link)
|
|
||||||
assert.NotContains(t, env.out.String(), "Running post-backup prune.")
|
|
||||||
|
|
||||||
snapshots, err := env.v.Repositories.Snapshots.ListRecent(
|
|
||||||
ctx, listRecentTestLimit)
|
|
||||||
require.NoError(t, err)
|
|
||||||
require.Len(t, snapshots, 1)
|
|
||||||
assert.Equal(t, firstID, snapshots[0].ID.String(),
|
|
||||||
"the snapshot that holds the files is kept")
|
|
||||||
|
|
||||||
for _, key := range stored {
|
|
||||||
_, err := env.v.Storage.Stat(ctx, key)
|
|
||||||
require.NoError(t, err, "%s is kept", key)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// A backup under --skip-errors --prune that both skipped a file it could
|
|
||||||
// not read and found nothing in a configured path names the empty path
|
|
||||||
// too when it skips the prune. See
|
|
||||||
// https://git.eeqj.de/sneak/vaultik/issues/388.
|
|
||||||
func TestBackupWithEmptySourcePathAndUnreadableFileNamesBoth(t *testing.T) {
|
|
||||||
log.Initialize(log.Config{})
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
const snapshotName = "media"
|
|
||||||
|
|
||||||
env := newDeletedCountEnv(t, map[string][]byte{
|
|
||||||
"docs/notes.txt": []byte("notes"),
|
|
||||||
})
|
|
||||||
require.NoError(t, os.Mkdir(filepath.Join(env.src, "music"), 0o750))
|
|
||||||
env.v.Config.Snapshots[snapshotName] = config.SnapshotConfig{
|
|
||||||
Paths: []string{
|
|
||||||
filepath.Join(env.src, "docs"),
|
|
||||||
filepath.Join(env.src, "music"),
|
|
||||||
},
|
|
||||||
}
|
|
||||||
|
|
||||||
// A mode does not lock out root, who runs the tests, so opening the
|
|
||||||
// file is made to fail instead.
|
|
||||||
env.v.Fs = &openFailFs{
|
|
||||||
path: filepath.Join(env.src, "docs", "notes.txt"),
|
|
||||||
err: os.ErrPermission,
|
|
||||||
}
|
|
||||||
|
|
||||||
err := env.v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
|
|
||||||
Prune: true,
|
|
||||||
SkipErrors: true,
|
|
||||||
Snapshots: []string{snapshotName},
|
|
||||||
})
|
|
||||||
require.ErrorIs(t, err, vaultik.ErrFilesUnreadable)
|
|
||||||
assert.Contains(t, env.out.String(),
|
|
||||||
"Skipped the post-backup prune because 1 file(s) could not be read")
|
|
||||||
assert.Contains(t, env.out.String(),
|
|
||||||
"Skipped the post-backup prune because nothing was found in ")
|
|
||||||
assert.Contains(t, env.out.String(), "music of snapshot "+snapshotName+";")
|
|
||||||
assert.NotContains(t, env.out.String(), "Running post-backup prune.")
|
|
||||||
}
|
|
||||||
|
|
||||||
// A backup under --prune that finds something in each configured path
|
|
||||||
// prunes the previous snapshot, also when a path is a single file. See
|
|
||||||
// https://git.eeqj.de/sneak/vaultik/issues/388.
|
|
||||||
func TestBackupWithNoEmptySourcePathPrunes(t *testing.T) {
|
|
||||||
log.Initialize(log.Config{})
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
const (
|
|
||||||
snapshotName = "album"
|
|
||||||
file = "pictures/one.jpg" // relative to the source directory
|
|
||||||
)
|
|
||||||
|
|
||||||
tests := []struct {
|
|
||||||
name string
|
|
||||||
path string // relative to the source directory
|
|
||||||
}{
|
|
||||||
{name: "directory", path: filepath.Dir(file)},
|
|
||||||
{name: "single file", path: file},
|
|
||||||
}
|
|
||||||
|
|
||||||
for _, tt := range tests {
|
|
||||||
t.Run(tt.name, func(t *testing.T) {
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
ctx := context.Background()
|
|
||||||
env := newDeletedCountEnv(t, map[string][]byte{
|
|
||||||
file: []byte("picture"),
|
|
||||||
})
|
|
||||||
env.setSnapshot(snapshotName, tt.path)
|
|
||||||
env.backUp(t, snapshotName)
|
|
||||||
|
|
||||||
firstID := localSnapshotID(ctx, t, env.v.Repositories, snapshotName)
|
|
||||||
|
|
||||||
require.NoError(t, env.v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
|
|
||||||
Prune: true,
|
|
||||||
Snapshots: []string{snapshotName},
|
|
||||||
}))
|
|
||||||
|
|
||||||
snapshots, err := env.v.Repositories.Snapshots.ListRecent(
|
|
||||||
ctx, listRecentTestLimit)
|
|
||||||
require.NoError(t, err)
|
|
||||||
require.Len(t, snapshots, 1, "the previous snapshot is pruned")
|
|
||||||
assert.NotEqual(t, firstID, snapshots[0].ID.String())
|
|
||||||
})
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// automountFs is the real filesystem with a volume at volumeDir that is
|
|
||||||
// mounted on first access, as by an autofs map that shows its mount
|
|
||||||
// points before mounting them: listing volumeDir mounts the volume or,
|
|
||||||
// while cannotMount, fails with "no such file or directory".
|
|
||||||
type automountFs struct {
|
|
||||||
afero.OsFs
|
|
||||||
|
|
||||||
volumeDir string
|
|
||||||
cannotMount bool
|
|
||||||
mounted bool
|
|
||||||
}
|
|
||||||
|
|
||||||
//nolint:ireturn // afero.Fs.Open is defined to return the interface.
|
|
||||||
func (f *automountFs) Open(name string) (afero.File, error) {
|
|
||||||
if name == f.volumeDir && f.cannotMount {
|
|
||||||
return nil, &os.PathError{Op: "open", Path: name, Err: syscall.ENOENT}
|
|
||||||
}
|
|
||||||
|
|
||||||
if name == f.volumeDir {
|
|
||||||
f.mounted = true
|
|
||||||
}
|
|
||||||
|
|
||||||
return f.OsFs.Open(name)
|
|
||||||
}
|
|
||||||
|
|
||||||
// A backup under --prune in which a volume that an earlier snapshot found
|
|
||||||
// mounted below the configured path is missing does not prune: run after
|
|
||||||
// run, the snapshot that holds the volume's files is kept with everything
|
|
||||||
// it stored, and the run fails. Once the volume is back, the prune runs.
|
|
||||||
// The volume is mounted on first access and every backup starts with it
|
|
||||||
// not mounted, so its directory is on its parent's device until the walk
|
|
||||||
// lists it. While the volume is missing, its directory is left empty, or
|
|
||||||
// listing it fails with "no such file or directory", as when an autofs
|
|
||||||
// volume cannot be mounted, which the walk counts as a directory removed
|
|
||||||
// during the backup. See https://git.eeqj.de/sneak/vaultik/issues/395.
|
|
||||||
func TestBackupWithVolumeNotMountedDoesNotPrune(t *testing.T) {
|
|
||||||
log.Initialize(log.Config{})
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
tests := []struct {
|
|
||||||
name string
|
|
||||||
listingFails bool
|
|
||||||
}{
|
|
||||||
{name: "directory left empty", listingFails: false},
|
|
||||||
{name: "listing fails", listingFails: true},
|
|
||||||
}
|
|
||||||
|
|
||||||
for _, tt := range tests {
|
|
||||||
t.Run(tt.name, func(t *testing.T) {
|
|
||||||
t.Parallel()
|
|
||||||
|
|
||||||
backUpWithVolumeNotMounted(t, tt.listingFails)
|
|
||||||
})
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// backUpWithVolumeNotMounted runs the backups of
|
|
||||||
// TestBackupWithVolumeNotMountedDoesNotPrune. While the volume is
|
|
||||||
// missing, listing its directory fails if listingFails; otherwise the
|
|
||||||
// directory is empty.
|
|
||||||
func backUpWithVolumeNotMounted(t *testing.T, listingFails bool) {
|
|
||||||
t.Helper()
|
|
||||||
|
|
||||||
// volume is the directory, below the configured path, where the
|
|
||||||
// volume is mounted.
|
|
||||||
const (
|
|
||||||
snapshotName = "data"
|
|
||||||
volume = "nas"
|
|
||||||
)
|
|
||||||
|
|
||||||
ctx := context.Background()
|
|
||||||
env := newDeletedCountEnv(t, map[string][]byte{
|
|
||||||
volume + "/a.txt": []byte("file a"),
|
|
||||||
"notes.txt": []byte("notes"),
|
|
||||||
})
|
|
||||||
env.setSnapshot(snapshotName, "")
|
|
||||||
prune := &vaultik.SnapshotCreateOptions{
|
|
||||||
Prune: true, Snapshots: []string{snapshotName},
|
|
||||||
}
|
|
||||||
|
|
||||||
// The volume's directory is on the volume's device, 2, while the
|
|
||||||
// volume is mounted. Everything else is on device 1.
|
|
||||||
volumeDir := filepath.Join(env.src, volume)
|
|
||||||
fs := &automountFs{volumeDir: volumeDir}
|
|
||||||
newScanner := env.v.ScannerFactory
|
|
||||||
env.v.ScannerFactory = func(params snapshot.ScannerParams) *snapshot.Scanner {
|
|
||||||
fs.mounted = false
|
|
||||||
params.Fs = fs
|
|
||||||
params.DeviceNumber = func(info os.FileInfo) (uint64, bool) {
|
|
||||||
if info.Name() == volume && fs.mounted {
|
|
||||||
return 2, true
|
|
||||||
}
|
|
||||||
|
|
||||||
return 1, true
|
|
||||||
}
|
|
||||||
|
|
||||||
return newScanner(params)
|
|
||||||
}
|
|
||||||
|
|
||||||
env.backUp(t, snapshotName)
|
|
||||||
|
|
||||||
firstID := localSnapshotID(ctx, t, env.v.Repositories, snapshotName)
|
|
||||||
stored, err := env.v.Storage.List(ctx, "")
|
|
||||||
require.NoError(t, err)
|
|
||||||
|
|
||||||
// The volume goes missing.
|
|
||||||
fs.cannotMount = listingFails
|
|
||||||
|
|
||||||
if !listingFails {
|
|
||||||
require.NoError(t, os.RemoveAll(volumeDir))
|
|
||||||
require.NoError(t, os.Mkdir(volumeDir, 0o750))
|
|
||||||
}
|
|
||||||
|
|
||||||
for range 2 {
|
|
||||||
env.out.Reset()
|
|
||||||
|
|
||||||
err := env.v.CreateSnapshot(prune)
|
|
||||||
require.ErrorIs(t, err, vaultik.ErrVolumeNotMounted)
|
|
||||||
assert.Contains(t, env.out.String(),
|
|
||||||
"did not find a mount point at "+volumeDir+" of snapshot "+snapshotName)
|
|
||||||
assert.Contains(t, env.out.String(), "'vaultik snapshot purge'")
|
|
||||||
assert.NotContains(t, env.out.String(), "Running post-backup prune.")
|
|
||||||
}
|
|
||||||
|
|
||||||
snapshots, err := env.v.Repositories.Snapshots.ListRecent(
|
|
||||||
ctx, listRecentTestLimit)
|
|
||||||
require.NoError(t, err)
|
|
||||||
require.Len(t, snapshots, 3)
|
|
||||||
assert.Equal(t, firstID, snapshots[2].ID.String(),
|
|
||||||
"the snapshot that holds the volume's files is kept")
|
|
||||||
|
|
||||||
for _, key := range stored {
|
|
||||||
_, err := env.v.Storage.Stat(ctx, key)
|
|
||||||
require.NoError(t, err, "%s is kept", key)
|
|
||||||
}
|
|
||||||
|
|
||||||
// The volume is back.
|
|
||||||
fs.cannotMount = false
|
|
||||||
|
|
||||||
require.NoError(t, os.WriteFile(
|
|
||||||
filepath.Join(volumeDir, "a.txt"), []byte("file a"), 0o600))
|
|
||||||
require.NoError(t, env.v.CreateSnapshot(prune))
|
|
||||||
|
|
||||||
snapshots, err = env.v.Repositories.Snapshots.ListRecent(
|
|
||||||
ctx, listRecentTestLimit)
|
|
||||||
require.NoError(t, err)
|
|
||||||
require.Len(t, snapshots, 1, "the older snapshots are pruned")
|
|
||||||
}
|
|
||||||
|
|||||||
Reference in New Issue
Block a user