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
- Variables
- func AuthorizationHeader(raw string) string
- func ExportKeyFile(key [32]byte, passphrase, hint string) ([]byte, error)
- func GenerateKey() ([32]byte, string, error)
- func KeyFingerprint(key [32]byte) (string, error)
- func NormalizeAPIToken(raw string) (string, error)
- func SplitAPIToken(raw string) (authID, secret string, err error)
- func TargetACLPath(datastore, namespace string) string
- func TokenID(raw string) string
- func ValidateMasterPublicKey(pemText string) (string, error)
- type BackupManifest
- type BackupStats
- type BackupType
- type ChunkDigest
- type FileInfo
- type ImportedKey
- type SnapshotIdentifier
- type TokenCheck
- type TokenFinding
Constants ¶
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
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 ¶
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
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
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
GenerateKey returns a fresh 32-byte key and its fingerprint
func KeyFingerprint ¶ added in v0.13.0
KeyFingerprint is the colon-separated fingerprint proxmox-backup shows for a key
func NormalizeAPIToken ¶ added in v0.6.0
NormalizeAPIToken returns the canonical "user@realm!tokenid:secret" form
func SplitAPIToken ¶ added in v0.6.0
SplitAPIToken parses a token in any accepted spelling into its auth id ("user@realm!tokenid") and secret
func TargetACLPath ¶ added in v1.0.0
TargetACLPath is the PBS ACL path a target writes to
func ValidateMasterPublicKey ¶ added in v0.13.0
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 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
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