README
¶
selfupdate: Build self-updating Go programs
NOTE: Original work at github.com/inconshreveable/go-update, modified for the needs within MinIO project
Package update provides functionality to implement secure, self-updating Go programs (or other single-file targets) A program can update itself by replacing its executable file with a new version.
It provides the flexibility to implement different updating user experiences like auto-updating, or manual user-initiated updates. It also boasts advanced features like binary patching and code signing verification.
Example of updating from a URL:
import (
"fmt"
"net/http"
"github.com/minio/selfupdate"
)
func doUpdate(url string) error {
resp, err := http.Get(url)
if err != nil {
return err
}
defer resp.Body.Close()
err = selfupdate.Apply(resp.Body, selfupdate.Options{})
if err != nil {
// error handling
}
return err
}
Features
- Cross platform support (Windows too!)
- Binary patch application
- Checksum verification
- Code signing verification
- Support for updating arbitrary files
License
This SDK is distributed under the Apache License, Version 2.0, see LICENSE for more information. Original work was also distributed under the same license.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var AppFs = afero.NewOsFs()
Functions ¶
func Apply ¶
Apply performs an update of the current executable or opts.TargetFile, with the contents of the given io.Reader. When the update fails, it is unlikely that old executable is corrupted, but still, applications need to check the returned error with RollbackError() and notify the user of the bad news and ask them to recover manually.
func CommitBinary ¶
CommitBinary moves the new executable to the location of the current executable or opts.TargetPath if specified. It performs the following operations:
- Renames /path/to/target to /path/to/.target.old
- Renames /path/to/.target.new to /path/to/target
- If the final rename is successful, deletes /path/to/.target.old, returns no error. On Windows, the removal of /path/to/target.old always fails, so instead Apply hides the old file instead.
- If the final rename fails, attempts to roll back by renaming /path/to/.target.old back to /path/to/target.
If the roll back operation fails, the file system is left in an inconsistent state where there is no new executable file and the old executable file could not be be moved to its original location. In this case you should notify the user of the bad news and ask them to recover manually. Applications can determine whether the rollback failed by calling RollbackError, see the documentation on that function for additional detail.
func PrepareAndCheckBinary ¶
PrepareAndCheckBinary reads the new binary content from io.Reader and performs the following actions:
- If configured, applies the contents of the update io.Reader as a binary patch.
- If configured, computes the checksum of the executable and verifies it matches.
- If configured, verifies the signature with a public key.
- Creates a new file, /path/to/.target.new with the TargetMode with the contents of the updated file
func RollbackError ¶
RollbackError takes an error value returned by Apply and returns the error, if any, that occurred when attempting to roll back from a failed update. Applications should always call this function on any non-nil errors returned by Apply.
If no rollback was needed or if the rollback was successful, RollbackError returns nil, otherwise it returns the error encountered when trying to roll back.
Types ¶
type Options ¶
type Options struct {
// TargetPath defines the path to the file to update.
// The emptry string means 'the executable file of the running program'.
TargetPath string
// Create TargetPath replacement with this file mode. If zero, defaults to 0755.
TargetMode os.FileMode
// Checksum of the new binary to verify against. If nil, no checksum or signature verification is done.
Checksum []byte
// Verifier for signature verification. If nil, no signature verification is done.
Verifier *Verifier
// Use this hash function to generate the checksum. If not set, SHA256 is used.
Hash crypto.Hash
// If nil, treat the update as a complete replacement for the contents of the file at TargetPath.
// If non-nil, treat the update contents as a patch and use this object to apply the patch.
Patcher Patcher
// Store the old executable file at this path after a successful update.
// The empty string means the old executable file will be removed after the update.
OldSavePath string
}
func (*Options) CheckPermissions ¶
CheckPermissions determines whether the process has the correct permissions to perform the requested update. If the update can proceed, it returns nil, otherwise it returns the error that would occur if an update were attempted.
type Patcher ¶
Patcher defines an interface for applying binary patches to an old item to get an updated item.
func NewBSDiffPatcher ¶
func NewBSDiffPatcher() Patcher
NewBSDifferPatcher returns a new Patcher that applies binary patches using the bsdiff algorithm. See http://www.daemonology.net/bsdiff/
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
func NewVerifier ¶
func NewVerifier() *Verifier
func (*Verifier) LoadFromFile ¶
func (*Verifier) LoadFromURL ¶
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
binarydist
Package binarydist implements binary diff and patch as described on http://www.daemonology.net/bsdiff/.
|
Package binarydist implements binary diff and patch as described on http://www.daemonology.net/bsdiff/. |
|
osext
Extensions to the standard "os" package.
|
Extensions to the standard "os" package. |