gokrazy

README

Overview

With gokrazy, you can deploy your Go programs as appliances to a Raspberry Pi or PC (→ supported platforms).

For a long time, we were unhappy with having to care about security issues and Linux distribution maintenance on our various Raspberry Pis.

Then, we had a crazy idea: what if we got rid of memory-unsafe languages and all software we don’t strictly need?

Turns out this is feasible. gokrazy is the result.

→ Learn more at gokrazy.org

GitHub Repository structure

• github.com/gokrazy/gokrazy: system code, main issue tracker, documentation
• github.com/gokrazy/tools: SD card image creation code, pulling in:
  • github.com/gokrazy/firmware: Raspberry Pi 3 or 4 firmware files
  • github.com/gokrazy/rpi-eeprom: Raspberry Pi 4 EEPROM files
  • github.com/gokrazy/kernel: pre-built kernel image and bootloader config

Documentation

gokrazy.org uses hugo for creating and generating the website. You can find the hugo install instructions here: Install Hugo. With hugo you can write documentation in Markdown and generate a static website from it.

The website subdirectory is hugo’s root directory. In order to preview the documentation or to re-generate the website, switch the directory to website.

To preview the website, run the hugo webserver:

hugo serve

Generate the website:

hugo

The updated website content will be stored in the ./docs directory. Do not update anything here manually.

Documentation

Overview

gokrazy packs your Go application(s) into an SD card image for the Raspberry Pi 3 which — aside from the Linux kernel and proprietary Raspberry Pi bootloader — only contains Go software.

Boot and Supervise are called by the auto-generated init program. They are provided in case you need to implement a custom init program.

PrivateInterfaceAddrs is useful for init and other processes.

DontStartOnBoot and WaitForClock are useful for non-init processes.

Index

• Constants
• func Boot(userBuildTimestamp string) error
• func DontStartOnBoot()
• func IsInPrivateNet(ip net.IP) bool
• func MachineID() string
• func Model() string
• func NewProcessState() *processState
• func PrivateInterfaceAddrs() ([]string, error)
• func PublicInterfaceAddrs() ([]string, error)
• func ReadSBOM() (*json.RawMessage, string, error)
• func Supervise(commands []*exec.Cmd) error
• func SuperviseServices(services []*Service) error
• func WaitFor(things ...string)
• func WaitForClock()
• type Service
  • func NewService(cmd *exec.Cmd) *Service
  • func NewStoppedService(cmd *exec.Cmd) *Service
  • func NewWaitForClockService(cmd *exec.Cmd) *Service

Constants

const (
	Stopped  statusCode = iota // Process not running
	Running                    // Process was started and is very likely still running
	Stopping                   // Process is being stopped, but it might still be running
)

const HTTPUnixSocket = "/run/gokrazy-http.sock"

HTTPUnixSocket is the unix socket path that the HTTP server listens on.

Functions

func Boot

func Boot(userBuildTimestamp string) error

Boot configures basic system settings. More specifically, it:

• mounts /dev, /tmp, /proc, /sys and /perm file systems
• mounts and populate /etc tmpfs overlay
• sets hostname from the /etc/hostname file
• sets HTTP password from the gokr-pw.txt file
• configures the loopback network interface

Boot should always be called to transition the machine into a useful state, even in custom init process implementations or single-process applications.

userBuildTimestamp will be exposed on the HTTP status handlers that are set up by Supervise.

func DontStartOnBoot

func DontStartOnBoot()

DontStartOnBoot informs the gokrazy init process to not supervise the process and exits. The user can manually start supervision, which turns DontStartOnBoot into a no-op.

func IsInPrivateNet

func IsInPrivateNet(ip net.IP) bool

IsInPrivateNet reports whether the specified IP address is a private address, including loopback and link-local unicast addresses.

func MachineID

func MachineID() string

MachineID returns the machine id (see https://manpages.debian.org/machine-id.5) of the running gokrazy instance.

`gok new` creates a random machine id, but on older gokrazy installations, the hostname is used as a fallback.

func Model

func Model() string

Model returns a human readable description of the current device model, e.g. “Raspberry Pi 4 Model B Rev 1.1” or “PC Engines apu2” or “QEMU” or ultimately “unknown model”.

func NewProcessState

func NewProcessState() *processState

func PrivateInterfaceAddrs

func PrivateInterfaceAddrs() ([]string, error)

PrivateInterfaceAddrs returns all private (as per RFC1918, RFC4193, RFC3330, RFC3513, RFC3927, RFC4291) host addresses of all active interfaces, suitable to be passed to net.JoinHostPort.

func PublicInterfaceAddrs

func PublicInterfaceAddrs() ([]string, error)

PublicInterfaceAddrs returns all public (excluding RFC1918, RFC4193, RFC3330, RFC3513, RFC3927, RFC4291) host addresses of all active interfaces, suitable to be passed to net.JoinHostPort.

func ReadSBOM

func ReadSBOM() (*json.RawMessage, string, error)

func Supervise

func Supervise(commands []*exec.Cmd) error

Supervise runs SuperviseServices, creating services from commands.

Deprecated: newer versions of gokr-packer run gokrazy.SuperviseServices() instead

func SuperviseServices

func SuperviseServices(services []*Service) error

SuperviseServices continuously restarts the processes specified in services unless they run DontStartOnBoot.

Password-protected HTTP handlers are installed, allowing to inspect the supervised services and update the gokrazy installation over the network.

HTTP is served on PrivateInterfaceAddrs(). New IP addresses will be picked up upon receiving SIGHUP.

func WaitFor

func WaitFor(things ...string)

WaitFor allows waiting for one or more conditions to be true. The currently defined conditions are:

• clock: Wait for the system clock to be set, signaling that devices like the Raspberry Pi (which loses the time when power is lost and boots with the clock set to January 1, 1970 UTC (UNIX epoch)) have obtained the current time via NTP. On machines that boot with a correct time, such as most PCs, this is a no-op.
• net-route: Wait for a default route to be installed, signaling that local network connectivity is available (typically via DHCP, or statically configured). Note that while the local network may be up, internet connectivity might not be available (see net-online), for example right after a power outage.
• net-online: wait for a connectivity check to succeed, specifically resolving the gokrazy.org domain name

func WaitForClock

func WaitForClock()

WaitForClock returns once the system clock appears to have been set.

New usages should prefer directly calling WaitFor("clock") instead.

Types

type Service

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

Service is a gokrazy service.

func NewService

func NewService(cmd *exec.Cmd) *Service

NewService constructs a new gokrazy service from the specified command.

func NewStoppedService

func NewStoppedService(cmd *exec.Cmd) *Service

NewStoppedService is like NewService, but the created gokrazy service will not be supervised, i.e. remain stopped on boot.

func NewWaitForClockService

func NewWaitForClockService(cmd *exec.Cmd) *Service

NewWaitForClockService is like NewService, but the created gokrazy service will wait for clock to be synchronized, i.e. blocked till the clock is accurate.