Skip site navigation (1)Skip section navigation (2)
Date:      Fri, 20 Nov 2009 12:26:44 -0800
From:      Jason <jhelfman@e-e.com>
To:        Giorgos Keramidas <keramida@FreeBSD.org>
Cc:        Tom Rhodes <trhodes@FreeBSD.org>, "doc@FreeBSD.org" <doc@FreeBSD.org>, Gabor PALI <pgj@FreeBSD.org>, Gabor Kovesdan <gabor@FreeBSD.org>, Rene Ladan <rene@FreeBSD.org>, Manolis Kiagias <manolis@FreeBSD.org>
Subject:   Re: [RFC] Article on freebsd-update-server
Message-ID:  <20091120202642.GK6241@eggman.experts-exchange.com>
In-Reply-To: <87ws1luqmx.fsf@kobe.laptop>
References:  <4B05BA06.3010303@FreeBSD.org> <87ws1luqmx.fsf@kobe.laptop>

next in thread | previous in thread | raw e-mail | index | archive | help

--x4pBfXISqBoDm8sr
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Disposition: inline

Hi Everyone,

I've made comments inline to the patch. I would not want to make any changes
to the formatting, as I believe it is good as it stands now.

I very much appreciate everyones input, time and comments on my article,
and have learned so much in this process.

I have attached the diff with comments.

Thanks, again
Jason

