Remove CTM from the Handbook. Some time back, CTM became deprecated or

impractical or both.  Cleared with clusteradm.
This commit is contained in:
Warren Block 2016-04-14 21:52:30 +00:00
parent 33b19512b8
commit 1fda3c5ac3
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=48637
2 changed files with 6 additions and 329 deletions

View file

@ -73,9 +73,8 @@
<itemizedlist>
<listitem>
<para>How to keep a &os; system up-to-date with
<application>freebsd-update</application>,
<application>Subversion</application>, or
<application>CTM</application>.</para>
<application>freebsd-update</application> or
<application>Subversion</application>.</para>
</listitem>
<listitem>
@ -1036,13 +1035,6 @@ before running "/usr/sbin/freebsd-update install"</screen>
-CURRENT code from the <literal>head</literal> branch of
one of the Subversion mirror sites listed in
<xref linkend="svn-mirrors"/>.</para>
<para>Users with very slow or limited Internet connectivity
can instead use CTM as described in <xref linkend="ctm"/>,
but it is not as reliable as
<application>svn</application> and
<application>svn</application> is the recommended method
for synchronizing source.</para>
</listitem>
<listitem>
@ -1150,9 +1142,7 @@ before running "/usr/sbin/freebsd-update install"</screen>
</indexterm> to check out the source for the desired
branch. Branch names, such as
<literal>stable/9</literal>, are listed at <link
xlink:href="&url.base;/releng/">www.freebsd.org/releng</link>.
CTM (<xref linkend="ctm"/>) can be used if a reliable
Internet connection is not available.</para>
xlink:href="&url.base;/releng/">www.freebsd.org/releng</link>.</para>
</listitem>
<listitem>
@ -1175,9 +1165,8 @@ before running "/usr/sbin/freebsd-update install"</screen>
<title>Synchronizing Source</title>
<para>There are various methods for staying up-to-date with the
&os; sources. This section compares the primary services,
<application>Subversion</application> and
<application>CTM</application>.</para>
&os; sources. This section describes the primary service,
<application>Subversion</application>.</para>
<warning>
<para>While it is possible to update only parts of the source
@ -1207,33 +1196,9 @@ before running "/usr/sbin/freebsd-update install"</screen>
<application>Subversion</application> is described in <xref
linkend="svn"/>.</para>
<indexterm>
<primary><application>CTM</application></primary>
</indexterm>
<para><application>CTM</application> does not interactively
compare the local sources with those on the master archive or
otherwise pull them across. Instead, a script which identifies
changes in files since its previous run is executed several
times a day on the master CTM machine. Any detected changes are
compressed, stamped with a sequence-number, and encoded for
transmission over email in printable <acronym>ASCII</acronym>
only. Once downloaded, these <firstterm>deltas</firstterm> can
be run through <command>ctm.rmail</command> which will
automatically decode, verify, and apply the changes to the
user's copy of the sources. This process is more efficient than
<application>Subversion</application> and places less strain on
server resources since it is a <emphasis>push</emphasis>, rather
than a <emphasis>pull</emphasis>, model. Instructions for using
<application>CTM</application> to synchronize source can be
found at <xref linkend="ctm"/>.</para>
<para>If a user inadvertently wipes out portions of the local
archive, <application>Subversion</application> will detect and
rebuild the damaged portions. <application>CTM</application>
will not, and if a user deletes some portion of the source tree
and does not have a backup, they will have to start from scratch
from the most recent <firstterm>base delta</firstterm> and
rebuild it all with <application>CTM</application>.</para>
rebuild the damaged portions during an update.</para>
</sect1>
<sect1 xml:id="makeworld">

View file

