bootserver

README

bootserver

bootserver is a tool that takes a set of images and paves a device. The go bootserver is meant to deprecate the C version at //tools/bootserver_old and will be backwards compatible with it.

The bootserver executable is not actually used by the infrastructure, but the library is used by botanist (which is used by the infrastructure) to pave devices. The executable is built and uploaded through artifactory to GCS along with other build artifacts to allow developers/testers to download it and pave their local devices with the images produced by a particular build.

Pave with explicitly specified images

The bootserver tool can take in specific images as command line arguments to pave either zedboot or fuchsia. It uses the same arguments as bootserver_old. See the flags at cmd/main.go to see which flags correspond to which images and also which unsupported bootserver_old flags are remaining.

Pave with image manifest

Alternatively, you can pave using the -images flag with the images.json manifest produced by a build. The manifest should follow the schema at //tools/build/images.go and include all the necessary images for paving. This will automatically be generated after a gn gen or fx set command in the build out directory, but the images will actually have to be built with ninja or fx build before you can call bootserver with it.

The -images flag takes either a path to a local image manifest on the filesystem, or it can also take a GCS path to an image manifest for a particular build (i.e. gs://fuchsia-artifacts/builds/<build id>/images/images.json). If using a GCS path, the images will be downloaded from the same directory in GCS as the manifest.

The -images flag must be used in conjunction with the -mode flag. The way bootserver determines which files to pave the device with is by looking at the bootserver_pave/bootserver_pave_zedboot/bootserver_netboot fields of each image entry in the manifest, and depending on the mode provided (either pave, pave-zedboot, or netboot), it chooses the images with non-empty args for that mode to send to the device.

Documentation

Index

• func Boot(ctx context.Context, t tftp.Client, imgs []Image, cmdlineArgs []string, ...) error
• func DownloadWithRetries(ctx context.Context, dest string, download func() error) error
• func ValidateBoard(ctx context.Context, t tftp.Client, boardName string) error
• type Image
  • func ConvertFromBuildImages(buildImages []build.Image, bootMode Mode, imageDir string) ([]Image, func() error, error)
  • func GetImages(ctx context.Context, imageManifest string, bootMode Mode) ([]Image, func() error, error)
  • func ImagesFromGCS(ctx context.Context, manifest *url.URL, bootMode Mode) ([]Image, func() error, error)
  • func ImagesFromLocalFS(manifest string, bootMode Mode) ([]Image, func() error, error)
• type Mode
  • func (m *Mode) Set(s string) error
  • func (m *Mode) String() string

Functions

func Boot

func Boot(ctx context.Context, t tftp.Client, imgs []Image, cmdlineArgs []string, authorizedKeys []byte) error

Boot prepares and boots a device at the given IP address.

func DownloadWithRetries

func DownloadWithRetries(ctx context.Context, dest string, download func() error) error

DownloadWithRetries runs a function that downloads a blob from GCS, and retries if the function returns an error that corresponds to a failure mode that's known to be transient.

func ValidateBoard

func ValidateBoard(ctx context.Context, t tftp.Client, boardName string) error

ValidateBoard reads the board info from the target and validates that it matches boardName.

Types

type Image

type Image struct {
	// Name is an identifier for this image that usually derives from its target partition.
	// TODO(fxbug.dev/38517): Remove when BootZedbootShim is deprecated.
	Name string
	// Path is the relative location of the image with respect to the image manifest
	// or the absolute location of the image on disk.
	Path string
	// Reader is a reader to the image.
	Reader io.ReaderAt
	// Size is the size of the reader in bytes.
	Size int64
	// Args correspond to the bootserver args that map to this image type.
	Args []string
	// IsExecutable is true if the image is actually a script or executable.
	IsExecutable bool
}

Image is a fuchsia image as viewed by bootserver; a simplified version of build.Image.

func ConvertFromBuildImages

func ConvertFromBuildImages(buildImages []build.Image, bootMode Mode, imageDir string) ([]Image, func() error, error)

ConvertFromBuildImages filters and returns Images corresponding to build Images of a given bootMode.

func GetImages

func GetImages(ctx context.Context, imageManifest string, bootMode Mode) ([]Image, func() error, error)

GetImages parses the imageManifest and gets a list of images with readers to each image. It returns the images as well as a func to close the image readers.

func ImagesFromGCS

func ImagesFromGCS(ctx context.Context, manifest *url.URL, bootMode Mode) ([]Image, func() error, error)

ImagesFromGCS returns Images of a given bootMode that exist in GCS. The image paths provided in the manifest at the given url are expected to be relative paths to the same directory of the manifest.

func ImagesFromLocalFS

func ImagesFromLocalFS(manifest string, bootMode Mode) ([]Image, func() error, error)

ImagesFromLocalFS returns Images of a given bootMode that exist on the local filesystem.

type Mode

type Mode int

Mode determines the arguments to use when booting/paving images.

const (
	// ModeNull is a null default that can be error checked against.
	ModeNull Mode = iota
	// ModePave is a directive to pave when booting.
	ModePave
	// ModeNetboot is a directive to netboot when booting.
	ModeNetboot
	// ModePaveZedboot is a directive to pave zedboot to partition A (the initial boot partition) when booting.
	ModePaveZedboot
)

func (*Mode) Set

func (m *Mode) Set(s string) error

Set assigns a value to the Mode given a string

func (*Mode) String

func (m *Mode) String() string

String returns the string value of the Mode type.