On Fri, Nov 20, 2009 at 06:07:02PM +0200, Giorgos Keramidas thus spake:
>On Thu, 19 Nov 2009 23:35:02 +0200, Manolis Kiagias <manolis@FreeBSD.org> wrote:
>> Hi all,
>>
>> I am sending this to my usual reviewers and the doc@ list, everyone is
>> welcome to comment.
>>
>> Jason Helfman (jhelfman@e-e.com) is  actively involved with our
>> documentation set and you may have seen some of his patches.
>>
>> His initial contribution however is the article in this PR:
>>
>> http://www.freebsd.org/cgi/query-pr.cgi?pr=139095
>>
>> I've been working  on this article with Jason for quite some time, and
>> we think it's about time it gets a broader review.
>>
>> The source is here:
>>
>> http://people.freebsd.org/~manolis/patches/freebsd-update-server/article.sgml.txt
>
>Some of the changes I made locally while reading the source are shown in
>diff format below.  They are based on the latest revision of the article
>source at http://mercurial.dyndns.org/mercurial/freebsd-doc-el (the last
>change I pulled was 6d8923ea5ca3 from 2009-11-20 10:05:02 +0200).
>
>Some of the changes I made to the article are rewording, formatting,
>spell checking fixes, or other tiny nits I noticed.  Others are merely
>adding inline SGML comments.  Most of them are things we can fix before
>committing this to CVS.  There are also a few that are probably ok to
>fix later.
>
>: diff -r 6d8923ea5ca3 en_US.ISO8859-1/articles/freebsd-update-server/article.sgml
>: --- a/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml       Fri Nov 20 10:05:02 2009 +0200
>: +++ b/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml       Fri Nov 20 17:47:40 2009 +0200
>: @@ -80,11 +80,11 @@
>:        </listitem>
>:
>:        <listitem>
>: -       <para>An <ulink
>: -           url="&url.books.handbook;/network-apache.html">Apache
>: -           web server</ulink>, with over half of the space required for the
>: -         build.  For instance, our test builds total 4&nbsp;GB, and the
>: -         webserver space needed to distribute updates is 2.6&nbsp;GB.</para>
>: +       <para>A web server, like <ulink
>: +           url="&url.books.handbook;/network-apache.html">Apache</ulink>,
>: +         with over half of the space required for the build.  For instance,
>: +         our test builds total 4&nbsp;GB, and the webserver space needed to
>: +         distribute updates is 2.6&nbsp;GB.</para>
>:        </listitem>
>
>If freebsd-update can work with other HTTP servers, it is a good idea to avoid
>writing Apache-specific instructions.  I know a few installations of FreeBSD
>that prefer lighttpd or nginx, for example.
>
>:      <title>Configuration: Installation & Setup</title>
>:
>: -    <para>Download <ulink url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink>
>: +    <para>Download
>: +      the <ulink url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink>
>:        software.  A tarball may be downloaded, or use &man.csup.1; and the
>
>Tiny nit.
>
>:         <listitem>
>: -         <para>This is where the subroutine <function>fetchiso()</function>
>: -           declared in <filename>scripts/build.subr</filename> will contact
>: -           the configured source for downloading the &os; ISO.  This setting
>: -           is not limited to <application>ftp</application>, it may also be
>: -           a web (<application>httpd</application>) address as well.
>: -           For our purposes, ISO's are on the same server as our internal
>: -           http server that will be serving updates.  The software has been
>: -           configured to look in that location.  For this setup, we have to
>: -           alter the routine to fetch the ISO.  By copying the source
>: -           <filename>build.subr</filename> to
>: -           <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename> this
>: -           file will be sourced instead of the released source for
>: -           <filename>build.subr</filename>.</para>
>: +         <para>This is the location where ISO images are downloaded from (by
>: +           the <function>fetchiso()</function> subroutine
>: +           of <filename>scripts/build.subr</filename>).  The location
>: +           configured here is not limited to FTP URIs.  Any URI scheme
>: +           supported by the standard &man.fetch.1; utility should work fine.
>: +           In our own setup the ISO images are on the same internal http
>: +           server that will be serving the updates.</para>
>: +
>: +         <para>Customizations to the <function>fetchiso()</function> code can
>: +           be installed by copying the
>: +           default <filename>build.subr</filename> script to the release- and
>: +           architecture-specific area
>: +           at <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename>
>: +           and applying local edits.</para>
>
>I tried to reword the original text here.  If you like the new version, please
>feel free to keep it.  If not, we have to find a good way to simplify the
>large sentences of the original.
>
>:         <term><literal>BUILDHOSTNAME</literal></term>
>:
>:         <listitem>
>: -         <para>Host where software will be built.  Coincidentally, this
>: -           information will be displayed on updated systems when
>: -           issuing:</para>
>: +         <para>The name of the build host.  This information will be
>: +           displayed on updated systems when issuing:</para>
>
>"Coincidentally" seems superfluous here.
>
>:         <term><literal>SSHKEY</literal></term>
>:
>:         <listitem>
>: -         <para>Key used when uploading data to an update server which will
>: -           provide patches or upgrades to clients.  A key pair may be
>: -           created using <command>ssh-keygen -t dsa</command>.  Alteration
>: -           of this parameter is not required as stadnard password
>: -           authentication through <application>ssh</application> will be
>: -           used.</para>
>: +         <para>The <application>SSH</application> key for uploading files to
>: +           the update server.  A key pair can be created by
>: +           typing <command>ssh-keygen -t dsa</command>.  This parameter is
>: +           optional; standard password authentication will be used as a
>: +           fallback authentication method when <literal>SSHKEY</literal> is
>: +           not defined.</para>
>:
>: -         <para>&man.ssh-keygen.1; has more detailed information in creating
>: -           a key pair.</para>
>: +         <para>&man.ssh-keygen.1; has more detailed information
>: +           about <application>SSH</application> and the appropriate steps for
>: +           creating and using one.</para>
>
>Another suggestion for rewording the text, writing smaller sentences, and
>other minor wording nits.
>
>:         <listitem>
>: -         <para>Account that files are uploaded to on remote system.</para>
>: +         <para>Account that files are uploaded to on the update
>: +           server.</para>
>:         </listitem>
>:        </varlistentry>
>:
>: @@ -194,54 +197,68 @@ MASTERDIR=update-master.freebsd.org</pro
>:         <term><literal>MASTERDIR</literal></term>
>:
>:         <listitem>
>: -         <para>Directory where files are uploaded to on remote
>: -           system.</para>
>: +         <para>Directory where files are uploaded to on the update
>: +           server.</para>
>
>I think I like "update server" better than "remote system" here.  The update
>server may be the same machine that builds the snapshots.  By removing the
>unstated assumption that it is *not*, the text sounds more accurate.
>
>:        </varlistentry>
>:      </variablelist>
>:
>: -    <para>Now that build directives are set, the installation files are
>: -      configured for a build.  For this example, we will use
>: -      <literal>RELEASE-7.2</literal> under <literal>amd64</literal>
>: -      architecture.  Configuration files for &i386;
>: -      architecture are available with downloaded source.</para>
>: +     <para>The default <filename>build.conf</filename> file shipped with
>: +       the <application>freebsd-update-server</application> 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:</para>
>
>We haven't actually described *any* installation so far.  So I changed this
>part to describe what freebsd-update-server defaults seem to be, and switched
>the rest of the section from alternating text and <screen> samples to a
><procedure> with separate steps:
>
>: -    <para>Create build environment directory under <filename
>: -       class="directory">scripts/RELEASE-7.2/amd64</filename>.</para>
>: +    <procedure>
>: +      <step>
>: +        <para>Create a build environment for AMD64:</para>
>:
>: -    <informalexample>
>: -      <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/scripts/RELEASE-7.2/amd64</userinput></screen>
>: -    </informalexample>
>: +        <informalexample>
>: +          <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/scripts/RELEASE-7.2/amd64</userinput></screen>
>: +        </informalexample>
>: +      </step>
>:
>: -    <para>This is the <filename>build.conf</filename> file that should be
>: -      placed in the directory just created.</para>
>: +      <step>
>:
>: -    <programlisting># SHA256 hash of RELEASE disc1.iso image.
>: +        <para>Install a <filename>build.conf</filename> file in the
>: +          newly created build directory.  The build configuration
>: +          options for &os; 7.2-RELEASE on AMD64 should be similar
>: +          to:</para>
>: +
>: +        <programlisting># SHA256 hash of RELEASE disc1.iso image.
>:  export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5
>:
>:  # Components of the world, source, and kernels
>:  export WORLDPARTS="base catpages dict doc games info manpages proflibs lib32"
>: -export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5 \
>: -               lib libexec release rescue sbin secure share sys tools  \
>: -               ubin usbin cddl"
>: +export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5  \
>: +                lib libexec release rescue sbin secure share sys tools  \
>: +                ubin usbin cddl"
>:  export KERNELPARTS="generic"
>:
>:  # EOL date
>:  export EOL=1275289200</programlisting>
>:
>: -    <note>
>: -      <para>To generate the "End of Life" number for
>: -       <filename>build.conf</filename>, refer to the "Estimated EOL" posted
>: -       on the <ulink url="&url.base;/security/security.html">&os;
>: -       Security Website</ulink>.  Based on this date, you can issue
>: -       <command>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' +%s</command>,
>: -       and substitute actual date parameters for those stated by
>: -       &os;.</para>
>: +        <note>
>: +          <para>To generate the "End of Life" number for
>: +            <filename>build.conf</filename>, refer to the "Estimated
>: +            EOL" posted on
>: +            the <ulink url="&url.base;/security/security.html">&os;
>: +              Security Website</ulink>.  You can derive the value
>: +            of <literal>EOL</literal> from the date listed on the web
>: +            site, using the &man.date.1; utility, e.g.:</para>
>:
>: -      <para>The &man.sha256.1; hash key for the desired release, is
>: -       published within the respective <ulink
>: -         url="&url.base;/releases/">release announcement </ulink>.</para>
>: -    </note>
>: +          <screen>&prompt.user; <userinput>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s'</userinput></screen>
>: +        </note>
>: +
>: +        <note>
>: +          <para>The &man.sha256.1; hash key for the desired release, is
>: +            published within the
>: +            respective <ulink url="&url.base;/releases/">release
>: +              announcement</ulink>.</para>
>: +        </note>
>: +      </step>
>: +    </procedure>
>:    </sect1>
>
>NOTE: The <notes> above can probably stand on their own, outside of the
><procedure> element.
>
>:    <sect1 id="build">
>: @@ -273,9 +290,9 @@ enter aes-256-cbc encryption password:
>:  Verifying - enter aes-256-cbc encryption password:</screen>
>:
>:      <note>
>: -      <para>Note down the generated KeyPrint; this value is entered into
>: -       <filename>/etc/freebsd-update.conf</filename> for binary
>: -       updates.</para>
>: +      <para>Keep a note of the generated key fingerpring.  This value is
>: +       entered into <filename>/etc/freebsd-update.conf</filename> for
>: +       binary updates.</para>
>:      </note>
>
>There are various places that the article refers to  "KeyPrint".  I think it
>means "key fingerpring", but I am not sure.  If that's what the real meaning
>should be, please use "key fingerprint".
>
>:      <screen>Mon Aug 24 17:54:07 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE
>: @@ -411,10 +428,7 @@ to sign the release.</screen>
>:        file named <filename>USAGE</filename>.  Execute
>:        <filename>scripts/approve.sh</filename>, as directed.  This will sign
>:        the release, and move components into a staging area suitable for
>: -      uploading.  It is important to make sure that your key is mounted
>: -      during this process.  A simple <command>df</command> will show if it
>: -      is mounted.  If not mounted, mount the key with the passphrase supplied
>: -      when creating it earlier.</para>
>: +      uploading.</para>
>
>I don't know where the key mounting bits come from.  It seems to refer to
>those FreeBSD installations where PGP keys are stored in removable media, like
>a USB flash disk.  Why do we have to explicitly mention this here?  After all,
>we don't describe how gpg-agent(1) works, or how seahorse(1) integrates PGP
>with Gnome, or any other case of the dozens of PGP setups possible...
>
>: @@ -524,9 +547,11 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
>:      <note>
>:        <para>When running a patch level build, we are assuming 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.  Beyond this,
>: -       you will have to take appropriate measures to verify authenticity
>: -       of the patch.</para>
>: +       patches less than or equal to the number specified.</para>
>: +
>: +      <para><emphasis>It is up to the administrator of the freebsd-update
>: +         server to take appropriate measures to verify the authenticity of
>: +         every patch.</emphasis></para>
>
>I think we ought to emphasize a bit the part about patch authenticity, but I
>am not sure if I chose the right way to do this.
>
>: -    <para>Follow the same process as noted before for appoving a build.</para>
>: +    <para>Follow the same process as noted before for approving a build:</para>
>
>Typo.
>
>There are more changes, in the attached patch.  Most of them are attempts to
>improve the wording of various small parts of the article.  Please see the
>attached diff for all of them.
>
>One more important detail.  We are still discussing at doceng@ how we can
>bring the final article into CVS.  So, please hold from committing this, until
>we have resolved all the remaining details.
>
>I'm sure that a lot of people will love reading an article that describes in
>detail how to set up a local freebsd-update server.  Thanks for all the work
>done so far on what seems to be an excellent article! :-D
>