@ -133,294 +133,6 @@ This site doesn't have any products newer than 8.1 which is now EOL'd
&chap.mirrors.ftp.inc;
</sect1>
<sect1 xml:id="ctm">
<title>Using CTM</title>
<indexterm>
<primary>CTM</primary>
</indexterm>
<para><application>CTM</application> is a method for keeping a
remote directory tree in sync with a central one. It is built
into &os; and can be used to synchronize a system with &os;'s
source repositories. It supports synchronization of an entire
repository or just a specified set of branches.</para>
<para><application>CTM</application> is specifically designed for
use on lousy or non-existent TCP/IP connections and provides
the ability for changes to be automatically sent by email. It
requires the user to obtain up to three deltas per day for the
most active branches. Update sizes are always kept as small as
possible and are typically less than 5K. About one in every ten
updates is 10-50K in size, and there will occasionally be an
update larger than 100K+.</para>
<para>When using <application>CTM</application> to track &os;
development, refer to the caveats related to working directly
from the development sources rather than a pre-packaged release.
These are discussed in <link linkend="current-stable">Tracking
a Development Branch</link>.</para>
<para>Little documentation exists on the process of creating
deltas or using <application>CTM</application> for other
purposes. Contact the &a.ctm-users.name; mailing list for
answers to questions on using
<application>CTM</application>.</para>
<sect2 xml:id="mirrors-ctm">
<title>Getting Deltas</title>
<para>The <quote>deltas</quote> used by
<application>CTM</application> can be obtained either through
anonymous <acronym>FTP</acronym> or email.</para>
<para><acronym>FTP</acronym> deltas can be obtained from the
following mirror sites. When using anonymous
<acronym>FTP</acronym> to obtain
<application>CTM</application> deltas, select a mirror that is
geographically nearby. In case of problems, contact the
&a.ctm-users.name; mailing list.</para>
<variablelist>
<varlistentry>
<term>Global mirror</term>
<listitem>
<itemizedlist>
<listitem>
<para><uri
xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/</uri></para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>South Africa, backup server for old deltas</term>
<listitem>
<itemizedlist>
<listitem>
<para><uri
xlink:href="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/">ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/</uri></para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Taiwan/R.O.C.</term>
<listitem>
<itemizedlist>
<listitem>
<para><uri
xlink:href="ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/</uri></para>
</listitem>
<listitem>
<para><uri
xlink:href="ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/</uri></para>
</listitem>
<listitem>
<para><uri
xlink:href="ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/</uri></para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
<para>To instead receive deltas through email, subscribe to one
of the <literal>ctm-src</literal> distribution lists available
from <uri
xlink:href="http://lists.freebsd.org/mailman/listinfo">http://lists.freebsd.org/mailman/listinfo</uri>.
For example, &a.ctm-src-cur.name; supports the head
development branch and &a.ctm-src-9.name; supports the 9.X
release branch.</para>
<para>As <application>CTM</application> updates arrive through
email, use <command>ctm_rmail</command> to unpack and apply
them. This command can be run directly from an entry in
<filename>/etc/aliases</filename> in order to automate this
process. Refer to &man.ctm.rmail.1; for more details.</para>
<note>
<para>Regardless of the method which is used to get deltas,
<application>CTM</application> users should subscribe
to the &a.ctm-announce.name; mailing list as this is the
only mechanism by which <application>CTM</application>
announcements are posted.</para>
</note>
</sect2>
<sect2>
<title><application>CTM</application> Usage</title>
<para>Before <application>CTM</application> deltas can be used
for the first time, a starting point must be produced.</para>
<para>One method is to apply a <quote>starter</quote> delta to
an empty directory. A starter delta can be recognized by the
<filename>XEmpty</filename> in its name, such as
<filename>src-cur.3210XEmpty.gz</filename>. The designation
following the <literal>X</literal> corresponds to the origin
of the initial <quote>seed</quote>, where
<filename>Empty</filename> is an empty directory. As a rule,
a base transition from <literal>Empty</literal> is produced
every 100 deltas. Be aware that starter deltas are large and
70 to 80 Megabytes of <command>gzip</command>'d data is common
for the <filename>XEmpty</filename> deltas.</para>
<para>Another method is to copy or extract an initial source
from a RELEASE media as this can save a significant transfer
of data from the Internet.</para>
<para>Once a base delta has been created, apply all deltas with
higher numbers. To apply the deltas:</para>
<screen>&prompt.root; <userinput>cd /directory/to/store/the/stuff</userinput>
&prompt.root; <userinput>ctm -v -v /directory/which/stores/the/deltas/src-xxx.*</userinput></screen>
<para>Multiple deltas can be applied with a single command as
they will be processed one at a time and any deltas that are
already applied will be ignored.
<application>CTM</application> understands
<command>gzip</command> compressed deltas, which saves disk
space.</para>
<para>To verify a delta without applying it, include
<option>-c</option> in the command line.
<application>CTM</application> will not actually modify the
local tree but will instead verify the integrity of the delta
to see if it would apply cleanly. Refer to &man.ctm.1; for
more information about available options and an overview of
the process <application>CTM</application> uses when applying
deltas.</para>
<para>To keep the local source tree up-to-date, every time a
new delta becomes available, apply it through
<application>CTM</application>.</para>
<para>Once applied, it is recommended to not delete the deltas
if it is a burden to download them again. This way, a local
copy is available in case it is needed for future disaster
recovery.</para>
</sect2>
<sect2>
<title>Keeping Local Changes</title>
<para>Developers often experiment with and
change files in their local source tree.
<application>CTM</application> supports local modifications in
a limited way: before checking for the presence of a file,
it first looks for a file with the same name and a
<filename>.ctm</filename> extension. If this file exists,
<application>CTM</application> will operate on it instead of
the original filename.</para>
<para>This behavior provides a simple way to maintain local
changes. Before modifying a file, make a copy with a
<filename>.ctm</filename> suffix. Make any changes to the
original filename, knowing that
<application>CTM</application> will only apply updates to the
file with the <filename>.ctm</filename> suffix.</para>
</sect2>
<sect2>
<title>Other <application>CTM</application> Options</title>
<variablelist>
<varlistentry>
<term>Finding Out Exactly What Would Be Touched by an
Update</term>
<listitem>
<para>To determine the list of changes that
<application>CTM</application> will make to the local
source repository, use <option>-l</option>. This option
is useful for creating logs of the changes or when
performing pre- or post-processing on any of the
modified files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Making Backups Before Updating</term>
<listitem>
<para>To backup all of the files that would be changed by
a <application>CTM</application> update, specify
<option>-B
<replaceable>backup-file</replaceable></option>. This
option tells <application>CTM</application> to backup
all files touched by the applied
<application>CTM</application> delta to
<filename>backup-file</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Restricting the Files Touched by an Update</term>
<listitem>
<para>To restrict the scope of a given
<application>CTM</application> update, or to extract
just a few files from a sequence of deltas, filtering
regular expressions can be specified using
<option>-e</option>, which specifies which files to
process, or <option>-x</option>, which specifies which
files to ignore.</para>
<para>For example, to extract an up-to-date copy of
<filename>lib/libc/Makefile</filename> from a collection
of saved <application>CTM</application> deltas:</para>
<screen>&prompt.root; <userinput>cd /directory/to/extract/to/</userinput>
&prompt.root; <userinput>ctm -e '^lib/libc/Makefile' /directory/which/stores/the/deltas/src-xxx.*</userinput></screen>
<para>For every file specified in a
<application>CTM</application> delta,
<option>-e</option> and <option>-x</option> are
applied in the order given on the command line. A file
is processed by <application>CTM</application> only if
it is marked as eligible after all <option>-e</option>
and <option>-x</option> options are applied.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<!--
Comment out for now until these can be verified.
<sect2>
<title>Future Plans for <application>CTM</application></title>
<para>Tons of them:</para>
<itemizedlist>
<listitem>
<para>Use some kind of authentication into the
<application>CTM</application> system, so as to allow
detection of spoofed <application>CTM</application>
updates.</para>
</listitem>
<listitem>
<para>Clean up the options to
<application>CTM</application>, they became confusing and
counter intuitive.</para>
</listitem>
</itemizedlist>
<para>There is a sequence of deltas for the
<literal>ports</literal> collection too, but interest has not
been all that high yet.</para>
</sect2>
-->
</sect1>
<sect1 xml:id="svn">
<title>Using <application>Subversion</application></title>