minio/selfupdate

The selfupdate package allows developers to build secure, self-updating Go programs or other single-file targets. It supports various update workflows, including auto-updates and manual user-initiated updates.

Key capabilities include:

• Cross-platform support: Works on multiple platforms, including Windows.
• Binary patching: Reduces download sizes by applying patches instead of full binaries.
• Security: Supports checksum verification and code signing verification to ensure binary integrity.
• Flexibility: Can be used to update arbitrary files, not just the running executable.

The osext package provides extensions to the standard os package to reliably locate the currently running executable file. This is useful for performing self-upgrades or locating resources relative to the binary.

It is preferred over using os.Args[0] or the current working directory, as both can be unreliable or manipulated. The package provides multi-platform support for:

• Linux
• OS X
• Windows
• Plan 9
• BSDs.

You can implement self-updating functionality by fetching a new binary from a URL and applying it using selfupdate.Apply. This method replaces the current executable with the content provided in the reader. Ensure you handle the HTTP response body and provide appropriate error handling for the update process.

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
}

The selfupdate.Options struct allows you to customize the update process. Key fields include:

• Patcher: An implementation of the Patcher interface used to apply binary patches (e.g., selfupdate.NewBSDiffPatcher()). Use this when shipping patches instead of full binaries to save bandwidth.
• Hash: The hash function used for checksum verification. It defaults to crypto.SHA256.
• Checksum: A byte slice representing the expected checksum of the new binary. This is used to verify the integrity of the update.

To ensure the integrity of the downloaded binary, provide a checksum in selfupdate.Options. By default, selfupdate uses crypto.SHA256 to validate the file.

import (
	"crypto"
	_ "crypto/sha256"
	"encoding/hex"
	"io"
	"github.com/minio/selfupdate"
)

func updateWithChecksum(binary io.Reader, hexChecksum string) error {
	checksum, err := hex.DecodeString(hexChecksum)
	if err != nil {
		return err
	}

	err = selfupdate.Apply(binary, selfupdate.Options{
		Hash:     crypto.SHA256, // default
		Checksum: checksum,
	})
	if err != nil {
		// handle error
	}
	return err
}

To reduce download sizes, you can ship binary patches instead of full binaries. You must provide a Patcher in the selfupdate.Options. The selfupdate package provides a NewBSDiffPatcher() for bsdiff format patches.

import (
	"io"
	"github.com/minio/selfupdate"
)

func updateWithPatch(patch io.Reader) error {
	err := selfupdate.Apply(patch, selfupdate.Options{
		Patcher: selfupdate.NewBSDiffPatcher(),
	})
	if err != nil {
		// handle error
	}
	return err
}

When Apply or CommitBinary fails, the library attempts to restore the original binary by renaming the .old file back to the target path. If this rollback attempt itself fails, the filesystem is left in an inconsistent state (the original binary is gone and the new one was not placed).

Use RollbackError(err) to inspect the error. If it returns a non-nil error, the update process failed to clean up after itself, and manual intervention is required.

The primary way to update a program is by calling selfupdate.Apply. This function takes an io.Reader containing the new binary (or patch) and a selfupdate.Options struct. If the update fails, you can use selfupdate.RollbackError(err) to check if the error is related to a failed rollback attempt, allowing you to handle failed updates gracefully.

import (
	"fmt"
	"net/http"
	"github.com/minio/selfupdate"
)

func doUpdate(url string) error {
	// request the new file
	resp, err := http.Get(url)
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	// Apply the update from the response body
	err = selfupdate.Apply(resp.Body, selfupdate.Options{})
	if err != nil {
		if rerr := selfupdate.RollbackError(err); rerr != nil {
			fmt.Printf("Failed to rollback from bad update: %v\n", rerr)
		}
	}
	return err
}

Before attempting an update, call CheckPermissions() to verify if the current process has sufficient rights to write to the target directory and create the necessary temporary files. It attempts to create and then immediately remove a dummy file (.<filename>.check-perm) in the target directory to validate write access.

opts := selfupdate.Options{TargetPath: "/usr/local/bin/myapp"}
if err := opts.CheckPermissions(); err != nil {
    log.Fatalf("Insufficient permissions to perform update: %v", err)
}