Documentation
¶
Overview ¶
Package host runs the host role: node agent and coordinator in one process on a Linux host without Kubernetes.
Index ¶
- Constants
- Variables
- func Deenroll(ctx context.Context, cfg *config.Config, reason string, d Deps) (err error)
- func Export(cfg *config.Config, fromSeq uint64, w io.Writer, d Deps) error
- func Run(ctx context.Context, cfg *config.Config, log *slog.Logger) error
- type BundleHealth
- type Clock
- type Deps
- type Freshness
- type Health
- type Host
- func (h *Host) Commit(_ context.Context, r admin.CommitReceipt) error
- func (h *Host) Deenroll(ctx context.Context, reason string) error
- func (h *Host) Export(_ context.Context, fromSeq uint64, w io.Writer) error
- func (h *Host) Investigate(ctx context.Context, req admin.InvestigateRequest) (any, error)
- func (h *Host) Run(ctx context.Context) (err error)
- func (h *Host) Status(context.Context) (any, error)
- type Investigator
- type JournalReader
- type LogsHealth
- type MetricsHealth
- type RuleHealth
- type ScrapeHealth
- type SessionStatus
- type SpoolHealth
- type Status
- type TSDBHealth
Constants ¶
const ( ExportRollBytes = 64 << 20 ExportRollAge = time.Hour )
Export file rolling limits for the air-gap profile.
const ( SpoolDirName = "spool" TSDBDirName = "tsdb" MetaFileName = "meta.db" )
State directory layout.
const ( DefaultCollectInterval = time.Minute DefaultTick = 10 * time.Second DefaultDiskInterval = time.Minute )
Defaults.
const DeenrollDrainTimeout = 30 * time.Second
DeenrollDrainTimeout bounds how long offline de-enrollment waits for spooled records to be committed first.
Variables ¶
var DefaultJournalDirs = []string{"/var/log/journal", "/run/log/journal"}
DefaultJournalDirs are read when host.journalDir is empty.
var ErrKubernetesNode = errors.New("host mode refuses to run on a Kubernetes node; install the Helm chart instead (docs/install-kubernetes.md)")
ErrKubernetesNode is returned when host mode is started on a Kubernetes node.
var ErrNoInvestigator = errors.New("host: no investigation service is configured on this agent")
ErrNoInvestigator is returned when this agent was started without investigation tools.
var ErrRunning = errors.New("the agent is running and holds the state directory lock; use its admin socket")
ErrRunning is returned by offline operations while an agent holds the state directory lock.
var Version = "dev"
Version is the agent version reported to the control plane; main sets it from its ldflags.
Functions ¶
func Deenroll ¶
Deenroll connects a stopped host agent with its stored credential, de-enrolls it, and clears the credential (PRD A6).
Types ¶
type BundleHealth ¶
type BundleHealth struct {
Version string `json:"version,omitempty"`
Unsupported map[string]string `json:"unsupported,omitempty"`
Error string `json:"error,omitempty"`
}
BundleHealth reports the active rule bundle.
type Deps ¶
type Deps struct {
Facts hostfacts.Options
// FSRoot is the root filesystem for kubelet detection and node_exporter.
FSRoot string
MetricsCollectors []string
OpenJournal func(journal.Options) (JournalReader, error)
// Roots overrides cfg.Trust.
Roots *bundle.Roots
Clock Clock
Tunnel tunnel.Options
Logger *slog.Logger
Investigator Investigator
// CollectInterval is the host state collection period.
CollectInterval time.Duration
Tick time.Duration
// Ticks replaces the internal tick timer.
Ticks <-chan time.Time
OnCycle func(time.Time)
HealthInterval time.Duration
BackoffBase time.Duration
BackoffMax time.Duration
}
Deps injects host sources and timing; zero values select the production defaults.
type Freshness ¶
type Freshness struct {
State time.Time `json:"state,omitzero"`
Metrics time.Time `json:"metrics,omitzero"`
Journal time.Time `json:"journal,omitzero"`
}
Freshness is the time of the last successful collection per source.
type Health ¶
type Health struct {
Role string `json:"role"`
Agent protocol.AgentInfo `json:"agent"`
TargetID string `json:"target_id"`
WriterID string `json:"writer_id"`
Incarnation uint64 `json:"incarnation"`
Epoch string `json:"epoch,omitempty"`
Head uint64 `json:"head"`
Capabilities []string `json:"capabilities"`
Freshness Freshness `json:"freshness"`
Spool SpoolHealth `json:"spool"`
Disk disk.Report `json:"disk"`
TSDB *TSDBHealth `json:"tsdb,omitempty"`
Metrics *MetricsHealth `json:"metrics,omitempty"`
Bundle BundleHealth `json:"bundle"`
Rules []RuleHealth `json:"rules"`
ScrapeTargets []ScrapeHealth `json:"scrape_targets,omitempty"`
RejectedEndpoints map[string]string `json:"rejected_endpoints,omitempty"`
Logs LogsHealth `json:"logs"`
EvidenceLimited []string `json:"evidence_limited_rules"`
Identity machineState `json:"identity"`
AirGap bool `json:"airgap"`
Errors map[string]string `json:"errors,omitempty"`
}
Health is the agent.health payload (PRD 8.1 host fields).
type Host ¶
type Host struct {
// contains filtered or unexported fields
}
Host is one host agent.
func New ¶
New validates the configuration and applies dependency defaults; nothing is opened until Run.
func (*Host) Deenroll ¶
Deenroll implements admin.Backend: revoke the credential over the active session, then stop writing.
func (*Host) Export ¶
Export implements admin.Backend; in the air-gap profile exported records are marked transmitted first.
func (*Host) Investigate ¶
Investigate implements admin.Backend (PRD A9 local investigation).
type Investigator ¶
type Investigator interface {
Tools() []client.Tool
Call(ctx context.Context, name string, args json.RawMessage) (any, error)
}
Investigator serves investigation tools over the tunnel and the admin socket.
type JournalReader ¶
type JournalReader interface {
Refresh() error
Next() (journal.Entry, bool)
SaveCursor() error
FileErrors() map[string]error
Close() error
}
JournalReader is the subset of *journal.Reader the host uses.
type LogsHealth ¶
type LogsHealth struct {
Files int `json:"files"`
Streams int `json:"streams"`
Lines uint64 `json:"lines"`
Gaps uint64 `json:"gaps"`
Journal bool `json:"journal"`
JournalEntries uint64 `json:"journal_entries"`
JournalErrors map[string]string `json:"journal_file_errors,omitempty"`
}
LogsHealth reports log inputs.
type MetricsHealth ¶
type MetricsHealth struct {
Series int `json:"series"`
DroppedSeries int `json:"dropped_series"`
DroppedFamilies []string `json:"dropped_families,omitempty"`
FailedCollectors []string `json:"failed_collectors,omitempty"`
AppendErrors int `json:"append_errors"`
}
MetricsHealth reports the last node metrics gather.
type RuleHealth ¶
type RuleHealth struct {
ID string `json:"id"`
Version int `json:"version"`
Class string `json:"class"`
State string `json:"state"`
Reason string `json:"reason,omitempty"`
Pending int `json:"pending"`
Firing int `json:"firing"`
Last time.Time `json:"last_eval,omitzero"`
}
RuleHealth is one rule state (PRD R9).
type ScrapeHealth ¶
type ScrapeHealth struct {
URL string `json:"url"`
Health string `json:"health"`
Reason string `json:"reason,omitempty"`
LastError string `json:"last_error,omitempty"`
Last time.Time `json:"last_scrape,omitzero"`
Series int `json:"series"`
}
ScrapeHealth is one local metrics endpoint.
type SessionStatus ¶
type SessionStatus struct {
Connected bool `json:"connected"`
SessionID string `json:"session_id,omitempty"`
Registered bool `json:"registered"`
Committed uint64 `json:"committed"`
BacklogRecords int `json:"backlog_records"`
BacklogBytes int64 `json:"backlog_bytes"`
LastError string `json:"last_error,omitempty"`
LastErrorCode string `json:"last_error_code,omitempty"`
Halted string `json:"halted,omitempty"`
Compat protocol.Compat `json:"compat"`
Exported uint64 `json:"exported_through,omitempty"`
}
SessionStatus reports the writer session.
type SpoolHealth ¶
type SpoolHealth struct {
Bytes int64 `json:"bytes"`
Capacity int64 `json:"capacity"`
Records int `json:"records"`
InFlightBytes int64 `json:"in_flight_bytes"`
Oldest time.Time `json:"oldest,omitzero"`
ProjectedWindowSeconds float64 `json:"projected_window_seconds"`
RebaselineRequired bool `json:"rebaseline_required"`
}
SpoolHealth reports spool use and the projected outage window.
type Status ¶
type Status struct {
Health
Session SessionStatus `json:"session"`
}
Status is the admin status document: health plus the session.