1Upgrade Instructions for OpenBSM
2--------------------------------
3
4OpenBSM integrates into the FreeBSD source tree in several places:
5
6src/contrib/openbsm        The OpenBSM distribution itself
7src/sys/bsm                Modified versions of some bsm/ include files
8src/sys/security/audit     Kernel audit framework, some OpenBSM-based files
9src/usr.sbin/*audit*       Makefiles for various OpenBSM tools
10src/etc/Makefile           Installation of /etc OpenBSM files
11src/lib/libbsm/*           Build for OpenBSM library
12
13OpenBSM is normally built using an integrated autoconf/automake build
14system.  For the purposes of tight integration with FreeBSD, we use an
15adapted BSD make (bmake) build system loosely based on the automake
16setup.  We also rely on a static config.h generated when OpenBSM is
17imported, rather than re-configuring every build.  This leads to a
18more reproduceable build environment, and avoids dependence on things
19not in the base tree (i.e., autoconf, automake, GNU make, etc).  An
20upgrade of OpenBSM generally involves the following steps:
21
22- Vendor import of OpenBSM into src/contrib.
23- Run configure, commit src/contrib/openbsm/config/config.h.
24- Replication of src/contrib/openbsm/bsm changes into src/sys/bsm.
25- Possible updates to src/sys/security/audit, especially relating to
26  audit_bsm_token.c.
27- Update any library, tool, or etc BSD Makefiles to add new files,
28  defines, or other generally useful or necessary things.
29
30Certain files are present only in the vendor branch, and not in FreeBSD
31development branches:
32
33  contrib/openbsm/bsm  audit.h audit_internal.h audit_kevents.h 
34                       audit_record.h 
35
36This prevents confusion regarding whether the src/sys/bsm or contrib
37versions of the include files should be used in the build.  Normally, the
38CVS vendor import goes along the following lines:
39
40  cd ~/p4/projects/trustedbsd/openbsm
41  cvs -n -d rwatson@repoman.FreeBSD.org:/home/ncvs -q import \
42	src/contrib/openbsm TrustedBSD OPENBSM_1_0_ALPHA_1
43
44Replacing the version string as required.  Remove the "-n" argument once
45the import is tested in order to perform the actual import.
46
47Propagation of changes to src/sys/{bsm,security/audit} is something that
48requires careful coordination and attention to detail.  These files are
49not on CVS vendor branches, but do have the same local vs. vendor merge
50issues.  Remember that contrib/openbsm (and the rest of the system) will
51be built with the version of the bsm/ include files in src/sys/bsm, not
52the version in contrib/openbsm/bsm, so buildworld tests before committing
53are necessary, and the commits to various parts of the system must be
54made in close succession.
55
56$FreeBSD$
57