<!-- $Id: adminscripts.sgml,v 1.24 2005/05/31 16:14:55 cbbrowne Exp $ -->
<sect1 id="altperl">
<title>&slony1; Administration Scripts</title>

<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.  An administrator should review the script
<emphasis>before</emphasis> submitting it to <xref linkend="slonik">.</para>

<sect2><title>Node/Cluster Configuration - cluster.nodes</title>

<para>The UNIX environment variable <envar>SLONYNODES</envar> is used
to determine what Perl configuration file will be used to control the
shape of the nodes in a &slony1; cluster.</para>

<para>What variables are set up.
<itemizedlist>

<listitem><para><envar>$CLUSTER_NAME</envar>=orglogs;	# What is the name of the replication cluster?</para></listitem>
<listitem><para><envar>$LOGDIR</envar>='/opt/OXRS/log/LOGDBS';	# What is the base directory for logs?</para></listitem>
<listitem><para><envar>$APACHE_ROTATOR</envar>="/opt/twcsds004/OXRS/apache/rotatelogs";  # If set, where to find Apache log rotator</para></listitem>
</itemizedlist>
</para>

<para> You then define the set of nodes that are to be replicated
using a set of calls to <function>add_node()</function>.
</para>

<para><command>
  add_node (host => '10.20.30.40', dbname => 'orglogs', port => 5437,
			  user => 'postgres', node => 4, parent => 1);
</command></para>

<para>The set of parameters for <function>add_node()</function> are thus:</para>

<programlisting>
my %PARAMS =   (host=> undef,		# Host name
	   	dbname => 'template1',	# database name
		port => 5432,		# Port number
		user => 'postgres',	# user to connect as
		node => undef,		# node number
		password => undef,	# password for user
		parent => 1,		# which node is parent to this node
		noforward => undef	# shall this node be set up to forward results?
                sslmode => undef        # SSL mode argument - determine priority of SSL usage = disable,allow,prefer,require
);
</programlisting>
</sect2>
<sect2><title>Set configuration - cluster.set1, cluster.set2</title>

<para>The UNIX environment variable <envar>SLONYSET</envar> is used to
determine what Perl configuration file will be used to determine what
objects will be contained in a particular replication set.</para>

<para>Unlike <envar>SLONYNODES</envar>, which is essential for
<emphasis>all</emphasis> of the <xref linkend="slonik">-generating
scripts, this only needs to be set when running
<filename>create_set</filename>, as that is the only script used to
control what tables will be in a particular replication set.</para>

<para>What variables are set up.</para>
<itemizedlist>
<listitem><para>$TABLE_ID = 44;</para>
<para> Each table must be identified by a unique number; this variable controls where numbering starts</para>
</listitem>
<listitem><para>$SEQUENCE_ID = 17;</para>
<para> Each sequence must be identified by a unique number; this variable controls where numbering starts</para>
</listitem>
<listitem><para>@PKEYEDTABLES</para>

<para> An array of names of tables to be replicated that have a
defined primary key so that &slony1; can automatically select its key</para>
</listitem>
<listitem><para>%KEYEDTABLES</para>
<para> A hash table of tables to be replicated, where the hash index
is the table name, and the hash value is the name of a unique not null
index suitable as a "candidate primary key."</para>
</listitem>
<listitem><para>@SERIALTABLES</para>

<para> An array of names of tables to be replicated that have no
candidate for primary key.  &slony1; will add a key field based on a
sequence that &slony1; generates</para>
</listitem>
<listitem><para>@SEQUENCES</para>

<para> An array of names of sequences that are to be replicated</para>
</listitem>
</itemizedlist>
</sect2>
<sect2><title>slonik_build_env</title>

<para>Queries a database, generating output hopefully suitable for
<filename>slon_tools.conf</filename> consisting of:</para>
<itemizedlist>

<listitem><para> a set of <function>add_node()</function> calls to configure the cluster</para></listitem>
<listitem><para> The arrays <envar>@KEYEDTABLES</envar>,
<envar>nvar>@SERIALT</envar>nvar>, and <envar>@SEQUENCES</envar></para></listitem>
</itemizedlist>
</sect2>
<sect2><title>slonik_create_set</title>

