Documentation
¶
Overview ¶
Package osqueryversions stores the osquery versions osctrl can roll out and the SHA-256 of each official package.
Index ¶
- Constants
- Variables
- func Bucket(envID uint, version, nodeUUID string) uint32
- func CleanHost(s string) string
- func Compare(a, b string) (int, error)
- func ComputeThresholds(envID uint, version string, uuids []string) [4]uint32
- func HostName(names ...string) string
- func NodePlatformSupported(platform string) bool
- func SupportedNodePlatformSQL(column string) string
- func ValidEntry(platform, arch, format, sha256 string) error
- func ValidVersion(v string) bool
- type DigestEntry
- type EnvTarget
- type Manager
- func (m *Manager) AbortRollout(envID uint, by string, now time.Time) (*Rollout, error)
- func (m *Manager) ClearEnvTarget(envID uint) (bool, error)
- func (m *Manager) CountBehind(now time.Time, fresh time.Duration) (map[uint]int, error)
- func (m *Manager) CountPaused() (map[uint]int, error)
- func (m *Manager) DeleteNodeRecords(nodeUUID string) error
- func (m *Manager) DeletePin(nodeUUID string) (bool, error)
- func (m *Manager) DeleteVersion(version string) error
- func (m *Manager) GetEntries(version string) ([]DigestEntry, error)
- func (m *Manager) GetEnvTarget(envID uint) (*EnvTarget, error)
- func (m *Manager) GetPin(nodeUUID string) (*NodePin, error)
- func (m *Manager) GetRollout(envID uint) (*Rollout, error)
- func (m *Manager) ListVersions() ([]VersionView, error)
- func (m *Manager) PauseRollout(envID uint, requestID, host, reason string, eventAt, now time.Time) (bool, error)
- func (m *Manager) Progress(r Rollout, now time.Time) (RolloutProgress, error)
- func (m *Manager) PutEntries(version string, entries []DigestEntry, by string) error
- func (m *Manager) Resolve(in ResolveInput, now time.Time) (Resolution, error)
- func (m *Manager) ResumeRollout(envID uint, by string, now time.Time) (*Rollout, error)
- func (m *Manager) SetEnvTarget(envID uint, version, by string) (*EnvTarget, error)
- func (m *Manager) SetEnvTargetRollout(envID uint, version, by string, uuids []string, now time.Time) (*EnvTarget, *Rollout, error)
- func (m *Manager) SetPin(nodeUUID string, envID uint, version string, expiresAt *time.Time, by string) (*NodePin, error)
- func (m *Manager) VersionNames() ([]string, error)
- type NodePin
- type Ref
- type Resolution
- type ResolveInput
- type RolledBackHost
- type Rollout
- func (r Rollout) EffectiveStage(now time.Time) int
- func (r Rollout) EffectiveState(now time.Time) string
- func (r Rollout) Eligible(bucket uint32, now time.Time) bool
- func (r Rollout) NextStageAt(now time.Time) *time.Time
- func (r Rollout) NodeStage(bucket uint32) int
- func (Rollout) TableName() string
- type RolloutCounts
- type RolloutProgress
- type VersionView
Constants ¶
const ( ReasonNoTarget = "no_target" ReasonAheadOfTarget = "ahead_of_target" ReasonNoDigestForTarget = "no_digest_for_target" ReasonNoDigestForInstalled = "no_digest_for_installed" ReasonUnsupportedPlatform = "unsupported_platform" ReasonRolloutPending = "rollout_pending" ReasonRolloutPaused = "rollout_paused" )
Reasons Resolve gives for not upgrading; "" means upgrade.
const ( RolloutRunning = "running" RolloutPaused = "paused" RolloutCompleted = "completed" RolloutAborted = "aborted" )
Rollout states. "completed" is only ever an effective state of a running row.
const RolloutStageWait = 2 * time.Hour
RolloutStageWait is how long each stage stays open before the next one.
Variables ¶
var ErrInUse = errors.New("osquery version is in use by a target or pin")
ErrInUse is returned when a change would break a target or pin referencing a version.
var ErrInvalid = errors.New("invalid osquery version input")
ErrInvalid is returned for invalid versions or entries.
var ErrNotFound = errors.New("osquery version not found")
ErrNotFound is returned when a version has no library entries.
var ErrRolloutState = errors.New("rollout is not in a state that allows this")
ErrRolloutState is returned when the rollout state does not allow a change.
var RolloutStages = [4]uint32{100, 1000, 5000, 10000}
RolloutStages are the stage shares in basis points (1%, 10%, 50%, 100%).
Functions ¶
func CleanHost ¶
CleanHost makes a host-reported name safe to store and log: it drops control and other non-printable runes (newlines, tabs, ...) and cuts to 255 runes.
func Compare ¶
Compare returns -1, 0 or 1 comparing versions part by part; a missing part counts as 0. It errors when either version is invalid.
func ComputeThresholds ¶
ComputeThresholds returns the stage thresholds for the given hosts: a host is eligible at stage i iff Bucket < thresholds[i]. Stage 1 has at least one host.
func NodePlatformSupported ¶
NodePlatformSupported is the one rule for whether a stored node platform is part of upgrades, shared by thresholds, progress, the behind gauge and the node API. Windows is supported; an empty or unknown platform keeps counting (it is unsupported only if listed above), case-insensitive.
func SupportedNodePlatformSQL ¶
SupportedNodePlatformSQL is NodePlatformSupported as a WHERE fragment on the given platform column, for the raw queries of packages that cannot be imported here.
func ValidEntry ¶
ValidEntry checks that the platform, arch and format are a supported combination and that sha256 is 64 lowercase hex characters.
func ValidVersion ¶
ValidVersion reports whether v is a 2 to 4 part numeric version with parts of at most 6 digits (so at most 27 characters, within the size-32 column).
Types ¶
type DigestEntry ¶
type DigestEntry struct {
ID uint `gorm:"primaryKey" json:"-"`
Version string `gorm:"uniqueIndex:idx_osq_digest;size:32" json:"version"`
Platform string `gorm:"uniqueIndex:idx_osq_digest;size:16" json:"platform"`
Arch string `gorm:"uniqueIndex:idx_osq_digest;size:16" json:"arch"`
Format string `gorm:"uniqueIndex:idx_osq_digest;size:16" json:"format"`
SHA256 string `gorm:"size:64" json:"sha256"`
CreatedBy string `json:"created_by"`
CreatedAt time.Time `json:"created_at"`
}
DigestEntry is the SHA-256 of one official osquery package (a version, for one platform, arch and format). It is the GORM model and the exchange type.
func (DigestEntry) TableName ¶
func (DigestEntry) TableName() string
TableName keeps the table name stable independent of the struct name.
type EnvTarget ¶
type EnvTarget struct {
gorm.Model
EnvironmentID uint `gorm:"uniqueIndex:idx_osq_env_target_env"`
Version string `gorm:"size:32"`
RequestID string `gorm:"size:32"`
UpdatedBy string
}
EnvTarget is the osquery version an environment is rolled out to. RequestID changes on every set so osctrld can tell a re-set from a repeat.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is the source of truth for the osquery version library, shared by osctrl-api and osctrl-tls through SQL.
func NewManager ¶
NewManager migrates the library tables and returns a manager.
func (*Manager) AbortRollout ¶
AbortRollout aborts a running or paused rollout and clears the environment target in the same transaction. Pins are kept.
func (*Manager) ClearEnvTarget ¶
ClearEnvTarget removes the environment's target and reports whether one was set.
func (*Manager) CountBehind ¶
CountBehind returns, per environment id, the nodes with an osctrld report newer than fresh whose stored osquery version is lower than their effective target: an unexpired pin of the same environment, else the environment's target. Nodes without a target, with an unparseable version or on an unsupported platform (see NodePlatformSupported) are not counted. The table names are those of the nodes and osctrld status models, which this package must not import.
func (*Manager) CountPaused ¶
CountPaused returns environment id -> 1 for every environment whose latest rollout row (highest id) is stored as paused. One bounded query: at most maxRolloutRows rows are kept per environment.
func (*Manager) DeleteNodeRecords ¶
DeleteNodeRecords removes everything stored for a node; used by node deletion.
func (*Manager) DeleteVersion ¶
DeleteVersion removes every digest of a version. It returns ErrInUse when a target or an unexpired pin references it and ErrNotFound when it has no rows.
func (*Manager) GetEntries ¶
func (m *Manager) GetEntries(version string) ([]DigestEntry, error)
GetEntries returns the digests of a version.
func (*Manager) GetEnvTarget ¶
GetEnvTarget returns the environment's target, or nil when none is set.
func (*Manager) GetRollout ¶
GetRollout returns the environment's latest rollout, or nil when none exists.
func (*Manager) ListVersions ¶
func (m *Manager) ListVersions() ([]VersionView, error)
ListVersions returns every version, newest first, with its digests.
func (*Manager) PauseRollout ¶
func (m *Manager) PauseRollout(envID uint, requestID, host, reason string, eventAt, now time.Time) (bool, error)
PauseRollout pauses the running rollout of request requestID, freezing its effective stage. eventAt is the server time the rollback was first recorded: a rollback that happened before the rollout was last resumed never pauses it (the host keeps re-reporting it). It returns false when no running rollout matches or the rollback is older than the last resume.
func (*Manager) Progress ¶
Progress counts the environment's hosts against the rollout at now. Hosts on an unsupported platform (NodePlatformSupported, the same rule as the thresholds' host set) are left out entirely: they are never eligible or waiting, nor listed when rolled back. Windows hosts count. The table names are those of the nodes and osctrld status models, which this package must not import.
func (*Manager) PutEntries ¶
func (m *Manager) PutEntries(version string, entries []DigestEntry, by string) error
PutEntries validates all entries and then upserts them, per (version, platform, arch, format), in one transaction.
func (*Manager) Resolve ¶
func (m *Manager) Resolve(in ResolveInput, now time.Time) (Resolution, error)
Resolve decides what a node should do: the unexpired pin wins over the environment target. Versions are matched by exact string, as stored.
func (*Manager) ResumeRollout ¶
ResumeRollout resumes a paused rollout at its frozen stage and restarts that stage's wait.
func (*Manager) SetEnvTarget ¶
SetEnvTarget sets the environment's target to a library version with a new request id. It does NOT start or replace a rollout: API code must use SetEnvTargetRollout.
func (*Manager) SetEnvTargetRollout ¶
func (m *Manager) SetEnvTargetRollout(envID uint, version, by string, uuids []string, now time.Time) (*EnvTarget, *Rollout, error)
SetEnvTargetRollout sets the environment target like SetEnvTarget and starts a rollout for it, aborting any active one, in one transaction.
func (*Manager) SetPin ¶
func (m *Manager) SetPin(nodeUUID string, envID uint, version string, expiresAt *time.Time, by string) (*NodePin, error)
SetPin pins a node to a library version. expiresAt, when set, must be in the future. Changing only the expiry of a pin of the same environment keeps its request id, so osctrld does not retry a version the host rejected; any other call, including an identical re-save (how an operator retries), gets a new request id.
func (*Manager) VersionNames ¶
VersionNames returns the versions that have library entries, oldest first, without digests or in-use queries.
type NodePin ¶
type NodePin struct {
gorm.Model
NodeUUID string `gorm:"uniqueIndex:idx_osq_node_pin_uuid;size:255"`
EnvironmentID uint `gorm:"index:idx_osq_node_pin_env"`
Version string `gorm:"size:32"`
RequestID string `gorm:"size:32"`
UpdatedBy string
ExpiresAt *time.Time
}
NodePin overrides the environment target for one node, optionally until ExpiresAt.
type Resolution ¶
Resolution is the answer for one node. Target and Previous are set only when Reason is "".
type ResolveInput ¶
type ResolveInput struct {
EnvironmentID uint
NodeUUID, Platform, Arch, Format, InstalledVersion string
}
ResolveInput is what a node reports plus its identity.
type RolledBackHost ¶
RolledBackHost is a host that rejected the rollout's version.
type Rollout ¶
type Rollout struct {
gorm.Model
EnvironmentID uint `gorm:"uniqueIndex:idx_osq_rollout_env_req"`
RequestID string `gorm:"uniqueIndex:idx_osq_rollout_env_req;size:32"`
Version string `gorm:"size:32"`
State string `gorm:"size:16"`
Stage int
StageOpenedAt time.Time
// Thresholds is the JSON of the [4]uint32 bucket thresholds.
Thresholds string `gorm:"size:96"`
CreatedBy string
PausedHost string
PausedReason string
PausedAt *time.Time
ResumedBy string
ResumedAt *time.Time
AbortedBy string
AbortedAt *time.Time
}
Rollout is the staged rollout of an environment target. The effective stage is a pure function of the row and the clock, so no background job exists.
func (Rollout) EffectiveStage ¶
EffectiveStage is the 0-based stage open at now.
func (Rollout) EffectiveState ¶
EffectiveState is the stored state, or completed once a running rollout reached the last stage.
func (Rollout) NextStageAt ¶
NextStageAt is when the next stage opens, or nil unless running and not at the last stage.
type RolloutCounts ¶
type RolloutCounts struct{ Eligible, Upgraded, Waiting, RolledBack int }
RolloutCounts are the host counts of a rollout.
type RolloutProgress ¶
type RolloutProgress struct {
Rollout Rollout
State string
Stage int
NextStageAt *time.Time
Counts RolloutCounts
RolledBackHosts []RolledBackHost
}
RolloutProgress is a rollout with its effective state and host counts.
type VersionView ¶
type VersionView struct {
Version string `json:"version"`
Entries []DigestEntry `json:"entries"`
// InUse is set when a target or an unexpired pin references the version.
InUse bool `json:"in_use"`
}
VersionView is a library version with its digests.