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 ¶
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.
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.
Types ¶
type ErrNotWritable ¶ added in v1.7.0
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
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
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.