agentsvc

package
v1.20.0 Latest Latest
Warning

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

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

Documentation

Overview

Package agentsvc serves the Controller side of the Agent protocol: enrollment on its own listener, and (from the session milestone) the mTLS session every enrolled Agent holds open.

Index

Constants

View Source 
const DefaultHeartbeatTimeout = 30 * time.Second

DefaultHeartbeatTimeout is how long a Node may stay silent before it is marked UNREACHABLE.

Variables

View Source 
var ErrNotConnected = errors.New("the Node is not connected")

ErrNotConnected is returned when a Node has no live session.

Functions

func NewEnrollmentServer 

func NewEnrollmentServer(svc *Enrollment, cert *ServerCert) *grpc.Server

NewEnrollmentServer returns a gRPC server for enrollment over server-authenticated TLS 1.3. Agents have no client certificate yet; the token is their credential.

func NewSessionServer added in v1.7.0 

func NewSessionServer(svc *Sessions, cert *ServerCert, authority *ca.CA, src ArtifactSource) *grpc.Server

NewSessionServer returns the gRPC server for Agent sessions and, when src is set, artifact downloads: TLS 1.3 with a client certificate from the Controller CA required in the handshake.

Types

type ArtifactServer added in v1.11.0 

type ArtifactServer struct {
	agentv1.UnimplementedArtifactServiceServer
	// contains filtered or unexported fields
}

ArtifactServer serves ArtifactService.Fetch to Agents.

func NewArtifactServer added in v1.11.0 

func NewArtifactServer(sessions *Sessions, src ArtifactSource) *ArtifactServer

NewArtifactServer returns the artifact service; Nodes are authenticated as for sessions.

func (*ArtifactServer) Fetch added in v1.11.0 

func (a *ArtifactServer) Fetch(req *agentv1.FetchRequest, stream agentv1.ArtifactService_FetchServer) error

Fetch streams an artifact to a Node that runs a server needing it. Anything else, including artifacts that exist but belong to other Nodes' servers, is NOT_FOUND, so a Node learns nothing about other Nodes.

type ArtifactSource added in v1.11.0 

type ArtifactSource interface {
	Open(ctx context.Context, id uuid.UUID) (io.ReadCloser, domain.Artifact, error)
	OpenPlugin(ctx context.Context, id uuid.UUID) (io.ReadCloser, domain.PluginArtifact, error)
}

ArtifactSource opens artifacts from the Controller's cache.

type Enrollment 

type Enrollment struct {
	agentv1.UnimplementedEnrollmentServiceServer
	// contains filtered or unexported fields
}

Enrollment serves EnrollmentService: a one-time token and a CSR in, a Node certificate out.

func NewEnrollment 

func NewEnrollment(st *store.Store, authority *ca.CA, logger *slog.Logger, now func() time.Time) *Enrollment

NewEnrollment returns the enrollment service. now may be nil.

func (*Enrollment) Enroll 

func (e *Enrollment) Enroll(ctx context.Context, req *agentv1.EnrollRequest) (*agentv1.EnrollResponse, error)

Enroll checks the token, signs the CSR's public key for the token's Node and returns the certificate with the CA bundle. The token is never logged.

type RelaySource added in v1.18.0 

type RelaySource struct {
	NodeID uuid.UUID
	// Export, when set, exports this server's data (only Parts, if any).
	Export *uuid.UUID
	Parts  []domain.DataPart
	// Otherwise, a stored backup on DestinationID at Key.
	DestinationID uuid.UUID
	Key           string
}

RelaySource is data one Node sends for another to restore: a server's data (an export) or a stored backup.

type SafetyBackup added in v1.18.0 

type SafetyBackup struct {
	BackupID      uuid.UUID
	DestinationID uuid.UUID
}

SafetyBackup is a backup to take before a restore replaces data.

type ServerCert 

type ServerCert struct {
	// contains filtered or unexported fields
}

ServerCert is the Controller's CA-issued certificate for the Agent listeners, renewed automatically. It presents the CA certificate after the leaf, so an enrolling Agent can find the CA it pinned.

