Date: Sun, 6 Mar 2011 21:19:14 GMT From: Rene Ladan <rene@FreeBSD.org> To: Perforce Change Reviews <perforce@FreeBSD.org> Subject: PERFORCE change 189626 for review Message-ID: <201103062119.p26LJE1b021459@skunkworks.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://p4web.freebsd.org/@@189626?ac=10 Change 189626 by rene@rene_acer on 2011/03/06 21:18:12 IFC Affected files ... .. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml#86 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/freebsd-update-server/Makefile#2 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml#2 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml#3 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/portbuild/article.sgml#31 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml#18 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/disks/chapter.sgml#18 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml#12 integrate .. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml#24 integrate .. //depot/projects/docproj_nl/share/sgml/freebsd.ent#20 integrate .. //depot/projects/docproj_nl/share/sgml/mirrors.xml#24 integrate .. //depot/projects/docproj_nl/www/en/cgi/man.cgi#22 integrate .. //depot/projects/docproj_nl/www/en/gnome/index.xsl#8 integrate .. //depot/projects/docproj_nl/www/en/releases/7.4R/Makefile#2 integrate .. //depot/projects/docproj_nl/www/en/releases/7.4R/announce.sgml#1 branch .. //depot/projects/docproj_nl/www/en/releases/7.4R/errata.html#1 branch .. //depot/projects/docproj_nl/www/en/releases/7.4R/hardware.html#1 branch .. //depot/projects/docproj_nl/www/en/releases/7.4R/readme.html#1 branch .. //depot/projects/docproj_nl/www/en/releases/7.4R/relnotes.html#1 branch .. //depot/projects/docproj_nl/www/en/releases/8.2R/Makefile#2 integrate .. //depot/projects/docproj_nl/www/en/releases/8.2R/announce.sgml#1 branch .. //depot/projects/docproj_nl/www/en/releases/8.2R/errata.html#1 branch .. //depot/projects/docproj_nl/www/en/releases/8.2R/hardware.html#1 branch .. //depot/projects/docproj_nl/www/en/releases/8.2R/readme.html#1 branch .. //depot/projects/docproj_nl/www/en/releases/8.2R/relnotes-detailed.html#1 branch .. //depot/projects/docproj_nl/www/en/releases/8.2R/relnotes.sgml#1 branch .. //depot/projects/docproj_nl/www/en/releases/index.sgml#13 integrate .. //depot/projects/docproj_nl/www/en/releng/index.sgml#40 integrate .. //depot/projects/docproj_nl/www/en/search/web.atoz#5 integrate .. //depot/projects/docproj_nl/www/en/security/security.sgml#19 integrate .. //depot/projects/docproj_nl/www/share/sgml/commercial.isp.xml#23 integrate .. //depot/projects/docproj_nl/www/share/sgml/news.xml#102 integrate .. //depot/projects/docproj_nl/www/share/sgml/release.ent#34 integrate Differences ... ==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml#86 (text+ko) ==== @@ -1,4 +1,4 @@ -<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml,v 1.987 2011/02/14 06:09:31 manolis Exp $ --> +<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml,v 1.988 2011/02/25 12:07:27 osa Exp $ --> <!-- NOTE TO COMMITTERS: Contributors lists are sorted in alphabetical order by first name. @@ -4058,6 +4058,11 @@ </listitem> <listitem> + <para>Jacob Atzen + <email>jatzen@gmail.com</email></para> + </listitem> + + <listitem> <para>Jacob Bohn Lorensen <email>jacob@jblhome.ping.mk</email></para> </listitem> ==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/freebsd-update-server/Makefile#2 (text+ko) ==== @@ -1,4 +1,4 @@ -# $FreeBSD: doc/en_US.ISO8859-1/articles/freebsd-update-server/Makefile,v 1.1 2011/02/13 17:53:26 manolis Exp $ +# $FreeBSD: doc/en_US.ISO8859-1/articles/freebsd-update-server/Makefile,v 1.2 2011/02/24 17:05:15 manolis Exp $ # # Article: FreeBSD Update Server @@ -17,6 +17,12 @@ SRCS= article.sgml SRCS+= ${EXTRAS} +IMAGES_LIB= callouts/1.png +IMAGES_LIB+= callouts/2.png +IMAGES_LIB+= callouts/3.png +IMAGES_LIB+= callouts/4.png +IMAGES_LIB+= callouts/5.png + afterinstall: .for entry in ${EXTRAS} ${INSTALL_DOCS} ${.CURDIR}/${entry} ${DESTDIR} ==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml#2 (text+ko) ==== @@ -22,7 +22,7 @@ <holder role="mailto:jhelfman@experts-exchange.com">Jason Helfman</holder> </copyright> - <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml,v 1.2 2011/02/14 20:41:53 manolis Exp $</pubdate> + <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/freebsd-update-server/article.sgml,v 1.3 2011/02/24 17:05:15 manolis Exp $</pubdate> <legalnotice id="trademarks" role="trademarks"> &tm-attrib.freebsd; @@ -62,7 +62,7 @@ Running a &fbus.ap; makes it easier to deploy security and software patches to selected test machines before rolling them out to production. It also means a number of systems can be updated from the - local network rather than a much slower Internet connection. + local network rather than a potentially slower Internet connection. This article outlines the steps involved in creating an internal &fbus.ap;.</para> </sect1> @@ -127,37 +127,36 @@ <para>Here is the default <filename>build.conf</filename>, which should be modified to suit your environment.</para> - <programlisting> + <informalexample> + <programlisting> # Main configuration file for FreeBSD Update builds. The # release-specific configuration data is lower down in # the scripts tree. # Location from which to fetch releases -export FTP=ftp://ftp2.freebsd.org/pub/FreeBSD/releases +export FTP=ftp://ftp2.freebsd.org/pub/FreeBSD/releases<co id="ftp-id"> # Host platform export HOSTPLATFORM=`uname -m` # Host name to use inside jails -export BUILDHOSTNAME=${HOSTPLATFORM}-builder.daemonology.net +export BUILDHOSTNAME=${HOSTPLATFORM}-builder.daemonology.net<co id="buildhost-id"> # Location of SSH key -export SSHKEY=/root/.ssh/id_dsa +export SSHKEY=/root/.ssh/id_dsa<co id="sshkey-id"> # SSH account into which files are uploaded -MASTERACCT=builder@wadham.daemonology.net +MASTERACCT=builder@wadham.daemonology.net<co id="mstacct-id"> # Directory into which files are uploaded -MASTERDIR=update-master.freebsd.org</programlisting> +MASTERDIR=update-master.freebsd.org<co id="mstdir-id"></programlisting> + </informalexample> <para>Parameters for consideration would be:</para> - <variablelist> - <varlistentry> - <term><literal>FTP</literal></term> - - <listitem> + <calloutlist> + <callout arearefs="ftp-id"> <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 @@ -171,24 +170,16 @@ architecture-specific area at <filename>scripts/RELEASE/ARCHITECTURE/build.subr</filename> and applying local changes.</para> - </listitem> - </varlistentry> + </callout> - <varlistentry> - <term><literal>BUILDHOSTNAME</literal></term> - - <listitem> + <callout arearefs="buildhost-id"> <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> - </varlistentry> + </callout> - <varlistentry> - <term><literal>SSHKEY</literal></term> - - <listitem> + <callout arearefs="sshkey-id"> <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 @@ -199,27 +190,18 @@ <para>The &man.ssh-keygen.1; manual page has more detailed information about <application>SSH</application> and the appropriate steps for creating and using one.</para> - </listitem> - </varlistentry> + </callout> - <varlistentry> - <term><literal>MASTERACCT</literal></term> - - <listitem> + <callout arearefs="mstacct-id"> <para>Account for uploading files to the update server.</para> - </listitem> - </varlistentry> + </callout> - <varlistentry> - <term><literal>MASTERDIR</literal></term> - - <listitem> + <callout arearefs="mstdir-id"> <para>Directory on the update server where files are uploaded to.</para> - </listitem> - </varlistentry> - </variablelist> + </callout> + </calloutlist> <para>The default <filename>build.conf</filename> file shipped with the <application>freebsd-update-server</application> sources is @@ -242,16 +224,11 @@ options for &os; 7.2-RELEASE on &arch.amd64; should be similar to:</para> + <informalexample> <programlisting># SHA256 hash of RELEASE disc1.iso image. -export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5</programlisting> +export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5<co id="sha256-id"> - <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> - - <programlisting># Components of the world, source, and kernels +# 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 \ @@ -259,9 +236,17 @@ export KERNELPARTS="generic" # EOL date -export EOL=1275289200</programlisting> +export EOL=1275289200<co id="eol-id"></programlisting> + </informalexample> + + <calloutlist> + <callout arearefs="sha256-id"> + <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> + </callout> - <note> + <callout arearefs="eol-id"> <para>To generate the "End of Life" number for <filename>build.conf</filename>, refer to the "Estimated EOL" posted on the <ulink @@ -269,9 +254,9 @@ Security Website</ulink>. The value of <literal>EOL</literal> can be derived from the date listed on the web site, using the &man.date.1; utility, for example:</para> - <screen>&prompt.user; <userinput>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s'</userinput></screen> - </note> + </callout> + </calloutlist> </step> </procedure> </sect1> @@ -818,7 +803,7 @@ url="&url.books.handbook;/firewalls.html">firewall</ulink> rule to block outgoing RST packets. Due to a bug noted <ulink url="http://lists.freebsd.org/pipermail/freebsd-stable/2009-April/049578.html">in a posting</ulink> - on the &a.stable; mailing list in April 2009, there may be + on the &a.stable; in April 2009, there may be time-outs and failures when updating a system.</para> </listitem> ==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml#3 (text+ko) ==== @@ -1,4 +1,4 @@ -<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml,v 1.8 2009/11/14 22:20:12 manolis Exp $ --> +<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml,v 1.9 2011/02/27 03:54:21 dougb Exp $ --> <!-- The FreeBSD Documentation Project --> <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ @@ -16,7 +16,7 @@ </author> </authorgroup> - <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml,v 1.8 2009/11/14 22:20:12 manolis Exp $</pubdate> + <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml,v 1.9 2011/02/27 03:54:21 dougb Exp $</pubdate> <copyright> <year>2004</year> @@ -484,22 +484,19 @@ some questions recur more often than others, sometimes as followups where the subject line no longer accurately reflects the new content. Nevertheless, the burden is on you, the poster, to do your homework - to help avoid these recurring topics, and especially the dreaded - <literal>bikeshed</literal>s.</para> + to help avoid these recurring topics.</para> </sect1> <sect1 id="bikeshed"> <title>What Is A "Bikeshed"?</title> <para>Literally, a <literal>bikeshed</literal> is a small outdoor shelter into which one may store one's two-wheeled form of - transportation. However, in &os; parlance, the word is a - derogatory term that refers to any oft-recurring discussion - about a particular subject; in particular, it is most often used - to refer to a topic which has never reached a consensus within - the &os; community, and instead remains controversial. (The + transportation. However, in &os; parlance, the term refers to + topics that are simple enough that (nearly) anyone can offer an + opinion about, and often (nearly) everyone does. The genesis of this term is explained in more detail <ulink url="&url.books.faq;/misc.html#BIKESHED-PAINTING"> - in this document</ulink>). You simply must have a working + in this document</ulink>. You simply must have a working knowledge of this concept before posting to any &os; mailing list.</para> ==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/portbuild/article.sgml#31 (text+ko) ==== @@ -11,7 +11,7 @@ <corpauthor>The &os; Ports Management Team</corpauthor> </authorgroup> - <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/portbuild/article.sgml,v 1.67 2011/01/23 04:07:34 linimon Exp $</pubdate> + <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/portbuild/article.sgml,v 1.68 2011/02/26 00:58:15 linimon Exp $</pubdate> <copyright> <year>2003</year> @@ -1141,16 +1141,9 @@ <para>Distfiles should be transferred with the <command>cpdistfiles</command> script:</para> - <screen>&prompt.root; <userinput>/var/portbuild/scripts/cpdistfiles <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>/var/portbuild/scripts/cpdistfiles <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> [-yesreally] | tee log2</userinput></screen> - <para>Or you can do it by hand using <command>rsync</command> - command:</para> - - <screen>&prompt.root; <userinput>cd /var/portbuild/<replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable></userinput> -&prompt.root; <userinput>rsync -n -r -v -l -p -c distfiles/ portmgr@ftp-master:w/ports/distfiles/ | tee log</userinput></screen> - - <para>Again, run the command without the <literal>-n</literal> - option after you have checked it.</para> + <para>Doing it by hand is deprecated.</para> </sect1> <sect1 id="expbuilds"> ==== //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml#18 (text+ko) ==== @@ -1,6 +1,6 @@ <!-- The FreeBSD Documentation Project - $FreeBSD: doc/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml,v 1.100 2011/01/29 14:29:29 ryusuke Exp $ + $FreeBSD: doc/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml,v 1.101 2011/02/25 09:12:49 blackend Exp $ --> <chapter id="desktop"> @@ -355,6 +355,11 @@ <screen>&prompt.root; <userinput>ln -s /usr/local/lib/npapi/linux-f10-flashplugin/libflashplayer.so \ /usr/local/lib/browser_plugins/</userinput></screen> + + <para>The <filename + class="directory">/usr/local/lib/browser_plugins</filename> + directory will have to be created manually if it does not + exist on the system.</para> </step> </procedure> ==== //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/disks/chapter.sgml#18 (text+ko) ==== @@ -1,7 +1,7 @@ <!-- The FreeBSD Documentation Project - $FreeBSD: doc/en_US.ISO8859-1/books/handbook/disks/chapter.sgml,v 1.302 2010/12/30 00:41:40 ryusuke Exp $ + $FreeBSD: doc/en_US.ISO8859-1/books/handbook/disks/chapter.sgml,v 1.303 2011/03/04 16:40:26 danger Exp $ --> <chapter id="disks"> @@ -3996,6 +3996,667 @@ </screen> </sect2> </sect1> + + <sect1 id="disks-hast"> + <sect1info> + <authorgroup> + <author> + <firstname>Daniel</firstname> + <surname>Gerzo</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Freddie</firstname> + <surname>Cash</surname> + <contrib>With inputs from </contrib> + </author> + <author> + <firstname>Pawel Jakub</firstname> + <surname>Dawidek</surname> + </author> + <author> + <firstname>Michael W.</firstname> + <surname>Lucas</surname> + </author> + <author> + <firstname>Viktor</firstname> + <surname>Petersson</surname> + </author> + </authorgroup> + <!-- Date of writing: 26 February 2011 --> + </sect1info> + + <title>Highly Available Storage (HAST)</title> + <indexterm> + <primary>HAST</primary> + <secondary>high availability</secondary> + </indexterm> + + <sect2> + <title>Synopsis</title> + + <para>High-availability is one of the main requirements in serious + business applications and highly-available storage is a key + component in such environments. Highly Available STorage, or + <acronym>HAST<remark role="acronym">Highly Available + STorage</remark></acronym>, was developed by &a.pjd; as a + framework which allows transparent storage of the same data + across several physically separated machines connected by a + TCP/IP network. <acronym>HAST</acronym> can be understood as + a network-based RAID1 (mirror), and is similar to the + DRBD® storage system known from the GNU/&linux; platform. + In combination with other high-availability features of &os; + like <acronym>CARP</acronym>, <acronym>HAST</acronym> makes it + possible to build a highly-available storage cluster that is + resistant to hardware failures.</para> + + <para>After reading this section, you will know:</para> + + <itemizedlist> + <listitem> + <para>What <acronym>HAST</acronym> is, how it works and + which features it provides.</para> + </listitem> + <listitem> + <para>How to set up and use <acronym>HAST</acronym> on + &os;.</para> + </listitem> + <listitem> + <para>How to integrate <acronym>CARP</acronym> and + &man.devd.8;; to build a robust storage system.</para> + </listitem> + </itemizedlist> + + <para>Before reading this section, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand &unix; and &os; basics + (<xref linkend="basics">).</para> + </listitem> + <listitem> + <para>Know how to configure network interfaces and other + core &os; subsystems (<xref + linkend="config-tuning">).</para> + </listitem> + <listitem> + <para>Have a good understanding of &os; networking + (<xref linkend="network-communication">).</para> + </listitem> + <listitem> + <para>Use &os; 8.1-RELEASE or newer.</para> + </listitem> + </itemizedlist> + + <para>The <acronym>HAST</acronym> project was sponsored by The + &os; Foundation with the support from <ulink + url="http://www.omc.net/">OMCnet Internet Service GmbH</ulink> + and <ulink url="http://www.transip.nl/">TransIP BV</ulink>.</para> + </sect2> + + <sect2> + <title>HAST Features</title> + + <para>The main features of the <acronym>HAST</acronym> system + are:</para> + + <itemizedlist> + <listitem> + <para>Can be used to mask I/O errors on local hard + drives.</para> + </listitem> + <listitem> + <para>File system agnostic, thus allowing to use any file + system supported by &os;.</para> + </listitem> + <listitem> + <para>Efficient and quick resynchronization, synchronizing + only blocks that were modified during the downtime of a + node.</para> + </listitem> + <!-- + <listitem> + <para>Has several synchronization modes to allow for fast + failover.</para> + </listitem> + --> + <listitem> + <para>Can be used in an already deployed environment to add + additional redundancy.</para> + </listitem> + <listitem> + <para>Together with <acronym>CARP</acronym>, + <application>Heartbeat</application>, or other tools, it + can be used to build a robust and durable storage + system.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>HAST Operation</title> + + <para>As <acronym>HAST</acronym> provides a synchronous + block-level replication of any storage media to several + machines, it requires at least two nodes (physical machines) + — the <literal>primary</literal> (also known as + <literal>master</literal>) node, and the + <literal>secondary</literal> (<literal>slave</literal>) node. + These two machines together will be called a cluster.</para> + + <note> + <para>HAST is currently limited to two cluster nodes in + total.</para> + </note> + + <para>Since the <acronym>HAST</acronym> works in + primary-secondary configuration, it allows only one of the + cluster nodes to be active at any given time. The + <literal>primary</literal> node, also called + <literal>active</literal>, is the one which will handle all + the I/O requests to <acronym>HAST</acronym>-managed + devices. The <literal>secondary</literal> node is then being + automatically synchronized from the <literal>primary</literal> + node.</para> + + <para>The physical components of the <acronym>HAST</acronym> + system are:</para> + + <itemizedlist> + <listitem> + <para>local disk (on primary node)</para> + </listitem> + <listitem> + <para>disk on remote machine (secondary node)</para> + </listitem> + </itemizedlist> + + <para><acronym>HAST</acronym> operates synchronously on a block + level, which makes it transparent for file systems and + applications. <acronym>HAST</acronym> provides regular GEOM + providers in <filename class="directory">/dev/hast/</filename> + directory for use by other tools or applications, thus there is + no difference between using <acronym>HAST</acronym>-provided + devices and raw disks, partitions, etc.</para> + + <para>Each write, delete or flush operation is sent to the local + disk and to the remote disk over TCP/IP. Each read operation + is served from the local disk, unless the local disk is not + up-to-date or an I/O error occurs. In such case, the read + operation is sent to the secondary node.</para> + + <sect3> + <title>Synchronization and Replication Modes</title> + + <para><acronym>HAST</acronym> tries to provide fast failure + recovery. For this reason, it is very important to reduce + synchronization time after a node's outage. To provide fast + synchronization, <acronym>HAST</acronym> manages an on-disk + bitmap of dirty extents and only synchronizes those during a + regular synchronization (with an exception of the initial + sync).</para> + + <para>There are many ways to handle synchronization. + <acronym>HAST</acronym> implements several replication modes + to handle different synchronization methods:</para> + + <itemizedlist> + <listitem> + <para><emphasis>memsync</emphasis>: report write operation + as completed when the local write operation is finished + and when the remote node acknowledges data arrival, but + before actually storing the data. The data on the + remote node will be stored directly after sending the + acknowledgement. This mode is intended to reduce + latency, but still provides very good reliability. The + <emphasis>memsync</emphasis> replication mode is + currently not implemented.</para> + </listitem> + <listitem> + <para><emphasis>fullsync</emphasis>: report write + operation as completed when local write completes and when + remote write completes. This is the safest and the + slowest replication mode. This mode is the + default.</para> + </listitem> + <listitem> + <para><emphasis>async</emphasis>: report write operation + as completed when local write completes. This is the + fastest and the most dangerous replication mode. It + should be used when replicating to a distant node where + latency is too high for other modes. The + <emphasis>async</emphasis> replication mode is currently + not implemented.</para> + </listitem> + </itemizedlist> + + <warning> + <para>Only the <emphasis>fullsync</emphasis> replication mode + is currently supported.</para> + </warning> + </sect3> + </sect2> + + <sect2> + <title>HAST Configuration</title> + + <para><acronym>HAST</acronym> requires + <literal>GEOM_GATE</literal> support in order to function. + The <literal>GENERIC</literal> kernel does + <emphasis>not</emphasis> include <literal>GEOM_GATE</literal> + by default, however the <filename>geom_gate.ko</filename> + loadable module is available in the default &os; installation. + For stripped-down systems, make sure this module is available. + Alternatively, it is possible to build + <acronym>GEOM_GATE</acronym> support into the kernel + statically, by adding the following line to the custom kernel + configuration file:</para> + + <programlisting>options GEOM_GATE</programlisting> + + <para>The <acronym>HAST</acronym> framework consists of several + parts from the operating system's point of view:</para> + + <itemizedlist> + <listitem> + <para>the &man.hastd.8; daemon responsible for the data + synchronization,</para> + </listitem> + <listitem> + <para>the &man.hastctl.8; userland management utility,</para> + </listitem> + <listitem> + <para>the &man.hast.conf.5; configuration file.</para> + </listitem> + </itemizedlist> + + <para>The following example describes how to configure two nodes + in <literal>master</literal>-<literal>slave</literal> / + <literal>primary</literal>-<literal>secondary</literal> + operation using <acronym>HAST</acronym> to replicate the data + between the two. The nodes will be called + <literal><replaceable>hasta</replaceable></literal> with an IP + address <replaceable>172.16.0.1</replaceable> and + <literal><replaceable>hastb</replaceable></literal> with an IP + address <replaceable>172.16.0.2</replaceable>. Both of these + nodes will have a dedicated hard drive + <devicename>/dev/<replaceable>ad6</replaceable></devicename> of + the same size for <acronym>HAST</acronym> operation. + The <acronym>HAST</acronym> pool (sometimes also referred to + as a resource, i.e. the GEOM provider in <filename + class="directory">/dev/hast/</filename>) will be called + <filename><replaceable>test</replaceable></filename>.</para> + + <para>The configuration of <acronym>HAST</acronym> is being done + in the <filename>/etc/hast.conf</filename> file. This file + should be the same on both nodes. The simplest configuration + possible is following:</para> + + <programlisting>resource test { + on hasta { + local /dev/ad6 + remote 172.16.0.1 + } + on hastb { + local /dev/ad6 + remote 172.16.0.2 + } +}</programlisting> + + <para>For more advanced configuration, please consult the + &man.hast.conf.5; manual page.</para> + + <tip> + <para>It is also possible to use host names in the + <literal>remote</literal> statements. In such a case, make + sure that these hosts are resolvable, e.g. they are defined + in the <filename>/etc/hosts</filename> file, or + alternatively in the local <acronym>DNS</acronym>.</para> + </tip> + + <para>Now that the configuration exists on both nodes, it is + possible to create the <acronym>HAST</acronym> pool. Run the + following commands on both nodes to place the initial metadata + onto the local disk, and start the &man.hastd.8; daemon:</para> + + <screen>&prompt.root; <userinput>hastctl create test</userinput> +&prompt.root; <userinput>/etc/rc.d/hastd onestart</userinput></screen> + + <note> + <para>It is <emphasis>not</emphasis> possible to use GEOM + providers with an existing file system (i.e. convert an + existing storage to <acronym>HAST</acronym>-managed pool), + because this procedure needs to store some metadata onto the + provider and there will not be enough required space + available.</para> + </note> + + <para>HAST is not responsible for selecting node's role + (<literal>primary</literal> or <literal>secondary</literal>). + Node's role has to be configured by an administrator or other + software like <application>Heartbeat</application> using the + &man.hastctl.8; utility. Move to the primary node + (<literal><replaceable>hasta</replaceable></literal>) and + issue the following command:</para> + + <screen>&prompt.root; <userinput>hastctl role primary test</userinput></screen> + + <para>Similarly, run the following command on the secondary node + (<literal><replaceable>hastb</replaceable></literal>):</para> + + <screen>&prompt.root; <userinput>hastctl role secondary test</userinput></screen> + + <caution> + <para>It may happen that both of the nodes are not able to + communicate with each other and both are configured as + primary nodes; the consequence of this condition is called + <literal>split-brain</literal>. In order to troubleshoot + this situation, follow the steps described in <xref + linkend="disks-hast-sb">.</para> + </caution> + + <para>It is possible to verify the result with the + &man.hastctl.8; utility on each node:</para> + + <screen>&prompt.root; <userinput>hastctl status test</userinput></screen> + + <para>The important text is the <literal>status</literal> line + from its output and it should say <literal>complete</literal> + on each of the nodes. If it says <literal>degraded</literal>, + something went wrong. At this point, the synchronization + between the nodes has already started. The synchronization + completes when the <command>hastctl status</command> command + reports 0 bytes of <literal>dirty</literal> extents.</para> + + + <para>The last step is to create a filesystem on the + <devicename>/dev/hast/<replaceable>test</replaceable></devicename> + GEOM provider and mount it. This has to be done on the + <literal>primary</literal> node (as the + <filename>/dev/hast/<replaceable>test</replaceable></filename> + appears only on the <literal>primary</literal> node), and + it can take a few minutes depending on the size of the hard + drive:</para> + + <screen>&prompt.root; <userinput>newfs -U /dev/hast/test</userinput> +&prompt.root; <userinput>mkdir /hast/test</userinput> +&prompt.root; <userinput>mount /dev/hast/test /hast/test</userinput></screen> + + <para>Once the <acronym>HAST</acronym> framework is configured + properly, the final step is to make sure that + <acronym>HAST</acronym> is started during the system boot time + automatically. The following line should be added to the + <filename>/etc/rc.conf</filename> file:</para> + + <programlisting>hastd_enable="YES"</programlisting> + + <sect3> + <title>Failover Configuration</title> + + <para>The goal of this example is to build a robust storage + system which is resistant from the failures of any given node. + The key task here is to remedy a scenario when a + <literal>primary</literal> node of the cluster fails. Should + it happen, the <literal>secondary</literal> node is there to + take over seamlessly, check and mount the file system, and + continue to work without missing a single bit of data.</para> + + <para>In order to accomplish this task, it will be required to + utilize another feature available under &os; which provides + for automatic failover on the IP layer — + <acronym>CARP</acronym>. <acronym>CARP</acronym> stands for + Common Address Redundancy Protocol and allows multiple hosts + on the same network segment to share an IP address. Set up + <acronym>CARP</acronym> on both nodes of the cluster according + to the documentation available in <xref linkend="carp">. + After completing this task, each node should have its own + <devicename>carp0</devicename> interface with a shared IP + address <replaceable>172.16.0.254</replaceable>. + Obviously, the primary <acronym>HAST</acronym> node of the + cluster has to be the master <acronym>CARP</acronym> + node.</para> + + <para>The <acronym>HAST</acronym> pool created in the previous + section is now ready to be exported to the other hosts on + the network. This can be accomplished by exporting it + through <acronym>NFS</acronym>, + <application>Samba</application> etc, using the shared IP + address <replaceable>172.16.0.254</replaceable>. The only + problem which remains unresolved is an automatic failover + should the primary node fail.</para> + + <para>In the event of <acronym>CARP</acronym> interfaces going + up or down, the &os; operating system generates a &man.devd.8; + event, which makes it possible to watch for the state changes + on the <acronym>CARP</acronym> interfaces. A state change on + the <acronym>CARP</acronym> interface is an indication that + one of the nodes failed or came back online. In such a case, + it is possible to run a particular script which will + automatically handle the failover.</para> + + <para>To be able to catch the state changes on the + <acronym>CARP</acronym> interfaces, the following + configuration has to be added to the + <filename>/etc/devd.conf</filename> file on each node:</para> + + <programlisting>notify 30 { + match "system" "IFNET"; + match "subsystem" "carp0"; + match "type" "LINK_UP"; + action "/usr/local/sbin/carp-hast-switch master"; +}; + +notify 30 { + match "system" "IFNET"; + match "subsystem" "carp0"; + match "type" "LINK_DOWN"; + action "/usr/local/sbin/carp-hast-switch slave"; +};</programlisting> + + <para>To put the new configuration into effect, run the + following command on both nodes:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/devd restart</userinput></screen> + + <para>In the event that the <devicename>carp0</devicename> + interface goes up or down (i.e. the interface state changes), + the system generates a notification, allowing the &man.devd.8; + subsystem to run an arbitrary script, in this case + <filename>/usr/local/sbin/carp-hast-switch</filename>. This + is the script which will handle the automatic + failover. For further clarification about the above + &man.devd.8; configuration, please consult the + &man.devd.conf.5; manual page.</para> + + <para>An example of such a script could be following:</para> + +<programlisting>#!/bin/sh + +# Original script by Freddie Cash <fjwcash@gmail.com> +# Modified by Michael W. Lucas <mwlucas@BlackHelicopters.org> +# and Viktor Petersson <vpetersson@wireload.net> + +# The names of the HAST resources, as listed in /etc/hast.conf +resources="test" + +# delay in mounting HAST resource after becoming master +# make your best guess +delay=3 + +# logging +log="local0.debug" +name="carp-hast" + +# end of user configurable stuff + +case "$1" in + master) + logger -p $log -t $name "Switching to primary provider for ${resources}." + sleep ${delay} + + # Wait for any "hastd secondary" processes to stop + for disk in ${resources}; do + while $( pgrep -lf "hastd: ${disk} \(secondary\)" > /dev/null 2>&1 ); do + sleep 1 + done + + # Switch role for each disk + hastctl role primary ${disk} + if [ $? -ne 0 ]; then + logger -p $log -t $name "Unable to change role to primary for resource ${disk}." + exit 1 + fi + done + + # Wait for the /dev/hast/* devices to appear + for disk in ${resources}; do + for I in $( jot 60 ); do + [ -c "/dev/hast/${disk}" ] && break + sleep 0.5 + done + + if [ ! -c "/dev/hast/${disk}" ]; then + logger -p $log -t $name "GEOM provider /dev/hast/${disk} did not appear." + exit 1 + fi + done + + logger -p $log -t $name "Role for HAST resources ${resources} switched to primary." + + + logger -p $log -t $name "Mounting disks." + for disk in ${resources}; do + mkdir -p /hast/${disk} + fsck -p -y -t ufs /dev/hast/${disk} + mount /dev/hast/${disk} /hast/${disk} + done + + ;; + + slave) + logger -p $log -t $name "Switching to secondary provider for ${resources}." + + # Switch roles for the HAST resources + for disk in ${resources}; do + if ! mount | grep -q "^${disk} on " + then + else + umount -f /hast/${disk} + fi + sleep $delay + hastctl role secondary ${disk} 2>&1 + if [ $? -ne 0 ]; then + logger -p $log -t $name "Unable to switch role to secondary for resource ${disk}." + exit 1 + fi + logger -p $log -t $name "Role switched to secondary for resource ${disk}." + done + ;; +esac</programlisting> + + <para>In a nutshell, the script does the following when a node + becomes <literal>master</literal> / + <literal>primary</literal>:</para> + + <itemizedlist> + <listitem> + <para>Promotes the <acronym>HAST</acronym> pools as + primary on a given node.</para> + </listitem> + <listitem> + <para>Checks the file system under the + <acronym>HAST</acronym> pool.</para> + </listitem> + <listitem> + <para>Mounts the pools at appropriate place.</para> + </listitem> + </itemizedlist> + + <para>When a node becomes <literal>backup</literal> / + <literal>secondary</literal>:</para> + + <itemizedlist> + <listitem> + <para>Unmounts the <acronym>HAST</acronym> pools.</para> + </listitem> + <listitem> + <para>Degrades the <acronym>HAST</acronym> pools to + secondary.</para> + </listitem> + </itemizedlist> + + <caution> + <para>Keep in mind that this is just an example script which + should serve as a proof of concept solution. It does not + handle all the possible scenarios and can be extended or + altered in any way, for example it can start/stop required + services etc.</para> + </caution> + + <tip> + <para>For the purpose of this example we used a standard UFS + file system. In order to reduce the time needed for + recovery, a journal-enabled UFS or ZFS file system can + be used.</para> + </tip> + + <para>More detailed information with additional examples can be >>> TRUNCATED FOR MAIL (1000 lines) <<<
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201103062119.p26LJE1b021459>