README

A layer that builds The Update Framework in Yocto

Dependencies
============

This layer depends on:

  URI: git://git.yoctoproject.org/poky
  branch: rocko
 
  or

  URI: git://git.openembedded.org/openembedded-core
  branch: rocko

  URI: git://git.openembedded.org/bitbake
  branch: 1.36

  URI: https://github.com/MontaVista-OpenSourceTechnology/meta-montavista-cgx
  branch: rocko

  URI: git://git.openembedded.org/meta-openembedded
  layers: meta-perl, meta-gnome, meta-multimedia, xfce-layer 
  branch: rocko

Source code
===========

https://github.com/MontaVista-OpenSourceTechnology/meta-tuf


Maintenance
===========

Maintainers:
    support@mvista.com


Contributing
============

Contributions and patches can be sent to the MontaVista  mailing
list: support@mvista.com"

When sending patches please take a look at the contribution guide available
here: https://wiki.yoctoproject.org/wiki/Contribution_Guidelines

example:
git send-email -1 -M --to support@mvista.com  --subject-prefix=meta-montavista-cgx][PATCH


Table of Contents
=================

  I. Adding the meta-tuf layer to your build
 II. Using meta-tuf
III. Key update
 IV. ostree and ostree-rpm


I. Adding the meta-tuf layer to your build
=================================================

In order to use this layer, you need to make the build system aware of
it.

Assuming the meta-montavista-cgl layer exists at the top-level of your
yocto build tree, you can add it to the build system by adding the
location of the meta-montavista-cgl layer to bblayers.conf, along with any
other layers needed. Adapt the below list to proper format.

  BBLAYERS:

    meta
    meta-openembedded/meta-networking
    meta-openembedded/meta-oe
    meta-openembedded/meta-python
    meta-openembedded/meta-webserver

II. Using meta-tuf
==================
The design of meta-tuf allows you to use TUF in a normal fashion with
assists from this layer.  This allows you to configure TUF as you want
but have semi-automated means for loading you TUF repository from the
build.

The meta-tuf layer is a little bit unusual because it is a setup to
allow deployment to a remote system.  It sets things up to use the
tuf-manifest repo tool deploying updates, and it installs the
tuf-manifest client tool on the client with the configuration files
specified in local.conf.  It also create the proper manifest files so
tufm-repo can use them to install files into a TUF repository.

Using this tool does require knowledge of The Update Framework (TUF).
See https://theupdateframework.github.io/ for that.  How you configure
things has security implications.

You should also refer to the tuf-manifest package documentation.

The following variables are used by meta-tuf and can be used to
control it's operation.  These are:

TUF_MANIFEST_DIR ?= "${DEPLOY_DIR_IMAGE}"

The place where the tuf-manifest manifest files will be stored.  By
default this is the standard image directory, but it can be any other
place that you want to maintain it (so it can be backed up, etc.).

TUF_MANIFEST_USER_FILENAME ?= "manifest"

The base name of the manifest files.  These will have a '.<num>'
appended to them for version, so manifest.1 is the first version,
manifest.2 the second, etc.  The default is "manifest".

TUF_MANIFEST_FILENR ?= "${TUF_MANIFEST_CURRENT_FILENR}"

The next file number for a manifest number.  This is used to set the
client manifest number it uses to know what version it is on. By
default TIF_MANIFEST_DIR is scanned for files named
TUF_MANIFEST_USER_FILENAME.<num>, this variable will be set to the
next sequence it finds.  So if manifest.1 and manifest.2 are there,
this variable will be "3".  If there is no manifest file, it will
be set to "1".  Manifest files must be in sequence!

TUF_MANIFEST_CLIENT_REPO

This is the client repository directory that you create when creating
your TUF repo.  It is installed on the client.

TUF_MANIFEST_CONF

The tuf-manifest configuration file to install on the client.  This
sets the URL where updates will come from, the handler for updates,
etc.

FIXME - add info about setting PRs properly, using the PR server.

The basic procedure is:

 1) Get your image working like you want.  The builds themselves are
    not tied to the framework directly, you have to add them by hand.
    So you can build, test, rebuild, etc. until you get what you want,
    then add them.

 2) Create a TUF repo.  You can do this with the repo.py tool from
    TUF.  You can also use the tufm-repo tool that is part of
    tuf-manifest, since it is a wrapper around the repo tool.  This is
    an important step to get right, as it will affect the security of
    your system.  For best security, you should:
    a) Create the repo on an air-gapped machine, and set the number
       of root keys (generally a minimum of 3).
    b) Create separate root signing keys on other machines (generally
       at least two other machine) and sign the repo with those keys.
       Make sure not to transfer the root keys off the machine they
       were created on.
    c) Transfer the repo to the build machine (preferably also air-gapped)
       without the root keys, of course, just the target, snapshot,
       and timestamp keys.  This is where you will install the files
       with tufm-repo.
    With this setup, you can survive the loss/compromise of any single
    key.

 3) Add:

      INHERIT =+ "tuf-manifest"
      IMAGE_INSTALL_append = " python3-tuf-manifest-client"
      TUF_MANIFEST_CLIENT_REPO = "/path/to/tuf/tufclient"
      TUF_MANIFEST_CONF = "/path/to/tuf-manifest.conf"
      EXTRA_IMAGE_FEATURES += "package-management"

    to your local.conf and rebuild.  You need RPM package management
    on, too.  This will create the manifest file and put
    tuf-manifest-client onto the target.  The two variables shown are
    required, you may need to set other variables as described above.

    Note that you cannot do the above until you have the repo in place
    on the build system.  The repo and conf files must be in place.
    You could do step 2 first, then step 1 and 3 together.

    The full format of tuf-manifest.conf is describe in the tuf_manifest
    documentation at
      https://github.com/MontaVista-OpenSourceTechnology/tuf_manifest
    In general, you should only need the following set:

      [Manifest]
      url=<user must set this>
      filebase=manifest
      handler=<user must set this>

    The filebase is optional, but if you use a different manifest name
    in the steps below, it must be set in filebase.

    The python-tufm-manifest-client package includes:
      /usr/lib/tuf-manifest/scripts/tuf-rpm-updater
    that is a simple script that will update RPM packages, you can
    use that for the handler if you are doing straight RPM.

 4) Build the host version of the tuf-manifest tools:

      bitbake python3-tuf-native python3-tuf-manifest-native
      bitbake build-sysroots
      source <the proper env script in the project bin directory>
      export PYTHONPATH=${BUILDROOT}/tmp/sysroots/x86_64/usr/lib/python2.7/site-packages

    This will get the tufm-repo command into your path.  Hopefully
    the PYTHONPATH thing will go away, but it's necessary for now.

 5) Copy the tmp/deploy/images/<target>/<imagename>.tuf-manifest to
    <TUF_MANIFEST_DIR>/manifest.1.  This will be the first version of
    the image.  The filename "manifest.<n>" is the default, you can use
    a different base name if you like, you just need to set it properly
    in the tuf-manifest.conf file on the target.

 6) Run:
      tufm-repo --load-manifest --manifest <TUF_MANIFEST_DIR>/manifest.1 
        --manifest-dir tmp/deploy/rpm/*
    To process the manifest and load all the files into the repository.

 7) Copy the repository to your web server.

 8) Deploy your target system and have it run tufm-client
    periodically.  this will look for updates and install them
    automatically.  You should log output and errors from tufm-client.

The tufm-repo command has a subcommand that allows updating the
timestamp and snapshot timeouts periodically, which is useful for
the web server.

To deploy the next update:

 1) Make the necessary changes, build, test, etc. as you normally
    would.

 2) Copy the tmp/deploy/images/<target>/<imagename>.tuf-manifest to
    TUF_MANIFEST_DIR/manifest.2.  This will be the second version of
    the image.

Then follow steps 4-7 above.  Your clients will automatically pick up
the changes and install them.

III. Key update
===============

If a key is compromised or it going to expire, or you need to issue a
new root metadata file because it is going to expire...

*Write this*

IV. ostree and ostree-rpm
=========================

describe how to use ostree and ostree-rpm