backup

package
v1.0.9 Latest Latest
Warning

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

 Go to latest Published: Apr 18, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package backup provides path validation helpers for backup operations.

Usage: 

absPath, err := backup.ValidateBackupPath(cfg.Backup.Dir, userSuppliedPath)

Package backup provides backup creation, listing, restoration, verification, pruning, and WAL archiving for nSelf projects.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ArchiveWAL added in v1.0.6 

func ArchiveWAL(ctx context.Context, opts ArchiveWALOptions) error

ArchiveWAL encrypts and uploads a single WAL file to the remote. This is the core logic for the nself-backup-archive helper binary.

func ConfigView added in v1.0.6 

func ConfigView(cfg *config.Config, format string) (string, error)

ConfigView returns the current backup configuration as a formatted string.

func Create added in v1.0.6 

func Create(ctx context.Context, cfg *config.Config, opts CreateOptions) error

Create performs a backup of the specified type. It writes the backup to the local backup directory and optionally uploads to the configured remote.

func FormatList added in v1.0.6 

func FormatList(backups []BackupEntry, format string) (string, error)

FormatList renders backup entries as a table or JSON string.

func FormatPruneJSON added in v1.0.6 

func FormatPruneJSON(result *PruneResult, keepDaily int) error

FormatPruneJSON prints a PruneResult as JSON to stdout.

func FormatStatus added in v1.0.6 

func FormatStatus(info *StatusInfo, format string) (string, error)

FormatStatus renders status info as a string.

func InitKey added in v1.0.6 

func InitKey(cfg *config.Config) (string, error)

InitKey generates an age keypair for backup encryption. Private key: ~/.config/nself/{project}-age.key (mode 0600) Public key: written to BACKUP_AGE_RECIPIENTS in the project .env.

func InstallSystemdUnits added in v1.0.6 

func InstallSystemdUnits(cfg *config.Config, opts SystemdInstallOptions) error

InstallSystemdUnits renders and writes unit files, then runs `systemctl daemon-reload` and enables each timer. Requires root.

func ListBackups 

func ListBackups(backupDir string) ([]string, error)

ListBackups returns the names of all regular files in backupDir. The returned slice is empty (not nil) when the directory contains no files. Directories and other non-regular entries are skipped.

func Restore added in v1.0.6 

func Restore(ctx context.Context, cfg *config.Config, opts RestoreOptions) error

Restore recovers a backup by ID or "latest".

func ValidateBackupPath 

func ValidateBackupPath(backupDir, userPath string) (string, error)

ValidateBackupPath resolves userPath relative to backupDir and verifies that the resolved absolute path is contained within backupDir. This prevents path traversal attacks (e.g. "../../../etc/passwd").

backupDir is the trusted root directory for backups (e.g. "/var/backups"). userPath is the caller-supplied relative or absolute path.

Returns the resolved absolute path on success, or an error if the path escapes backupDir.

Types

type ArchiveWALOptions added in v1.0.6 

type ArchiveWALOptions struct {
	WALFile       string // path to local WAL file
	Remote        string // rclone remote path
	AgeRecipient  string // age public key for encryption
	Timeline      string // PG timeline ID
	MaxRetries    int    // max upload retries (default: 3)
	RetryInterval time.Duration
}

ArchiveWALOptions holds configuration for WAL file archiving.

type BackupEntry added in v1.0.6 

type BackupEntry struct {
	ID        string    `json:"id"`
	Date      time.Time `json:"date"`
	Size      int64     `json:"size"`
	Type      string    `json:"type"`      // full, metadata, minio, wal
	Tag       string    `json:"tag"`       // user tag if present
	Encrypted bool      `json:"encrypted"` // .age suffix
}

BackupEntry holds parsed metadata for a single backup file.

func List added in v1.0.6 

func List(cfg *config.Config, opts ListOptions) ([]BackupEntry, error)

List returns backup entries from the local backup directory.

type BackupType added in v1.0.6 

type BackupType string

BackupType identifies the kind of backup to create. 

const (
	BackupTypeFull     BackupType = "full"
	BackupTypeWAL      BackupType = "wal"
	BackupTypeMetadata BackupType = "metadata"
	BackupTypeMinio    BackupType = "minio"
	BackupTypeAll      BackupType = "all"
)

type CreateOptions added in v1.0.6 

type CreateOptions struct {
	Type      BackupType // full, wal, metadata, minio, all
	Remote    string     // remote name override
	Encrypt   bool       // force encryption on
	NoEncrypt bool       // force encryption off
	Tag       string     // human label for this backup
	DryRun    bool       // preview only
}

CreateOptions holds flags for `nself backup create`.

type ListOptions added in v1.0.6 

type ListOptions struct {
	Remote string        // filter by remote name
	Env    string        // filter by environment
	Since  time.Duration // only show backups newer than this
	Format string        // table or json
}

