Update of /home/cvsd/slony1/slony1-engine/doc/adminguide
In directory main:/tmp/cvs-serv22861

Modified Files:
	adminscripts.sgml firstdb.sgml monitoring.sgml 
Log Message:
mark at summersault.com
  * provide examples of using the altperl scripts for initial replication set up.

cbbrowne fixed some tagging


Index: monitoring.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/monitoring.sgml,v
retrieving revision 1.34
retrieving revision 1.35
diff -C2 -d -r1.34 -r1.35
*** monitoring.sgml	24 Jan 2007 15:42:14 -0000	1.34
--- monitoring.sgml	30 Jan 2007 19:23:19 -0000	1.35
***************
*** 201,205 ****
  Doing commit Slony_replication.wiki with host: logtail and lang: en
  </screen>
- </sect2>
  
  <para> Note that <command>mvs</command> is a client written in Perl;
--- 201,204 ----
***************
*** 209,212 ****
--- 208,212 ----
  may have a packaged version of this under some similar name. </para>
  
+ </sect2>
  </sect1>
  <!-- Keep this comment at the end of the file

Index: adminscripts.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/adminscripts.sgml,v
retrieving revision 1.45
retrieving revision 1.46
diff -C2 -d -r1.45 -r1.46
*** adminscripts.sgml	5 Jan 2007 19:32:29 -0000	1.45
--- adminscripts.sgml	30 Jan 2007 19:23:19 -0000	1.46
***************
*** 14,34 ****
  <indexterm><primary>altperl scripts for &slony1;</primary></indexterm>
  
! <para>In the <filename>altperl</filename> directory in the
! <application>CVS</application> tree, there is a sizable set of
! <application>Perl</application> scripts that may be used to administer
! a set of &slony1; instances, which support having arbitrary numbers of
! nodes.</para>
  
! <para>Most of them generate Slonik scripts that are then to be passed
! on to the <xref linkend="slonik"> utility to be submitted to all of
! the &slony1; nodes in a particular cluster.  At one time, this
! embedded running <xref linkend="slonik"> on the slonik scripts.
  Unfortunately, this turned out to be a pretty large calibre
  <quote>foot gun</quote>, as minor typos on the command line led, on a
! couple of occasions, to pretty calamitous actions, so the behavior has
! been changed so that the scripts simply submit output to standard
! output.  The savvy administrator should review the script
! <emphasis>before</emphasis> submitting it to <xref
! linkend="slonik">.</para>
  
  <sect3><title>Node/Cluster Configuration - cluster.nodes</title>
--- 14,37 ----
  <indexterm><primary>altperl scripts for &slony1;</primary></indexterm>
  
! <para>There is a set of scripts to simplify administeration
! of set of &slony1; instances. The scripts support having arbitrary numbers of
! nodes. They may be installed as part of the installation process:</para>
  
! <para><command>
!  ./configure --with-perltools
! </command></para>
! 
! <para>This will produce a number of scripts with the prefix <command>slonik_</command>.
! They eliminate tedium by always referring to a central configuration file
! for the details of your site configuration. Most also include some command 
! line help with the "-h" option, making them easier to learn and use.
! </para>
! 
! <para>Most generate Slonik scripts that are printed to STDOUT. 
! At one time, the commands were passed directly to <xref linkend="slonik"> for execution. 
  Unfortunately, this turned out to be a pretty large calibre
  <quote>foot gun</quote>, as minor typos on the command line led, on a
! couple of occasions, to pretty calamitous actions. The savvy administrator should review the script
! <emphasis>before</emphasis> piping it to <xref linkend="slonik">.</para>
  
  <sect3><title>Node/Cluster Configuration - cluster.nodes</title>

Index: firstdb.sgml
===================================================================
RCS file: /home/cvsd/slony1/slony1-engine/doc/adminguide/firstdb.sgml,v
retrieving revision 1.20
retrieving revision 1.21
diff -C2 -d -r1.20 -r1.21
*** firstdb.sgml	2 Aug 2006 18:34:58 -0000	1.20
--- firstdb.sgml	30 Jan 2007 19:23:19 -0000	1.21
***************
*** 140,146 ****
  and configuration is all done through the <xref linkend="slonik">
  tool. It is a specialized scripting aid that mostly calls stored
! procedures in the master/slave (node) databases.  The script to create
  the initial configuration for the simple master-slave setup of our
! <application>pgbench</application> database looks like this:
  
  <programlisting>
--- 140,184 ----
  and configuration is all done through the <xref linkend="slonik">
  tool. It is a specialized scripting aid that mostly calls stored
! procedures in the master/slave (node) databases. </para>
! 
! <sect3><title>Using the altperl scripts</title>
! 
! <para>
! Using the <xref linkend="altperl"> scripts is an easy way to get started.  The
! <command>slonik_build_env</command> script will generate output providing
! details you need to  omplete building a <filename>slon_tools.conf</filename>. 
! An example <filename>slon_tools.conf</filename> is provided in the distribution
! to get you started.  The altperl scripts will all reference
! this central configuration file in the future to ease administration. Once 
! slon_tools.conf has been created, you can proceed as follows:
! </para>
! 
! <programlisting>
! # Initialize cluster:
! $ slonik_init_cluster  | slonik 
! 
! # Start slon  (here 1 and 2 are node numbers)
! $ slon_start 1    
! $ slon_start 2
! 
! # Create Sets (here 1 is a set number)
! $ slonik_create_set 1             
! 
! # subscribe set to second node (1= set ID, 2= node ID)
! $ slonik_subscribe_set  2 | slonik
! </programlisting>
! 
! <para> You have now replicated your first database.  You can skip the following section
! of documentation if you'd like, which documents more of a <quote>bare-metal</quote> approach.</para>
! </sect3>
! 
! <sect3><title>Using slonik command directly</title>
! <para>The traditional approach to administering slony is to craft slonik
! commands directly. An example of this given here. </para>
! 
! 
! <para> The script to create
  the initial configuration for the simple master-slave setup of our
! <application>pgbench</application> database looks like this:</para>
  
  <programlisting>
***************
*** 203,207 ****
  	store listen (origin=2, provider = 2, receiver =1);
  _EOF_
! </programlisting></para>
  
  <para>Is the <application>pgbench</application> still running?  If
--- 241,245 ----
  	store listen (origin=2, provider = 2, receiver =1);
  _EOF_
! </programlisting>
  
  <para>Is the <application>pgbench</application> still running?  If
***************
*** 283,287 ****
  <application>pgbench</application> has completed, so that there are no
  new updates hitting the origin node, and that your slon sessions have
! caught up.
  
  <programlisting>
--- 321,325 ----
  <application>pgbench</application> has completed, so that there are no
  new updates hitting the origin node, and that your slon sessions have
! caught up.</para>
  
  <programlisting>
***************
*** 319,323 ****
  fi
  </programlisting>
- </para>
  
  <para>Note that there is somewhat more sophisticated documentation of
--- 357,360 ----