selfupdate

package
v1.7.3 Latest Latest
Warning

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

Go to latest
Published: Nov 6, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package selfupdate implements `dockercmd --self-upgrade`: download the latest GitHub release asset for this OS/arch, verify its SHA-256 and atomically replace the running executable.

Self-update executes downloaded code, so the checksum check is mandatory: the binary is only swapped in once its SHA-256 matches the digest GitHub records for the asset. The download lands in the target directory (same filesystem) so the final swap is an atomic rename.

Index

Constants

This section is empty.

Variables

View Source
var ErrPolicyRefused = errors.New("update refused by policy")

ErrPolicyRefused is returned by ApplyChecked when the release actually resolved by this call fails the caller's allow predicate (e.g. a granularity ceiling). The predicate is evaluated against the SAME fetch that would be installed, not an earlier/cached one, so a release published between an earlier check and this call can never slip past the gate.

View Source
var ErrUpToDate = errors.New("already up to date")

ErrUpToDate is returned by Apply when the running version is already current.

Functions

func Precheck added in v1.7.3

func Precheck() error

Precheck reports why installing an update in place would fail or must not be attempted, without downloading or writing anything: *ErrPackageManaged for a packaged binary, *ErrNotWritable when the binary's directory can't be written (e.g. systemd's ProtectSystem=strict without it in ReadWritePaths). nil means an install may go ahead. The UI uses it to decide whether to offer the in-app update at all, instead of offering one that is bound to fail.

func Run

func Run(ctx context.Context, current string, w io.Writer, checkOnly bool) error

Run checks for a newer release and, unless checkOnly is set, downloads and installs it. Progress is written to w; it is a no-op (with a message) when the running version is already current. This is the CLI (`--self-upgrade`) entry.

Types

type ErrNotWritable added in v1.7.0

type ErrNotWritable struct {
	Dir string
	Err error
}

ErrNotWritable is returned when the executable's directory can't be written to — surfaced before any download happens (see preflightWritable). The CLI path (Run, called from `--self-upgrade`) can offer to re-exec elevated when it sees this; the in-app path (Apply, behind the web UI's "Update & restart") has no terminal to prompt on and just reports it — that surface needs the permission granted at install time instead (see ReadWritePaths in deploy/dockercmd.service, added in v1.6.2).

func (*ErrNotWritable) Error added in v1.7.0

func (e *ErrNotWritable) Error() string

func (*ErrNotWritable) Unwrap added in v1.7.0

func (e *ErrNotWritable) Unwrap() error

type ErrPackageManaged added in v1.7.3

type ErrPackageManaged struct {
	Exe     string
	Manager string // "apt" or "dnf"
}

ErrPackageManaged is returned when the executable belongs to a .deb/.rpm package. Replacing it in place would leave the package manager believing an older version is installed (and fight it on the next upgrade), and making /usr/bin writable for the service so the in-app path could do it would hand the service every system binary. So it is never attempted, from the web UI or the CLI: the package manager updates it instead.

func (*ErrPackageManaged) Command added in v1.7.3

func (e *ErrPackageManaged) Command() string

Command is the package-manager command that updates dockercmd.

func (*ErrPackageManaged) Error added in v1.7.3

func (e *ErrPackageManaged) Error() string

type Result added in v1.5.0

type Result struct {
	From   string `json:"from"`   // version before the upgrade
	To     string `json:"to"`     // version now staged on disk
	Asset  string `json:"asset"`  // release asset that was installed
	SHA256 string `json:"sha256"` // verified checksum of the new binary
}

Result describes a completed upgrade.

func Apply added in v1.5.0

func Apply(ctx context.Context, current string) (Result, error)

Apply downloads, verifies and installs the latest release, returning a Result describing the upgrade. It is the programmatic (in-app) entry point and writes no progress output. ErrUpToDate is returned when nothing newer exists.

func ApplyChecked added in v1.7.0

func ApplyChecked(ctx context.Context, current string, allowed func(latestTag string) bool) (Result, error)

ApplyChecked is Apply, but the resolved release's tag must also pass allowed before anything is installed — checked against the exact release this call is about to install, never a value resolved by an earlier, possibly-stale call (e.g. a cached "update available" status). This closes a TOCTOU gap a caller enforcing a policy (like a version-granularity ceiling) would otherwise have: checking that policy against yesterday's cached status and then calling plain Apply lets whatever is latest AT INSTALL TIME through unchecked, which can be a newer release than the one the check saw. Returns ErrPolicyRefused, without downloading anything, when allowed(tag) is false.

Jump to

Keyboard shortcuts

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