<para>This requires <envar>SLONYSET</envar> to be set as well as
<envar>SLONYNODES</envar>; it is used to generate the <command>slonik</command> script to set up
a replication set consisting of a set of tables and sequences that are
to be replicated.</para>
</sect2>
<sect2><title>slonik_drop_node</title>

<para>Generates Slonik script to drop a node from a &slony1; cluster.</para>
</sect2>
<sect2><title>slonik_drop_set</title>

<para>Generates Slonik script to drop a replication set
(<emphasis>e.g.</emphasis> - set of tables and sequences) from a
&slony1; cluster.</para>
</sect2>
<sect2><title>slonik_execute_script</title>

<para>Generates Slonik script to push DDL changes to a replication set.</para>
</sect2>
<sect2><title>slonik_failover</title>

<para>Generates Slonik script to request failover from a dead node to some new origin</para>
</sect2>
<sect2><title>slonik_init_cluster</title>

<para>Generates Slonik script to initialize a whole &slony1; cluster,
including setting up the nodes, communications paths, and the listener
routing.</para>
</sect2>
<sect2><title>slonik_merge_sets</title>

<para>Generates Slonik script to merge two replication sets together.</para>
</sect2>
<sect2><title>slonik_move_set</title>

<para>Generates Slonik script to move the origin of a particular set to a different node.</para>
</sect2>
<sect2><title>replication_test</title>

<para>Script to test whether &slony1; is successfully replicating
data.</para>
</sect2>
<sect2><title>slonik_restart_node</title>

<para>Generates Slonik script to request the restart of a node.  This was
particularly useful pre-1.0.5 when nodes could get snarled up when
slon daemons died.</para>
</sect2>
<sect2><title>slonik_restart_nodes</title>

<para>Generates Slonik script to restart all nodes in the cluster.  Not
particularly useful.</para>
</sect2>
<sect2><title>slony_show_configuration</title>

<para>Displays an overview of how the environment (e.g. - <envar>SLONYNODES</envar>) is set
to configure things.</para>
</sect2>
<sect2><title>slon_kill</title>

<para>Kills slony watchdog and all slon daemons for the specified set.  It
only works if those processes are running on the local host, of
course!</para>
</sect2>
<sect2><title>slon_start</title>

<para>This starts a slon daemon for the specified cluster and node, and uses
slon_watchdog to keep it running.</para>
</sect2>
<sect2><title>slon_watchdog</title>

<para>Used by <command>slon_start</command>.</para>

</sect2><sect2><title>slon_watchdog2</title>

<para>This is a somewhat smarter watchdog; it monitors a particular
&slony1; node, and restarts the slon process if it hasn't seen updates
go in in 20 minutes or more.</para>

<para>This is helpful if there is an unreliable network connection such that
the slon sometimes stops working without becoming aware of it.</para>

</sect2>
<sect2><title>slonik_store_node</title>

<para>Adds a node to an existing cluster.</para>
</sect2>
<sect2><title>slonik_subscribe_set</title>

<para>Generates Slonik script to subscribe a particular node to a particular replication set.</para>

</sect2><sect2><title>slonik_uninstall_nodes</title>

<para>This goes through and drops the &slony1; schema from each node;
use this if you want to destroy replication throughout a cluster.
This is a <emphasis>VERY</emphasis> unsafe script!</para>

</sect2><sect2><title>slonik_unsubscribe_set</title>

<para>Generates Slonik script to unsubscribe a node from a replication set.</para>

</sect2>
<sect2><title>slonik_update_nodes</title>

<para>Generates Slonik script to tell all the nodes to update the
&slony1; functions.  This will typically be needed when you upgrade
from one version of &slony1; to another.</para>
</sect2>
<sect2 id="regenlisten"><title>regenerate-listens</title>

<para>This script connects to a &slony1; node, and queries various
tables (sl_set, sl_node, sl_subscribe, sl_path) to compute what <xref
    linkend="stmtstorelisten"> requests should be submitted to the
cluster.</para>

<para> See the documentation in <xref linkend="autolisten"> for more
details on how this works.</para>
</sect2>

</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:"book.sgml"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
