api

package
v1.0.0-alpha.6 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const BackupTicketHeader = "X-Fallbck-Backup-Ticket"

BackupTicketHeader carries the backup ticket on agent HTTP requests

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentEncryptionKey added in v0.13.0 

type AgentEncryptionKey struct {
	Mode            string    `json:"mode"`
	Key             string    `json:"key,omitempty"` // base64, 32 bytes
	Fingerprint     string    `json:"fingerprint,omitempty"`
	KeyCreatedAt    time.Time `json:"key_created_at,omitempty"`
	MasterPublicKey string    `json:"master_public_key,omitempty"`
}

AgentEncryptionKey is what an agent receives for an encrypted run (GET /agents/encryption-key, agent token + backup ticket)

type AgentUpdate added in v0.14.3 

type AgentUpdate struct {
	Version string `json:"version"`
	// URL serves the extracted binary and SHA256 its digest: what agents from before
	// release signing use. Newer agents ignore both.
	URL    string `json:"url"`
	SHA256 string `json:"sha256"`
	// ArchiveURL serves the goreleaser archive named Archive; ChecksumsURL and
	// BundleURL the release's checksums file and its Sigstore bundle. The agent
	// verifies the bundle, then the archive against the signed checksums.
	Archive      string `json:"archive,omitempty"`
	ArchiveURL   string `json:"archive_url,omitempty"`
	ChecksumsURL string `json:"checksums_url,omitempty"`
	BundleURL    string `json:"bundle_url,omitempty"`
}

AgentUpdate tells an agent to replace its binary: URL is the server path of the binary (agent token auth), SHA256 its digest

type CloneTargetRequest added in v0.11.0 

type CloneTargetRequest struct {
	Name       string `json:"name"`
	Namespace  string `json:"namespace"`
	PxarFormat string `json:"pxar_format,omitempty"`
}

CloneTargetRequest creates a target from an existing one with another namespace (POST /targets/{id}/clone); the API token is copied server-side

type CreateAPIKeyRequest 

