autoupdate

Documentation

Overview

Package autoupdate provides a TUF Updater for the launcher and related binaries. This is abstracted across two packages, as well as main, making for a rather complex tangle.

As different binaries need different strategies for restarting, there are several moving parts to this:

github.com/kolide/updater/tuf is kolide's client to The Update
Framework (also called notary). This library is based around
signed metadata. When the metadata changes, it will download the
linked file. (This idiom is a bit confusing, and a bit
limiting. It downloads on _metadata_ change, and not as a file
comparison)

tuf.NotificationHandler is responsible for moving the downloaded
binary into the desired location. It defined by this package,
and is passed to TUF as a function. It is also used by TUF as a
ad-hoc logging mechanism.

autoupdate.UpdateFinalizer is responsible for finalizing the
update. Eg: restarting the service appropriately. As it is
different per binary, it is defined by main, and passed in to
autoupdate.NewUpdater.

Expected Usage

For each binary that is being updated, main will create a rungroup actor.Actor, for the autouopdate.Updater. main is responsible for setting an appropriate finalizer.

This actor is a wrapper around TUF. TUF will check at a specified interval for new metadata. If found, it will update the local metadata repo, and fetch a new binary.

tuf will then call the updater's handler to move the resultant binary. And finally pass off to the finalizer.

Testing

While some functions can be unit tested, integration is tightly coupled to TUF. One of the simplest ways to test this, is by attaching to the `nightly` channel, and causing frequent updates.

Index

• Constants
• func DeleteCorruptUpdates() newestOption
• func DeleteOldUpdates() newestOption
• func FindBaseDir(path string) string
• func FindNewest(ctx context.Context, fullBinaryPath string, opts ...newestOption) string
• func FindNewestSelf(ctx context.Context, opts ...newestOption) (string, error)
• func IsLauncherRestartNeededErr(err error) bool
• func SkipFullBinaryPathCheck() newestOption
• type LauncherRestartNeeded
  • func NewLauncherRestartNeededErr(msg string) LauncherRestartNeeded
  • func (e LauncherRestartNeeded) Error() string
• type UpdateChannel
• type UpdateFinalizer
• type Updater
  • func NewUpdater(binaryPath, rootDirectory string, opts ...UpdaterOption) (*Updater, error)
  • func (u *Updater) Run(opts ...tuf.Option) (stop func(), err error)
• type UpdaterOption
  • func WithFinalizer(f UpdateFinalizer) UpdaterOption
  • func WithHTTPClient(client *http.Client) UpdaterOption
  • func WithLogger(logger log.Logger) UpdaterOption
  • func WithMirrorURL(url string) UpdaterOption
  • func WithNotaryPrefix(prefix string) UpdaterOption
  • func WithNotaryURL(url string) UpdaterOption
  • func WithSigChannel(sc chan os.Signal) UpdaterOption
  • func WithUpdateChannel(channel UpdateChannel) UpdaterOption

Constants

const (
	Stable  UpdateChannel = "stable"
	Beta                  = "beta"
	Nightly               = "nightly"
)

const (
	DefaultMirror       = "https://dl.kolide.co"
	DefaultNotary       = "https://notary.kolide.co"
	DefaultNotaryPrefix = "kolide"
)

Functions

func DeleteCorruptUpdates

func DeleteCorruptUpdates() newestOption

func DeleteOldUpdates

func DeleteOldUpdates() newestOption

func FindBaseDir

func FindBaseDir(path string) string

FindBaseDir takes a binary path, that may or may not include the update directory, and returns the base directory. It's used by the launcher runtime in finding the various binaries.

func FindNewest

func FindNewest(ctx context.Context, fullBinaryPath string, opts ...newestOption) string

FindNewest takes the full path to a binary, and returns the newest update on disk. If there are no updates on disk, it returns the original path. It will return the same fullBinaryPath if that is the newest version.

func FindNewestSelf

func FindNewestSelf(ctx context.Context, opts ...newestOption) (string, error)

FindNewestSelf invokes `FindNewest` with the running binary path, as determined by os.Executable. However, if the current running version is the same as the newest on disk, it will return empty string.

func IsLauncherRestartNeededErr

func IsLauncherRestartNeededErr(err error) bool

func SkipFullBinaryPathCheck

func SkipFullBinaryPathCheck() newestOption

SkipFullBinaryPathCheck skips the final check on FindNewest. This is desirable when being called by FindNewestSelf, otherewise we end up in a infineite recursion. (The recursion is saved by the exec check, but it's better not to trigger it.

Types

type LauncherRestartNeeded

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

func NewLauncherRestartNeededErr

func NewLauncherRestartNeededErr(msg string) LauncherRestartNeeded

func (LauncherRestartNeeded) Error

func (e LauncherRestartNeeded) Error() string

type UpdateChannel

type UpdateChannel string

UpdateChannel determines the TUF target for a Updater. The Default UpdateChannel is Stable.

type UpdateFinalizer

type UpdateFinalizer func() error

UpdateFinalizer is executed after the Updater updates a destination. The UpdateFinalizer is usually a function which will handle restarting the updated binary.

type Updater

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

Updater is a TUF autoupdater. It expects a tar.gz archive with an executable binary, which will be placed into an update area and spawned via appropriate platform mechanisms.

func NewUpdater

func NewUpdater(binaryPath, rootDirectory string, opts ...UpdaterOption) (*Updater, error)

NewUpdater creates a unstarted updater for a specific binary updated from a TUF mirror.

func (*Updater) Run

func (u *Updater) Run(opts ...tuf.Option) (stop func(), err error)

Run starts the updater, which will run until the stop function is called.

type UpdaterOption

type UpdaterOption func(*Updater)

UpdaterOption customizes the Updater.

func WithFinalizer

func WithFinalizer(f UpdateFinalizer) UpdaterOption

WithFinalizer configures an UpdateFinalizer for the updater.

func WithHTTPClient

func WithHTTPClient(client *http.Client) UpdaterOption

WithHTTPClient client configures an http client for the updater. If unspecified, http.DefaultClient will be used.

func WithLogger

func WithLogger(logger log.Logger) UpdaterOption

WithLogger configures a logger.

func WithMirrorURL

func WithMirrorURL(url string) UpdaterOption

WithMirrorURL configures a MirrorURL in the TUF settings.

func WithNotaryPrefix

func WithNotaryPrefix(prefix string) UpdaterOption

WithNotaryPrefix configures a prefix for the binaryTargets

func WithNotaryURL

func WithNotaryURL(url string) UpdaterOption

WithNotaryURL configures a NotaryURL in the TUF settings.

func WithSigChannel

func WithSigChannel(sc chan os.Signal) UpdaterOption

WithSigChannel configures the channel uses for shutdown signaling

func WithUpdateChannel

func WithUpdateChannel(channel UpdateChannel) UpdaterOption

WithUpdate configures the update channel. If unspecified, the Updater will use the Stable channel.