func NewServerCert 

func NewServerCert(authority *ca.CA, names []string, now func() time.Time) *ServerCert

NewServerCert returns a certificate source covering names, plus localhost and the host name.

func (*ServerCert) GetCertificate 

func (s *ServerCert) GetCertificate(*tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate is a tls.Config.GetCertificate callback.

type SessionConfig added in v1.7.0 

type SessionConfig struct {
	// HeartbeatTimeout defaults to DefaultHeartbeatTimeout; Agents
	// heartbeat three times within it.
	HeartbeatTimeout time.Duration
	// Now defaults to time.Now.
	Now func() time.Time
	// CA signs the certificates Agents rotate to.
	CA *ca.CA
	// RequestTimeout bounds waiting for a Node to answer a request or open
	// a stream (default 30 seconds).
	RequestTimeout time.Duration
}

SessionConfig tunes the session service.

type Sessions added in v1.7.0 

type Sessions struct {
	agentv1.UnimplementedAgentServiceServer
	// contains filtered or unexported fields
}

Sessions serves AgentService and keeps the live session of each Node. A Node is identified only by its client certificate.

func NewSessions added in v1.7.0 

func NewSessions(st *store.Store, logger *slog.Logger, cfg SessionConfig) *Sessions

NewSessions returns the session service.

func (*Sessions) Connect added in v1.7.0 

func (s *Sessions) Connect(stream agentv1.AgentService_ConnectServer) error

Connect runs one Agent session: Hello and Welcome, then heartbeats, inventories, status updates and events until the stream ends or a newer session from the same Node replaces it.

func (*Sessions) Console added in v1.12.0 

func (s *Sessions) Console(ctx context.Context, nodeID, serverID uuid.UUID, tail int) (io.ReadCloser, error)

Console streams a server's console: the last tail lines, then new output, until the reader is closed or ctx ends. Nothing is stored.

func (*Sessions) CreateBackup added in v1.18.0 

func (s *Sessions) CreateBackup(ctx context.Context, nodeID, serverID, backupID, destinationID uuid.UUID, trigger domain.BackupTrigger) error

CreateBackup asks a Node for a backup of one of its servers. The Node answers at once and reports the backup later.

func (*Sessions) DeleteFile added in v1.12.0 

func (s *Sessions) DeleteFile(ctx context.Context, nodeID, serverID uuid.UUID, path string) error

DeleteFile deletes a file or directory from a server's files.

func (*Sessions) DeleteStoredBackup added in v1.18.0 

func (s *Sessions) DeleteStoredBackup(ctx context.Context, nodeID, destinationID uuid.UUID, key string) error

DeleteStoredBackup asks a Node to delete a stored backup.

func (*Sessions) DestinationsChanged added in v1.18.0 

func (s *Sessions) DestinationsChanged()

DestinationsChanged sends every connected Agent the new destinations. Called after the change is committed.

func (*Sessions) Download added in v1.12.0 

func (s *Sessions) Download(ctx context.Context, nodeID, serverID uuid.UUID, path string) (io.ReadCloser, error)

Download streams a file from a server's files.

func (*Sessions) ListFiles added in v1.12.0 

func (s *Sessions) ListFiles(ctx context.Context, nodeID, serverID uuid.UUID, path string) ([]domain.FileEntry, bool, error)

ListFiles lists a directory of a server's files.

func (*Sessions) ListPluginJars added in v1.14.0 

func (s *Sessions) ListPluginJars(ctx context.Context, nodeID, serverID uuid.UUID) (domain.PluginJars, error)

ListPluginJars lists a server's plugin jars with what each declares.

func (*Sessions) MakeDirectory added in v1.12.0 

func (s *Sessions) MakeDirectory(ctx context.Context, nodeID, serverID uuid.UUID, path string) error

MakeDirectory creates a directory in a server's files.

func (*Sessions) MoveFile added in v1.12.0 

func (s *Sessions) MoveFile(ctx context.Context, nodeID, serverID uuid.UUID, from, to string) error

MoveFile moves a file or directory within a server's files.

func (*Sessions) NetworkChanged added in v1.19.0 

func (s *Sessions) NetworkChanged()

NetworkChanged sends every connected Agent the network's secret, and brings the proxy and the members up to date.

func (*Sessions) NodeAdminChanged added in v1.7.0 

func (s *Sessions) NodeAdminChanged(nodeID uuid.UUID, state domain.NodeAdminState)

NodeAdminChanged tells a connected Agent its Node's admin state changed.

func (*Sessions) ReadBackup added in v1.18.0 

func (s *Sessions) ReadBackup(ctx context.Context, nodeID, destinationID uuid.UUID, key string, decrypt bool) (io.ReadCloser, error)

ReadBackup streams a stored backup from a Node, decrypted (its zstd archive) or as stored.

func (*Sessions) RelayRestore added in v1.18.0 

func (s *Sessions) RelayRestore(ctx context.Context, src RelaySource, toNode, serverID, workflowID uuid.UUID, parts []domain.DataPart, safety *SafetyBackup) error

RelayRestore pipes data from one Node into a restore on another: Nodes never connect to each other. It returns once the receiving Node has restored the data (or failed to); RestoreFinished is reported too.

func (*Sessions) RestoreStored added in v1.18.0 

func (s *Sessions) RestoreStored(ctx context.Context, nodeID, serverID, workflowID, destinationID uuid.UUID, key string, parts []domain.DataPart, safety *SafetyBackup) error

RestoreStored asks a Node to restore one of its servers from a backup it can read itself. The Node answers at once; RestoreFinished follows.

func (*Sessions) RotateCertificate added in v1.8.0 

func (s *Sessions) RotateCertificate(nodeID uuid.UUID) error

RotateCertificate asks a connected Agent to rotate its certificate now.

func (*Sessions) SendCommand added in v1.12.0 

func (s *Sessions) SendCommand(ctx context.Context, nodeID, serverID uuid.UUID, line string) error

SendCommand types a line into a running server's console.

func (*Sessions) ServerChanged added in v1.8.0 

func (s *Sessions) ServerChanged(serverID uuid.UUID)

ServerChanged pushes a server's new spec to its Node's live session, if any. Called after the change is committed.

func (*Sessions) SetWorkflowEvents added in v1.18.0 

func (s *Sessions) SetWorkflowEvents(w WorkflowEvents)

SetWorkflowEvents sets who hears about restores.

func (*Sessions) Sweep added in v1.7.0 

func (s *Sessions) Sweep(ctx context.Context)

Sweep marks Nodes whose heartbeats stopped UNREACHABLE.

func (*Sessions) Upload added in v1.12.0 

func (s *Sessions) Upload(ctx context.Context, nodeID, serverID uuid.UUID, path string, content io.Reader) error

Upload writes content to a file in a server's files.

func (*Sessions) Watch added in v1.7.0 

func (s *Sessions) Watch(ctx context.Context)

Watch sweeps until ctx ends.

type StreamServer added in v1.12.0 

type StreamServer struct {
	agentv1.UnimplementedStreamServiceServer
	// contains filtered or unexported fields
}

StreamServer serves StreamService: Agents dial it for streams the Controller asked them to open.

func NewStreamServer added in v1.12.0 

func NewStreamServer(sessions *Sessions) *StreamServer

NewStreamServer returns the stream service.

func (*StreamServer) Stream added in v1.12.0 

func (ss *StreamServer) Stream(stream agentv1.StreamService_StreamServer) error

Stream matches an Agent's stream to the request that asked for it, from that same Node, and keeps it open while it is used.

type WorkflowEvents added in v1.18.0 

type WorkflowEvents interface {
	// RestoreFinished reports the end of a restore an Agent ran for a
	// workflow (the restore's ID is the workflow's); failure is empty when
	// it worked.
	RestoreFinished(ctx context.Context, serverID, workflowID uuid.UUID, failure string)
}

WorkflowEvents hears what Agents report about workflows.

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.