Documentation
¶
Overview ¶
Package backup owns the shared Rustic backup engine used by volume and system backups: typed repository operations, per-repository serialization and run admission.
Index ¶
- Constants
- Variables
- func AcceptedBackupID(run scheduler.Run) string
- func AcceptedTarget(backupID string) scheduler.TargetOutcome
- func CheckRemoteRepository(ctx context.Context, destinations *s3.S3DestinationService, ...) (backup.RepositoryObservation, error)
- func CheckScheduledRemote(ctx context.Context, db *database.DB, destinations *s3.S3DestinationService, ...) error
- func DisableMissingRemote(remoteErr error, localEnabled bool, s3Enabled, enabled *bool, ...) (bool, error)
- func DisableStoredRemote(ctx context.Context, db *database.DB, model any, id, destinationID string, ...) (bool, error)
- func ExpiredRunIDs(ctx context.Context, db *database.DB, table, policyID string, keep int) ([]string, error)
- func GenerateRecoveryKey() (string, error)
- func NewRequester(ctx context.Context, requestedBy user.Actor, environmentID, permission string) backup.Requester
- func RemoteSnapshotChecker(ctx context.Context, destinations *s3.S3DestinationService) func(destinationID, root, snapshotID string) *bool
- func RunSnapshotTag(runID string) string
- func ValidatePolicyUpdate(ctx context.Context, domain string, update backup.UpdateBackupPolicy, ...) (backup.UpdateBackupPolicy, error)
- func ValidateRecoveryKey(key string) error
- type CreateSnapshotInput
- type DiscoveredSnapshot
- type Engine
- func (e *Engine) AcquireRun(ctx context.Context, scope, id, run string) (*runs.Lease, bool, error)
- func (e *Engine) Authorize(ctx context.Context, requester backup.Requester) error
- func (e *Engine) ChangeRepositoryPassword(ctx context.Context, dockerClient *client.Client, repository Repository, ...) error
- func (e *Engine) ConfirmRunSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, ...) (Snapshot, error)
- func (e *Engine) CreateSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, ...) (Snapshot, error)
- func (e *Engine) FindRunSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, ...) (Snapshot, bool, error)
- func (e *Engine) ForgetSnapshots(ctx context.Context, dockerClient *client.Client, repository Repository, ...) error
- func (e *Engine) Hold(scope, id, run string, lease *runs.Lease) func(context.Context)
- func (e *Engine) ListSnapshotFiles(ctx context.Context, dockerClient *client.Client, repository Repository, ...) ([]string, error)
- func (e *Engine) ListSnapshots(ctx context.Context, dockerClient *client.Client, repository Repository, ...) ([]DiscoveredSnapshot, error)
- func (e *Engine) ReadSnapshotTextFile(ctx context.Context, dockerClient *client.Client, repository Repository, ...) (string, error)
- func (e *Engine) Replicate(ctx context.Context, dockerClient *client.Client, from Repository, ...) (Snapshot, error)
- func (e *Engine) RestoreSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, ...) error
- func (e *Engine) SetAuthorize(authorize func(context.Context, backup.Requester) error)
- func (e *Engine) Stop(ctx context.Context) error
- func (e *Engine) TryAcquireRun(ctx context.Context, scope, id string) (*runs.Lease, bool, error)
- type PolicyReconciliation
- type RecoveryKeyStore
- func (s *RecoveryKeyStore) Configured(ctx context.Context) (bool, error)
- func (s *RecoveryKeyStore) Get(ctx context.Context) (string, error)
- func (s *RecoveryKeyStore) HoldRunKey(ctx context.Context, runID, recoveryKey string) error
- func (s *RecoveryKeyStore) ReleaseRunKey(ctx context.Context, runID string) error
- func (s *RecoveryKeyStore) RunKey(ctx context.Context, runID string) (string, error)
- func (s *RecoveryKeyStore) Set(ctx context.Context, recoveryKey string) error
- type Repository
- type RestoreOptions
- type Snapshot
- type SystemBackupRecoveryConfig
Constants ¶
const ( VolumeAdmissionScope = "volume-backup" SystemAdmissionScope = "system-backup" // SystemAdmissionID is the one admission key system and system-managed volume backups share. SystemAdmissionID = "system" RecoveryKeyConfigID = "system-recovery" // VolumeRoot is the S3 prefix under which each instance keeps its volume backup repository. VolumeRoot = "arcane-volume-backups" )
const RemoteDisabledMessage = "S3 backup storage is missing. Remote backups were disabled; edit the policy to resume."
Variables ¶
var ( ErrRecoveryKeyNotConfigured = errors.New("recovery key is not configured") // ErrBackupSettled reports a checkpointed backup whose own attempt already failed it, so there is nothing to // resume; a retry starts a new backup instead. ErrBackupSettled = errors.New("the checkpointed backup already failed") // RecoveryKeyFormat is 8 hyphenated groups of 6 base32 characters, used verbatim as the Rustic password. RecoveryKeyFormat = regexp.MustCompile(`^[A-Z2-7]{6}(-[A-Z2-7]{6}){7}$`) )
var ErrRemoteRepositoryMissing = errors.New("S3 backup storage is missing")
Functions ¶
func AcceptedBackupID ¶ added in v2.16.0
AcceptedBackupID returns the backup a manual backup workflow's run owns, from its AcceptedTarget.
func AcceptedTarget ¶ added in v2.16.0
func AcceptedTarget(backupID string) scheduler.TargetOutcome
AcceptedTarget is the progress a manual backup's workflow starts with, so startup recovery protects its record from the moment the backup is accepted.
func CheckRemoteRepository ¶ added in v2.15.1
func CheckRemoteRepository(ctx context.Context, destinations *s3.S3DestinationService, destinationID, root string) (backup.RepositoryObservation, error)
CheckRemoteRepository probes the destination's repository config within a bounded budget. Transport and credential failures are returned as errors so callers never forget snapshots blindly.
func CheckScheduledRemote ¶ added in v2.11.0
func CheckScheduledRemote(ctx context.Context, db *database.DB, destinations *s3.S3DestinationService, table, destinationID, root string) error
CheckScheduledRemote permits first-use initialization, but detects lost repositories.
func DisableMissingRemote ¶ added in v2.16.0
func DisableMissingRemote(remoteErr error, localEnabled bool, s3Enabled, enabled *bool, save func(field string) (bool, error)) (bool, error)
DisableMissingRemote stops a scheduled policy from using S3 storage that went missing: a policy that also backs up locally loses S3, an S3-only one is disabled. save clears that field on the stored policy unless it changed since it was loaded, and reports whether it did; the loaded flags then follow. It reports whether S3 was turned off.
func DisableStoredRemote ¶ added in v2.16.0
func DisableStoredRemote(ctx context.Context, db *database.DB, model any, id, destinationID string, localEnabled bool, field string) (bool, error)
DisableStoredRemote is DisableMissingRemote's save for a policy table row, which it changes only while the row still matches the loaded policy.
func ExpiredRunIDs ¶
func ExpiredRunIDs(ctx context.Context, db *database.DB, table, policyID string, keep int) ([]string, error)
ExpiredRunIDs returns the IDs of succeeded runs with snapshots that fall outside the newest keep entries for one policy, oldest last. Callers delete each run through their own delete path so snapshots are forgotten too.
func GenerateRecoveryKey ¶ added in v2.12.0
GenerateRecoveryKey creates a random recovery key in RecoveryKeyFormat.
func NewRequester ¶ added in v2.16.0
func NewRequester(ctx context.Context, requestedBy user.Actor, environmentID, permission string) backup.Requester
NewRequester captures the user, and API key if any, behind a manual backup request.
func RemoteSnapshotChecker ¶ added in v2.11.0
func RemoteSnapshotChecker(ctx context.Context, destinations *s3.S3DestinationService) func(destinationID, root, snapshotID string) *bool
RemoteSnapshotChecker memoizes targeted checks within one response budget; each lookup names the repository root that holds the snapshot. A nil result means the remote copy could not be verified.
func RunSnapshotTag ¶ added in v2.15.0
RunSnapshotTag links committed snapshots to their durable backup record.
func ValidatePolicyUpdate ¶ added in v2.10.0
func ValidatePolicyUpdate(ctx context.Context, domain string, update backup.UpdateBackupPolicy, s3Service *s3.S3DestinationService) (backup.UpdateBackupPolicy, error)
ValidatePolicyUpdate applies the shared cron, retention, and destination rules used by backup policies.
func ValidateRecoveryKey ¶ added in v2.12.0
ValidateRecoveryKey checks that a key has the generated recovery key format.
Types ¶
type CreateSnapshotInput ¶ added in v2.13.1
type CreateSnapshotInput struct {
Mounts []mount.Mount
Sources []string
AsPath string
Tags []string
Globs []string
}
CreateSnapshotInput describes what one snapshot captures: the mounts to attach to the helper and the helper paths to back up. AsPath rewrites the snapshot path of a single source and cannot combine with several.
func RootSnapshotInput ¶ added in v2.13.1
func RootSnapshotInput(source mount.Mount, tags ...string) CreateSnapshotInput
RootSnapshotInput captures one mount with its contents at the snapshot root.
type DiscoveredSnapshot ¶
type DiscoveredSnapshot struct {
ID string `json:"id"`
Time time.Time `json:"time"`
Label string `json:"label"`
Tags []string `json:"tags"`
Summary struct {
TotalBytesProcessed int64 `json:"total_bytes_processed"`
} `json:"summary"`
}
DiscoveredSnapshot describes one snapshot found in a repository.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine owns repository serialization and backup admission.
func NewEngine ¶
func NewEngine(admission *runs.Admission, imageService *image.ImageService) *Engine
NewEngine builds the backup engine on the shared admission gate.
func (*Engine) AcquireRun ¶ added in v2.16.0
AcquireRun takes over the lease held for run, or acquires admission otherwise, such as after a restart. A lease parked for another run stays parked, so that run's task still finds its admission.
func (*Engine) Authorize ¶ added in v2.16.0
Authorize checks that the requester may still run the backup.
func (*Engine) ChangeRepositoryPassword ¶ added in v2.12.0
func (e *Engine) ChangeRepositoryPassword(ctx context.Context, dockerClient *client.Client, repository Repository, currentPassword, newPassword string) error
ChangeRepositoryPassword re-keys the repository; the scratch Rustic image has no shell, so the new password travels as an argument.
func (*Engine) ConfirmRunSnapshot ¶ added in v2.15.0
func (e *Engine) ConfirmRunSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, password, runID, snapshotID string) (Snapshot, error)
ConfirmRunSnapshot makes a validated snapshot discoverable by run ID.
func (*Engine) CreateSnapshot ¶
func (e *Engine) CreateSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, password, label string, input CreateSnapshotInput) (Snapshot, error)
CreateSnapshot backs the input's sources up into the repository as one snapshot. The repository is initialized on first use.
func (*Engine) FindRunSnapshot ¶ added in v2.15.0
func (e *Engine) FindRunSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, password, runID, snapshotID string) (Snapshot, bool, error)
FindRunSnapshot verifies a known snapshot or recovers its committed response by run tag.
func (*Engine) ForgetSnapshots ¶ added in v2.10.0
func (e *Engine) ForgetSnapshots(ctx context.Context, dockerClient *client.Client, repository Repository, password string, snapshotIDs []string) error
ForgetSnapshots removes the snapshots and prunes their data in a single pass; with no IDs it only prunes, skipping an uninitialized repository.
func (*Engine) Hold ¶ added in v2.16.0
Hold parks a lease won by a manual start for run until that run's task takes it over with AcquireRun. The returned func releases the lease if the run never took it, such as a start that failed to submit.
func (*Engine) ListSnapshotFiles ¶
func (e *Engine) ListSnapshotFiles(ctx context.Context, dockerClient *client.Client, repository Repository, password, snapshotID, filePath string, recursive bool) ([]string, error)
ListSnapshotFiles lists a snapshot path and returns paths relative to the snapshot root. A supplied path is nonrecursive unless recursive is true.
func (*Engine) ListSnapshots ¶
func (e *Engine) ListSnapshots(ctx context.Context, dockerClient *client.Client, repository Repository, password string) ([]DiscoveredSnapshot, error)
ListSnapshots enumerates every snapshot in the repository.
func (*Engine) ReadSnapshotTextFile ¶ added in v2.10.0
func (e *Engine) ReadSnapshotTextFile(ctx context.Context, dockerClient *client.Client, repository Repository, password, snapshotID, filePath string) (string, error)
ReadSnapshotTextFile returns one text file from a snapshot.
func (*Engine) Replicate ¶
func (e *Engine) Replicate(ctx context.Context, dockerClient *client.Client, from Repository, fromSnapshotID string, to Repository, password, label string, tags ...string) (Snapshot, error)
Replicate copies one snapshot into another repository through a temporary volume, never the live data. Rustic's native `copy` needs a TOML profile for the target, which the env-only Repository cannot express.
func (*Engine) RestoreSnapshot ¶
func (e *Engine) RestoreSnapshot(ctx context.Context, dockerClient *client.Client, repository Repository, password, snapshotID string, target mount.Mount, options RestoreOptions) error
RestoreSnapshot restores a snapshot (or one path inside it) onto the target mount.
func (*Engine) SetAuthorize ¶ added in v2.15.0
SetAuthorize sets the check Authorize applies to manual backup requesters.
type PolicyReconciliation ¶
type PolicyReconciliation[P, U any] struct { // Domain names the backup flavor in validation errors ("volume", "system"). Domain string DB *database.DB // Existing is every policy currently persisted for the reconciled scope. Existing []P ID func(*P) string UpdateID func(U) string // New returns the blank policy for created entries, pre-scoped by the // caller (e.g. with the volume name set). New func() P // Build validates an update and applies it to an existing or new policy. Build func(ctx context.Context, policy *P, update U) error // Persist overrides the default GORM transaction for settings-backed policies. Persist func(ctx context.Context, policies []P) error Unregister func(ctx context.Context, policyID string) Reschedule func(ctx context.Context, policy *P) }
PolicyReconciliation reconciles a full set of policy updates against the existing policies of one backup domain, then swaps the scheduled jobs.
type RecoveryKeyStore ¶ added in v2.12.0
type RecoveryKeyStore struct {
// contains filtered or unexported fields
}
RecoveryKeyStore persists the recovery key shared by the system and volume backup domains.
func NewRecoveryKeyStore ¶ added in v2.12.0
func NewRecoveryKeyStore(db *database.DB) *RecoveryKeyStore
NewRecoveryKeyStore builds the recovery key store.
func (*RecoveryKeyStore) Configured ¶ added in v2.12.0
func (s *RecoveryKeyStore) Configured(ctx context.Context) (bool, error)
Configured reports whether a recovery key is stored.
func (*RecoveryKeyStore) Get ¶ added in v2.12.0
func (s *RecoveryKeyStore) Get(ctx context.Context) (string, error)
Get returns the decrypted recovery key or ErrRecoveryKeyNotConfigured.
func (*RecoveryKeyStore) HoldRunKey ¶ added in v2.16.0
func (s *RecoveryKeyStore) HoldRunKey(ctx context.Context, runID, recoveryKey string) error
HoldRunKey keeps a recovery key entered for one backup run, encrypted, until ReleaseRunKey, so the run can resume after a restart without it ever entering the run's workflow payload.
func (*RecoveryKeyStore) ReleaseRunKey ¶ added in v2.16.0
func (s *RecoveryKeyStore) ReleaseRunKey(ctx context.Context, runID string) error
ReleaseRunKey forgets the key held for a run.
type RestoreOptions ¶
type RestoreOptions struct {
// DeleteExtra removes files in the target that are absent from the snapshot.
DeleteExtra bool
// SourcePath restores only this path inside the snapshot when non-empty.
SourcePath string
// DestinationPath overrides the restore target path inside the helper
// container; the target mount's path is used when empty.
DestinationPath string
// ExtraMounts are attached alongside the target, e.g. mounts nested inside it.
ExtraMounts []mount.Mount
}
RestoreOptions selects what a snapshot restore writes and where.
type SystemBackupRecoveryConfig ¶ added in v2.12.0
type SystemBackupRecoveryConfig struct {
database.BaseModel
EncryptedRecoveryKey string `gorm:"column:encrypted_recovery_key;type:text;not null"`
}
SystemBackupRecoveryConfig stores the encrypted recovery key; it must be reversible because Rustic needs the plaintext.
func (SystemBackupRecoveryConfig) TableName ¶ added in v2.12.0
func (SystemBackupRecoveryConfig) TableName() string
TableName is the recovery key table.