presets

Documentation

Overview

Package presets provides the embedded conventions library for linuxctl.

Presets are shipped as YAML files under pkg/presets/data/ and embedded into the linuxctl binary via go:embed. Each preset declares a named, reusable fragment of desired state for one of five categories (directories, users_groups, packages, sysctl, limits) plus a "Bundle" meta-preset that composes one preset per category.

Merge precedence (lowest → highest): bundle_preset < individual *_preset fields < explicit entries in the stack's linux.yaml. See plan 033.

Index

• Constants
• func BundleExpand(name string, tierFn TierFunc) (map[string]string, error)
• func DirectoriesSpec(p *Preset) ([]config.Directory, error)
• func LimitsSpec(p *Preset) ([]config.LimitEntry, error)
• func MergeDirectories(explicit []config.Directory, preset []config.Directory) []config.Directory
• func MergeLimits(explicit []config.LimitEntry, preset []config.LimitEntry) []config.LimitEntry
• func MergePackages(explicit config.Packages, preset config.Packages) config.Packages
• func MergeSysctl(explicit []config.SysctlEntry, preset []config.SysctlEntry) []config.SysctlEntry
• func MergeUsersGroups(explicit config.UsersGroups, preset config.UsersGroups) config.UsersGroups
• func PackagesSpec(p *Preset) (*config.Packages, error)
• func SysctlSpec(p *Preset) ([]config.SysctlEntry, error)
• func UsersGroupsSpec(p *Preset) (*config.UsersGroups, error)
• type Bundle
• type Preset
  • func Resolve(name string, tierFn TierFunc) (*Preset, error)
  • func ResolveCategory(category, name string, tierFn TierFunc) (*Preset, error)
• type PresetMeta
  • func List(tierFn TierFunc) []PresetMeta
• type Tier
• type TierFunc

Constants

const APIVersion = "linuxctl.itunified.io/preset/v1"

APIVersion is the current preset schema identifier.

Functions

func BundleExpand

func BundleExpand(name string, tierFn TierFunc) (map[string]string, error)

BundleExpand resolves a bundle name and returns a map of category → child preset name. The caller can then call ResolveCategory(category, childName, ...) for each category.

func DirectoriesSpec

func DirectoriesSpec(p *Preset) ([]config.Directory, error)

DirectoriesSpec returns the directories list from a directories preset.

func LimitsSpec

func LimitsSpec(p *Preset) ([]config.LimitEntry, error)

LimitsSpec returns the limits list from a limits preset.

func MergeDirectories

func MergeDirectories(explicit []config.Directory, preset []config.Directory) []config.Directory

MergeDirectories merges explicit entries with a preset's entries, deduping by path. Explicit entries win on path collision. Output is sorted by path for deterministic comparison.

func MergeLimits

func MergeLimits(explicit []config.LimitEntry, preset []config.LimitEntry) []config.LimitEntry

MergeLimits merges explicit + preset limit entries, deduping by (user, type, item). Explicit wins.

func MergePackages

func MergePackages(explicit config.Packages, preset config.Packages) config.Packages

MergePackages merges explicit + preset package lists. Install and Remove sets are unioned; identical names survive only once. If a package appears in both Install and Remove (conflict), the explicit side wins.

func MergeSysctl

func MergeSysctl(explicit []config.SysctlEntry, preset []config.SysctlEntry) []config.SysctlEntry

MergeSysctl merges explicit + preset sysctl entries, deduping by key. Explicit wins on key collision. Output is sorted by key.

func MergeUsersGroups

func MergeUsersGroups(explicit config.UsersGroups, preset config.UsersGroups) config.UsersGroups

MergeUsersGroups merges explicit groups + users with a preset's, deduping by name. For users, the group list is unioned (preset groups + explicit groups); other user fields are overridden by the explicit entry when set.

func PackagesSpec

func PackagesSpec(p *Preset) (*config.Packages, error)

PackagesSpec returns the packages block from a packages preset.

func SysctlSpec

func SysctlSpec(p *Preset) ([]config.SysctlEntry, error)

SysctlSpec returns the sysctl list from a sysctl preset.

func UsersGroupsSpec

func UsersGroupsSpec(p *Preset) (*config.UsersGroups, error)

UsersGroupsSpec returns the users+groups block from a users_groups preset.

Types

type Bundle

type Bundle struct {
	DirectoriesPreset string `yaml:"directories_preset,omitempty"`
	UsersGroupsPreset string `yaml:"users_groups_preset,omitempty"`
	PackagesPreset    string `yaml:"packages_preset,omitempty"`
	SysctlPreset      string `yaml:"sysctl_preset,omitempty"`
	LimitsPreset      string `yaml:"limits_preset,omitempty"`
}

Bundle is a meta-preset that composes one preset per category.

type Preset

type Preset struct {
	APIVersion string     `yaml:"apiVersion"`
	Kind       string     `yaml:"kind"`
	Metadata   PresetMeta `yaml:"metadata"`
	// RawSpec holds the unparsed spec map — category-specific typed views
	// are decoded on demand by the registry helpers.
	RawSpec map[string]any `yaml:"spec"`
}

Preset is a single named fragment of desired state. The Spec field is decoded category-specifically by the registry (the raw decoded YAML map is retained in RawSpec for rendering / show commands).

func Resolve

func Resolve(name string, tierFn TierFunc) (*Preset, error)

Resolve loads a preset by name. Returns an error if unknown, ambiguous (same name in multiple categories), or if the caller's tier is below the preset's required tier. For ambiguous names, use ResolveCategory.

func ResolveCategory

func ResolveCategory(category, name string, tierFn TierFunc) (*Preset, error)

ResolveCategory loads a preset by (category, name). This is the form the managers use, since each manager owns a single category.

type PresetMeta

type PresetMeta struct {
	Name     string `yaml:"name"`
	Category string `yaml:"category"`
	Tier     Tier   `yaml:"tier"`
	Source   string `yaml:"source,omitempty"`
	Version  string `yaml:"version,omitempty"`
}

PresetMeta is the common metadata block on every preset + bundle.

func List

func List(tierFn TierFunc) []PresetMeta

List returns metadata for all presets available at the caller's tier. Results are sorted by (category, name) for stable output.

type Tier

type Tier string

Tier mirrors pkg/license.Tier without a circular import.

const (
	// TierCommunity is the default / free tier. All shipped Phase-1 presets
	// are at this tier.
	TierCommunity Tier = "community"
	// TierBusiness unlocks hardened-cis and other enterprise-leaning presets.
	TierBusiness Tier = "business"
	// TierEnterprise is the highest tier; reserved for future presets.
	TierEnterprise Tier = "enterprise"
)

type TierFunc

type TierFunc func() Tier

TierFunc is a callback supplied by the caller (usually wired to the license gate) that reports the user's active tier. Passing nil defaults to Community.