Documentation
¶
Overview ¶
Package proxy carries agents' Proxmox Backup Server sessions through the FallBCK server.
PBS ingests backups over its own protocol: an HTTP/1.1 request upgraded with `proxmox-backup-protocol-v1`, after which the connection speaks HTTP/2. Agents never hold PBS credentials; instead the server opens the session (this file), scoped to the snapshot identity bound into the agent's backup ticket, and pipes the bytes to the agent over a gRPC stream (tunnel.go). The agent side (client.go) exposes that stream as a net.Conn for gopbs.
Index ¶
- Constants
- Variables
- func Dial(ctx context.Context, cc grpc.ClientConnInterface, ticket string) (net.Conn, error)
- func DialPBS(ctx context.Context, target *db.BackupTarget) (net.Conn, error)
- func OpenBackupSession(ctx context.Context, target *db.BackupTarget, p SessionParams) (net.Conn, error)
- func TokenPermissions(ctx context.Context, target *db.BackupTarget, path string) (map[string]map[string]bool, error)
- func UpgradeBackupSession(ctx context.Context, conn net.Conn, host, apiToken string, p SessionParams) (net.Conn, error)
- type BackupTunnel
- type SessionOpener
- type SessionParams
- type TargetStore
- type UpgradeError
Constants ¶
const ( ServiceName = "fallbck.pbs.v1.BackupTunnel" MethodSession = "/" + ServiceName + "/Session" TicketMetadataKey = "x-fallbck-backup-ticket" )
gRPC wire identifiers of the tunnel. Frames are google.protobuf.BytesValue, so no generated code is needed on either side.
const BackupProtocol = "proxmox-backup-protocol-v1"
BackupProtocol is the PBS backup protocol identifier
Variables ¶
var ServiceDesc = grpc.ServiceDesc{ ServiceName: ServiceName, HandlerType: (*sessionServer)(nil), Streams: []grpc.StreamDesc{{ StreamName: "Session", Handler: func(srv any, ss grpc.ServerStream) error { return srv.(sessionServer).Session(ss) }, ServerStreams: true, ClientStreams: true, }}, Metadata: "fallbck/pbs/v1/tunnel", }
ServiceDesc describes the tunnel service for grpc.Server / grpc.ClientConn
var SessionStreamDesc = grpc.StreamDesc{StreamName: "Session", ServerStreams: true, ClientStreams: true}
SessionStreamDesc is the client-side stream descriptor
Functions ¶
func Dial ¶ added in v0.6.0
Dial opens a tunnelled PBS backup session through the FallBCK server. cc must carry the agent's bearer token (per-RPC credentials); ticket is the backup ticket for the run. The returned connection already speaks the backup protocol (HTTP/2) and is meant for gopbs's pbs.Config.DialSession.
func OpenBackupSession ¶ added in v0.6.0
func OpenBackupSession(ctx context.Context, target *db.BackupTarget, p SessionParams) (net.Conn, error)
OpenBackupSession dials the target and opens a backup session for p
func TokenPermissions ¶ added in v1.0.0
func TokenPermissions(ctx context.Context, target *db.BackupTarget, path string) (map[string]map[string]bool, error)
TokenPermissions asks PBS what the target's API token may do: GET /api2/json/access/permissions as the token itself, which needs no privilege ("limited to own privileges"). path "" lists every path where the token holds something; a path asks about that one. TLS is the backup tunnel's: the target's fingerprint pin, else chain verification unless TLSVerify is off.
func UpgradeBackupSession ¶ added in v0.6.0
func UpgradeBackupSession(ctx context.Context, conn net.Conn, host, apiToken string, p SessionParams) (net.Conn, error)
UpgradeBackupSession performs the PBS protocol upgrade on conn with the target's API token for the snapshot described by p. On success the returned connection speaks HTTP/2 (the backup session); on refusal the error is an *UpgradeError.
Types ¶
type BackupTunnel ¶ added in v0.6.0
type BackupTunnel struct {
// contains filtered or unexported fields
}
BackupTunnel is the server side: it authenticates the agent's backup ticket, opens the PBS session it describes with the target's API token, and pipes bytes.
func NewBackupTunnel ¶ added in v0.6.0
func NewBackupTunnel(tm *auth.TokenManager, targets TargetStore, logger *slog.Logger) *BackupTunnel
NewBackupTunnel creates the tunnel service
func (*BackupTunnel) Register ¶ added in v0.6.0
func (t *BackupTunnel) Register(s grpc.ServiceRegistrar)
Register adds the tunnel service to a gRPC server (e.g. the agent gateway, whose interceptors authenticate the agent token first)
func (*BackupTunnel) Session ¶ added in v0.6.0
func (t *BackupTunnel) Session(ss grpc.ServerStream) error
Session handles one tunnelled backup session
func (*BackupTunnel) WithOpener ¶ added in v0.6.0
func (t *BackupTunnel) WithOpener(open SessionOpener) *BackupTunnel
WithOpener overrides how PBS sessions are opened (tests)
type SessionOpener ¶ added in v0.6.0
type SessionOpener func(ctx context.Context, target *db.BackupTarget, p SessionParams) (net.Conn, error)
SessionOpener opens a PBS backup session for a target (OpenBackupSession by default)
type SessionParams ¶ added in v0.6.0
type SessionParams struct {
Datastore string
Namespace string
BackupType string // host | vm | ct
BackupID string
BackupTime int64 // unix seconds
}
SessionParams identifies the snapshot a backup session writes
type TargetStore ¶ added in v0.6.0
type TargetStore interface {
GetTargetByID(ctx context.Context, id uuid.UUID, scope db.Scope) (*db.BackupTarget, error)
}
TargetStore looks up backup targets (implemented by *db.DB)
type UpgradeError ¶ added in v0.6.0
UpgradeError is returned when PBS refuses the protocol upgrade
func (*UpgradeError) Error ¶ added in v0.6.0
func (e *UpgradeError) Error() string
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package pbstest is a minimal fake Proxmox Backup Server for tests: it accepts the backup-protocol upgrade over TLS and implements the session endpoints gopbs uses (dynamic index create/append/close, chunk and blob upload, previous, finish).
|
Package pbstest is a minimal fake Proxmox Backup Server for tests: it accepts the backup-protocol upgrade over TLS and implements the session endpoints gopbs uses (dynamic index create/append/close, chunk and blob upload, previous, finish). |