--- article.sgml.orig 2009-11-20 16:47:34.000000000 +0100 +++ article.sgml 2009-11-22 01:11:07.000000000 +0100 @@ -1,11 +1,14 @@ %articles.ent; -FreeBSD Update Server"> + +&os; Update Server"> ]>
- Your Very Own FreeBSD Update Server + + How to Set Up a &os; Update Server Jason @@ -38,9 +41,14 @@ The freebsd-update-server software is written by &a.cperciva;, current Security Officer of &os;. - If you thought it was fun to update your system against an Official - Update Server, just wait until you have an updated system from your - very own &fbus.ap;. + + For users who think it is convenient to update their systems + against an official update server, building an own &fbus.ap; may + help to extend its functionality by supporting manually-tweaked + &os; releases or by providing a local mirror. @@ -60,7 +68,8 @@ Prerequisites - To build an internal &fbus.ap; some requirements should be + + To build an internal &fbus.ap; the following requirements should be met. @@ -70,8 +79,10 @@ A user account with at least 4 GB of available space. - This will allow for creation of updates for 7.1 and 7.2. Beyond - this, new space requirements will need to be considered. + + This will allow for creation of updates for 7.1 and 7.2, but + the exact space requirements may change from version to + version. @@ -83,7 +94,10 @@ A web server, like Apache, with over half of the space required for the build. For instance, - our test builds total 4 GB, and the webserver space needed to + + test builds for 7.1 and 7.2 total 4 GB, and the webserver space needed to distribute updates is 2.6 GB. @@ -205,14 +219,17 @@ The default build.conf file shipped with the freebsd-update-server sources are - suitable for building &i386; releases of &os;. As an example of - building an update server for other architectures we will show in - the following paragraphs the configuration changes needed for an - AMD64 update server: + + suitable for building &arch.i386; releases of &os;. As an example of + building an update server for other architectures, configuration + changes needed for &arch.amd64; will be presented in the + following paragraphs. - Create a build environment for AMD64: + + Create a build environment for &arch.amd64;: &prompt.user; mkdir -p /usr/local/freebsd-update-server/scripts/RELEASE-7.2/amd64 @@ -223,7 +240,8 @@ Install a build.conf file in the newly created build directory. The build configuration - options for &os; 7.2-RELEASE on AMD64 should be similar + + options for &os; 7.2-RELEASE on &arch.amd64; should be similar to: # SHA256 hash of RELEASE disc1.iso image. @@ -244,8 +262,10 @@ build.conf, refer to the "Estimated EOL" posted on the &os; - Security Website. You can derive the value - of EOL from the date listed on the web + Security Website. The value + + of EOL can be derived from the date listed on the web site, using the &man.date.1; utility, e.g.: &prompt.user; date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s' @@ -295,15 +315,17 @@ binary updates. - At this point, we are ready to stage a build. + + At this point, everything is ready to stage a build. &prompt.root; cd /usr/local/freebsd-update-server &prompt.root; sh scripts/init.sh amd64 RELEASE-7.2 - What follows is sample of an initial build - run. + + The output of the command, a sample of an initial build + run is shown below. &prompt.root; sh scripts/init.sh amd64 7.2-RELEASE Mon Aug 24 16:04:36 PDT 2009 Starting fetch for FreeBSD/amd64 7.2-RELEASE @@ -342,14 +364,24 @@ world|base|/usr/lib/libalias_cuseeme.a world|base|/usr/lib/libalias_dummy.a world|base|/usr/lib/libalias_ftp.a -... ... - + Then the build of the world is performed again, with world patches. A more detailed explanation may be found in scripts/build.subr. - + + + In order for &os; Update Server to work properly, updates + for both the current release and the + release one wants to upgrade to need to be + built. This is necessary for determining the differences of + files between releases. For example, when upgrading a &os; + system from version 7.1 to 7.2, updates will need to be built + for 7.1-RELEASE as well as for 7.2-RELEASE. Mon Aug 24 17:54:07 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE Wed Sep 29 00:54:34 UTC 2010 Building world for FreeBSD/amd64 7.2-RELEASE @@ -383,12 +415,11 @@ world|base|/usr/lib/libalias_cuseeme.a world|base|/usr/lib/libalias_dummy.a world|base|/usr/lib/libalias_ftp.a -... ... - - And then the build completes... - + + Finally the build completes. Values of build stamps, excluding library archive headers: v1.2 (Aug 25 2009 00:40:36) @@ -423,8 +454,9 @@ # sh -e approve.sh amd64 7.2-RELEASE to sign the release. - Approve the build if everything looks ok. More information on - determining if things are ok can be found in the distributed source + + Approve the build if everything is correct. More information on + determining this can be found in the distributed source file named USAGE. Execute scripts/approve.sh, as directed. This will sign the release, and move components into a staging area suitable for @@ -442,7 +474,8 @@ Wed Aug 26 12:50:07 PDT 2009 Updating databases for FreeBSD/amd64 7.2-RELEASE Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE - After completing the approval process, you may proceed with the + + After completing the approval process, it may be followed by the upload. @@ -452,39 +485,42 @@ + The uploaded files will need to be in the - DocumentRoot of the webserver in order for updates - to be distributed. For further explanation, please refer to the - Configuration section of the Apache - documentation. + document root of the webserver in order for updates + to be distributed. For further explanation for Apache, please refer to the + section about Configuration of Apache servers + in the Handbook. - - Updates for the current release of the &os; system you are - updating, and what you want to upgrade to need - to be built in order for &os; Update Server to work properly. This - is necessary for merging of files between releases. For example, if - you are updating a system from &os; 7.1 to &os; 7.2, you will need - to have update code built for &os; 7.1-RELEASE and - &os; 7.2-RELEASE. - - Update client's KeyPrint and - ServerName in + + Update the KeyPrint and + ServerName values in the client's /etc/freebsd-update.conf, and perform updates as instructed in the &os; Update - instructions in the Handbook. - - For reference, here is the entire run of init.sh. + + section of the Handbook. + + + For reference, the entire run of init.sh is attached. @@ -494,7 +530,8 @@ url="&url.base;/security/advisories.html">security advisory is announced, a patch update can be built. - For this example, we will be using 7.1-RELEASE. + + For this example, 7.1-RELEASE will be used. A couple of assumptions are made for a different release build: @@ -514,49 +551,61 @@ under /usr/local/freebsd-update-server/patches/. - &prompt.user; mkdir -p /usr/local/freebsd-update-server/patches/RELEASE-7.1/ + + &prompt.user; mkdir -p /usr/local/freebsd-update-server/patches/RELEASE-7.1/ +&prompt.user; cd /usr/local/freebsd-update-server/patches/RELEASE-7.1 As an example, take the patch for &man.named.8;. Read the advisory, and grab the necessary file from &os; Security - Advisories. If you have trouble interpreting the advisory, - please read this help - page for more information. + + Advisories. More information on interpreting the advisory, + can be found in the Handbook. From the security brief, - we can see it is called SA-09:12.bind. After + + it can be seen that it is called SA-09:12.bind. After downloading the file, it is required to rename the file to an appropriate patch level. It is suggested to keep this inline with - official &os; patch levels, but you are free to choose any name you prefer. + + official &os; patch levels, but its name can be chosen freely. For this build, let us follow the currently established practice of &os; and call this p7. Rename the file: - &prompt.user; cd /usr/local/freebsd-update-server/patches/RELEASE-7.1/; mv bind.patch 7-SA-09:12.bind + + &prompt.user; mv bind.patch 7-SA-09:12.bind - or: + Or: - &prompt.user; cd /usr/local/freebsd-update-server/patches/RELEASE-7.1/; fetch -o 7-SA-09:12.bind http://security.FreeBSD.org/patches/SA-09:12/bind.patch + &prompt.user; fetch -o 7-SA-09:12.bind http://security.FreeBSD.org/patches/SA-09:12/bind.patch - When running a patch level build, we are assuming that previous + + When running a patch level build, it is assumed that previous patches are in place. When a patch build is run, it will run all patches less than or equal to the number specified. - It is up to the administrator of the freebsd-update - server to take appropriate measures to verify the authenticity of - every patch. - - You can also add your own patches to any build. Use the number + There can be custom patches added to any build. Use the number zero, or any other number. + + + It is up to the administrator of the freebsd-update + server to take appropriate measures to verify the authenticity of + every patch. + + + At this point, a diff is ready to be built. The software checks first to see if a scripts/init.sh has been run on the respective @@ -597,7 +646,6 @@ Wed Aug 26 12:43:23 PDT 2009 Copying metadata files into staging area for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 12:43:25 PDT 2009 Constructing metadata index and tag for FreeBSD/amd64 7.1-RELEASE-p7 ... -... Files found which include build stamps: kernel|generic|/GENERIC/hptrr.ko kernel|generic|/GENERIC/kernel @@ -615,7 +663,6 @@ world|base|/usr/lib/libalias_dummy.a world|base|/usr/lib/libalias_ftp.a ... -... Values of build stamps, excluding library archive headers: v1.2 (Aug 26 2009 18:13:46) v1.2 (Aug 26 2009 18:11:44) @@ -642,12 +689,10 @@ Wed Aug 26 17:55:02 UTC 2009 Wed Aug 26 17:55:02 UTC 2009 Wed Aug 26 17:20:39 UTC 2009 -... ... - + Updates are printed, and approval is requested. - New updates: kernel|generic|/GENERIC/kernel.symbols|f|0|0|0555|0|7c8dc176763f96ced0a57fc04e7c1b8d793f27e006dd13e0b499e1474ac47e10| @@ -689,8 +734,9 @@ &prompt.root; sh scripts/upload.sh amd64 RELEASE-7.1 - For reference, here is the entire run of - diff.sh. + + For reference, the entire run of + diff.sh is attached. @@ -712,27 +758,31 @@ - If you build your own release using the native + + If a custom release is built by using the native make release procedure, the freebsd-update-server code will work - from your release. As an example, you may build a release without - ports or documentation and add a custom kernel. After removing + from your release. As an example, a release without + ports or documentation or with a custom kernel can be built. After removing functionality pertaining to the documentation subroutine and altering the buildworld() subroutine in scripts/build.subr, the freebsd-update-code will successfully - build update code on this release. + build update code based on this release. + Add make -j NUMBER to scripts/build.subr to speed up processing. - Adding flags to anything other than + Adding flags to anything in the script other than make buildworld and make obj may cause the build to become unreliable. @@ -745,14 +795,19 @@ kernel can rate-limit most of the "strange" packets alredy. --> Create a firewall rule to block outgoing RST packets. Due to a bug noted in this posting, - you will have many time-outs and fail to update a system. + url="http://lists.freebsd.org/pipermail/freebsd-stable/2009-April/049578.html">in a posting + on the &a.stable; mailing list in April 2009, there may be time-outs and fail when updating a system. + Create an appropriate DNS - SRV record for your update server, and put others behind it with + + SRV record for the update server, and put others behind it with variable weights. This effectively creates update mirrors. _http._tcp.update.myserver.com. IN SRV 0 2 80 host1.myserver.com.