Documentation
¶
Overview ¶
Package backupsftp implements the SFTP remote-backup destination: config and secrets persisted in a root-only file under the etc dir, the SSH/SFTP client, upload with checksum verification, remote listing/download, and a remote retention prune that shares the policy decision with the local archive prune in internal/backup.
Two safety invariants shape the remote side:
- Remote storage is encrypted-only: Upload refuses archives without the .enc suffix or the Veil encrypted-archive magic (#1188), mirroring the fetch side's .enc-only policy.
- Remote work happens under <remoteDir>/veil-node-<install-id>/, a per-installation namespace minted once and persisted in the state dir, so nodes sharing one remoteDir never list, fetch, or prune each other's archives (#1184). Archives written by older versions at the remoteDir root are orphans the engine deliberately never touches.
Secret fields (password, key passphrase, pinned host key) live only in the on-disk config file. Anything returned over the API goes through View, which reports "configured" flags instead of the values.
Per-installation remote namespace for the SFTP backup destination.
Several Veil nodes may legitimately point at the same SFTP server and remoteDir — one backup box is the natural operator setup. Because archive names carry no host identity, a node must never trust the shared listing: its retention would otherwise prune archives belonging to other nodes (#1184). Every remote operation therefore happens under <remoteDir>/veil-node-<install-id>/ where <install-id> is a random 128-bit identity persisted locally the first time the node talks to a remote.
The id file lives under the state dir (beside the status and known_hosts files) so the scheduled backup unit — which mounts only /var/lib/veil writable — can mint it. It is not a secret and is never sent anywhere except as the remote directory name. Archives another node uploaded into its own namespace, and archives written by older Veil versions at the remoteDir root, stay invisible to List/Fetch and untouchable by Prune.
Index ¶
- Constants
- Variables
- func DeleteConfig(path string) error
- func Fetch(ctx context.Context, fs RemoteFS, config Config, localDir, name string) (backup.ArchiveEntry, error)
- func List(ctx context.Context, fs RemoteFS, config Config) ([]backup.ArchiveEntry, error)
- func Prune(ctx context.Context, fs RemoteFS, config Config, policy backup.RetentionPolicy) (backup.PruneResult, error)
- func SaveConfig(path string, config Config) error
- func SaveStatus(path string, status Status) error
- type Config
- type Dialer
- type Engine
- func (e Engine) DeleteConfig() error
- func (e Engine) FetchArchive(ctx context.Context, config Config, localDir, name string) (backup.ArchiveEntry, error)
- func (e Engine) LoadConfig() (*Config, error)
- func (e Engine) RemoteList(ctx context.Context, config Config) ([]backup.ArchiveEntry, error)
- func (e Engine) RemotePrune(ctx context.Context, config Config, policy backup.RetentionPolicy) (backup.PruneResult, error)
- func (e Engine) RemotePruneIfConfigured(ctx context.Context, policy backup.RetentionPolicy) (result backup.PruneResult, attempted bool, err error)
- func (e Engine) SaveConfig(config Config) error
- func (e Engine) Status() Status
- func (e Engine) SyncArchive(ctx context.Context, localPath, name string, policy *backup.RetentionPolicy) (result SyncResult, configured bool, err error)
- type Paths
- type RemoteFS
- type Status
- type SyncResult
- type UploadReceipt
- type View
Constants ¶
const ( // ConfigFileName is the root-only destination config under the etc dir. ConfigFileName = "backup-sftp.json" // StatusFileName records the last remote operation outcome under the // state dir (the config dir itself is read-only for the scheduled unit). StatusFileName = "backup-sftp-status.json" // KnownHostsFileName holds the trust-on-first-use remote host keys. KnownHostsFileName = "backup-sftp.known_hosts" // InstallIDFileName persists the random per-installation identity that // namespaces this node's remote archives (#1184). InstallIDFileName = "backup-sftp.install-id" AuthTypeKey = "key" AuthTypePassword = "password" DefaultPort = 22 MaxPasswordBytes = 4096 MaxKeyPassphraseBts = 4096 )
Variables ¶
var ErrUnencryptedArchive = errors.New("unencrypted archives are not uploaded to the SFTP destination")
ErrUnencryptedArchive rejects plaintext at the remote-publish boundary: the SFTP destination is an encrypted-only tier, the mirror image of the fetch side's .enc-only policy (#1188). Callers unwrap it with errors.Is to distinguish a policy refusal from a transport failure.
Functions ¶
func DeleteConfig ¶
DeleteConfig removes the destination config; a missing file is a no-op.
func Fetch ¶
func Fetch(ctx context.Context, fs RemoteFS, config Config, localDir, name string) (backup.ArchiveEntry, error)
Fetch downloads one remote archive into localDir atomically: the bytes land at a hidden .part sibling first, the sha256 sidecar is verified when the remote carries one, size is checked against the remote stat, and the file is published by hardlink so a name that already exists locally can never be replaced.
func List ¶
List returns the managed archives present in the remote directory in newest-first order, using the same managed-name filter the local listing applies. A missing remote directory lists as empty.
func Prune ¶
func Prune(ctx context.Context, fs RemoteFS, config Config, policy backup.RetentionPolicy) (backup.PruneResult, error)
Prune applies the shared daily/weekly/monthly bucket decision to the remote listing and removes remote archives (plus their .sha256 sidecars) the policy would not keep. This mirrors local PruneArchives semantics.
func SaveConfig ¶
SaveConfig writes the destination config atomically with root-only permissions — the file carries secrets and must never be world-readable. A zero port normalizes to the SSH default before persisting.
func SaveStatus ¶
SaveStatus persists the status file atomically (root-only; it mentions archive names and error text, not secrets).
Types ¶
type Config ¶
type Config struct {
Enabled bool `json:"enabled"`
Host string `json:"host"`
Port int `json:"port,omitempty"`
User string `json:"user"`
RemoteDir string `json:"remoteDir"`
AuthType string `json:"authType"`
KeyPath string `json:"keyPath,omitempty"`
KeyPassphrase string `json:"keyPassphrase,omitempty"`
Password string `json:"password,omitempty"`
// HostKey optionally pins the server host public key in authorized_keys
// format ("ssh-ed25519 AAAA…"). When empty the first observed key is
// trusted and persisted in the known_hosts file (TOFU).
HostKey string `json:"hostKey,omitempty"`
}
Config is the SFTP destination as stored on disk. Password and KeyPassphrase are secrets: they are write-only over the API and must never be echoed back or stored in the management state DB.
func LoadConfig ¶
LoadConfig reads the destination config. A missing file is not an error: it returns a nil config so callers can report "not configured".
func (Config) PublicView ¶
PublicView renders the secret-free view. PasswordSet/KeyPassphraseSet/ HostKeySet tell the UI a value is on file without revealing it.
type Dialer ¶
Dialer connects and authenticates to the configured SFTP endpoint. It is the seam tests replace with an in-memory fake.
var Dial Dialer = dialSFTP
Dial connects to cfg's endpoint with a real SSH/SFTP client. It is a var so helper and CLI tests can inject a fake at the shared seam.
type Engine ¶
type Engine struct {
Paths Paths
// Dial connects to the configured endpoint; nil uses the package-level
// real SSH/SFTP dialer.
Dial Dialer
Now func() time.Time
}
Engine binds the destination paths to the dial and clock seams so the privileged helper (socket-driven operations) and the scheduled backup CLI (which runs without the helper) share one orchestration path for upload/list/fetch/prune and the status bookkeeping around them.
func (Engine) DeleteConfig ¶
func (Engine) FetchArchive ¶
func (e Engine) FetchArchive(ctx context.Context, config Config, localDir, name string) (backup.ArchiveEntry, error)
FetchArchive downloads one archive from this installation's remote namespace into localDir and records the outcome in the status file.
func (Engine) LoadConfig ¶
func (Engine) RemoteList ¶
RemoteList returns the managed archives in this installation's remote namespace and records dial/list failures in the status file. Archives other nodes or older unscoped uploads left in remoteDir are not shown.
func (Engine) RemotePrune ¶
func (e Engine) RemotePrune(ctx context.Context, config Config, policy backup.RetentionPolicy) (backup.PruneResult, error)
RemotePrune applies the shared retention decision to this installation's remote namespace and records the outcome. Foreign archives — other nodes' namespaces and pre-namespacing orphans at the remoteDir root — are never candidates for removal (#1184).
func (Engine) RemotePruneIfConfigured ¶
func (e Engine) RemotePruneIfConfigured(ctx context.Context, policy backup.RetentionPolicy) (result backup.PruneResult, attempted bool, err error)
RemotePruneIfConfigured mirrors a retention policy onto the remote listing when a destination is configured and enabled; attempted is false when there is nothing to do.
func (Engine) SaveConfig ¶
func (Engine) Status ¶
Status returns the recorded remote-operation outcomes; a missing or unreadable status file reports empty rather than erroring.
func (Engine) SyncArchive ¶
func (e Engine) SyncArchive(ctx context.Context, localPath, name string, policy *backup.RetentionPolicy) (result SyncResult, configured bool, err error)
SyncArchive is the post-create hook shared by the privileged helper's backup_create handling and the scheduled veil-backup.service CLI path: it uploads the freshly written archive to this installation's remote namespace and, when a retention policy is supplied, mirrors the daily/weekly/monthly prune on the remote listing. configured is false when no destination is on file or it is disabled, so callers distinguish "nothing to do" from a real skip.
A plaintext archive — a name without the .enc suffix or content missing the encrypted-archive magic — is refused with ErrUnencryptedArchive before the remote is even dialed: remote storage is an encrypted-only tier, so --allow-unencrypted stays a purely local opt-in (#1188).
Failures return the error — callers decide how loud to make it — while the status file records the same outcome for the status endpoint.
type Paths ¶
type Paths struct {
ConfigPath string
StatusPath string
KnownHostsPath string
InstallIDPath string
}
Paths locates the on-disk state an SFTP destination needs. ConfigPath is the root-only secrets file under the etc dir; StatusPath and KnownHostsPath live under the state dir so the scheduled backup unit — which mounts /var/lib/veil writable but keeps /etc read-only — can record outcomes and complete trust-on-first-use without relaxing its filesystem confinement. InstallIDPath persists the random per-installation identity that namespaces this node's remote archives (#1184); when empty it falls back to a backup-sftp.install-id file beside the status file.
type RemoteFS ¶
type RemoteFS interface {
Stat(name string) (os.FileInfo, error)
ReadDir(dir string) ([]os.FileInfo, error)
Open(name string) (io.ReadCloser, error)
Create(name string) (io.WriteCloser, error)
ReadFile(name string) ([]byte, error)
MkdirAll(dir string) error
// Rename must replace an existing destination atomically (POSIX rename);
// uploads publish through a .part name so a partial transfer never sits
// at the final archive name.
Rename(oldname, newname string) error
Remove(name string) error
Close() error
}
RemoteFS abstracts the SFTP operations the destination logic needs so tests can substitute an in-memory fake instead of a live SSH server.
type Status ¶
type Status struct {
LastUploadAt string `json:"lastUploadAt,omitempty"`
LastUploadArchive string `json:"lastUploadArchive,omitempty"`
LastFetchAt string `json:"lastFetchAt,omitempty"`
LastFetchArchive string `json:"lastFetchArchive,omitempty"`
LastPruneAt string `json:"lastPruneAt,omitempty"`
LastError string `json:"lastError,omitempty"`
LastErrorAt string `json:"lastErrorAt,omitempty"`
}
Status records the outcome of the most recent remote operation attempts. It lives under the state dir so both the helper and the scheduled backup oneshot (which mounts only /var/lib/veil writable) can update it.
func LoadStatus ¶
LoadStatus reads the last remote-operation status; missing is empty.
type SyncResult ¶
type SyncResult struct {
Uploaded *UploadReceipt `json:"uploaded,omitempty"`
// Pruned/Kept describe the remote retention run when a policy was given.
Pruned []string `json:"pruned,omitempty"`
Kept []string `json:"kept,omitempty"`
}
SyncResult reports what one remote synchronization achieved.
type UploadReceipt ¶
type UploadReceipt struct {
Archive string `json:"archive"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
}
UploadReceipt describes one verified remote upload.
type View ¶
type View struct {
Configured bool `json:"configured"`
Enabled bool `json:"enabled"`
Host string `json:"host,omitempty"`
Port int `json:"port,omitempty"`
User string `json:"user,omitempty"`
RemoteDir string `json:"remoteDir,omitempty"`
AuthType string `json:"authType,omitempty"`
KeyPath string `json:"keyPath,omitempty"`
PasswordSet bool `json:"passwordSet,omitempty"`
KeyPassphraseSet bool `json:"keyPassphraseSet,omitempty"`
HostKeySet bool `json:"hostKeySet,omitempty"`
}
View is the API-safe rendering of Config: secrets are replaced by "configured" flags so a GET can never echo them.