[RFC] Article on freebsd-update-server
Jason
jhelfman at e-e.com
Fri Nov 20 20:27:53 UTC 2009
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 at 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 at 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 GB, and the
>: - webserver space needed to distribute updates is 2.6 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 GB, and the webserver space needed to
>: + distribute updates is 2.6 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 GB, and the
>- webserver space needed to distribute updates is 2.6 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 GB, and the webserver space needed to
>+ distribute updates is 2.6 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: freebsd-update.6d8923ea5ca3.diff
Type: text/x-diff
Size: 20879 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20091120/a1ef3ac9/attachment.diff>
More information about the freebsd-doc
mailing list