Add snapshot files to list a snapshot's files without restoring it (closes #435)
check / check (push) Waiting to run
check / check (push) Waiting to run
`vaultik snapshot files <snapshot-id> [path] [--json]` downloads and decrypts the snapshot database, as restore does, and prints mode, size, modification time and path for every file at or under the path. A path that matches nothing is an error. It needs the private key. The mode is in Go's file-mode notation, which the README spells out. Named `files` because `ls` is already the alias of `snapshot list`. The missing-key error no longer says "for restore", since this command and deep verify return it too. The README opening now states the private-key rule first. Model: opus-5-5
This commit is contained in:
sneak committed
1 parent
5ca0d46932
commit
a717539650
8 files changed
+445
-40
No files matched your search
@@ -2,9 +2,9 @@
|
||||
|
||||
`vaultik` is an incremental backup tool written in Go. It encrypts data using an
|
||||
`age` public key and uploads each encrypted blob directly to a remote
|
||||
S3-compatible object store. It requires no private keys, secrets, or credentials
|
||||
(other than those required to PUT to encrypted object storage, such as S3 API
|
||||
keys) stored on the backed-up system.
|
||||
S3-compatible object store. The backed-up system never needs the private key. A
|
||||
backup needs only the public key and the credentials to write to the object
|
||||
store, such as S3 API keys.
|
||||
|
||||
## quickstart
|
||||
|
||||
@@ -171,6 +171,7 @@ vaultik [--config <path>] config get <key>
|
||||
vaultik [--config <path>] config set <key> <value>
|
||||
vaultik [--config <path>] snapshot create [snapshot-names...] [--cron] [--prune] [--keep-newer-than <duration>]
|
||||
vaultik [--config <path>] snapshot list [--json] # alias: ls
|
||||
vaultik [--config <path>] snapshot files <snapshot-id> [path] [--json]
|
||||
vaultik [--config <path>] snapshot verify <snapshot-id> [--deep] [--json]
|
||||
vaultik [--config <path>] snapshot purge [--keep-latest | --older-than <duration>] [--snapshot <name>...] [--force]
|
||||
vaultik [--config <path>] snapshot remove <snapshot-id> [--dry-run] [--force] [--local-only] [--json] # alias: rm
|
||||
@@ -223,12 +224,18 @@ the backup can delete it; the new snapshot then cannot be restored.
|
||||
`remote nuke` deletes everything regardless. To not depend on the grace period,
|
||||
give each host or user its own prefix (or directory) on the destination.
|
||||
|
||||
Read-only commands — `info`, `snapshot list`, `snapshot verify`, and
|
||||
`remote info` — do not take the lock and are never blocked, so they run even
|
||||
while a backup is in progress. `snapshot restore` does not take the lock either:
|
||||
it writes only to the target directory you name, not the local index or the
|
||||
destination store. `config`, `database delete`, `completion`, and `version` do
|
||||
not take the lock.
|
||||
These read-only commands do not take the lock, so they are never blocked, even
|
||||
while a backup is in progress:
|
||||
|
||||
- `info`
|
||||
- `snapshot list`
|
||||
- `snapshot files`
|
||||
- `snapshot verify`
|
||||
- `remote info`
|
||||
|
||||
`snapshot restore` does not take the lock either: it writes only to the target
|
||||
directory you name, not the local index or the destination store. `config`,
|
||||
`database delete`, `completion`, and `version` do not take the lock.
|
||||
|
||||
### stdout and stderr
|
||||
|
||||
@@ -261,9 +268,9 @@ work as written.
|
||||
### environment variables
|
||||
|
||||
- `VAULTIK_AGE_SECRET_KEY`: Age private key for decryption (required for
|
||||
`snapshot restore` and `snapshot verify --deep`). May hold the whole
|
||||
`age-keygen` file — comments and every identity in it are accepted. Set it
|
||||
from the file, e.g.
|
||||
`snapshot restore`, `snapshot files` and `snapshot verify --deep`). May hold
|
||||
the whole `age-keygen` file — comments and every identity in it are accepted.
|
||||
Set it from the file, e.g.
|
||||
`export VAULTIK_AGE_SECRET_KEY="$(cat vaultik_backup_private_key.txt)"`, so
|
||||
the key is not typed into your shell history.
|
||||
- `VAULTIK_CONFIG`: Path to config file (overridden by `--config`)
|
||||
@@ -408,6 +415,24 @@ point behind.
|
||||
truncated listing all go to stderr through the logger, so stdout stays a
|
||||
single parseable document.
|
||||
|
||||
**`snapshot files`**: List the files in a snapshot without restoring it. Each
|
||||
row of the table shows mode, size in bytes, modification time and path, sorted
|
||||
by path.
|
||||
|
||||
- Requires `VAULTIK_AGE_SECRET_KEY`: the file list is only in the snapshot's
|
||||
encrypted database, which the command downloads and decrypts.
|
||||
- Accepts the same identifiers as `snapshot restore`.
|
||||
- An optional path limits the list to that path and what is under it. A path
|
||||
that matches nothing in the snapshot is an error.
|
||||
- `--json`: Output an array of objects with `path`, `size`, `mode` and `mtime`.
|
||||
- The mode is in Go's file-mode notation, in the table and in `--json`. Letters
|
||||
before the nine permission characters show the file type and any special bit,
|
||||
as in `dtrwxrwxrwx` for a sticky directory. These letters differ from `ls -l`:
|
||||
- `L`: a symbolic link, which `ls -l` shows as `l`.
|
||||
- `u`: setuid, which `ls -l` shows as `s` in place of the owner's `x`.
|
||||
- `g`: setgid, which `ls -l` shows as `s` in place of the group's `x`.
|
||||
- `t`: sticky, which `ls -l` shows as `t` in place of the others' `x`.
|
||||
|
||||
**`snapshot verify`**: Verify snapshot integrity.
|
||||
|
||||
- Default (shallow): checks that every blob the manifest lists is present in
|
||||
@@ -722,7 +747,7 @@ annotated example also lives in
|
||||
| Field | Default | Description |
|
||||
| -------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `age_recipients` | (required by `snapshot create`) | Age public keys for encryption. Other commands run without one, so a machine that only restores can leave it empty |
|
||||
| `age_secret_key` | (unset) | Age private key for decryption (`snapshot restore`, `snapshot verify --deep`). Setting it in the config file places the private key on the backed-up host, defeating the public-key-only design (see "why" above). Prefer the `VAULTIK_AGE_SECRET_KEY` environment variable, supplied only on the machine you restore from. |
|
||||
| `age_secret_key` | (unset) | Age private key for decryption (`snapshot restore`, `snapshot files`, `snapshot verify --deep`). Setting it in the config file places the private key on the backed-up host, defeating the public-key-only design (see "why" above). Prefer the `VAULTIK_AGE_SECRET_KEY` environment variable, supplied only on the machine you restore from. |
|
||||
| `snapshots` | (required) | Named snapshot definitions with paths and excludes |
|
||||
| `storage_url` | | Storage backend URL (`s3://`, `file://`, `rclone://`) |
|
||||
| `s3.*` | | Legacy S3 configuration (endpoint, bucket, credentials) |
|
||||
@@ -839,15 +864,21 @@ environment variable is unset (https://no-color.org/).
|
||||
`database delete`.
|
||||
- **The data a command exists to produce** is written plain, with no marker and
|
||||
no color, because a marker would corrupt a table or a parsed document. This
|
||||
covers the `version`, `info`, `remote info` and `snapshot verify` reports, the
|
||||
`snapshot list` table, `config get` values, and every `--json` document.
|
||||
`--quiet` silences the human reports and tables (`version`, `info`,
|
||||
`remote info`, `snapshot verify`, `snapshot list`) but never the
|
||||
machine-consumed `config get` value or the `--json` documents, which a script
|
||||
depends on. The confirmation prompts of `database delete`, `prune`,
|
||||
`snapshot purge` and `snapshot remove`, each with what it asks to delete, are
|
||||
also written this way and always shown: they are an interactive exchange the
|
||||
operator must see.
|
||||
covers the report or table of each of these commands:
|
||||
- `version`
|
||||
- `info`
|
||||
- `remote info`
|
||||
- `snapshot verify`
|
||||
- `snapshot list`
|
||||
- `snapshot files`
|
||||
|
||||
`config get` values and every `--json` document are written plain too.
|
||||
`--quiet` silences the reports and tables above, but never a `config get`
|
||||
value or a `--json` document, which a script depends on. The confirmation
|
||||
prompts of `database delete`, `prune`, `snapshot purge` and
|
||||
`snapshot remove`, each with what it asks to delete, are also written this
|
||||
way and always shown: they are an interactive exchange the operator must
|
||||
see.
|
||||
|
||||
`internal/ui` writes to stdout; it is the output the user asked for. The
|
||||
exceptions are the startup banner and the error a failed command ends with,
|
||||
|
||||
Reference in new issue
Block a user