[RFC] Article on freebsd-update-server
Giorgos Keramidas
keramida at FreeBSD.org
Fri Nov 20 16:07:16 UTC 2009
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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: freebsd-update.6d8923ea5ca3.diff
Type: text/x-diff
Size: 18780 bytes
Desc: Proposed changes and comments for freebsd-update-server rev. 6d8923ea5ca3
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20091120/6fe22e66/attachment.diff>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 195 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20091120/6fe22e66/attachment.sig>
More information about the freebsd-doc
mailing list