backupproxy

package
v0.3.2 Latest Latest
Warning

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

 Go to latest Published: Apr 13, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package backupproxy provides a pull-mode backup architecture where a server (running on the PBS machine) orchestrates backups by walking a remote client's filesystem, encoding pxar archives, chunking with buzhash, and uploading to a backup store. The client only serves raw filesystem data.

The transport between server and client is pluggable — this package defines interfaces and message types. Users provide their own transport implementation (gRPC, HTTP, SSH, etc.).

PBS Reader Protocol

For restoring backups, the PBSReader type provides access to the Proxmox Backup Server reader protocol (proxmox-backup-reader-protocol-v1) via HTTP/2. This enables efficient downloading of:

  • Index files (.didx, .fidx, .blob) via GET /download
  • Individual chunks by digest via GET /chunk

The reader integrates with the datastore.Restorer to reconstruct files from their chunks, supporting both full file restoration and partial/range reads.

Example: 

reader := backupproxy.NewPBSReader(cfg, "host", "mybackup", backupTime)
if err := reader.Connect(ctx); err != nil {
    return err
}
defer reader.Close()

// Download index
didxData, _ := reader.DownloadFile("root.pxar.didx")
idx, _ := datastore.ReadDynamicIndex(didxData)

// Restore entire file
var buf bytes.Buffer
reader.RestoreFile(idx, &buf)

// Or restore just a range (e.g., bytes 1024-2048)
reader.RestoreFileRange(idx, 1024, 1024, &buf)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BackupConfig 

type BackupConfig struct {
	Store       string               // datastore name
	BackupType  datastore.BackupType // vm, ct, or host
	BackupID    string               // backup identifier
	BackupTime  int64
	Namespace   string         // Unix timestamp for this snapshot
	Compress    bool           // compress chunks with zstd
	ChunkConfig buzhash.Config // buzhash chunking parameters
}

BackupConfig holds parameters for a single backup operation.

type BackupResult 

type BackupResult struct {
	Manifest   *datastore.Manifest
	TotalBytes int64
	FileCount  int
	DirCount   int
	Duration   time.Duration
}

BackupResult describes the outcome of a backup operation.

type BackupSession 

type BackupSession interface {
	UploadArchive(ctx context.Context, name string, data io.Reader) (*UploadResult, error)
	UploadBlob(ctx context.Context, name string, data []byte) error
	Finish(ctx context.Context) (*datastore.Manifest, error)
}

BackupSession represents an active backup upload session.

type ClientProvider 

type ClientProvider interface {
	Stat(ctx context.Context, path string) (format.Stat, error)
	ReadDir(ctx context.Context, path string) ([]DirEntry, error)
	ReadFile(ctx context.Context, path string, offset, length int64) ([]byte, error)
	ReadLink(ctx context.Context, path string) (string, error)
}

ClientProvider is the interface the server uses to access client data. Transport implementations bridge this to the actual network. Each method call corresponds to one request-response round trip.

type DirEntry 

type DirEntry struct {
	Name string
	Stat format.Stat
}

DirEntry represents a single entry from a directory listing on the client.

type FileSystemAccessor 

type FileSystemAccessor interface {
	Stat(path string) (format.Stat, error)
	ReadDir(path string) ([]DirEntry, error)
	ReadFile(path string, offset, length int64) ([]byte, error)
	ReadLink(path string) (string, error)
}

FileSystemAccessor is the interface the client uses to access the local filesystem. Users provide their own implementation. This indirection allows testing without a real filesystem and running in constrained environments.

type LocalClient 

type LocalClient struct {
	// contains filtered or unexported fields
}

LocalClient implements ClientProvider by delegating to a FileSystemAccessor. This is the client-side component: runs on the machine being backed up.

func NewLocalClient 

func NewLocalClient(fs FileSystemAccessor) *LocalClient

NewLocalClient creates a client backed by the given FileSystemAccessor.

func (*LocalClient) ReadDir 

func (lc *LocalClient) ReadDir(_ context.Context, path string) ([]DirEntry, error)

func (*LocalClient) ReadFile 

func (lc *LocalClient) ReadFile(_ context.Context, path string, offset, length int64) ([]byte, error)
func (lc *LocalClient) ReadLink(_ context.Context, path string) (string, error)

func (*LocalClient) Stat 

func (lc *LocalClient) Stat(_ context.Context, path string) (format.Stat, error)

type LocalStore 

type LocalStore struct {
	// contains filtered or unexported fields
}

