gokrazy

package module
v0.0.0-...-7fca4d5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 21, 2024 License: BSD-3-Clause Imports: 46 Imported by: 36

README

GitHub Actions CI Go Report Card

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

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

View Source
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
)

Variables

This section is empty.

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 deprecated

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 WaitForClock

func WaitForClock()

WaitForClock returns once the system clock appears to have been set. Assumes that the system boots with a clock value of January 1, 1970 UTC (UNIX epoch), as is the case on the Raspberry Pi 3.

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.

Directories

Path Synopsis
cmd
dhcp
dhcp is a minimal DHCP client for gokrazy.
dhcp is a minimal DHCP client for gokrazy.
ntp
ntp is a minimal NTP client for gokrazy.
ntp is a minimal NTP client for gokrazy.
randomd
Binary randomd carries entropy across restarts.
Binary randomd carries entropy across restarts.
Package empty is pulled in only for the side-effect of checking out the gokrazy git repository.
Package empty is pulled in only for the side-effect of checking out the gokrazy git repository.
Package ifaddr provides functions to obtain the private and public host addresses of all active interfaces.
Package ifaddr provides functions to obtain the private and public host addresses of all active interfaces.
integration
internal
teelogger
Package teelogger provides loggers which send their output to multiple writers, like the tee(1) command.
Package teelogger provides loggers which send their output to multiple writers, like the tee(1) command.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL