USAGE

$FreeBSD: projects/freebsd-update-server/USAGE,v 1.1 2006/08/31 07:48:40 cperciva Exp $

How to use the FreeBSD Update build code
========================================

0. Extract the files in this directory and the src, scripts, and 
patches subdirectories somewhere; /usr/midnightbsd-update-server/ is a
good option.

1. Edit scripts/build.conf as appropriate.

2. Run `scripts/make.sh'.  This will build some binaries, create some
directories, and generate an RSA signing key.  You will be prompted to
enter a passphrase with which to encrypt the signing key.

3. Run `scripts/init.sh ${ARCHITECTURE} ${RELEASE}' for each pair
(architecture, release) for which you want to be able to build updates.
Note that as of 0.1.1-RELEASE, cross-building releases doesn't work (some
files don't cross-build correctly); but once those problems are fixed
it will be possible to cross build updates.

4. Read the output of each `init.sh' run, and check that everything
looks right.  Problem signs to watch out for include:
 * Files which are listed as "built but not released".
 * Files which are listed as "released but not build".
 * Files listed are "differ by more than contents" (this would include
files which have incorrect permissions or file flags).
 * A very long list of files listed as "differ between release and build".
 * A list of build stamps which includes any non-text characters.

5. Run `scripts/mountkey.sh' to prepare the signing key for use.

6. Run `scripts/approve.sh ${ARCHITECTURE} ${RELEASE}' for each
architecture / release pair.  This signs the build, prepares it for
uploading, and "commits" various internal bookkeeping changes (e.g.,
the list of locations of build stamps) in order to prepare for the
next build.

7. Run `scripts/umountkey.sh' to remove the unencrypted signing key
from memory.

8. Run `scripts/upload.sh ${ARCHITECTURE} ${RELEASE}' to upload the 
files to your server.

9. For each security / errata update, copy the patch distributed by the
security team into the appropriate `patches/${RELEASE}' directory(s),
and run `scripts/diff.sh ${ARCHITECTURE} ${RELEASE} ${PATCHNUM}', where
${PATCHNUM} is the patch number (e.g., 9 for 6.0-RELEASE-p9).

10. Assuming the output from `diff.sh' looks ok, repeat steps 5-8 to
sign and upload the binary updates built.

Tips
----

* If you want to allow two different users to sign updates, have the
person who ran `make.sh' run `mountkey.sh' to mount the key, then have
the other(s) run `encryptkey.sh' to save a copy of the key encrypted
with their own passphrase.  (Obviously, everybody involved must use
su or sudo to become root in order to do this.)

* If you want to distribute and update a customized version of MidnightBSD,
there are two options:

  1. Building a custom release.  If you have a custom release and the
  source code in your custom-build ISO matches the binaries you are
  distributing, everything will Just Work once you edit the appropriate
  build.conf files to reflect the location and SHA256 hash of the custom
  release ISO.

  2. Treating local customizations as a patch.  Construct a patch file
  via `cd /usr/src && cvs diff' (note that the patches MUST be relative
  to /usr/src), and place it into the appropriate patches directory.
  Run `diff.sh' specifying a patch number of zero; then install the
  original FreeBSD release onto systems and use the FreeBSD Update
  client to download "updates"; they will end up with your customized
  release.

* If something goes wrong in the `diff' run and you need to modify the
build by hand, BE VERY CAREFUL and modify the files in newworld/R/trees
and the build manifest newworld-index.  Then run `restage.sh' before
running `approve.sh'.

* If you're building updates for multiple releases, the `multi.sh' script
can be very helpful.  It will run the same operation (e.g., "diff") on a
number of architectures and releases, and log the output of each.