LocalStore implements RemoteStore using a local filesystem directory. It uses datastore.ChunkStore for chunk storage and writes index/blob files to disk. Intended for testing and offline backups.

func NewLocalStore 

func NewLocalStore(baseDir string, config buzhash.Config, compress bool) (*LocalStore, error)

NewLocalStore creates a LocalStore backed by the given directory.

func (*LocalStore) StartSession 

func (ls *LocalStore) StartSession(_ context.Context, config BackupConfig) (BackupSession, error)

StartSession creates a new local backup session.

type PBSConfig 

type PBSConfig struct {
	BaseURL       string // PBS API base URL (e.g. "https://pbs:8007/api2/json")
	Datastore     string // target datastore name
	AuthToken     string // PBS API token ("TOKENID:SECRET")
	SkipTLSVerify bool   // disable TLS certificate verification
	Namespace     string // optional namespace for the backup
}

PBSConfig holds configuration for connecting to a Proxmox Backup Server.

type PBSReader 

type PBSReader struct {
	// contains filtered or unexported fields
}

PBSReader provides read access to a PBS datastore via the reader protocol.

func NewPBSReader 

func NewPBSReader(config PBSConfig, backupType, backupID string, backupTime int64) *PBSReader

NewPBSReader creates a new PBS reader for the given backup snapshot.

func (*PBSReader) AsChunkSource 

func (r *PBSReader) AsChunkSource() datastore.ChunkSource

AsChunkSource returns a ChunkSource interface for the restorer.

func (*PBSReader) Close 

func (r *PBSReader) Close() error

Close closes the reader connection.

func (*PBSReader) Connect 

func (r *PBSReader) Connect(ctx context.Context) error

Connect establishes the H2 reader connection to PBS.

func (*PBSReader) DownloadChunk 

func (r *PBSReader) DownloadChunk(digest [32]byte) ([]byte, error)

DownloadChunk downloads a chunk by its digest. The reader protocol requires that the index file referencing this chunk has been downloaded first (via DownloadFile), which populates the server-side allowed_chunks set.

func (*PBSReader) DownloadFile 

func (r *PBSReader) DownloadFile(fileName string) ([]byte, error)

DownloadFile downloads an index file (.didx, .fidx, .blob) from PBS.

func (*PBSReader) RestoreFile 

func (r *PBSReader) RestoreFile(idx *datastore.DynamicIndexReader, w io.Writer) error

RestoreFile restores a complete file from a dynamic index. This downloads all chunks and reconstructs the file content. Each chunk download uses a fresh connection to avoid H2 stream multiplexing issues with PBS.

func (*PBSReader) RestoreFileRange 

func (r *PBSReader) RestoreFileRange(idx *datastore.DynamicIndexReader, offset, length uint64, w io.Writer) error

RestoreFileRange restores a specific byte range from a file. Useful for partial reads without downloading the entire file.

type PBSRemoteStore 

type PBSRemoteStore struct {
	// contains filtered or unexported fields
}

PBSRemoteStore implements RemoteStore via the PBS H2 backup protocol.

func NewPBSRemoteStore 

func NewPBSRemoteStore(config PBSConfig, chunkCfg buzhash.Config, compress bool) *PBSRemoteStore

NewPBSRemoteStore creates a PBS remote store with the given configuration.

func (*PBSRemoteStore) StartSession 

func (ps *PBSRemoteStore) StartSession(ctx context.Context, config BackupConfig) (BackupSession, error)

StartSession dials PBS via H2 upgrade and returns a backup session.

type RemoteStore 

type RemoteStore interface {
	StartSession(ctx context.Context, config BackupConfig) (BackupSession, error)
}

RemoteStore abstracts the backup storage backend.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server orchestrates pull backups: walks the client filesystem, encodes a pxar archive, chunks it with buzhash, and uploads to a RemoteStore.

func NewServer 

func NewServer(client ClientProvider, store RemoteStore) *Server

NewServer creates a backup server with the given client provider and store.

func (*Server) RunBackup 

func (s *Server) RunBackup(ctx context.Context, root string, config BackupConfig) (*BackupResult, error)

RunBackup executes a full pull backup of the given root path from the client.

type UploadResult 

type UploadResult struct {
	Filename string   // e.g., "root.pxar.didx"
	Size     uint64   // total index size
	Digest   [32]byte // SHA-256 of the index
}

UploadResult describes the outcome of an archive upload.

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.