From owner-svn-doc-all@FreeBSD.ORG Sat May 24 20:23:35 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 9432AAFE; Sat, 24 May 2014 20:23:35 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 7E8CF2A9F; Sat, 24 May 2014 20:23:35 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s4OKNZAH088771; Sat, 24 May 2014 20:23:35 GMT (envelope-from bcr@svn.freebsd.org) Received: (from bcr@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s4OKNZS5088770; Sat, 24 May 2014 20:23:35 GMT (envelope-from bcr@svn.freebsd.org) Message-Id: <201405242023.s4OKNZS5088770@svn.freebsd.org> From: Benedict Reuschling Date: Sat, 24 May 2014 20:23:35 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44942 - head/en_US.ISO8859-1/articles/freebsd-update-server X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 24 May 2014 20:23:35 -0000 Author: bcr Date: Sat May 24 20:23:35 2014 New Revision: 44942 URL: http://svnweb.freebsd.org/changeset/doc/44942 Log: Whitespace fixes (bad tag indents, wrap long lines) that igor complained about. Translators can ignore. Modified: head/en_US.ISO8859-1/articles/freebsd-update-server/article.xml Modified: head/en_US.ISO8859-1/articles/freebsd-update-server/article.xml ============================================================================== --- head/en_US.ISO8859-1/articles/freebsd-update-server/article.xml Sat May 24 19:59:04 2014 (r44941) +++ head/en_US.ISO8859-1/articles/freebsd-update-server/article.xml Sat May 24 20:23:35 2014 (r44942) @@ -1,15 +1,22 @@ - - FreeBSD Update Server"> ]> -
- Build Your Own &os; Update Server - - - JasonHelfman +
+ + Build Your Own &os; Update Server + + + + Jason + Helfman + +
&a.jgh.email;
- + + 2009 @@ -30,35 +37,40 @@ $FreeBSD$ - - This article describes building an internal &fbus.ap;. - The freebsd-update-server - is written by &a.cperciva.email;, Security Officer Emeritus of &os;. - For users that think it is convenient to update their systems - against an official update server, building their own &fbus.ap; may - help to extend its functionality by supporting manually-tweaked - &os; releases or by providing a local mirror that will allow faster - updates for a number of machines. - + + This article describes building an internal &fbus.ap;. + The freebsd-update-server + is written by &a.cperciva.email;, Security Officer Emeritus of + &os;. For users that think it is convenient to update their + systems against an official update server, building their own + &fbus.ap; may help to extend its functionality by supporting + manually-tweaked &os; releases or by providing a local mirror + that will allow faster updates for a number of + machines. + Acknowledgments - This article was subsequently printed at BSD - Magazine. + + This article was subsequently printed at BSD + Magazine. Introduction - Experienced users or administrators are often responsible for - several machines or environments. They understand the difficult - demands and challenges of maintaining such an infrastructure. - Running a &fbus.ap; makes it easier to deploy security and software - patches to selected test machines before rolling them out to - production. It also means a number of systems can be updated from the - local network rather than a potentially slower Internet connection. - This article outlines the steps involved in creating an internal + Experienced users or administrators are often responsible + for several machines or environments. They understand the + difficult demands and challenges of maintaining such an + infrastructure. Running a &fbus.ap; makes it easier to deploy + security and software patches to selected test machines before + rolling them out to production. It also means a number of + systems can be updated from the local network rather than a + potentially slower Internet connection. This article outlines + the steps involved in creating an internal &fbus.ap;. @@ -80,9 +92,10 @@ - A user account with at least 4 GB of available space. - This will allow the creation of updates for 7.1 and 7.2, but the - exact space requirements may change from version to version. + A user account with at least 4 GB of available + space. This will allow the creation of updates for 7.1 and + 7.2, but the exact space requirements may change from + version to version. @@ -91,10 +104,12 @@ - A web server, like Apache, - with over half of the space required for the build. For instance, - test builds for 7.1 and 7.2 consume a total amount of 4 GB, - and the webserver space needed to distribute these updates is + A web server, like Apache, + with over half of the space required for the build. For + instance, test builds for 7.1 and 7.2 consume a total amount + of 4 GB, and the webserver space needed to distribute + these updates is 2.6 GB. @@ -108,21 +123,24 @@ Configuration: Installation & Setup - Download the - freebsd-update-server software by installing devel/subversion , and execute: - - &prompt.user; svn co http://svn.freebsd.org/base/user/cperciva/freebsd-update-build freebsd-update-server + Download the + freebsd-update-server software by installing + devel/subversion , and execute: + + &prompt.user; svn co + http://svn.freebsd.org/base/user/cperciva/freebsd-update-build + freebsd-update-server + + Update scripts/build.conf + appropriately. It is sourced during all build + operations. - Update scripts/build.conf appropriately. - It is sourced during all build operations. - - Here is the default build.conf, which should - be modified to suit your environment. + Here is the default build.conf, which + should be modified to suit your environment. - - -# Main configuration file for FreeBSD Update builds. The + # Main configuration file for FreeBSD Update builds. The # release-specific configuration data is lower down in # the scripts tree. @@ -149,57 +167,57 @@ MASTERDIR=update-master.freebsd.org - This is the location where ISO images are downloaded from (by - the fetchiso() subroutine - of scripts/build.subr). The location - configured is not limited to FTP URIs. Any URI scheme - supported by standard &man.fetch.1; utility should work - fine. - - Customizations to the fetchiso() code can - be installed by copying the - default build.subr script to the release and - architecture-specific area - at scripts/RELEASE/ARCHITECTURE/build.subr - and applying local changes. + This is the location where ISO images are downloaded + from (by the fetchiso() subroutine of + scripts/build.subr). The location + configured is not limited to FTP URIs. Any URI scheme + supported by standard &man.fetch.1; utility should work + fine. + + Customizations to the fetchiso() + code can be installed by copying the default + build.subr script to the release and + architecture-specific area at + scripts/RELEASE/ARCHITECTURE/build.subr + and applying local changes. - The name of the build host. This information will be - displayed on updated systems when issuing: + The name of the build host. This information will be + displayed on updated systems when issuing: &prompt.user; uname -v - The SSH key for uploading files to - the update server. A key pair can be created by - typing ssh-keygen -t dsa. This parameter is - optional; standard password authentication will be used as a - fallback authentication method when SSHKEY is - not defined. - - The &man.ssh-keygen.1; manual page has more detailed - information about SSH and the - appropriate steps for creating and using one. + The SSH key for uploading + files to the update server. A key pair can be created by + typing ssh-keygen -t dsa. This parameter + is optional; standard password authentication will be used + as a fallback authentication method when + SSHKEY is not defined. + + The &man.ssh-keygen.1; manual page has more detailed + information about SSH and the + appropriate steps for creating and using one. - Account for uploading files to the update - server. + Account for uploading files to the update server. - Directory on the update server where files are uploaded - to. + Directory on the update server where files are uploaded + to. - The default build.conf shipped with - the freebsd-update-server sources is - suitable for building &arch.i386; releases of &os;. As an example of - building an update server for other architectures, the following steps - outline the configuration changes needed for &arch.amd64;: + The default build.conf shipped with the + freebsd-update-server sources is + suitable for building &arch.i386; releases of &os;. As an + example of building an update server for other architectures, + the following steps outline the configuration changes needed for + &arch.amd64;: @@ -211,13 +229,13 @@ MASTERDIR=update-master.freebsd.org - Install a build.conf in the - newly created build directory. The build configuration - options for &os; 7.2-RELEASE on &arch.amd64; should be similar + Install a build.conf in the newly + created build directory. The build configuration options + for &os; 7.2-RELEASE on &arch.amd64; should be similar to: - # SHA256 hash of RELEASE disc1.iso image. + # SHA256 hash of RELEASE disc1.iso image. export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5 # Components of the world, source, and kernels @@ -233,17 +251,22 @@ export EOL=1275289200 - The &man.sha256.1; hash key for the desired release, is - published within the respective release announcement. + The &man.sha256.1; hash key for the desired release, + is published within the respective release + announcement. - To generate the "End of Life" number for - build.conf, refer to the "Estimated - EOL" posted on the &os; - Security Website. The value - of EOL can be derived from the date listed on - the web site, using the &man.date.1; utility, for example: + To generate the "End of Life" number for + build.conf, refer to the "Estimated + EOL" posted on the &os; + Security Website. The value of + EOL can be derived from the date + listed on the web site, using the &man.date.1; utility, + for example: + &prompt.user; date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s' @@ -254,10 +277,11 @@ export EOL=1275289200 Building Update Code - The first step is to run scripts/make.sh. - This will build some binaries, create directories, and generate an RSA - signing key used for approving builds. In this step, a passphrase will - have to be supplied for the final creation of the signing key. + The first step is to run + scripts/make.sh. This will build some + binaries, create directories, and generate an RSA signing key + used for approving builds. In this step, a passphrase will have + to be supplied for the final creation of the signing key. &prompt.root; sh scripts/make.sh cc -O2 -fno-strict-aliasing -pipe findstamps.c -o findstamps @@ -281,8 +305,8 @@ Verifying - enter aes-256-cbc encryption Keep a note of the generated key fingerprint. This value - is required in /etc/freebsd-update.conf for - binary updates. + is required in /etc/freebsd-update.conf + for binary updates. At this point, we are ready to stage a build. @@ -292,8 +316,8 @@ Verifying - enter aes-256-cbc encryption &prompt.root; sh scripts/init.sh amd64 7.2-RELEASE - What follows is a sample of an initial build - run. + What follows is a sample of an initial + build run. &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 @@ -341,11 +365,13 @@ world|base|/usr/lib/libalias_ftp.a During this second build cycle, the network time protocol daemon, &man.ntpd.8;, is turned off. Per &a.cperciva.email;, - Security Officer Emeritus of &os;, "the freebsd-update-server - build code needs to identify timestamps which are stored in files so - that they can be ignored when comparing builds to determine which - files need to be updated. This timestamp-finding works by doing two - builds 400 days apart and comparing the results." + Security Officer Emeritus of &os;, "the freebsd-update-server + build code needs to identify timestamps which are stored in + files so that they can be ignored when comparing builds to + determine which files need to be updated. This + timestamp-finding works by doing two builds 400 days apart and + comparing the results." Mon Aug 24 17:54:07 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE @@ -417,12 +443,12 @@ they look sensible, then run # sh -e approve.sh amd64 7.2-RELEASE to sign the release. - 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 - uploading. + 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 uploading. &prompt.root; cd /usr/local/freebsd-update-server @@ -436,8 +462,8 @@ Wed Aug 26 12:50:06 PDT 2009 Copying fil 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 the approval process is complete, the upload procedure may - be started. + After the approval process is complete, the upload procedure + may be started. &prompt.root; cd /usr/local/freebsd-update-server @@ -445,9 +471,9 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st - In the event update code needs to be re-uploaded, this may be - done by changing to the public distributions directory for the - target release and updating attributes of the + In the event update code needs to be re-uploaded, this may + be done by changing to the public distributions directory for + the target release and updating attributes of the uploaded file. @@ -460,12 +486,13 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st avoid making the instructions Apache-specific here. --> - The uploaded files will need to be in the - document root of the webserver in order for updates - to be distributed. The exact configuration will vary depending on the - web server used. For the Apache web server, - please refer to the Configuration of - Apache servers section in the Handbook. + The uploaded files will need to be in the document root of + the webserver in order for updates to be distributed. The exact + configuration will vary depending on the web server used. For + the Apache web server, please refer + to the Configuration + of Apache servers section in the Handbook. Update client's KeyPrint and ServerName in - /etc/freebsd-update.conf, and perform updates as - instructed in the &os; + /etc/freebsd-update.conf, and perform + updates as instructed in the &os; Update - - - section of the Handbook. + section of the + Handbook. - In order for &fbus.ap; 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 7.1-RELEASE to 7.2-RELEASE, updates will need to be built - and uploaded to your distribution server for both versions. + In order for &fbus.ap; 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 7.1-RELEASE to 7.2-RELEASE, updates will need to be built + and uploaded to your distribution server for both + versions. - For reference, the entire run of init.sh is + For reference, the entire run of init.sh is attached. Building a Patch - Every time a security advisory - or security notice - is announced, a patch update can be built. + Every time a security + advisory or security + notice is announced, a patch update can be + built. For this example, 7.1-RELEASE will be used. @@ -537,38 +572,43 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st - Create the patch directory of the respective release - under /usr/local/freebsd-update-server/patches/. + Create the patch directory of the respective release under + /usr/local/freebsd-update-server/patches/. &prompt.user; mkdir -p /usr/local/freebsd-update-server/patches/7.1-RELEASE/ &prompt.user; cd /usr/local/freebsd-update-server/patches/7.1-RELEASE - As an example, take the patch for &man.named.8;. Read the advisory, - and grab the necessary file from &os; Security - Advisories. More information on interpreting the advisory, - can be found in the &os; Handbook. - - In the security brief, - this advisory 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 consistent with - official &os; patch levels, but its name may be freely chosen. - For this build, let us follow the currently established practice of - &os; and call this p7. Rename the file: + As an example, take the patch for &man.named.8;. Read the + advisory, and grab the necessary file from &os; Security + Advisories. More information on interpreting the + advisory, can be found in the &os; + Handbook. + + In the security + brief, this advisory 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 consistent with official &os; patch + levels, but its name may be freely chosen. 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/7.1-RELEASE/; mv bind.patch 7-SA-09:12.bind - 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 contained in the patch directory. + 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 contained in the patch directory. - There can be custom patches added to any build. Use the number - zero, or any other number. + There can be custom patches added to any build. Use the + number zero, or any other number. @@ -577,18 +617,18 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st 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 - release prior to running the diff build. + 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 release prior to running the diff build. &prompt.root; cd /usr/local/freebsd-update-server &prompt.root; sh scripts/diff.sh amd64 7.1-RELEASE 7 - What follows is a sample of a differential - build run. + What follows is a sample of a + differential build run. &prompt.root; sh -e scripts/diff.sh amd64 7.1-RELEASE 7 Wed Aug 26 10:09:59 PDT 2009 Extracting world+src for FreeBSD/amd64 7.1-RELEASE-p7 @@ -704,8 +744,8 @@ the new builds. &prompt.root; sh scripts/upload.sh amd64 7.1-RELEASE - For reference, the entire run of - diff.sh is + For reference, the entire run of diff.sh is attached. @@ -732,17 +772,20 @@ the new builds. If a custom release is built using the native - make release procedure, - freebsd-update-server code will work - from your release. As an example, a release without ports or - documentation can be built by clearing functionality pertaining - to documentation subroutines findextradocs (), - addextradocs () and altering the download - location in fetchiso (), respectively, in - scripts/build.subr. As a last step, change - the &man.sha256.1; hash in build.conf under - your respective release and architecture and you are ready to build - off your custom release. + make release procedure, + freebsd-update-server code will + work from your release. As an example, a release without + ports or documentation can be built by clearing + functionality pertaining to documentation subroutines + findextradocs (), + addextradocs () and altering the + download location in fetchiso (), + respectively, in scripts/build.subr. + As a last step, change the &man.sha256.1; hash in + build.conf under your respective + release and architecture and you are ready to build off your + custom release. # Compare ${WORKDIR}/release and ${WORKDIR}/$1, identify which parts # of the world|doc subcomponent are missing from the latter, and @@ -752,17 +795,18 @@ the new builds. # Add extra docs to ${WORKDIR}/$1 addextradocs () { - } - + } - Adding - flags to buildworld and + Adding flags to + buildworld and obj targets in the scripts/build.subr script may speed up processing depending on the hardware used, however it is not necessary. Using these flags in other targets is not - recommended, as it may cause the build to become unreliable. + recommended, as it may cause the build to become + unreliable. # Build the world log "Building world" @@ -777,11 +821,12 @@ the new builds. - Create an appropriate DNS - SRV record for the update server, and put others behind it with - variable weights. Using this facility will provide update - mirrors, however this tip is not necessary unless you wish to - provide a redundant service. + Create an appropriate DNS + SRV record for the update server, and put others behind it + with variable weights. Using this facility will provide + update mirrors, however this tip is not necessary unless you + wish to provide a redundant service. _http._tcp.update.myserver.com. IN SRV 0 2 80 host1.myserver.com. SRV 0 1 80 host2.myserver.com.