Fussy Firmware Packager
=======================

Fussy provide "embedded firmware" style upgrade mechanics (field upgrades) where 
a user uploads a (signed, possibly encrypted) package to your device and you 
want to verify, unpack and switch to running with that package.  It provides a 
back-off mechanic where a "failsafe" software bundle can be installed to which 
the system will back off in the event of a firmware upgrade failure.

Fussy is focussed on Linux machines, and should not be expected to work on any 
other platform.  It expects to work on fairly "full" distributions, such as an 
Ubuntu Server LTS platform, but even a fairly minimal Debian distribution should 
work.

If you are more interested in desktop auto-updaters, the `Esky`_ project is likely 
closer to your requirements.

.. _Esky: https://github.com/cloudmatrix/esky

Installation
------------

Standard installation (note: rsync is only required to install firmware, not 
pack it):

.. code-block:: bash
    
    $ apt-get install tar rsync gnupg
    $ virtualenv fussy-env
    $ source fussy-env/bin/activate
    $ pip install fussy 

If you would like to extend/enhance Fussy, see :doc:`contribute`
    
Firmware Structure
------------------

Your Fussy-packaged firmware needs to be "self contained" in that all of your 
upgradable code resides within a single directory, with any system-level hooks 
added by symlinking from required directory into your package.

A minimal package named "my-package" might look like this on disk::

    /opt/my-package/current -> firmware-2012-04-12T13.30.03.796749
    /opt/my-package/firmware-2012-04-12T13.30.03.796749
    /opt/my-package/firmware-2012-04-12T13.30.03.796749/.pre-install
    /opt/my-package/firmware-2012-04-12T13.30.03.796749/.post-install
    /opt/my-package/firmware-2012-04-12T13.30.03.796749/etc/fussy/keys

and the system would contain links such that various components of the firmware 
would appear in the "correct" spot on the filesystem::

    /etc/fussy -> /opt/my-package/current/etc/fussy

So that, on the (atomic) switch between any two versions of the software (the 
updating of the `current` link), the new version of the software will be picked 
up by all processes.

Quick Start
-----------

With the above structure, and :ref:`gpg-setup`, the use of fussy looks like 
this (the -e argument says to encrypt for the given client key)::

    $ fussy-pack -r sample-setup -e C064B21C
    ...
    Enter passphrase:
    /tmp/fussy-bsPsty-pack/sample-setup.tar.gz.gpg
    $ fussy-install /tmp/fussy-bsPsty-pack/sample-setup.tar.gz.gpg
    ...
    $ la /opt/firmware/
    total 24K
    drwxr-xr-x 6 mcfletch root  4.0K 2012-04-12 12:01 .
    drwxr-xr-x 4 root     root  4.0K 2012-04-12 11:14 ..
    lrwxrwxrwx 1 mcfletch users   28 2012-04-12 12:01 current -> /opt/firmware/sample-setup-3
    drwxr-xr-x 3 mcfletch users 4.0K 2012-04-12 11:25 sample-setup
    drwxr-xr-x 3 mcfletch users 4.0K 2012-04-12 11:26 sample-setup-1
    drwxr-xr-x 3 mcfletch users 4.0K 2012-04-12 11:37 sample-setup-2
    drwxr-xr-x 3 mcfletch users 4.0K 2012-04-12 12:01 sample-setup-3

Obviously `fussy-install` would normally be run on a different machine than the 
machine doing `fussy-pack`.  The machine doing the `fussy-install` needs to be 
properly set up with the structure described above.

Contents
--------

.. toctree::
   :maxdepth: 2
   
   setupencryption
   pack
   install
   contribute
   nbio
   linktree
   cronlock
   southrollback

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`