source: build-files/freebsd-update/USAGE @ 635dc54

9.2-releasereleng/10.0releng/10.0.1releng/10.0.2releng/10.0.3
Last change on this file since 635dc54 was 635dc54, checked in by Kris Moore <kris@…>, 15 months ago

Add our freebsd-update code to GIT

This will become a dumping ground for mods we may make to the freebsd-update
build process, as well as the specific patches we have going into a release

  • Property mode set to 100644
File size: 3.7 KB
Line 
1$FreeBSD$
2
3How to use the FreeBSD Update build code
4========================================
5
60. Extract the files in this directory and the src, scripts, and
7patches subdirectories somewhere; /usr/freebsd-update-server/ is a
8good option.
9
101. Edit scripts/build.conf as appropriate.
11
122. Run `scripts/make.sh'.  This will build some binaries, create some
13directories, and generate an RSA signing key.  You will be prompted to
14enter a passphrase with which to encrypt the signing key.
15
163. Run `scripts/init.sh ${ARCHITECTURE} ${RELEASE}' for each pair
17(architecture, release) for which you want to be able to build updates.
18Note that as of 6.1-RELEASE, cross-building releases doesn't work (some
19files don't cross-build correctly); but once those problems are fixed
20it will be possible to cross build updates.
21
224. Read the output of each `init.sh' run, and check that everything
23looks right.  Problem signs to watch out for include:
24 * Files which are listed as "built but not released".
25 * Files which are listed as "released but not build".
26 * Files listed are "differ by more than contents" (this would include
27files which have incorrect permissions or file flags).
28 * A very long list of files listed as "differ between release and build".
29 * A list of build stamps which includes any non-text characters.
30
315. Run `scripts/mountkey.sh' to prepare the signing key for use.
32
336. Run `scripts/approve.sh ${ARCHITECTURE} ${RELEASE}' for each
34architecture / release pair.  This signs the build, prepares it for
35uploading, and "commits" various internal bookkeeping changes (e.g.,
36the list of locations of build stamps) in order to prepare for the
37next build.
38
397. Run `scripts/umountkey.sh' to remove the unencrypted signing key
40from memory.
41
428. Run `scripts/upload.sh ${ARCHITECTURE} ${RELEASE}' to upload the
43files to your server.
44
459. For each security / errata update, copy the patch distributed by the
46security team into the appropriate `patches/${RELEASE}' directory(s),
47and run `scripts/diff.sh ${ARCHITECTURE} ${RELEASE} ${PATCHNUM}', where
48${PATCHNUM} is the patch number (e.g., 9 for 6.0-RELEASE-p9).
49
5010. Assuming the output from `diff.sh' looks ok, repeat steps 5-8 to
51sign and upload the binary updates built.
52
53Tips
54----
55
56* If you want to allow two different users to sign updates, have the
57person who ran `make.sh' run `mountkey.sh' to mount the key, then have
58the other(s) run `encryptkey.sh' to save a copy of the key encrypted
59with their own passphrase.  (Obviously, everybody involved must use
60su or sudo to become root in order to do this.)
61
62* If you want to distribute and update a customized version of FreeBSD,
63there are two options:
64
65  1. Building a custom release.  If you have a custom release and the
66  source code in your custom-build ISO matches the binaries you are
67  distributing, everything will Just Work once you edit the appropriate
68  build.conf files to reflect the location and SHA256 hash of the custom
69  release ISO.
70
71  2. Treating local customizations as a patch.  Construct a patch file
72  via `cd /usr/src && cvs diff' (note that the patches MUST be relative
73  to /usr/src), and place it into the appropriate patches directory.
74  Run `diff.sh' specifying a patch number of zero; then install the
75  original FreeBSD release onto systems and use the FreeBSD Update
76  client to download "updates"; they will end up with your customized
77  release.
78
79* If something goes wrong in the `diff' run and you need to modify the
80build by hand, BE VERY CAREFUL and modify the files in newworld/R/trees
81and the build manifest newworld-index.  Then run `restage.sh' before
82running `approve.sh'.
83
84* If you're building updates for multiple releases, the `multi.sh' script
85can be very helpful.  It will run the same operation (e.g., "diff") on a
86number of architectures and releases, and log the output of each.
Note: See TracBrowser for help on using the repository browser.