backupsftp

package
v0.7.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 22, 2026 License: GPL-3.0 Imports: 27 Imported by: 0

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

View Source
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

View Source
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

func DeleteConfig(path string) error

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

func List(ctx context.Context, fs RemoteFS, config Config) ([]backup.ArchiveEntry, error)

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

func SaveConfig(path string, config Config) error

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

func SaveStatus(path string, status Status) error

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

func LoadConfig(path string) (*Config, error)

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) Address

func (c Config) Address() string

Address returns the host:port dial address with the default port applied.

func (Config) PublicView

func (c Config) PublicView() View

PublicView renders the secret-free view. PasswordSet/KeyPassphraseSet/ HostKeySet tell the UI a value is on file without revealing it.

func (Config) Validate

func (c Config) Validate() error

Validate checks a destination config before it is persisted. Address is the TCP dial address.

type Dialer

type Dialer func(ctx context.Context, config Config, knownHostsPath string) (RemoteFS, error)

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 (e Engine) DeleteConfig() error

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 (e Engine) LoadConfig() (*Config, error)

func (Engine) RemoteList

func (e Engine) RemoteList(ctx context.Context, config Config) ([]backup.ArchiveEntry, error)

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 (e Engine) SaveConfig(config Config) error

func (Engine) Status

func (e Engine) Status() 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

func LoadStatus(path string) Status

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.

func Upload

func Upload(ctx context.Context, fs RemoteFS, config Config, localPath, name string) (UploadReceipt, error)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址