pbs

package
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: Oct 26, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

Documentation

Overview

Package pbs holds the server's Proxmox Backup Server helpers: API token parsing, key files and the token permission check. FallBCK never prunes, forgets or deletes anything on PBS, and the API tokens it is given should not carry the privileges to (Datastore.Backup only, which EvaluateToken checks). Retention is a PBS datastore prune job. Do not add mutating calls.

Index

Constants

View Source 
const (
	TokenOK      = "ok"      // Datastore.Backup within the target's datastore, nothing else
	TokenExcess  = "excess"  // more than that somewhere
	TokenMissing = "missing" // no Datastore.Backup on the target path: backups fail
	TokenError   = "error"   // the check itself failed
)

Token check statuses

View Source 
const MinPassphrase = 12

MinPassphrase is the shortest passphrase an exported key file may have. The file is the only way to decrypt the backups without the server, so it gets kept for years, often next to the backups; scrypt slows guessing, length does the rest. Importing an existing file takes whatever passphrase it was made with.

View Source 
const PrivBackup = "Datastore.Backup"

PrivBackup is the one privilege a FallBCK target token needs: FallBCK only speaks the backup protocol (snapshot notes travel in the manifest, retention is a PBS prune job), and Datastore.Backup also reads back the groups the token owns.

Variables

View Source 
var ErrInvalidAPIToken = errors.New("invalid PBS API token: expected user@realm!tokenid:secret")

ErrInvalidAPIToken is returned for tokens that cannot be parsed

Functions

func AuthorizationHeader added in v0.6.0 

func AuthorizationHeader(raw string) string

AuthorizationHeader returns the PBS Authorization header value for a token in any accepted spelling; malformed tokens are passed through so PBS reports the failure

func ExportKeyFile added in v0.13.0 

func ExportKeyFile(key [32]byte, passphrase, hint string) ([]byte, error)

ExportKeyFile renders the key as a passphrase-protected (scrypt) key file that proxmox-backup-client restores with (--keyfile)

func GenerateKey added in v0.13.0 

func GenerateKey() ([32]byte, string, error)

GenerateKey returns a fresh 32-byte key and its fingerprint

func KeyFingerprint added in v0.13.0 

func KeyFingerprint(key [32]byte) (string, error)

KeyFingerprint is the colon-separated fingerprint proxmox-backup shows for a key

func NormalizeAPIToken added in v0.6.0 

func NormalizeAPIToken(raw string) (string, error)

NormalizeAPIToken returns the canonical "user@realm!tokenid:secret" form

func SplitAPIToken added in v0.6.0 

func SplitAPIToken(raw string) (authID, secret string, err error)

SplitAPIToken parses a token in any accepted spelling into its auth id ("user@realm!tokenid") and secret

func TargetACLPath added in v1.0.0 

func TargetACLPath(datastore, namespace string) string

TargetACLPath is the PBS ACL path a target writes to

func TokenID added in v0.6.0 

func TokenID(raw string) string

TokenID returns the loggable part of a token (no secret)

func ValidateMasterPublicKey added in v0.13.0 

func ValidateMasterPublicKey(pemText string) (string, error)

ValidateMasterPublicKey checks an RSA public key in PEM form ("PUBLIC KEY" or "RSA PUBLIC KEY"), at least 2048 bits, and returns it normalised

Types

type BackupManifest 

type BackupManifest struct {
	BackupType BackupType `json:"backup-type"`
	BackupID   string     `json:"backup-id"`
	BackupTime int64      `json:"backup-time"`
	Files      []FileInfo `json:"files"`
	Signature  string     `json:"signature,omitempty"`
}

BackupManifest represents the PBS V2 manifest (index.json)

type BackupStats 

type BackupStats struct {
	BytesScanned  int64         `json:"bytes_scanned"`
	BytesUploaded int64         `json:"bytes_uploaded"`
	ChunkCount    int           `json:"chunk_count"`
	DedupRatio    float64       `json:"dedup_ratio"`
	Duration      time.Duration `json:"duration"`
	SnapshotID    string        `json:"snapshot_id"`
}

BackupStats summarizes an executed backup run

type BackupType 

type BackupType string

BackupType represents the type of backup in PBS (host, ct, vm) 

const (
	BackupTypeHost BackupType = "host"
	BackupTypeCT   BackupType = "ct"
	BackupTypeVM   BackupType = "vm"
)

type ChunkDigest 

type ChunkDigest [32]byte

ChunkDigest represents a SHA256 hex digest of a chunk

type FileInfo 

type FileInfo struct {
	Filename string `json:"filename"` // e.g. "root.pxar.didx" or "catalog.pcat1.didx"
	Size     int64  `json:"size"`
	Csum     string `json:"csum"`
}

FileInfo describes an archive or index file inside a snapshot

type ImportedKey added in v0.13.0 

type ImportedKey struct {
	Key         [32]byte
	Fingerprint string
	Created     time.Time
}

ImportedKey is a key read from a proxmox-backup-client key file

func ImportKeyFile added in v0.13.0 

func ImportKeyFile(data []byte, passphrase string) (ImportedKey, error)

ImportKeyFile reads a key file (passphrase-protected or plain)

type SnapshotIdentifier 

type SnapshotIdentifier struct {
	Datastore  string     `json:"datastore"`
	Namespace  string     `json:"namespace,omitempty"`
	BackupType BackupType `json:"backup_type"`
	BackupID   string     `json:"backup_id"`
	BackupTime int64      `json:"backup_time"` // Unix timestamp
}

SnapshotIdentifier uniquely identifies a PBS snapshot

func (SnapshotIdentifier) String 

func (s SnapshotIdentifier) String() string

type TokenCheck added in v1.0.0 

type TokenCheck struct {
	Status    string         `json:"status"`
	Findings  []TokenFinding `json:"findings,omitempty"`
	Error     string         `json:"error,omitempty"`
	TokenID   string         `json:"token_id,omitempty"`
	CheckedAt time.Time      `json:"checked_at"`
	// Permissions is PBS's answer (path → privilege → propagates), kept for the UI
	Permissions map[string]map[string]bool `json:"permissions,omitempty"`
}

TokenCheck is the stored result of checking a target's API token against PBS

func EvaluateToken added in v1.0.0 

func EvaluateToken(all, atTarget map[string]map[string]bool, datastore, namespace string) TokenCheck

EvaluateToken judges PBS's answer to GET /access/permissions for the token. all is the answer without a path (every path where the token holds something); atTarget the answer for the target's own path, which decides whether backups can run at all (the target's namespace need not appear in all when it has no ACL entry).

Datastore.Backup anywhere inside the target's datastore is fine: granting it on the datastore is the common setup and the token only owns the groups it wrote. Anything else, on any path, is excess. A privilege a propagating ancestor already explains is reported once, at that ancestor.

func (*TokenCheck) Warn added in v1.0.0 

func (c *TokenCheck) Warn() bool

Warn reports whether the check should show a warning (anything but ok)

type TokenFinding added in v1.0.0 

type TokenFinding struct {
	Path       string   `json:"path"`
	Privileges []string `json:"privileges"`
	Problem    string   `json:"problem"`
}

TokenFinding is one path where the token holds more than it should

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.