api

package
v0.12.4 Latest Latest
Warning

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

 Go to latest Published: Oct 1, 2026 License: AGPL-3.0 Imports: 26 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 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"`
}

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 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"`
}

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"`
}

HeartbeatResponse acknowledges a heartbeat and carries server-side agent settings

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
}

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) 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) 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) HandleCreateTarget 

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

HandleCreateTarget registers a new backup target

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) HandleDeleteTarget 

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

HandleDeleteTarget deletes a target

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) 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) 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) 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) 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) 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) HandleListTokens 

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

HandleListTokens lists all enrollment tokens

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) 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 (same token version, so the old token stays valid until it expires or the agent is revoked).

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) 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) 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) 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) 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) HandleVolumeTicket added in v0.7.2 

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

HandleVolumeTicket mints a per-volume backup ticket for a kubernetes run: identical claims to the session ticket, with the backup group swapped to the volume's group (which must extend the session group with "-pvc-"). Fetched just-in-time per volume so retried volumes 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) 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

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 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 asks for a per-volume backup ticket during a kubernetes run

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.