>diff -r 6d8923ea5ca3 en_US.ISO8859-1/articles/freebsd-update-server/article.sgml
>--- a/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml	Fri Nov 20 10:05:02 2009 +0200
>+++ b/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml	Fri Nov 20 17:48:23 2009 +0200
>@@ -80,11 +80,11 @@
>       </listitem>
> 
>       <listitem>
>-	<para>An <ulink
>-	    url="&url.books.handbook;/network-apache.html">Apache
>-	    web server</ulink>, with over half of the space required for the
>-	  build.  For instance, our test builds total 4&nbsp;GB, and the
>-	  webserver space needed to distribute updates is 2.6&nbsp;GB.</para>
>+	<para>A web server, like <ulink
>+	    url="&url.books.handbook;/network-apache.html">Apache</ulink>,
>+	  with over half of the space required for the build.  For instance,
>+	  our test builds total 4&nbsp;GB, and the webserver space needed to
>+	  distribute updates is 2.6&nbsp;GB.</para>
>       </listitem>
> 
>       <listitem>
>@@ -97,7 +97,8 @@
>   <sect1 id="Configuration">
>     <title>Configuration: Installation & Setup</title>
> 
>-    <para>Download <ulink url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink>
>+    <para>Download
>+      the <ulink url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink>
>       software.  A tarball may be downloaded, or use &man.csup.1; and the
>       <literal>projects-all</literal> collection.</para>
> 
>@@ -138,19 +139,20 @@ MASTERDIR=update-master.freebsd.org</pro
> 	<term><literal>FTP</literal></term>
> 
> 	<listitem>
>-	  <para>This is where the subroutine <function>fetchiso()</function>
>-	    declared in <filename>scripts/build.subr</filename> will contact
>-	    the configured source for downloading the &os; ISO.  This setting
>-	    is not limited to <application>ftp</application>, it may also be
>-	    a web (<application>httpd</application>) address as well.
>-	    For our purposes, ISO's are on the same server as our internal
>-	    http server that will be serving updates.  The software has been
>-	    configured to look in that location.  For this setup, we have to
>-	    alter the routine to fetch the ISO.  By copying the source
>-	    <filename>build.subr</filename> to
>-	    <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename> this
>-	    file will be sourced instead of the released source for
>-	    <filename>build.subr</filename>.</para>
>+	  <para>This is the location where ISO images are downloaded from (by
>+	    the <function>fetchiso()</function> subroutine
>+	    of <filename>scripts/build.subr</filename>).  The location
>+	    configured here is not limited to FTP URIs.  Any URI scheme
>+	    supported by the standard &man.fetch.1; utility should work fine.
>+	    In our own setup the ISO images are on the same internal http
>+	    server that will be serving the updates.</para>
>+
>+	  <para>Customizations to the <function>fetchiso()</function> code can
>+	    be installed by copying the
>+	    default <filename>build.subr</filename> script to the release- and
>+	    architecture-specific area
>+	    at <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename>
>+	    and applying local edits.</para>
> 	</listitem>
>       </varlistentry>
> 
>@@ -158,9 +160,8 @@ MASTERDIR=update-master.freebsd.org</pro
> 	<term><literal>BUILDHOSTNAME</literal></term>
> 
> 	<listitem>
>-	  <para>Host where software will be built.  Coincidentally, this
>-	    information will be displayed on updated systems when
>-	    issuing:</para>
>+	  <para>The name of the build host.  This information will be
>+	    displayed on updated systems when issuing:</para>
> 
> 	  <screen>&prompt.user; <userinput>uname -v</userinput></screen>
> 	</listitem>
>@@ -170,15 +171,16 @@ MASTERDIR=update-master.freebsd.org</pro
> 	<term><literal>SSHKEY</literal></term>
> 
> 	<listitem>
>-	  <para>Key used when uploading data to an update server which will
>-	    provide patches or upgrades to clients.  A key pair may be
>-	    created using <command>ssh-keygen -t dsa</command>.  Alteration
>-	    of this parameter is not required as stadnard password
>-	    authentication through <application>ssh</application> will be
>-	    used.</para>
>+	  <para>The <application>SSH</application> key for uploading files to
>+	    the update server.  A key pair can be created by
>+	    typing <command>ssh-keygen -t dsa</command>.  This parameter is
>+	    optional; standard password authentication will be used as a
>+	    fallback authentication method when <literal>SSHKEY</literal> is
>+	    not defined.</para>
> 
>-	  <para>&man.ssh-keygen.1; has more detailed information in creating
>-	    a key pair.</para>
>+	  <para>&man.ssh-keygen.1; has more detailed information
>+	    about <application>SSH</application> and the appropriate steps for
>+	    creating and using one.</para>
> 	</listitem>
>       </varlistentry>
> 
>@@ -186,7 +188,8 @@ MASTERDIR=update-master.freebsd.org</pro
> 	<term><literal>MASTERACCT</literal></term>
> 
> 	<listitem>
>-	  <para>Account that files are uploaded to on remote system.</para>
>+	  <para>Account that files are uploaded to on the update
>+	    server.</para>
> 	</listitem>
>       </varlistentry>
> 
>@@ -194,54 +197,68 @@ MASTERDIR=update-master.freebsd.org</pro
> 	<term><literal>MASTERDIR</literal></term>
> 
> 	<listitem>
>-	  <para>Directory where files are uploaded to on remote
>-	    system.</para>
>+	  <para>Directory where files are uploaded to on the update
>+	    server.</para>
> 	</listitem>
>       </varlistentry>
>     </variablelist>
> 
>-    <para>Now that build directives are set, the installation files are
>-      configured for a build.  For this example, we will use
>-      <literal>RELEASE-7.2</literal> under <literal>amd64</literal>
>-      architecture.  Configuration files for &i386;
>-      architecture are available with downloaded source.</para>
>+     <para>The default <filename>build.conf</filename> file shipped with
>+       the <application>freebsd-update-server</application> 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:</para>
> 
>-    <para>Create build environment directory under <filename
>-	class="directory">scripts/RELEASE-7.2/amd64</filename>.</para>
>+    <procedure>
>+      <step>
>+        <para>Create a build environment for AMD64:</para>
> 
>-    <informalexample>
>-      <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/scripts/RELEASE-7.2/amd64</userinput></screen>
>-    </informalexample>
>+        <informalexample>
>+          <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/scripts/RELEASE-7.2/amd64</userinput></screen>
>+        </informalexample>
>+      </step>
> 
>-    <para>This is the <filename>build.conf</filename> file that should be
>-      placed in the directory just created.</para>
>+      <step>
> 
>-    <programlisting># SHA256 hash of RELEASE disc1.iso image.
>+        <para>Install a <filename>build.conf</filename> file in the
>+          newly created build directory.  The build configuration
>+          options for &os; 7.2-RELEASE on AMD64 should be similar
>+          to:</para>
>+
>+        <programlisting># SHA256 hash of RELEASE disc1.iso image.
> export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5
> 
> # Components of the world, source, and kernels
> export WORLDPARTS="base catpages dict doc games info manpages proflibs lib32"
>-export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5	\
>-		lib libexec release rescue sbin secure share sys tools	\
>-		ubin usbin cddl"
>+export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5  \
>+                lib libexec release rescue sbin secure share sys tools  \
>+                ubin usbin cddl"
> export KERNELPARTS="generic"
> 
> # EOL date
> export EOL=1275289200</programlisting>
> 
>-    <note>
>-      <para>To generate the "End of Life" number for
>-	<filename>build.conf</filename>, refer to the "Estimated EOL" posted
>-	on the <ulink url="&url.base;/security/security.html">&os;
>-	Security Website</ulink>.  Based on this date, you can issue
>-	<command>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' +%s</command>,
>-	and substitute actual date parameters for those stated by
>-	&os;.</para>
>+        <note>
>+          <para>To generate the "End of Life" number for
>+            <filename>build.conf</filename>, refer to the "Estimated
>+            EOL" posted on
>+            the <ulink url="&url.base;/security/security.html">&os;
>+              Security Website</ulink>.  You can derive the value
>+            of <literal>EOL</literal> from the date listed on the web
>+            site, using the &man.date.1; utility, e.g.:</para>
> 
>-      <para>The &man.sha256.1; hash key for the desired release, is
>-	published within the respective <ulink
>-	  url="&url.base;/releases/">release announcement </ulink>.</para>
>-    </note>
>+          <screen>&prompt.user; <userinput>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s'</userinput></screen>
>+        </note>
>+
>+        <note>
>+          <para>The &man.sha256.1; hash key for the desired release, is
>+            published within the
>+            respective <ulink url="&url.base;/releases/">release
>+              announcement</ulink>.</para>
>+        </note>
>+      </step>
>+    </procedure>
>   </sect1>
> 
>   <sect1 id="build">
>@@ -273,9 +290,9 @@ enter aes-256-cbc encryption password:
> Verifying - enter aes-256-cbc encryption password:</screen>
> 
>     <note>
>-      <para>Note down the generated KeyPrint; this value is entered into
>-	<filename>/etc/freebsd-update.conf</filename> for binary
>-	updates.</para>
>+      <para>Keep a note of the generated key fingerpring.  This value is
>+	entered into <filename>/etc/freebsd-update.conf</filename> for
>+	binary updates.</para>
>     </note>
> 
>     <para>At this point, we are ready to stage a build.</para>
>@@ -330,8 +347,8 @@ world|base|/usr/lib/libalias_ftp.a
> 
>     <note>
>       <para>Then the build of the world is performed again, with world
>-	patches.  A more detailed explanation may be found in
>-	<filename>scripts/build.subr</filename>.</para>
>+	patches.  A more detailed explanation may be found
>+	in <filename>scripts/build.subr</filename>.</para>
>     </note>
> 
>     <screen>Mon Aug 24 17:54:07 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE
>@@ -411,10 +428,7 @@ to sign the release.</screen>
>       file named <filename>USAGE</filename>.  Execute
>       <filename>scripts/approve.sh</filename>, as directed.  This will sign
>       the release, and move components into a staging area suitable for
>-      uploading.  It is important to make sure that your key is mounted
>-      during this process.  A simple <command>df</command> will show if it
>-      is mounted.  If not mounted, mount the key with the passphrase supplied
>-      when creating it earlier.</para>
>+      uploading.</para>
> 
>     <informalexample>
>       <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
>@@ -436,6 +450,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
> &prompt.root; <userinput>sh scripts/upload.sh <replaceable>amd64 RELEASE-7.2</replaceable></userinput></screen>
>     </informalexample>
> 
>+    <!-- If freebsd-update works with other http servers too, we should
>+	 avoid making the instructions Apache-specific here. -->
>     <para>The uploaded files will need to be in the
>       <literal>DocumentRoot</literal> of the webserver in order for updates
>       to be distributed.  For further explanation, please refer to the
>@@ -443,6 +459,10 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
> 	url="&url.books.handbook;/network-apache.html">Apache
> 	documentation</ulink>.</para>
> 
>+    <!-- This note seems either out of place.  I find it hard to read and it
>+	 is a bit difficult to understand why it is related to the rest of
>+	 this section.  It looks like something that would fit nicely in an
>+	 introductory section about the way a freebsd-update server works. -->
>     <note>
>       <para>Updates for the current release of the &os; system you are
> 	updating, and what you want to upgrade <emphasis>to</emphasis> need
>@@ -453,11 +473,14 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
> 	&os; 7.2-RELEASE.</para>
>     </note>
> 
>+    <!-- What is a 'KeyPrint'? -->
>     <para>Update client's <literal>KeyPrint</literal> and
>       <literal>ServerName</literal> in
>       <filename>/etc/freebsd-update.conf</filename>, and perform updates as
>       instructed in the <ulink
> 	url="&url.books.handbook;/updating-freebsdupdate.html">&os; Update</ulink>
>+      <!-- One sentence, two instances of 'in'.  We can probably reword this
>+	   part to avoid repetition. -->
>       instructions in the Handbook.</para>
> 
>     <para>For reference, here is the entire run of <ulink
>@@ -467,9 +490,9 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
>   <sect1 id="patch">
>     <title>Building a Patch</title>
> 
>-    <para>In the event a <ulink
>+    <para>Every time a <ulink
> 	url="&url.base;/security/advisories.html">security advisory</ulink>
>-      is posted, a patch update can be built.</para>
>+      is announced, a patch update can be built.</para>
> 
>     <para>For this example, we will be using 7.1-RELEASE.</para>
> 
>@@ -487,8 +510,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
>       </listitem>
>     </itemizedlist>
> 
>-    <para>Create patch directory under
>-      <filename class="directory">/usr/local/freebsd-update-server/patches/</filename> for the respective release.</para>
>+    <para>Create the patch directory of the respective release
>+      under <filename class="directory">/usr/local/freebsd-update-server/patches/</filename>.</para>
> 
>     <informalexample>
>       <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/patches/RELEASE-7.1/</userinput></screen>
>@@ -507,8 +530,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
>       we can see it is called <literal>SA-09:12.bind</literal>.  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, however, this is just a suggestion.
>-      For this build, let us follow the brief and call this
>+      official &os; patch levels, but you are free to choose any name you prefer.
>+      For this build, let us follow the currently established practice of &os; and call this
>       <literal>p7</literal>.  Rename the file:</para>
> 
>     <informalexample>
>@@ -524,9 +547,11 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
>     <note>
>       <para>When running a patch level build, we are assuming 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.  Beyond this,
>-	you will have to take appropriate measures to verify authenticity
>-	of the patch.</para>
>+	patches less than or equal to the number specified.</para>
>+
>+      <para><emphasis>It is up to the administrator of the freebsd-update
>+	  server to take appropriate measures to verify the authenticity of
>+	  every patch.</emphasis></para>
> 
>       <para>You can also add your own patches to any build.  Use the number
> 	zero, or any other number.</para>
>@@ -642,7 +667,7 @@ files to confirm that they look sensible
> # sh -e approve.sh amd64 7.1-RELEASE
> to sign the build.</screen>
> 
>-    <para>Follow the same process as noted before for appoving a build.</para>
>+    <para>Follow the same process as noted before for approving a build:</para>
> 
>     <screen>&prompt.root; <userinput>sh -e scripts/approve.sh amd64 7.1-RELEASE</userinput>
> Wed Aug 26 12:50:06 PDT 2009 Signing build for FreeBSD/amd64 7.1-RELEASE
>@@ -657,7 +682,7 @@ ready to be uploaded.  Remember to run
> to unmount the decrypted key once you have finished signing all
> the new builds.</screen>
> 
>-    <para>After approving the build, upload the software.</para>
>+    <para>After approving the build, upload the software:</para>
> 
>     <informalexample>
>       <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
>@@ -671,21 +696,40 @@ the new builds.</screen>
>   <sect1 id="tips">
>     <title>Tips</title>
> 
>+    <!-- These are nice tips, but there are only a few of them and they need a
>+	 bit of rewording to make sense.  I'd like to see something that
>+	 explains at least the following for every tip:
>+
>+	 * Why is this tip necessary?  What is the original problem it tries
>+	   to solve?
>+	 * How to install the changes of the tip (preferrably in a <procedure>
>+	   element, with clearly separated steps.
>+	 * How to check that the changes of the tip had a measurable and
>+	   noticeable effect.
>+
>+	 We can do this in a followup commit.  It doesn't have to be completed
>+	 *before* we commit this to CVS. -->
>+
>     <itemizedlist>
>       <listitem>
> 	<para>If you build your own release using the native
>-	  <command>make release</command>,
>+	  <command>make release</command> procedure, the
> 	  <application>freebsd-update-server</application> code will work
>+	  <!-- "from your release" seems a bit odd.  I think this part means
>+	       that the freebsd-update code can be tweaked to build custom,
>+	       locally tuned release snapshots.  Is that so? -->
> 	  from your release.  As an example, you may build a release without
> 	  ports or documentation and add a custom kernel.  After removing
> 	  functionality pertaining to the documentation subroutine and
>-	  altering the <literal>buildworld()</literal> subroutine in
>-	  <filename>scripts/build.subr</filename> the
>+	  altering the <function>buildworld()</function> subroutine in
>+	  <filename>scripts/build.subr</filename>, the
> 	  <application>freebsd-update-code</application> will successfully
> 	  build update code on this release.</para>
>       </listitem>
> 
>       <listitem>
>+	<!-- We seem to be contradicting ourselves here.  Is it safe to add -j
>+	     or other flags?  If not, why are we recommending it? -->
> 	<para>Add <command>make -j <replaceable>NUMBER</replaceable></command>
> 	  to <filename>scripts/build.subr</filename> to speed up processing.
> 	  Adding flags to anything other than
>@@ -695,6 +739,10 @@ the new builds.</screen>
>       </listitem>
> 
>       <listitem>
>+	<!-- Parse error.  I don't understand what this paragraph suggests or
>+	     recommends.  Also, why do we need to block RSTs?  I don't really
>+	     like gratuitous blocking of RST, ICMP or other packets.  Our
>+	     kernel can rate-limit most of the "strange" packets alredy. -->
> 	<para>Create a firewall rule to block outgoing RST packets.  Due to
> 	  a bug noted <ulink
> 	    url="http://unix.derkeiler.com/Mailing-Lists/FreeBSD/stable/2009-04/msg00365.html">in this posting</ulink>,




-- 
i am a mutthead

--x4pBfXISqBoDm8sr
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="freebsd-update.6d8923ea5ca3.diff"

I have made my notes and commments inline, and would rather not create another patch based on my thoughts.

diff -r 6d8923ea5ca3 en_US.ISO8859-1/articles/freebsd-update-server/article.sgml
--- a/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml	Fri Nov 20 10:05:02 2009 +0200
+++ b/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml	Fri Nov 20 17:48:23 2009 +0200
@@ -80,11 +80,11 @@
       </listitem>
 
       <listitem>
-	<para>An <ulink
-	    url="&url.books.handbook;/network-apache.html">Apache
-	    web server</ulink>, with over half of the space required for the
-	  build.  For instance, our test builds total 4&nbsp;GB, and the
-	  webserver space needed to distribute updates is 2.6&nbsp;GB.</para>
+	<para>A web server, like <ulink
+	    url="&url.books.handbook;/network-apache.html">Apache</ulink>,
+	  with over half of the space required for the build.  For instance,
+	  our test builds total 4&nbsp;GB, and the webserver space needed to
+	  distribute updates is 2.6&nbsp;GB.</para>
       </listitem>

I agree with this, as Apache is a choice, however there are configuration files that are uploaded as part of the code that are Apache specific. I tried using lighttpd, however RST resets prevented updates.

       <listitem>
@@ -97,7 +97,8 @@
   <sect1 id="Configuration">
     <title>Configuration: Installation & Setup</title>
 
-    <para>Download <ulink url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink>
+    <para>Download
+      the <ulink url="&url.base;/cgi/cvsweb.cgi/projects/freebsd-update-server/">freebsd-update-server</ulink>
       software.  A tarball may be downloaded, or use &man.csup.1; and the
       <literal>projects-all</literal> collection.</para>

The word "the" really doesn't add any special clarity here, from what I can see. As an English and Journalism major, I was told that the word the is one of the most overused words in the language, and to use it as sparsely as possible. :)
 
@@ -138,19 +139,20 @@ MASTERDIR=update-master.freebsd.org</pro
 	<term><literal>FTP</literal></term>
 
 	<listitem>
-	  <para>This is where the subroutine <function>fetchiso()</function>
-	    declared in <filename>scripts/build.subr</filename> will contact
-	    the configured source for downloading the &os; ISO.  This setting
-	    is not limited to <application>ftp</application>, it may also be
-	    a web (<application>httpd</application>) address as well.
-	    For our purposes, ISO's are on the same server as our internal
-	    http server that will be serving updates.  The software has been
-	    configured to look in that location.  For this setup, we have to
-	    alter the routine to fetch the ISO.  By copying the source
-	    <filename>build.subr</filename> to
-	    <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename> this
-	    file will be sourced instead of the released source for
-	    <filename>build.subr</filename>.</para>
+	  <para>This is the location where ISO images are downloaded from (by
+	    the <function>fetchiso()</function> subroutine
+	    of <filename>scripts/build.subr</filename>).  The location
+	    configured here is not limited to FTP URIs.  Any URI scheme
+	    supported by the standard &man.fetch.1; utility should work fine.
+	    In our own setup the ISO images are on the same internal http
+	    server that will be serving the updates.</para>
+
+	  <para>Customizations to the <function>fetchiso()</function> code can
+	    be installed by copying the
+	    default <filename>build.subr</filename> script to the release- and
+	    architecture-specific area
+	    at <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename>
+	    and applying local edits.</para>
 	</listitem>
       </varlistentry>

I agree with this change. A symlink can also work.
 
@@ -158,9 +160,8 @@ MASTERDIR=update-master.freebsd.org</pro
 	<term><literal>BUILDHOSTNAME</literal></term>
 
 	<listitem>
-	  <para>Host where software will be built.  Coincidentally, this
-	    information will be displayed on updated systems when
-	    issuing:</para>
+	  <para>The name of the build host.  This information will be
+	    displayed on updated systems when issuing:</para>

I agree with this.
 
 	  <screen>&prompt.user; <userinput>uname -v</userinput></screen>
 	</listitem>
@@ -170,15 +171,16 @@ MASTERDIR=update-master.freebsd.org</pro
 	<term><literal>SSHKEY</literal></term>
 
 	<listitem>
-	  <para>Key used when uploading data to an update server which will
-	    provide patches or upgrades to clients.  A key pair may be
-	    created using <command>ssh-keygen -t dsa</command>.  Alteration
-	    of this parameter is not required as stadnard password
-	    authentication through <application>ssh</application> will be
-	    used.</para>
+	  <para>The <application>SSH</application> key for uploading files to
+	    the update server.  A key pair can be created by
+	    typing <command>ssh-keygen -t dsa</command>.  This parameter is
+	    optional; standard password authentication will be used as a
+	    fallback authentication method when <literal>SSHKEY</literal> is
+	    not defined.</para>
 
-	  <para>&man.ssh-keygen.1; has more detailed information in creating
-	    a key pair.</para>
+	  <para>&man.ssh-keygen.1; has more detailed information
+	    about <application>SSH</application> and the appropriate steps for
+	    creating and using one.</para>
 	</listitem>
       </varlistentry>
 
@@ -186,7 +188,8 @@ MASTERDIR=update-master.freebsd.org</pro
 	<term><literal>MASTERACCT</literal></term>
 
 	<listitem>
-	  <para>Account that files are uploaded to on remote system.</para>
+	  <para>Account that files are uploaded to on the update
+	    server.</para>
 	</listitem>
       </varlistentry>

@@ -194,54 +197,68 @@ MASTERDIR=update-master.freebsd.org</pro
 	<term><literal>MASTERDIR</literal></term>
 
 	<listitem>
-	  <para>Directory where files are uploaded to on remote
-	    system.</para>
+	  <para>Directory where files are uploaded to on the update
+	    server.</para>
 	</listitem>
       </varlistentry>
     </variablelist>

No need for the word "the," here. Good change.
 
-    <para>Now that build directives are set, the installation files are
-      configured for a build.  For this example, we will use
-      <literal>RELEASE-7.2</literal> under <literal>amd64</literal>
-      architecture.  Configuration files for &i386;
-      architecture are available with downloaded source.</para>
+     <para>The default <filename>build.conf</filename> file shipped with
+       the <application>freebsd-update-server</application> 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:</para>

As note before, these are build directives, and other directives could be seen as release directives.
 
-    <para>Create build environment directory under <filename
-	class="directory">scripts/RELEASE-7.2/amd64</filename>.</para>
+    <procedure>
+      <step>
+        <para>Create a build environment for AMD64:</para>
 
-    <informalexample>
-      <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/scripts/RELEASE-7.2/amd64</userinput></screen>
-    </informalexample>
+        <informalexample>
+          <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/scripts/RELEASE-7.2/amd64</userinput></screen>
+        </informalexample>
+      </step>

I like the "steps." Wasn't aware of this function.
 
-    <para>This is the <filename>build.conf</filename> file that should be
-      placed in the directory just created.</para>
+      <step>
 
-    <programlisting># SHA256 hash of RELEASE disc1.iso image.
+        <para>Install a <filename>build.conf</filename> file in the
+          newly created build directory.  The build configuration
+          options for &os; 7.2-RELEASE on AMD64 should be similar
+          to:</para>
+
+        <programlisting># SHA256 hash of RELEASE disc1.iso image.
 export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5
 
 # Components of the world, source, and kernels
 export WORLDPARTS="base catpages dict doc games info manpages proflibs lib32"
-export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5	\
-		lib libexec release rescue sbin secure share sys tools	\
-		ubin usbin cddl"
+export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5  \
+                lib libexec release rescue sbin secure share sys tools  \
+                ubin usbin cddl"
 export KERNELPARTS="generic"
 
 # EOL date
 export EOL=1275289200</programlisting>
 
-    <note>
-      <para>To generate the "End of Life" number for
-	<filename>build.conf</filename>, refer to the "Estimated EOL" posted
-	on the <ulink url="&url.base;/security/security.html">&os;
-	Security Website</ulink>.  Based on this date, you can issue
-	<command>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' +%s</command>,
-	and substitute actual date parameters for those stated by
-	&os;.</para>
+        <note>
+          <para>To generate the "End of Life" number for
+            <filename>build.conf</filename>, refer to the "Estimated
+            EOL" posted on
+            the <ulink url="&url.base;/security/security.html">&os;
+              Security Website</ulink>.  You can derive the value
+            of <literal>EOL</literal> from the date listed on the web
+            site, using the &man.date.1; utility, e.g.:</para>
 
-      <para>The &man.sha256.1; hash key for the desired release, is
-	published within the respective <ulink
-	  url="&url.base;/releases/">release announcement </ulink>.</para>
-    </note>
+          <screen>&prompt.user; <userinput>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s'</userinput></screen>
+        </note>
+
+        <note>
+          <para>The &man.sha256.1; hash key for the desired release, is
+            published within the
+            respective <ulink url="&url.base;/releases/">release
+              announcement</ulink>.</para>
+        </note>
+      </step>
+    </procedure>
   </sect1>

I like this modification.
 
   <sect1 id="build">
@@ -273,9 +290,9 @@ enter aes-256-cbc encryption password:
 Verifying - enter aes-256-cbc encryption password:</screen>
 
     <note>
-      <para>Note down the generated KeyPrint; this value is entered into
-	<filename>/etc/freebsd-update.conf</filename> for binary
-	updates.</para>
+      <para>Keep a note of the generated key fingerpring.  This value is
+	entered into <filename>/etc/freebsd-update.conf</filename> for
+	binary updates.</para>
     </note>

Typo. "fingerprint" 
 
     <para>At this point, we are ready to stage a build.</para>
@@ -330,8 +347,8 @@ world|base|/usr/lib/libalias_ftp.a
 
     <note>
       <para>Then the build of the world is performed again, with world
-	patches.  A more detailed explanation may be found in
-	<filename>scripts/build.subr</filename>.</para>
+	patches.  A more detailed explanation may be found
+	in <filename>scripts/build.subr</filename>.</para>
     </note>
 
     <screen>Mon Aug 24 17:54:07 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE
@@ -411,10 +428,7 @@ to sign the release.</screen>
       file named <filename>USAGE</filename>.  Execute
       <filename>scripts/approve.sh</filename>, as directed.  This will sign
       the release, and move components into a staging area suitable for
-      uploading.  It is important to make sure that your key is mounted
-      during this process.  A simple <command>df</command> will show if it
-      is mounted.  If not mounted, mount the key with the passphrase supplied
-      when creating it earlier.</para>
+      uploading.</para>
 
Your build will not upload if it isn't approved, and it can't be approved if it isn't signed. It can't be signed if your key is not mounted. The key is essential for the building process.

     <informalexample>
       <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
@@ -436,6 +450,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
 &prompt.root; <userinput>sh scripts/upload.sh <replaceable>amd64 RELEASE-7.2</replaceable></userinput></screen>
     </informalexample>
 
+    <!-- If freebsd-update works with other http servers too, we should
+	 avoid making the instructions Apache-specific here. -->

It may work, however there are specific files uploaded during the upload process that are for Apache. If the functionality can be adapted into other http servers, the end-user may choose to use another webserver. I experimented with lighttpd, however it did not work. Colin notes that Apache handles memory better in the source.

     <para>The uploaded files will need to be in the
       <literal>DocumentRoot</literal> of the webserver in order for updates
       to be distributed.  For further explanation, please refer to the
@@ -443,6 +459,10 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
 	url="&url.books.handbook;/network-apache.html">Apache
 	documentation</ulink>.</para>
 
+    <!-- This note seems either out of place.  I find it hard to read and it
+	 is a bit difficult to understand why it is related to the rest of
+	 this section.  It looks like something that would fit nicely in an
+	 introductory section about the way a freebsd-update server works. -->
     <note>
       <para>Updates for the current release of the &os; system you are
 	updating, and what you want to upgrade <emphasis>to</emphasis> need
@@ -453,11 +473,14 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
 	&os; 7.2-RELEASE.</para>
     </note>

I re-worded this for clarity, however I thought it was a good place to put it. Right after a build. If you want to update from 7.1 to 7.2, you will need to have build code on your update server for both releases.
 
+    <!-- What is a 'KeyPrint'? -->

KeyPrint is the key fingerprint that needs to be updated in /etc/freebsd-update.conf in order to install updates.

     <para>Update client's <literal>KeyPrint</literal> and
       <literal>ServerName</literal> in
       <filename>/etc/freebsd-update.conf</filename>, and perform updates as
       instructed in the <ulink
 	url="&url.books.handbook;/updating-freebsdupdate.html">&os; Update</ulink>
+      <!-- One sentence, two instances of 'in'.  We can probably reword this
+	   part to avoid repetition. -->
       instructions in the Handbook.</para>
 
     <para>For reference, here is the entire run of <ulink
@@ -467,9 +490,9 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
   <sect1 id="patch">
     <title>Building a Patch</title>
 
-    <para>In the event a <ulink
+    <para>Every time a <ulink
 	url="&url.base;/security/advisories.html">security advisory</ulink>
-      is posted, a patch update can be built.</para>
+      is announced, a patch update can be built.</para>
 
     <para>For this example, we will be using 7.1-RELEASE.</para>
 
@@ -487,8 +510,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
       </listitem>
     </itemizedlist>
 
-    <para>Create patch directory under
-      <filename class="directory">/usr/local/freebsd-update-server/patches/</filename> for the respective release.</para>
+    <para>Create the patch directory of the respective release
+      under <filename class="directory">/usr/local/freebsd-update-server/patches/</filename>.</para>
 
     <informalexample>
       <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/patches/RELEASE-7.1/</userinput></screen>
@@ -507,8 +530,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
       we can see it is called <literal>SA-09:12.bind</literal>.  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, however, this is just a suggestion.
-      For this build, let us follow the brief and call this
+      official &os; patch levels, but you are free to choose any name you prefer.
+      For this build, let us follow the currently established practice of &os; and call this
       <literal>p7</literal>.  Rename the file:</para>
 
     <informalexample>
@@ -524,9 +547,11 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st
     <note>
       <para>When running a patch level build, we are assuming 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.  Beyond this,
-	you will have to take appropriate measures to verify authenticity
-	of the patch.</para>
+	patches less than or equal to the number specified.</para>
+
+      <para><emphasis>It is up to the administrator of the freebsd-update
+	  server to take appropriate measures to verify the authenticity of
+	  every patch.</emphasis></para>
 
       <para>You can also add your own patches to any build.  Use the number
 	zero, or any other number.</para>
@@ -642,7 +667,7 @@ files to confirm that they look sensible
 # sh -e approve.sh amd64 7.1-RELEASE
 to sign the build.</screen>
 
-    <para>Follow the same process as noted before for appoving a build.</para>
+    <para>Follow the same process as noted before for approving a build:</para>
 
     <screen>&prompt.root; <userinput>sh -e scripts/approve.sh amd64 7.1-RELEASE</userinput>
 Wed Aug 26 12:50:06 PDT 2009 Signing build for FreeBSD/amd64 7.1-RELEASE
@@ -657,7 +682,7 @@ ready to be uploaded.  Remember to run
 to unmount the decrypted key once you have finished signing all
 the new builds.</screen>
 
-    <para>After approving the build, upload the software.</para>
+    <para>After approving the build, upload the software:</para>
 
     <informalexample>
       <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput>
@@ -671,21 +696,40 @@ the new builds.</screen>
   <sect1 id="tips">
     <title>Tips</title>
 
+    <!-- These are nice tips, but there are only a few of them and they need a
+	 bit of rewording to make sense.  I'd like to see something that
+	 explains at least the following for every tip:
+
+	 * Why is this tip necessary?  What is the original problem it tries
+	   to solve?
+	 * How to install the changes of the tip (preferrably in a <procedure>
+	   element, with clearly separated steps.
+	 * How to check that the changes of the tip had a measurable and
+	   noticeable effect.
I believe this is for the end-user to determine.
+
+	 We can do this in a followup commit.  It doesn't have to be completed
+	 *before* we commit this to CVS. -->

Agreed.
+

I agree with the above.

     <itemizedlist>
       <listitem>
 	<para>If you build your own release using the native
-	  <command>make release</command>,
+	  <command>make release</command> procedure, the
 	  <application>freebsd-update-server</application> code will work
+	  <!-- "from your release" seems a bit odd.  I think this part means
+	       that the freebsd-update code can be tweaked to build custom,
+	       locally tuned release snapshots.  Is that so? -->
 	  from your release.  As an example, you may build a release without
 	  ports or documentation and add a custom kernel.  After removing
 	  functionality pertaining to the documentation subroutine and
-	  altering the <literal>buildworld()</literal> subroutine in
-	  <filename>scripts/build.subr</filename> the
+	  altering the <function>buildworld()</function> subroutine in
+	  <filename>scripts/build.subr</filename>, the
 	  <application>freebsd-update-code</application> will successfully
 	  build update code on this release.</para>
       </listitem>

This allows for you to maintain an update server with a custom and generic kernel, and a modified world, if you wish.
 
       <listitem>
+	<!-- We seem to be contradicting ourselves here.  Is it safe to add -j
+	     or other flags?  If not, why are we recommending it? -->
 	<para>Add <command>make -j <replaceable>NUMBER</replaceable></command>
 	  to <filename>scripts/build.subr</filename> to speed up processing.
 	  Adding flags to anything other than
@@ -695,6 +739,10 @@ the new builds.</screen>
       </listitem>

It is safe to add it to the buildworld and obj process, but not others. Update code will fail on anything besides this.
 
       <listitem>
+	<!-- Parse error.  I don't understand what this paragraph suggests or
+	     recommends.  Also, why do we need to block RSTs?  I don't really
+	     like gratuitous blocking of RST, ICMP or other packets.  Our
+	     kernel can rate-limit most of the "strange" packets alredy. -->

Updates will fail if this isn't put in place.

 	<para>Create a firewall rule to block outgoing RST packets.  Due to
 	  a bug noted <ulink
 	    url="http://unix.derkeiler.com/Mailing-Lists/FreeBSD/stable/2009-04/msg00365.html">in this posting</ulink>,

--x4pBfXISqBoDm8sr--



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20091120202642.GK6241>