ListOptions holds flags for `nself backup list`.

type PruneJSONEntry added in v1.0.6 

type PruneJSONEntry struct {
	Path    string `json:"path"`
	AgeDays int    `json:"age_days"`
}

PruneJSONEntry is one entry in the would_delete or kept arrays.

type PruneJSONReport added in v1.0.6 

type PruneJSONReport struct {
	DryRun      bool             `json:"dry_run"`
	KeepDaily   int              `json:"keep_daily"`
	WouldDelete []PruneJSONEntry `json:"would_delete"`
	Kept        []PruneJSONEntry `json:"kept"`
}

PruneJSONReport is the machine-readable output of `backup prune --format json`.

type PruneOptions added in v1.0.6 

type PruneOptions struct {
	DryRun      bool
	KeepDaily   int
	KeepWeekly  int
	KeepMonthly int
}

PruneOptions holds flags for `nself backup prune`.

type PruneResult added in v1.0.6 

type PruneResult struct {
	Kept   []string
	Pruned []string
	DryRun bool
}

PruneResult summarizes what was (or would be) pruned.

func Prune added in v1.0.6 

func Prune(cfg *config.Config, opts PruneOptions) (*PruneResult, error)

Prune removes old backups according to the retention policy. Retention: keep last N daily, N weekly (Sundays), N monthly (1st of month). Backups tagged "keep" are never deleted. WAL segments newer than the oldest surviving base backup are never deleted.

type RestoreOptions added in v1.0.6 

type RestoreOptions struct {
	BackupID    string   // backup ID or "latest"
	ToDir       string   // restore to alternate directory
	Only        []string // pg, minio, metadata — subset to restore
	PointInTime string   // ISO8601 timestamp for PITR
	DecryptKey  string   // path to age identity file
	Yes         bool     // skip confirmation
}

RestoreOptions holds flags for `nself backup restore`.

type StatusInfo added in v1.0.6 

type StatusInfo struct {
	LastRun          string `json:"last_run"`
	NextRun          string `json:"next_run"`
	Health           string `json:"health"` // healthy, warning, error
	TotalSize        string `json:"total_size"`
	BackupCount      int    `json:"backup_count"`
	RetentionDaily   int    `json:"retention_daily"`
	RetentionWeekly  int    `json:"retention_weekly"`
	RetentionMonthly int    `json:"retention_monthly"`
}

StatusInfo holds backup subsystem status.

func Status added in v1.0.6 

func Status(cfg *config.Config) (*StatusInfo, error)

Status computes and returns the current backup subsystem status.

type SystemdInstallOptions added in v1.0.6 

type SystemdInstallOptions struct {
	FullAt      string // "HH:MM" UTC, e.g. "03:00"
	WALEvery    string // e.g. "15m"
	PruneAt     string // "HH:MM" UTC, default "04:00"
	VerifyOnDay string // systemd OnCalendar day name (Sun..Sat), default "Sun"
	VerifyAt    string // "HH:MM", default "05:00"
	UnitDir     string // default /etc/systemd/system
	EnvFile     string // default /etc/nself/backup.env
	BinaryPath  string // default /usr/local/bin/nself
	ProjectDir  string // working directory for nself commands
	Remote      string // e.g. b2-nclaw
	DryRun      bool
}

SystemdInstallOptions controls install of nself-backup systemd units.

type SystemdUnitFiles added in v1.0.6 

type SystemdUnitFiles map[string]string

SystemdUnitFiles maps filename -> unit contents.

func RenderSystemdUnits added in v1.0.6 

func RenderSystemdUnits(cfg *config.Config, opts SystemdInstallOptions) (SystemdUnitFiles, error)

RenderSystemdUnits produces the unit files needed for unattended backup, verify, and prune without writing to disk. Returns a map suitable for writing into /etc/systemd/system.

type VerifyOptions added in v1.0.6 

type VerifyOptions struct {
	BackupID    string // backup ID or "latest"
	RestoreTest bool   // spin up test container and restore
	Cleanup     bool   // remove test container after verify
	Keep        bool   // keep test container for inspection
}

VerifyOptions holds flags for `nself backup verify`.

type VerifyResult added in v1.0.6 

type VerifyResult struct {
	BackupID  string    `json:"backup_id"`
	Verified  bool      `json:"verified"`
	StartedAt time.Time `json:"started_at"`
	Duration  string    `json:"duration"`
	Method    string    `json:"method"` // checksum, restore-test
	Details   string    `json:"details"`
}

VerifyResult holds the outcome of a backup verification.

func Verify added in v1.0.6 

func Verify(ctx context.Context, cfg *config.Config, opts VerifyOptions) (*VerifyResult, error)

Verify checks backup integrity, optionally performing a restore test.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.