type CreateAPIKeyRequest struct {
	Name      string     `json:"name"`
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

CreateAPIKeyRequest creates an admin API key for fallbck-ctl / automation

type CreateAPIKeyResponse 

type CreateAPIKeyResponse struct {
	ID        uuid.UUID  `json:"id"`
	Name      string     `json:"name"`
	RawKey    string     `json:"raw_key"`
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

CreateAPIKeyResponse returns the raw key exactly once

type CreateTargetRequest added in v0.6.0 

type CreateTargetRequest struct {
	Name        string `json:"name"`
	TargetType  string `json:"target_type"`
	Endpoint    string `json:"endpoint"`
	Datastore   string `json:"datastore"`
	Namespace   string `json:"namespace"`
	AuthToken   string `json:"auth_token"`
	Fingerprint string `json:"fingerprint"`
	TLSVerify   bool   `json:"tls_verify"`
	PxarFormat  string `json:"pxar_format"`
	// EncryptionMode none | encrypt ("" = none on create, unchanged on update).
	// KeyRingID attaches the target to an existing key ring (shared key, shared
	// dedup); empty with encrypt creates a ring named after the target.
	EncryptionMode string `json:"encryption_mode"`
	KeyRingID      string `json:"key_ring_id"`
	// MasterPublicKey (RSA, PEM) is stored on the target's key ring and wraps the
	// encryption key into every snapshot for recovery; nil keeps the stored one, ""
	// clears it
	MasterPublicKey *string `json:"master_public_key"`
}

CreateTargetRequest registers a backup target. AuthToken is the PBS API token ("user@realm!tokenid=secret" or with the PBSAPIToken= prefix); it is stored and used only server-side.

type CreateTokenRequest 

type CreateTokenRequest struct {
	Name      string    `json:"name"`
	MaxUses   int       `json:"max_uses"` // 0 for unlimited, default 1
	ExpiresAt time.Time `json:"expires_at"`
}

CreateTokenRequest is used by the admin UI/CLI to create an agent enrollment token

type CreateTokenResponse 

type CreateTokenResponse struct {
	ID        uuid.UUID `json:"id"`
	Name      string    `json:"name"`
	RawToken  string    `json:"raw_token"`
	ExpiresAt time.Time `json:"expires_at"`
	MaxUses   int       `json:"max_uses"`
}

CreateTokenResponse returns the raw one-time enrollment token to the admin

type DBCredentials added in v0.6.0 

type DBCredentials struct {
	Password string `json:"password"`
}

DBCredentials hands an agent the server-stored database password for a run

type EnrollRequest 

type EnrollRequest struct {
	Token     string `json:"token"`
	Hostname  string `json:"hostname"`
	OS        string `json:"os"`
	Arch      string `json:"arch"`
	Version   string `json:"version"`
	IPAddress string `json:"ip_address,omitempty"`
	// AgentType is "filesystem" (default) or "database"
	AgentType string `json:"agent_type,omitempty"`
	// PVEHost is set by a filesystem agent running on a Proxmox VE node
	PVEHost bool `json:"pve_host,omitempty"`
	// DockerHost is set by a filesystem agent that can reach a Docker daemon
	DockerHost bool `json:"docker_host,omitempty"`
	// DBEngines are the database engines a filesystem agent can back up (postgres,
	// mysql, mongodb by their client tools; mssql always). DBTools is the older yes/no
	// form, still sent for servers and agents that predate the list.
	DBEngines []string `json:"db_engines,omitempty"`
	DBTools   bool     `json:"db_tools,omitempty"`
}

EnrollRequest is sent by an agent to enroll with the central server

type EnrollResponse 

type EnrollResponse struct {
	AgentID        uuid.UUID `json:"agent_id"`
	TaskQueue      string    `json:"task_queue"`
	Namespace      string    `json:"namespace"`
	AuthToken      string    `json:"auth_token"`
	TokenExpiresAt time.Time `json:"token_expires_at"`
	ServerURL      string    `json:"server_url"`
	// ServerCAPEM optionally carries a private CA bundle the agent must trust for ServerURL
	ServerCAPEM string `json:"server_ca_pem,omitempty"`
	ProxyURL    string `json:"proxy_url"`
}

EnrollResponse contains the credentials and configuration needed for the agent to start. Everything the agent talks to (HTTP API, PBS proxy, Temporal gRPC) lives behind ServerURL.

type ExportKeyRequest added in v0.13.0 

type ExportKeyRequest struct {
	Passphrase string `json:"passphrase"`
	Hint       string `json:"hint"`
	// KeyID selects a retired key; default: the active one
	KeyID string `json:"key_id"`
}

ExportKeyRequest (POST /keyrings/{id}/export, POST /targets/{id}/encryption/export)

type HeartbeatRequest 

type HeartbeatRequest struct {
	AgentID uuid.UUID `json:"agent_id"`
	Status  string    `json:"status"`
	Version string    `json:"version"`
	// PVEHost reports whether the agent runs on a Proxmox VE node
	PVEHost bool `json:"pve_host,omitempty"`
	// DockerHost reports whether a Docker daemon answers on the agent's host
	DockerHost bool `json:"docker_host,omitempty"`
	// DBEngines / DBTools: see EnrollRequest
	DBEngines []string `json:"db_engines,omitempty"`
	DBTools   bool     `json:"db_tools,omitempty"`
	// Inventory is the compact inventory summary (inventory.Summary), attached every
	// few minutes rather than with every heartbeat
	Inventory json.RawMessage `json:"inventory,omitempty"`
	// SelfUpdate reports that the agent can replace its own binary
	SelfUpdate bool `json:"self_update,omitempty"`
	// UpdateError is the agent's last self-update failure, repeated until it restarts
	UpdateError string `json:"update_error,omitempty"`
}

HeartbeatRequest is sent by an agent periodically

type HeartbeatResponse added in v0.6.2 

type HeartbeatResponse struct {
	Status string `json:"status"`
	// DebugLogging tells the agent to raise its log level to debug (web UI toggle)
	DebugLogging bool `json:"debug_logging"`
	// Update is set when the agent should update itself to the server's version
	Update *AgentUpdate `json:"update,omitempty"`
}

HeartbeatResponse acknowledges a heartbeat and carries server-side agent settings

type ImportKeyRequest added in v0.13.0 

type ImportKeyRequest struct {
	KeyFile    string `json:"keyfile"`
	Passphrase string `json:"passphrase"`
}

ImportKeyRequest adopts an existing proxmox-backup-client key file as the active key

type KeyRingRequest added in v0.14.12 

type KeyRingRequest struct {
	Name            string  `json:"name"`
	MasterPublicKey *string `json:"master_public_key"`
}

KeyRingRequest creates or updates a ring (POST /keyrings, PUT /keyrings/{id})

type KeyRingResponse added in v0.14.12 

type KeyRingResponse struct {
	*db.KeyRing
	Keys []*db.TargetKey `json:"keys"`
}

KeyRingResponse is a ring with its key history

type MeResponse 

type MeResponse struct {
	Kind    string `json:"kind"`
	Subject string `json:"subject"`
	Email   string `json:"email,omitempty"`
	Name    string `json:"name,omitempty"`
}

MeResponse describes the authenticated admin principal

type MergeAgentRequest added in v0.10.1 

type MergeAgentRequest struct {
	Into uuid.UUID `json:"into"`
}

MergeAgentRequest moves the jobs and runs of one agent onto another and deletes the first (POST /agents/{id}/merge): used to retire a fallbck-db-agent in favour of the combined fallbck-agent on the same host

type MergeAgentResponse added in v0.10.1 

type MergeAgentResponse struct {
	Status    string    `json:"status"`
	From      uuid.UUID `json:"from"`
	Into      uuid.UUID `json:"into"`
	JobsMoved int64     `json:"jobs_moved"`
	RunsMoved int64     `json:"runs_moved"`
}

MergeAgentResponse reports what was moved

type Middleware 

type Middleware = func(http.Handler) http.Handler

Middleware is a chi-compatible middleware

type PBSCredentials added in v0.6.0 

type PBSCredentials struct {
	Endpoint    string `json:"endpoint"`
	Datastore   string `json:"datastore"`
	Namespace   string `json:"namespace"`
	Fingerprint string `json:"fingerprint"`
	TLSVerify   bool   `json:"tls_verify"`
	// APIToken is the canonical user@realm!tokenid:secret
	APIToken string `json:"api_token"`
}

PBSCredentials are handed to an agent for a job configured with direct_pbs

type RotateTokenResponse 

type RotateTokenResponse struct {
	AuthToken      string    `json:"auth_token"`
	TokenExpiresAt time.Time `json:"token_expires_at"`
}

RotateTokenResponse carries a freshly issued agent token

type RunProgressRequest added in v0.9.0 

type RunProgressRequest struct {
	RunID uuid.UUID `json:"run_id"`
	// Phase is the current human-readable step (optional)
	Phase string `json:"phase,omitempty"`
	// Items are per-unit statuses keyed by a stable id (PVC group, database) (optional)
	Items map[string]rundetail.ProgressItem `json:"items,omitempty"`
}

RunProgressRequest is posted by an agent during a run to update its live progress

type ServerAPI 

type ServerAPI struct {
	DB           *db.DB
	Temporal     client.Client
	Config       *config.ServerConfig
	TokenManager *auth.TokenManager
	// Verifier is used to invalidate cached agent state on revocation (may be nil)
	Verifier *auth.AgentVerifier
	// Scheduler keeps Temporal Schedules aligned with jobs (may be nil: tests, and a
	// server started without Temporal). A concrete pointer on purpose: a nil
	// *scheduler.Scheduler stored in an interface field would not compare equal to nil.
	Scheduler *scheduler.Scheduler
	// Updates mirrors the agent binary of the server's release for self-updating
	// agents (nil: feature off)
	Updates *agentupdate.Cache
}

ServerAPI holds database, Temporal client, config and token services for HTTP requests

func NewServerAPI 

func NewServerAPI(database *db.DB, temporalClient client.Client, cfg *config.ServerConfig, tm *auth.TokenManager, verifier *auth.AgentVerifier) *ServerAPI

NewServerAPI initializes the API service

func (*ServerAPI) HandleAgentEncryptionKey added in v0.13.0 

func (s *ServerAPI) HandleAgentEncryptionKey(w http.ResponseWriter, r *http.Request)

HandleAgentEncryptionKey hands an agent the key for the run named by its backup ticket. The ticket binds agent, job and target; the key is returned only while the ticket is valid and only for an encrypted target.

func (*ServerAPI) HandleAgentEnroll 

func (s *ServerAPI) HandleAgentEnroll(w http.ResponseWriter, r *http.Request)

HandleAgentEnroll processes an agent enrollment request with a one-time token and issues the agent its bearer token.

func (*ServerAPI) HandleAgentHeartbeat 

func (s *ServerAPI) HandleAgentHeartbeat(w http.ResponseWriter, r *http.Request)

HandleAgentHeartbeat updates agent last_seen_at and status

func (*ServerAPI) HandleAgentInventory added in v0.12.0 

func (s *ServerAPI) HandleAgentInventory(w http.ResponseWriter, r *http.Request)

HandleAgentInventory refreshes the agent's full inventory and stores it (POST /agents/{id}/inventory)

func (*ServerAPI) HandleAgentLogs added in v0.12.0 

func (s *ServerAPI) HandleAgentLogs(w http.ResponseWriter, r *http.Request)

HandleAgentLogs fetches the agent's recent log lines (POST /agents/{id}/logs)

func (*ServerAPI) HandleAgentUpdateArchive added in v0.14.12 

func (s *ServerAPI) HandleAgentUpdateArchive(w http.ResponseWriter, r *http.Request)

HandleAgentUpdateArchive serves the verified release archive for an OS/arch

func (*ServerAPI) HandleAgentUpdateBinary added in v0.14.3 

func (s *ServerAPI) HandleAgentUpdateBinary(w http.ResponseWriter, r *http.Request)

HandleAgentUpdateBinary serves the mirrored agent binary for an OS/arch (agents from before release signing)

func (*ServerAPI) HandleAgentUpdateBundle added in v0.14.12 

func (s *ServerAPI) HandleAgentUpdateBundle(w http.ResponseWriter, r *http.Request)

func (*ServerAPI) HandleAgentUpdateChecksums added in v0.14.12 

func (s *ServerAPI) HandleAgentUpdateChecksums(w http.ResponseWriter, r *http.Request)

HandleAgentUpdateChecksums serves the release's checksums file; HandleAgentUpdateBundle its Sigstore bundle. Both are mirrored with the first binary, so any mirrored platform makes them available.

func (*ServerAPI) HandleCancelRun added in v0.3.1 

func (s *ServerAPI) HandleCancelRun(w http.ResponseWriter, r *http.Request)

HandleCancelRun cancels an in-flight backup run. The Temporal workflow is cancelled, which tells the agent activity to stop; the workflow then finalises the run as "cancelled". Until that happens the run shows as "cancelling". A run that never started (still pending, or no workflow) is marked cancelled immediately.

func (*ServerAPI) HandleCloneTarget added in v0.11.0 

func (s *ServerAPI) HandleCloneTarget(w http.ResponseWriter, r *http.Request)

HandleCloneTarget creates a target from an existing one with a different namespace. The stored API token is copied on the server; it is never returned to a client.

func (*ServerAPI) HandleCreateAPIKey 

func (s *ServerAPI) HandleCreateAPIKey(w http.ResponseWriter, r *http.Request)

HandleCreateAPIKey mints an admin API key

func (*ServerAPI) HandleCreateJob 

func (s *ServerAPI) HandleCreateJob(w http.ResponseWriter, r *http.Request)

HandleCreateJob creates a backup job

func (*ServerAPI) HandleCreateKeyRing added in v0.14.12 

func (s *ServerAPI) HandleCreateKeyRing(w http.ResponseWriter, r *http.Request)

HandleCreateKeyRing creates a ring with a fresh active key

func (*ServerAPI) HandleCreateTarget 

func (s *ServerAPI) HandleCreateTarget(w http.ResponseWriter, r *http.Request)

HandleCreateTarget registers a new backup target

func (*ServerAPI) HandleCreateTenant added in v0.14.0 

func (s *ServerAPI) HandleCreateTenant(w http.ResponseWriter, r *http.Request)

HandleCreateTenant registers a tenant

func (*ServerAPI) HandleCreateToken 

func (s *ServerAPI) HandleCreateToken(w http.ResponseWriter, r *http.Request)

HandleCreateToken creates a new one-time enrollment token

func (*ServerAPI) HandleDBCredentials added in v0.6.0 

func (s *ServerAPI) HandleDBCredentials(w http.ResponseWriter, r *http.Request)

HandleDBCredentials hands a database agent the password stored on a database job for the run identified by its backup ticket. Like HandlePBSCredentials, the ticket must have been issued to the calling agent.

func (*ServerAPI) HandleDeleteAgent 

func (s *ServerAPI) HandleDeleteAgent(w http.ResponseWriter, r *http.Request)

HandleDeleteAgent removes an agent

func (*ServerAPI) HandleDeleteJob 

func (s *ServerAPI) HandleDeleteJob(w http.ResponseWriter, r *http.Request)

HandleDeleteJob deletes a job

func (*ServerAPI) HandleDeleteKeyRing added in v0.14.12 

func (s *ServerAPI) HandleDeleteKeyRing(w http.ResponseWriter, r *http.Request)

HandleDeleteKeyRing deletes an unused ring and its keys

func (*ServerAPI) HandleDeleteTarget 

func (s *ServerAPI) HandleDeleteTarget(w http.ResponseWriter, r *http.Request)

HandleDeleteTarget deletes a target

func (*ServerAPI) HandleDeleteTenant added in v0.14.0 

func (s *ServerAPI) HandleDeleteTenant(w http.ResponseWriter, r *http.Request)

HandleDeleteTenant removes a tenant no job references

func (*ServerAPI) HandleDeleteToken added in v0.6.0 

func (s *ServerAPI) HandleDeleteToken(w http.ResponseWriter, r *http.Request)

HandleDeleteToken invalidates an enrollment token immediately

func (*ServerAPI) HandleExportKeyRingKey added in v0.14.12 

func (s *ServerAPI) HandleExportKeyRingKey(w http.ResponseWriter, r *http.Request)

func (*ServerAPI) HandleExportTargetKey added in v0.13.0 

func (s *ServerAPI) HandleExportTargetKey(w http.ResponseWriter, r *http.Request)

HandleExportTargetKey returns a key of the target's ring as a key file download

func (*ServerAPI) HandleGetAgent 

func (s *ServerAPI) HandleGetAgent(w http.ResponseWriter, r *http.Request)

HandleGetAgent returns a single agent by ID

func (*ServerAPI) HandleGetJob 

func (s *ServerAPI) HandleGetJob(w http.ResponseWriter, r *http.Request)

HandleGetJob returns job by ID

func (*ServerAPI) HandleGetKeyRing added in v0.14.12 

func (s *ServerAPI) HandleGetKeyRing(w http.ResponseWriter, r *http.Request)

func (*ServerAPI) HandleGetRun added in v0.3.1 

func (s *ServerAPI) HandleGetRun(w http.ResponseWriter, r *http.Request)

HandleGetRun returns a single backup run

func (*ServerAPI) HandleGetTarget 

func (s *ServerAPI) HandleGetTarget(w http.ResponseWriter, r *http.Request)

HandleGetTarget gets target by ID

func (*ServerAPI) HandleGetTargetEncryption added in v0.13.0 

func (s *ServerAPI) HandleGetTargetEncryption(w http.ResponseWriter, r *http.Request)

HandleGetTargetEncryption returns the mode, ring, active key fingerprint and key history

func (*ServerAPI) HandleGetTenant added in v0.14.0 

func (s *ServerAPI) HandleGetTenant(w http.ResponseWriter, r *http.Request)

HandleGetTenant returns one tenant (credentials redacted)

func (*ServerAPI) HandleGetToken added in v0.11.0 

func (s *ServerAPI) HandleGetToken(w http.ResponseWriter, r *http.Request)

HandleGetToken returns one enrollment token (without its hash) including the agent that used it, which the onboarding page polls while waiting for an enrollment

func (*ServerAPI) HandleHealth 

func (s *ServerAPI) HandleHealth(w http.ResponseWriter, r *http.Request)

HandleHealth returns the system health status

func (*ServerAPI) HandleImportKeyRingKey added in v0.14.12 

func (s *ServerAPI) HandleImportKeyRingKey(w http.ResponseWriter, r *http.Request)

func (*ServerAPI) HandleImportTargetKey added in v0.13.0 

func (s *ServerAPI) HandleImportTargetKey(w http.ResponseWriter, r *http.Request)

HandleImportTargetKey adopts a key file as the active key of the target's ring

func (*ServerAPI) HandleListAPIKeys 

func (s *ServerAPI) HandleListAPIKeys(w http.ResponseWriter, r *http.Request)

HandleListAPIKeys lists API keys (hashes are never returned)

func (*ServerAPI) HandleListAgents 

func (s *ServerAPI) HandleListAgents(w http.ResponseWriter, r *http.Request)

HandleListAgents returns all registered agents

func (*ServerAPI) HandleListJobs 

func (s *ServerAPI) HandleListJobs(w http.ResponseWriter, r *http.Request)

HandleListJobs returns all jobs

func (*ServerAPI) HandleListKeyRings added in v0.14.12 

func (s *ServerAPI) HandleListKeyRings(w http.ResponseWriter, r *http.Request)

func (*ServerAPI) HandleListRuns 

func (s *ServerAPI) HandleListRuns(w http.ResponseWriter, r *http.Request)

HandleListRuns returns recent backup runs

func (*ServerAPI) HandleListTargets 

func (s *ServerAPI) HandleListTargets(w http.ResponseWriter, r *http.Request)

HandleListTargets returns all backup targets

func (*ServerAPI) HandleListTenants added in v0.14.0 

func (s *ServerAPI) HandleListTenants(w http.ResponseWriter, r *http.Request)

HandleListTenants returns every tenant (credentials redacted)

func (*ServerAPI) HandleListTokens 

func (s *ServerAPI) HandleListTokens(w http.ResponseWriter, r *http.Request)

HandleListTokens lists all enrollment tokens

func (*ServerAPI) HandleM365Credentials added in v0.14.0 

func (s *ServerAPI) HandleM365Credentials(w http.ResponseWriter, r *http.Request)

HandleM365Credentials hands an agent the tenant credentials of the Microsoft 365 job named by its backup ticket (agent token + ticket, like db-credentials)

func (*ServerAPI) HandleMe 

func (s *ServerAPI) HandleMe(w http.ResponseWriter, r *http.Request)

HandleMe returns the authenticated admin principal

func (*ServerAPI) HandleMergeAgent added in v0.10.1 

func (s *ServerAPI) HandleMergeAgent(w http.ResponseWriter, r *http.Request)

HandleMergeAgent moves the jobs and run history of one agent onto another agent and deletes the first. Every job must be runnable by the target (type and capability flags), which is what makes this safe for retiring a database agent once the combined fallbck-agent on the same host reports database tools.

func (*ServerAPI) HandlePBSCredentials added in v0.6.0 

func (s *ServerAPI) HandlePBSCredentials(w http.ResponseWriter, r *http.Request)

HandlePBSCredentials hands an agent the PBS connection details for a run whose job is configured with direct_pbs. The agent authenticates with its bearer token and presents the run's backup ticket; the ticket must belong to the agent and the job must be in direct mode. Jobs using the server tunnel never expose the token.

func (*ServerAPI) HandleRefreshTicket added in v0.9.5 

func (s *ServerAPI) HandleRefreshTicket(w http.ResponseWriter, r *http.Request)

HandleRefreshTicket re-issues a run's backup ticket with a new snapshot timestamp. Retried backup activities call it: PBS refuses a backup whose timestamp is not newer than the group's latest snapshot, so an attempt that finalised its snapshot but failed afterwards would otherwise make every retry fail with "backup timestamp is older than last backup". The agent authenticates with its bearer token and presents the current (still valid) ticket; every other claim is carried over unchanged.

func (*ServerAPI) HandleRequestAgentUpdate added in v0.14.3 

func (s *ServerAPI) HandleRequestAgentUpdate(w http.ResponseWriter, r *http.Request)

HandleRequestAgentUpdate asks an agent to update to the server's version on its next heartbeat

func (*ServerAPI) HandleRevokeAPIKey 

func (s *ServerAPI) HandleRevokeAPIKey(w http.ResponseWriter, r *http.Request)

HandleRevokeAPIKey revokes an API key

func (*ServerAPI) HandleRotateAgentToken 

func (s *ServerAPI) HandleRotateAgentToken(w http.ResponseWriter, r *http.Request)

HandleRotateAgentToken issues a fresh bearer token to an authenticated agent. The token version is bumped, so the presented token (and every other token of that agent, worker tokens included) stops validating at once. Worker tokens are short-lived on purpose and may not rotate themselves into a long-lived one.

func (*ServerAPI) HandleRotateKeyRing added in v0.14.12 

func (s *ServerAPI) HandleRotateKeyRing(w http.ResponseWriter, r *http.Request)

func (*ServerAPI) HandleRotateTargetKey added in v0.13.0 

func (s *ServerAPI) HandleRotateTargetKey(w http.ResponseWriter, r *http.Request)

HandleRotateTargetKey rotates the target's ring (every target on it switches key)

func (*ServerAPI) HandleRunProgress added in v0.9.0 

func (s *ServerAPI) HandleRunProgress(w http.ResponseWriter, r *http.Request)

HandleRunProgress records live progress for a run. The caller presents its agent bearer token and the run's backup ticket; the run must belong to the ticket's job and agent and still be active. Progress is best-effort — failures never fail a run.

func (*ServerAPI) HandleSetAgentAutoUpdate added in v0.14.3 

func (s *ServerAPI) HandleSetAgentAutoUpdate(w http.ResponseWriter, r *http.Request)

HandleSetAgentAutoUpdate toggles the per-agent auto-update opt-in

func (*ServerAPI) HandleSetAgentDebug added in v0.6.2 

func (s *ServerAPI) HandleSetAgentDebug(w http.ResponseWriter, r *http.Request)

HandleSetAgentDebug toggles remote debug logging for an agent; the agent applies it on its next heartbeat (within ~30s), no restart needed

func (*ServerAPI) HandleSetTargetEncryption added in v0.13.0 

func (s *ServerAPI) HandleSetTargetEncryption(w http.ResponseWriter, r *http.Request)

HandleSetTargetEncryption switches the mode, attaches a ring and sets or clears the ring's master public key

func (*ServerAPI) HandleSubTicket added in v0.14.0 

func (s *ServerAPI) HandleSubTicket(w http.ResponseWriter, r *http.Request)

HandleSubTicket mints a per-unit backup ticket: identical claims to the session ticket, with the backup group swapped to the unit's group. Kubernetes runs name one per volume (<cluster group>-pvc-<ns>-<name>), Microsoft 365 runs one per user, site or team (<job group>-<kind>-<name>). Fetched just-in-time per unit so retried units always hold a fresh ticket, with a fresh snapshot timestamp: PBS refuses a backup whose time is not newer than the group's latest snapshot, so a retry after an attempt that finalised its snapshot must not reuse the run's time.

func (*ServerAPI) HandleTargetCredentials added in v0.9.5 

func (s *ServerAPI) HandleTargetCredentials(w http.ResponseWriter, r *http.Request)

HandleTargetCredentials returns a target's PBS API token to an administrator, for restores with proxmox-backup-client (e.g. the Proxmox VE host restore runbook). The request is logged with the acting principal.

func (*ServerAPI) HandleTestTenant added in v0.14.0 

func (s *ServerAPI) HandleTestTenant(w http.ResponseWriter, r *http.Request)

HandleTestTenant acquires a Graph token with the stored credentials and reads the organization (POST /m365/tenants/{id}/test). The server itself talks to Microsoft here, so a failure can also mean the server has no outbound HTTPS; the error says so.

func (*ServerAPI) HandleTriggerJob 

func (s *ServerAPI) HandleTriggerJob(w http.ResponseWriter, r *http.Request)

HandleTriggerJob starts an on-demand backup execution for a job

func (*ServerAPI) HandleUpdateJob added in v0.6.0 

func (s *ServerAPI) HandleUpdateJob(w http.ResponseWriter, r *http.Request)

HandleUpdateJob replaces a job's configuration (name, agent, target, paths, schedule, enabled, direct_pbs). The job ID in the path wins over any in the body.

func (*ServerAPI) HandleUpdateKeyRing added in v0.14.12 

func (s *ServerAPI) HandleUpdateKeyRing(w http.ResponseWriter, r *http.Request)

HandleUpdateKeyRing renames a ring and sets or clears its master public key

func (*ServerAPI) HandleUpdateTarget added in v0.9.0 

func (s *ServerAPI) HandleUpdateTarget(w http.ResponseWriter, r *http.Request)

HandleUpdateTarget replaces a target's configuration. The API token is optional on update: leave auth_token blank to keep the stored token, or supply a new one to replace it. The path ID wins over any ID in the body.

func (*ServerAPI) HandleUpdateTenant added in v0.14.0 

func (s *ServerAPI) HandleUpdateTenant(w http.ResponseWriter, r *http.Request)

HandleUpdateTenant replaces a tenant's settings; blank credentials keep the stored ones

func (*ServerAPI) HandleWorkerToken added in v0.7.2 

func (s *ServerAPI) HandleWorkerToken(w http.ResponseWriter, r *http.Request)

HandleWorkerToken mints a short-lived secondary agent bearer for a run's worker pods (same agent identity, 6h TTL); requires the run's session ticket.

func (*ServerAPI) RegisterRoutes 

func (s *ServerAPI) RegisterRoutes(r chi.Router, admin, agent Middleware)

RegisterRoutes registers all API routes onto the Chi router. admin protects the administrative API, agent protects agent-authenticated endpoints.

type SetAgentDebugRequest added in v0.6.2 

type SetAgentDebugRequest struct {
	Enabled bool `json:"enabled"`
}

SetAgentDebugRequest toggles an agent's remote debug logging; the same shape toggles auto-update

type SubTicketRequest added in v0.14.0 

type SubTicketRequest struct {
	BackupID string `json:"backup_id"`
	// VolumeBackupID is the field name kubernetes agents send
	VolumeBackupID string `json:"volume_backup_id"`
}

SubTicketRequest asks for a per-unit backup ticket during a run that writes several snapshots: one per PVC of a kubernetes run, one per user / site / team of a Microsoft 365 run. The group must extend the run's own group.

type SubTicketResponse added in v0.14.0 

type SubTicketResponse = VolumeTicketResponse

SubTicketResponse is the sub-ticket answer (same shape for every job type)

type TargetCredentials added in v0.9.5 

type TargetCredentials struct {
	Endpoint    string `json:"endpoint"`
	Datastore   string `json:"datastore"`
	Namespace   string `json:"namespace,omitempty"`
	Fingerprint string `json:"fingerprint,omitempty"`
	TLSVerify   bool   `json:"tls_verify"`
	TokenID     string `json:"token_id"`
	Secret      string `json:"secret"`
	// Repository is the PBS_REPOSITORY value: <token id>@<host[:port]>:<datastore>
	Repository string `json:"repository"`
}

TargetCredentials hands an administrator the PBS connection details of a target in the form proxmox-backup-client expects (restores are done with PBS's own tools)

type TargetEncryption added in v0.13.0 

type TargetEncryption struct {
	Mode            string          `json:"mode"`
	KeyRingID       string          `json:"key_ring_id,omitempty"`
	KeyRingName     string          `json:"key_ring_name,omitempty"`
	Fingerprint     string          `json:"fingerprint,omitempty"`
	KeyCreatedAt    *time.Time      `json:"key_created_at,omitempty"`
	HasMasterKey    bool            `json:"has_master_key"`
	MasterPublicKey string          `json:"master_public_key,omitempty"`
	Keys            []*db.TargetKey `json:"keys"`
}

TargetEncryption describes a target's encryption (GET /targets/{id}/encryption and embedded in the target form response)

type TargetEncryptionRequest added in v0.13.0 

type TargetEncryptionRequest struct {
	// Mode: none | encrypt
	Mode string `json:"mode"`
	// KeyRingID attaches an existing ring (encrypt mode). Empty: keep the target's ring,
	// or create one named after the target when it has none.
	KeyRingID string `json:"key_ring_id"`
	// MasterPublicKey (PEM, optional) is set on the target's ring: every snapshot then
	// carries the encryption key wrapped with it for recovery; "" removes it. nil
	// keeps the stored one.
	MasterPublicKey *string `json:"master_public_key"`
}

TargetEncryptionRequest sets a target's encryption (PUT /targets/{id}/encryption)

type TenantRequest added in v0.14.0 

type TenantRequest struct {
	m365.Tenant
	Secret         string `json:"secret"`
	CertificatePEM string `json:"certificate_pem"`
	KeyPEM         string `json:"key_pem"`
}

TenantRequest creates or updates a tenant (POST /m365/tenants, PUT /m365/tenants/{id}). On update a blank secret or certificate keeps the stored one.

type TicketRefreshResponse added in v0.9.5 

type TicketRefreshResponse struct {
	Ticket     string `json:"ticket"`
	BackupTime int64  `json:"backup_time"`
}

TicketRefreshResponse carries a re-issued backup ticket and its snapshot timestamp

type VolumeTicketRequest added in v0.7.2 

type VolumeTicketRequest struct {
	// VolumeBackupID must extend the run's group: <cluster group>-pvc-<ns>-<name>
	VolumeBackupID string `json:"volume_backup_id"`
}

VolumeTicketRequest is what kubernetes agents post (older name of SubTicketRequest)

type VolumeTicketResponse added in v0.7.2 

type VolumeTicketResponse struct {
	Ticket     string `json:"ticket"`
	BackupTime int64  `json:"backup_time"`
}

VolumeTicketResponse carries the freshly minted ticket and the snapshot timestamp embedded in it (the worker must use the same one)

type WorkerTokenResponse added in v0.7.2 

type WorkerTokenResponse struct {
	AuthToken      string    `json:"auth_token"`
	TokenExpiresAt time.Time `json:"token_expires_at"`
}

WorkerTokenResponse carries a short-lived agent bearer for worker pods

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.