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).

.. code-block:: bash

    $ 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.

.. code-block:: bash
    
    $ 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
------------------

.. automodule:: fussy.pack
    :members: