Packing Your Firmware

Your firmware will be packed into a .tar.gz.gpg format for delivery to your customers. The firmware SHOULD include the fussy package, as well as whatever mechanism you are using to deliver the new firmware packages to your devices. Your system should also make the /etc/fussy directory point into your firmware package so that you can update the keys your machines trust.

Install Scripts

The two installation scripts .pre-install and .post-install are entry points which allow you to control your software before and after the installation process completes. Normally these scripts should shut down and restart services, perform pre-upgrade backups of data, migrate databases, etc. In some cases, they may need to e.g. create system-level symlinks, run apt updates or the like.

These scripts are critical failure points. They must be coded defensively and idempotently, they potentially can be run “backward” (that is, a downgrade rather than an upgrade), or update from extremely old firmware versions. If they fail to run properly, a firware installation failure will occur, and your machine will fall back to the failsafe firmware.

fussy-pack

fussy-pack packs a firmware image into a .tar.gz.gpg file suitable to be delivered to the machine (for example, by a user uploading it).

$ fussy-pack --help
Usage: fussy-pack [options]

Options:
  -h, --help            show this help message and exit
  -x EXCLUDE, --exclude=EXCLUDE
                        Paths/patterns to exclude from the archive
  -r ROOT, --root=ROOT  The root of the directory hierarchy (where tar will be
                        run)
  -e ENCRYPT, --encrypt-for=ENCRYPT
                        The name of the key for which to encrypt (otherwise
                        just sign)

Fussy packing should be integrated into your build script such that it runs on a directory which is uniquely named, for instance:

$ sudo fussy-pack -r build/firmware-2012-04-12T18.32.45

where the name firmware-... is the name of directory to appear in the final /opt/mypackage directory.

$ mkdir firmware-2012-04-12T18.32.45
...
$ fussy-pack -r firmware-2012-04-12T18.32.45 --exclude .coverage

You will be prompted for your gpg pass-phrase during the packing phase if you set a password on your GPG key. The result will be a firmware package with a name such as:

/tmp/fussy-1341234-pack/firmware-2012-04-12T18.32.45.tar.gz.gpg

with the filename printed to stdout at the end of the build process.

Module: fussy.pack

Bundle a package as a signed firmware for installation/redistribution

fussy.pack.get_options()

Produces the OptionParser for :func:main

fussy.pack.main()

Main function for the packing script

fussy.pack.pack(root_dir, excludes=None, encrypt_for=None)

Bundle directory into a firmware file...

• root_dir – directory to be packed into the firmware, the

  os.path.basename() of this directory will be the name used in the created bundle filename and the directory installed into the target on client machines

• excludes – patterns to exclude from the firmware image (passed to

  tar during packing)

• encrypt_for – if specified also encrypts for the given key, should

  be the key ID, fingerprint, or (unique) email

returns absolute filename for generated gpg firmware (created in a temporary directory)