Date: Fri, 20 Nov 2009 18:07:02 +0200 From: Giorgos Keramidas <keramida@FreeBSD.org> To: Manolis Kiagias <manolis@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> Subject: Re: [RFC] Article on freebsd-update-server Message-ID: <87ws1luqmx.fsf@kobe.laptop> References: <4B05BA06.3010303@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--==-=-= Content-Type: multipart/mixed; boundary="=-=-=" --=-=-= 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 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 --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=freebsd-update.6d8923ea5ca3.diff Content-Transfer-Encoding: quoted-printable Content-Description: Proposed changes and comments for freebsd-update-server rev. 6d8923ea5ca3 diff -r 6d8923ea5ca3 en_US.ISO8859-1/articles/freebsd-update-server/article= .sgml =2D-- 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 2= 0 17:48:23 2009 +0200 @@ -80,11 +80,11 @@ </listitem> =20 <listitem> =2D <para>An <ulink =2D url=3D"&url.books.handbook;/network-apache.html">Apache =2D web server</ulink>, with over half of the space required for the =2D build. For instance, our test builds total 4 GB, and the =2D webserver space needed to distribute updates is 2.6 GB.</para> + <para>A web server, like <ulink + url=3D"&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> =20 <listitem> @@ -97,7 +97,8 @@ <sect1 id=3D"Configuration"> <title>Configuration: Installation & Setup</title> =20 =2D <para>Download <ulink url=3D"&url.base;/cgi/cvsweb.cgi/projects/free= bsd-update-server/">freebsd-update-server</ulink> + <para>Download + the <ulink url=3D"&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> =20 @@ -138,19 +139,20 @@ MASTERDIR=3Dupdate-master.freebsd.org</pro <term><literal>FTP</literal></term> =20 <listitem> =2D <para>This is where the subroutine <function>fetchiso()</function> =2D declared in <filename>scripts/build.subr</filename> will contact =2D the configured source for downloading the &os; ISO. This setting =2D is not limited to <application>ftp</application>, it may also be =2D a web (<application>httpd</application>) address as well. =2D For our purposes, ISO's are on the same server as our internal =2D http server that will be serving updates. The software has been =2D configured to look in that location. For this setup, we have to =2D alter the routine to fetch the ISO. By copying the source =2D <filename>build.subr</filename> to =2D <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename> this =2D file will be sourced instead of the released source for =2D <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> =20 @@ -158,9 +160,8 @@ MASTERDIR=3Dupdate-master.freebsd.org</pro <term><literal>BUILDHOSTNAME</literal></term> =20 <listitem> =2D <para>Host where software will be built. Coincidentally, this =2D information will be displayed on updated systems when =2D issuing:</para> + <para>The name of the build host. This information will be + displayed on updated systems when issuing:</para> =20 <screen>&prompt.user; <userinput>uname -v</userinput></screen> </listitem> @@ -170,15 +171,16 @@ MASTERDIR=3Dupdate-master.freebsd.org</pro <term><literal>SSHKEY</literal></term> =20 <listitem> =2D <para>Key used when uploading data to an update server which will =2D provide patches or upgrades to clients. A key pair may be =2D created using <command>ssh-keygen -t dsa</command>. Alteration =2D of this parameter is not required as stadnard password =2D authentication through <application>ssh</application> will be =2D 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> =20 =2D <para>&man.ssh-keygen.1; has more detailed information in creating =2D 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> =20 @@ -186,7 +188,8 @@ MASTERDIR=3Dupdate-master.freebsd.org</pro <term><literal>MASTERACCT</literal></term> =20 <listitem> =2D <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> =20 @@ -194,54 +197,68 @@ MASTERDIR=3Dupdate-master.freebsd.org</pro <term><literal>MASTERDIR</literal></term> =20 <listitem> =2D <para>Directory where files are uploaded to on remote =2D system.</para> + <para>Directory where files are uploaded to on the update + server.</para> </listitem> </varlistentry> </variablelist> =20 =2D <para>Now that build directives are set, the installation files are =2D configured for a build. For this example, we will use =2D <literal>RELEASE-7.2</literal> under <literal>amd64</literal> =2D architecture. Configuration files for &i386; =2D 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> =20 =2D <para>Create build environment directory under <filename =2D class=3D"directory">scripts/RELEASE-7.2/amd64</filename>.</para> + <procedure> + <step> + <para>Create a build environment for AMD64:</para> =20 =2D <informalexample> =2D <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-updat= e-server/scripts/RELEASE-7.2/amd64</userinput></screen> =2D </informalexample> + <informalexample> + <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-upd= ate-server/scripts/RELEASE-7.2/amd64</userinput></screen> + </informalexample> + </step> =20 =2D <para>This is the <filename>build.conf</filename> file that should be =2D placed in the directory just created.</para> + <step> =20 =2D <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=3D1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc7= 1ef5 =20 # Components of the world, source, and kernels export WORLDPARTS=3D"base catpages dict doc games info manpages proflibs l= ib32" =2Dexport SOURCEPARTS=3D"base bin contrib crypto etc games gnu include krb5= \ =2D lib libexec release rescue sbin secure share sys tools \ =2D ubin usbin cddl" +export SOURCEPARTS=3D"base bin contrib crypto etc games gnu include krb5 \ + lib libexec release rescue sbin secure share sys tools \ + ubin usbin cddl" export KERNELPARTS=3D"generic" =20 # EOL date export EOL=3D1275289200</programlisting> =20 =2D <note> =2D <para>To generate the "End of Life" number for =2D <filename>build.conf</filename>, refer to the "Estimated EOL" posted =2D on the <ulink url=3D"&url.base;/security/security.html">&os; =2D Security Website</ulink>. Based on this date, you can issue =2D <command>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' +%s</command>, =2D and substitute actual date parameters for those stated by =2D &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=3D"&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> =20 =2D <para>The &man.sha256.1; hash key for the desired release, is =2D published within the respective <ulink =2D url=3D"&url.base;/releases/">release announcement </ulink>.</para> =2D </note> + <screen>&prompt.user; <userinput>date -j -f '%Y%m%d-%H%M%S' '200= 90401-000000' '+%s'</userinput></screen> + </note> + + <note> + <para>The &man.sha256.1; hash key for the desired release, is + published within the + respective <ulink url=3D"&url.base;/releases/">release + announcement</ulink>.</para> + </note> + </step> + </procedure> </sect1> =20 <sect1 id=3D"build"> @@ -273,9 +290,9 @@ enter aes-256-cbc encryption password: Verifying - enter aes-256-cbc encryption password:</screen> =20 <note> =2D <para>Note down the generated KeyPrint; this value is entered into =2D <filename>/etc/freebsd-update.conf</filename> for binary =2D 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> =20 <para>At this point, we are ready to stage a build.</para> @@ -330,8 +347,8 @@ world|base|/usr/lib/libalias_ftp.a =20 <note> <para>Then the build of the world is performed again, with world =2D patches. A more detailed explanation may be found in =2D <filename>scripts/build.subr</filename>.</para> + patches. A more detailed explanation may be found + in <filename>scripts/build.subr</filename>.</para> </note> =20 <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 =2D uploading. It is important to make sure that your key is mounted =2D during this process. A simple <command>df</command> will show if = it =2D is mounted. If not mounted, mount the key with the passphrase sup= plied =2D when creating it earlier.</para> + uploading.</para> =20 <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> =20 + <!-- 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=3D"&url.books.handbook;/network-apache.html">Apache documentation</ulink>.</para> =20 + <!-- 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> =20 + <!-- 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=3D"&url.books.handbook;/updating-freebsdupdate.html">&os; Update</uli= nk> + <!-- One sentence, two instances of 'in'. We can probably reword th= is + part to avoid repetition. --> instructions in the Handbook.</para> =20 <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=3D"patch"> <title>Building a Patch</title> =20 =2D <para>In the event a <ulink + <para>Every time a <ulink url=3D"&url.base;/security/advisories.html">security advisory</ulink> =2D is posted, a patch update can be built.</para> + is announced, a patch update can be built.</para> =20 <para>For this example, we will be using 7.1-RELEASE.</para> =20 @@ -487,8 +510,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning st </listitem> </itemizedlist> =20 =2D <para>Create patch directory under =2D <filename class=3D"directory">/usr/local/freebsd-update-server/pat= ches/</filename> for the respective release.</para> + <para>Create the patch directory of the respective release + under <filename class=3D"directory">/usr/local/freebsd-update-server= /patches/</filename>.</para> =20 <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 =2D official &os; patch levels, however, this is just a suggestion. =2D 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> =20 <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 =2D patches less than or equal to the number specified. Beyond this, =2D you will have to take appropriate measures to verify authenticity =2D 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> =20 <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> =20 =2D <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> =20 <screen>&prompt.root; <userinput>sh -e scripts/approve.sh amd64 7.1-RE= LEASE</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> =20 =2D <para>After approving the build, upload the software.</para> + <para>After approving the build, upload the software:</para> =20 <informalexample> <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server= </userinput> @@ -671,21 +696,40 @@ the new builds.</screen> <sect1 id=3D"tips"> <title>Tips</title> =20 + <!-- These are nice tips, but there are only a few of them and they ne= ed 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 =2D <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 =2D altering the <literal>buildworld()</literal> subroutine in =2D <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> =20 <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> =20 <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=3D"http://unix.derkeiler.com/Mailing-Lists/FreeBSD/stable/2009-04= /msg00365.html">in this posting</ulink>, --=-=-=-- --==-=-= Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.11 (FreeBSD) iEYEARECAAYFAksGvq0ACgkQ1g+UGjGGA7ZWHwCcDcBO2CXgOdILU/XPsD8wsfmE m8UAoK0CDgSoic7TWEH1pcJ5c3bYrmuI =cY04 -----END PGP SIGNATURE----- --==-=-=--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?87ws1luqmx.fsf>