config

Documentation

Overview

Package config allows tools such as the gokr-packer or breakglass reading gokrazy instance configuration (with fallback to the older host-specific configuration) for data such as the HTTP password, or package-specific command line flags.

Index

• func Gokrazy() string
• func InstanceConfigPath() string
• func InstancePath() string
• type HostnameDir
  • func HostnameSpecific(hostname string) HostnameDir
  • func (h HostnameDir) ReadFile(configBaseName string) (string, error)
• type InternalCompatibilityFlags
  • func (i *InternalCompatibilityFlags) SudoOrDefault() string
• type MountDevice
• type PackageConfig
• type Struct
  • func NewStruct(hostname string) *Struct
  • func ReadFromFile() (*Struct, error)
  • func (s *Struct) EEPROMPackageOrDefault() string
  • func (s *Struct) FirmwarePackageOrDefault() string
  • func (s *Struct) FormatForFile() ([]byte, error)
  • func (s *Struct) GokrazyPackagesOrDefault() []string
  • func (s *Struct) KernelPackageOrDefault() string
  • func (s *Struct) SerialConsoleOrDefault() string
• type UpdateStruct
  • func (u *UpdateStruct) WithFallbackToHostSpecific(host string) (*UpdateStruct, error)

Functions

func Gokrazy

func Gokrazy() string

func InstanceConfigPath

func InstanceConfigPath() string

func InstancePath

func InstancePath() string

Types

type HostnameDir

type HostnameDir string

func HostnameSpecific

func HostnameSpecific(hostname string) HostnameDir

func (HostnameDir) ReadFile

func (h HostnameDir) ReadFile(configBaseName string) (string, error)

type InternalCompatibilityFlags

type InternalCompatibilityFlags struct {
	// These have become 'gok overwrite' flags:
	Overwrite          string `json:",omitempty"` // -overwrite
	OverwriteBoot      string `json:",omitempty"` // -overwrite_boot
	OverwriteMBR       string `json:",omitempty"` // -overwrite_mbr
	OverwriteRoot      string `json:",omitempty"` // -overwrite_root
	Sudo               string `json:",omitempty"` // -sudo
	TargetStorageBytes int    `json:",omitempty"` // -target_storage_bytes

	// These have become 'gok update' flags:
	Update   string `json:",omitempty"` // -update
	Insecure bool   `json:",omitempty"` // -insecure
	Testboot bool   `json:",omitempty"` // -testboot

	// These will likely not be carried over from gokr-packer to gok because of
	// a lack of usage.
	InitPkg       string `json:",omitempty"` // -init_pkg
	OverwriteInit string `json:",omitempty"` // -overwrite_init
}

InternalCompatibilityFlags keep older gokr-packer behavior or user interface working, but should never be set by users in config.json manually.

func (*InternalCompatibilityFlags) SudoOrDefault

func (i *InternalCompatibilityFlags) SudoOrDefault() string

type MountDevice

type MountDevice struct {
	Source  string // e.g. /dev/sdx or PARTUUID=abcdef
	Type    string // e.g. ext4
	Target  string // e.g. /mnt/usb, will be created by the packer
	Options string // a subset of mount(8)-like options
}

MountDevice instructs gokrazy to mount the specified source on the specified target using the specified file system type and the specified options.

If Target contains a directory in /mnt (not a subdirectory), the packer will create it on the (read-only) root file system.

type PackageConfig

type PackageConfig struct {
	// GoBuildFlags will be passed to “go build” as extra arguments.
	//
	// To pass build tags, do not use -tags=mycustomtag; instead set the
	// GoBuildTags field to not overwrite the gokrazy default build tags.
	GoBuildFlags []string `json:",omitempty"`

	// GoBuildTags will be added to the list of gokrazy default build tags.
	GoBuildTags []string `json:",omitempty"`

	// Environment contains key=value pairs, like in Go’s os.Environ().
	Environment []string `json:",omitempty"`

	// CommandLineFlags will be set when starting the program.
	CommandLineFlags []string `json:",omitempty"`

	// DontStart makes the gokrazy init not start this program
	// automatically. Users can still start it manually via the web interface,
	// or interactively via breakglass.
	DontStart bool `json:",omitempty"`

	// WaitForClock makes the gokrazy init wait for clock synchronization before
	// starting the program. This is useful when modifying the program source to
	// call gokrazy.WaitForClock() is inconvenient.
	WaitForClock bool `json:",omitempty"`

	// ExtraFilePaths maps from root file system destination path to a relative
	// or absolute path on the host on which the packer is running.
	//
	// Lookup order:
	// 1. <path>_<target_goarch>.tar
	// 2. <path>.tar
	// 3. <path> (directory)
	ExtraFilePaths map[string]string `json:",omitempty"`

	// ExtraFileContents maps from root file system destination path to the
	// plain text contents of the file.
	ExtraFileContents map[string]string `json:",omitempty"`
}

type Struct

type Struct struct {
	Hostname   string        // -hostname
	DeviceType string        `json:",omitempty"` // -device_type
	Update     *UpdateStruct `json:",omitempty"`

	Packages []string // flag.Args()

	// If PackageConfig is specified, all package config is taken from the
	// config struct, no longer from the file system, except for extrafiles/.
	PackageConfig map[string]PackageConfig `json:",omitempty"`

	SerialConsole string `json:",omitempty"`

	GokrazyPackages *[]string `json:",omitempty"` // -gokrazy_pkgs
	KernelPackage   *string   `json:",omitempty"` // -kernel_package
	FirmwarePackage *string   `json:",omitempty"` // -firmware_package
	EEPROMPackage   *string   `json:",omitempty"` // -eeprom_package

	// extra lines to append to the config.txt file on the boot partition which
	// is read by the Raspberry Pi bootloader:
	// https://www.raspberrypi.com/documentation/computers/config_txt.html
	BootloaderExtraLines []string `json:",omitempty"`

	MountDevices []MountDevice `json:",omitempty"`

	// Do not set these manually in config.json, these fields only exist so that
	// the entire old gokr-packer flag surface keeps working.
	InternalCompatibilityFlags *InternalCompatibilityFlags `json:",omitempty"`

	Meta struct {
		Instance     string
		Path         string
		LastModified time.Time
	} `json:"-"` // omit from JSON
}

Fields where we need to distinguish between not being set (= use the default) and being set to an empty value (= disable), such as FirmwarePackage, are pointers. Fields that are required (Hostname) or where the empty value is not valid (InternalCompatibilityFlags.Sudo) don’t need to be pointers. If needed, we can switch fields from non-pointer to pointer, as the JSON on-disk representation does not change, and the config package is in github.com/gokrazy/internal.

func NewStruct

func NewStruct(hostname string) *Struct

NewStruct returns a config.Struct that was not loaded from a file, but instead created empty, with only the hostname field set.

This is handy for best-effort compatibility for older setups (before instance config was introduced). Aside from compatibility, ReadFromFile() should be used instead of NewStruct().

func ReadFromFile

func ReadFromFile() (*Struct, error)

func (*Struct) EEPROMPackageOrDefault

func (s *Struct) EEPROMPackageOrDefault() string

func (*Struct) FirmwarePackageOrDefault

func (s *Struct) FirmwarePackageOrDefault() string

func (*Struct) FormatForFile

func (s *Struct) FormatForFile() ([]byte, error)

FormatForFile pretty-prints the config struct as JSON, ready for storing it in the config.json file.

func (*Struct) GokrazyPackagesOrDefault

func (s *Struct) GokrazyPackagesOrDefault() []string

func (*Struct) KernelPackageOrDefault

func (s *Struct) KernelPackageOrDefault() string

func (*Struct) SerialConsoleOrDefault

func (s *Struct) SerialConsoleOrDefault() string

type UpdateStruct

type UpdateStruct struct {
	// Hostname (in UpdateStruct) overrides Struct.Hostname, but only for
	// deploying the update via HTTP, not in the generated image.
	Hostname string `json:",omitempty"`

	// UseTLS can be one of:
	//
	// - empty (""), meaning use TLS if certificates exist
	// - "off", disabling TLS even if certificates exist
	// - "self-signed", creating TLS certificates if needed
	UseTLS string `json:",omitempty"` // -tls

	HTTPPort     string `json:",omitempty"` // -http_port
	HTTPSPort    string `json:",omitempty"` // -https_port
	HTTPPassword string `json:",omitempty"` // http-password.txt
	CertPEM      string `json:",omitempty"` // cert.pem
	KeyPEM       string `json:",omitempty"` // key.pem
}

func (*UpdateStruct) WithFallbackToHostSpecific

func (u *UpdateStruct) WithFallbackToHostSpecific(host string) (*UpdateStruct, error)