<!--  -->
<refentry id="slon">
 <refmeta>
  <refentrytitle id="app-slon-title"><application>slon</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname><application>slon</application></refname>
  <refpurpose>
   &slony1; daemon
  </refpurpose>
 </refnamediv>
 
 <indexterm zone="slon">
  <primary>slon</primary>
 </indexterm>
 
 <refsynopsisdiv>
  <cmdsynopsis>
   <command>slon</command>
   <arg rep="repeat"><replaceable class="parameter">option</replaceable></arg>
   <arg><replaceable class="parameter">clustername</replaceable></arg>
   <arg><replaceable class="parameter">conninfo</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>
 
 <refsect1>
  <title>Description</title>
  <para>
   <application>slon</application> is the daemon application that
   <quote>runs</quote> &slony1; replication.  A
   <application>slon</application> instance must be run for each node
   in a &slony1; cluster.
  </para>
 </refsect1>
 
 <refsect1 id="r1-app-slon-3">
  <title>Options</title>
  
  <variablelist>
   <varlistentry>
    <term><option>-d</option><replaceable class="parameter"> log_level</replaceable></term>
    <listitem>
     <para>
      The <envar>log_level</envar> specifies which levels of debugging messages
      <application>slon</application> should display when logging its
      activity.
     </para>
     <para id="nineloglevels">
      The nine levels of logging are:
      <itemizedlist>
       <listitem><para>Fatal</para></listitem>
       <listitem><para>Error</para></listitem>
       <listitem><para>Warn</para></listitem>
       <listitem><para>Config</para></listitem>
       <listitem><para>Info</para></listitem>
       <listitem><para>Debug1</para></listitem>
       <listitem><para>Debug2</para></listitem>
       <listitem><para>Debug3</para></listitem>
       <listitem><para>Debug4</para></listitem>
      </itemizedlist>
     </para>

     <para> The first five non-debugging log levels (from Fatal to
     Info) are <emphasis>always</emphasis> displayed in the logs.  In
     early versions of &slony1;, the <quote>suggested</quote>
     <envar>log_level</envar> value was 2, which would list output at
     all levels down to debugging level 2.  In &slony1; version 2, it
     is recommended to set <envar>log_level</envar> to 0; most of the
     consistently interesting log information is generated at levels
     higher than that. </para>

    </listitem>
   </varlistentry>
   
   <varlistentry>
    <term><option>-s</option><replaceable class="parameter"> SYNC check interval</replaceable></term>
    <listitem>

     <para>
      The <envar>sync_interval</envar>, measured in milliseconds,
      indicates how often <application>slon</application> should check
      to see if a <command>SYNC</command> should be introduced.
      Default is 2000 ms.  The main loop in
      <function>sync_Thread_main()</function> sleeps for intervals of
      <envar>sync_interval</envar> milliseconds between iterations.
     </para>
     
     <para>
      Short sync check intervals keep the origin on a <quote>short
      leash</quote>, updating its subscribers more frequently.  If you
      have replicated sequences that are frequently updated
      <emphasis>without</emphasis> there being tables that are
      affected, this keeps there from being times when only sequences
      are updated, and therefore <emphasis>no</emphasis> syncs take
      place
     </para>

     <para>
      If the node is not an origin for any replication set, so no
      updates are coming in, it is somewhat wasteful for this value to
      be much less the <envar>sync_interval_timeout</envar> value.
     </para>

    </listitem>
   </varlistentry>
   
   <varlistentry>
    <term><option>-t</option><replaceable class="parameter"> SYNC
    interval timeout</replaceable></term>
    <listitem>

     <para>
      At the end of each <envar>sync_interval_timeout</envar> timeout
      period, a <command>SYNC</command> will be generated on the
      <quote>local</quote> node even if there has been no replicable
      data updated that would have caused a
      <command>SYNC</command> to be generated. </para>

     <para> If application activity ceases, whether because the
     application is shut down, or because human users have gone home
     and stopped introducing updates, the &lslon; will iterate away,
     waking up every <envar>sync_interval</envar> milliseconds, and,
     as no updates are being made, no <command>SYNC</command> events
     would be generated.  Without this timeout parameter,
     <emphasis>no</emphasis> <command>SYNC</command> events would be
     generated, and it would appear that replication was falling
     behind. </para>

     <para> The <envar>sync_interval_timeout</envar> value will lead
     to eventually generating a <command>SYNC</command>, even though
     there was no real replication work to be done.  The lower that
     this parameter is set, the more frequently &lslon; will generate
     <command>SYNC</command> events when the application is not
     generating replicable activity; this will have two effects:</para>
      <itemizedlist>

      <listitem><para> The system will do more replication work.</para> 

      <para> (Of course, since there is no application load on the
      database, and no data to replicate, this load will be very easy
      to handle.  </para></listitem>

      <listitem><para> Replication will appear to be kept more
      <quote>up to date.</quote></para>

      <para> (Of course, since there is no replicable activity going
      on, being <quote>more up to date</quote> is something of a
      mirage.) </para></listitem>

      </itemizedlist>

      <para>
      Default is 10000 ms and maximum is 120000 ms. By default, you
      can expect each node to <quote>report in</quote> with a
      <command>SYNC</command> every 10 seconds.
     </para>
     <para>
      Note that <command>SYNC</command> events are also generated on
      subscriber nodes.  Since they are not actually generating any
      data to replicate to other nodes, these <command>SYNC</command>
      events are of not terribly much value.
     </para>
    </listitem>
   </varlistentry>
   
   <varlistentry>
    <term><option>-g</option><replaceable class="parameter"> group size</replaceable></term>
    <listitem>
     <para>
      This controls the maximum <command>SYNC</command> group size,
      <envar>sync_group_maxsize</envar>; defaults to 20.  Thus, if a
      particular node is behind by 200 <command>SYNC</command>s, it
      will try to group them together into groups of a maximum size of
      <envar>sync_group_maxsize</envar>.  This can be expected to
      reduce transaction overhead due to having fewer transactions to
      <command>COMMIT</command>.
     </para>
     <para>
      The default of 20 is probably suitable for small systems that can
      devote only very limited bits of memory to
      <application>slon</application>.  If you have plenty of memory,
      it would be reasonable to increase this, as it will increase the
      amount of work done in each transaction, and will allow a
      subscriber that is behind by a lot to catch up more quickly.
     </para>
     <para>
      Slon processes usually stay pretty small; even with large value
      for this option, <application>slon</application> would be
      expected to only grow to a few MB in size.
     </para>
     <para>
      The big advantage in increasing this parameter comes from
      cutting down on the number of transaction
      <command>COMMIT</command>s; moving from 1 to 2 will provide
      considerable benefit, but the benefits will progressively fall
      off once the transactions being processed get to be reasonably
      large.  There isn't likely to be a material difference in
      performance between 80 and 90; at that point, whether
      <quote>bigger is better</quote> will depend on whether the
      bigger set of <command>SYNC</command>s makes the
      <envar>LOG</envar> cursor behave badly due to consuming more
      memory and requiring more time to sortt.
     </para>
     <para>
      In &slony1; version 1.0, <application>slon</application> will
      always attempt to group <command>SYNC</command>s together to
      this maximum, which <emphasis>won't</emphasis> be ideal if
      replication has been somewhat destabilized by there being very
      large updates (<emphasis>e.g.</emphasis> - a single transaction
      that updates hundreds of thousands of rows) or by
      <command>SYNC</command>s being disrupted on an origin node with
      the result that there are a few <command>SYNC</command>s that
      are very large.  You might run into the problem that grouping
      together some very large <command>SYNC</command>s knocks over a
      <application>slon</application> process.  When it picks up
      again, it will try to process the same large grouped set of
      <command>SYNC</command>s, and run into the same problem over and
      over until an administrator interrupts this and changes the
      <option>-g</option> value to break this <quote>deadlock.</quote>
     </para> 
     <para>
      In &slony1; version 1.1 and later versions, the <application>slon</application>
      instead adaptively <quote>ramps up</quote> from doing 1
      <command>SYNC</command> at a time towards the maximum group
      size.  As a result, if there are a couple of
      <command>SYNC</command>s that cause problems, the
      <application>slon</application> will (with any relevant watchdog
      assistance) always be able to get to the point where it
      processes the troublesome <command>SYNC</command>s one by one,
      hopefully making operator assistance unnecessary.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-o</option><replaceable class="parameter"> desired sync time</replaceable></term>
    <listitem><para> A <quote>maximum</quote> time planned for grouped <command>SYNC</command>s.</para>

     <para> If replication is running behind, slon will gradually
     increase the numbers of <command>SYNC</command>s grouped
     together, targeting that (based on the time taken for the
     <emphasis>last</emphasis> group of <command>SYNC</command>s) they
     shouldn't take more than the specified
     <envar>desired_sync_time</envar> value.</para>

     <para> The default value for <envar>desired_sync_time</envar> is
     60000ms, equal to one minute. </para>

     <para> That way, you can expect (or at least hope!) that you'll
      get a <command>COMMIT</command> roughly once per minute. </para>

     <para> It isn't <emphasis>totally</emphasis> predictable, as it
     is entirely possible for someone to request a <emphasis>very
     large update,</emphasis> all as one transaction, that can
     <quote>blow up</quote> the length of the resulting
     <command>SYNC</command> to be nearly arbitrarily long.  In such a
     case, the heuristic will back off for the
     <emphasis>next</emphasis> group.</para>

     <para> The overall effect is to improve
      <productname>Slony-I</productname>'s ability to cope with
      variations in traffic.  By starting with 1 <command>SYNC</command>, and gradually
      moving to more, even if there turn out to be variations large
      enough to cause <productname>PostgreSQL</productname> backends to
      crash, <productname>Slony-I</productname> will back off down to
      start with one sync at a time, if need be, so that if it is at
      all possible for replication to progress, it will.</para>
    </listitem>
   </varlistentry>      

   <varlistentry>
    <term><option>-c</option><replaceable class="parameter"> cleanup cycles</replaceable></term>
    <listitem>
     <para>
      The value <envar>vac_frequency</envar> indicates how often to
      <command>VACUUM</command> in cleanup cycles.
     </para>
     <para>
      Set this to zero to disable
      <application>slon</application>-initiated vacuuming. If you are
      using something like <application>pg_autovacuum</application> to
      initiate vacuums, you may not need for slon to initiate vacuums
      itself.  If you are not, there are some tables
      <productname>Slony-I</productname> uses that collect a
      <emphasis>lot</emphasis> of dead tuples that should be vacuumed
      frequently, notably &pglistener;.
     </para>

     <para> In &slony1; version 1.1, this changes a little; the
     cleanup thread tracks, from iteration to iteration, the earliest
     transaction ID still active in the system.  If this doesn't
     change, from one iteration to the next, then an old transaction
     is still active, and therefore a <command>VACUUM</command> will
     do no good.  The cleanup thread instead merely does an
     <command>ANALYZE</command> on these tables to update the
     statistics in <envar>pg_statistics</envar>.
     </para>
    </listitem>
   </varlistentry>
   
   <varlistentry>
    <term><option>-p</option><replaceable class="parameter"> PID filename</replaceable></term>
    <listitem>
     <para>
      <envar>pid_file</envar> contains the filename in which the PID
      (process ID) of the <application>slon</application> is stored.
     </para>

     <para>
      This may make it easier to construct scripts to monitor multiple
      <application>slon</application> processes running on a single
      host.
     </para>
    </listitem>
   </varlistentry>
   
   <varlistentry>
    <term><option>-f</option><replaceable class="parameter"> config file</replaceable></term>
    <listitem>
     <para>
      File from which to read <application>slon</application> configuration.
     </para>

     <para> This configuration is  discussed  further  in <link 
     linkend="runtime-config">Slon  Run-time Configuration</link>. If there are to be a complex set of
     configuration parameters, or if there are parameters you do not
     wish to be visible in the process environment variables (such as
     passwords), it may be convenient to draw many or all parameters
     from a configuration file.  You might either put common
     parameters for all slon processes in a commonly-used
     configuration file, allowing the command line to specify little
     other than the connection info.  Alternatively, you might create
     a configuration file for each node.</para>

    </listitem>
   </varlistentry>
   <varlistentry>
    <term><option>-a</option><replaceable class="parameter"> archive directory</replaceable></term>
    <listitem>
     <para>
      <envar>archive_dir</envar> indicates a directory in which to
      place a sequence of <command>SYNC</command> archive files for
      use in &logshiplink; mode.
     </para>
    </listitem>
   </varlistentry>


   <varlistentry>
    <term><option>-x</option><replaceable class="parameter"> command to run on log archive</replaceable></term>
    <listitem>
     <para>
      <envar>command_on_logarchive</envar> indicates a command to be run 
      each time a SYNC file is successfully generated.
     </para>

     <para> See more details on <xref linkend="slon-config-command-on-logarchive">.</para>
    </listitem>
   </varlistentry>


   <varlistentry>
    <term><option>-q</option><replaceable class="parameter"> quit based on SYNC provider </replaceable></term>
    <listitem>
     <para>
      <envar>quit_sync_provider</envar> indicates which provider's
      worker thread should be watched in order to terminate after a
      certain event.  This must be used in conjunction with the
      <option>-r</option> option below...
     </para>

     <para> This allows you to have a <application>slon</application>
     stop replicating after a certain point. </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-r</option><replaceable class="parameter"> quit at event number </replaceable></term>
    <listitem>
     <para>
      <envar>quit_sync_finalsync</envar> indicates the event number
      after which the remote worker thread for the provider above
      should terminate.  This must be used in conjunction with the
      <option>-q</option> option above...
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-l</option><replaceable class="parameter"> lag interval </replaceable></term>
    <listitem>
     <para>
      <envar>lag_interval</envar> indicates an interval value such as
      <command> 3 minutes </command> or <command> 4 hours </command>
      or <command> 2 days </command> that indicates that this node is
      to lag its providers by the specified interval of time.  This
      causes events to be ignored until they reach the age
      corresponding to the interval.
     </para>

     <warning><para> There is a concommittant downside to this lag;
     events that require all nodes to synchronize, as typically
     happens with <xref linkend="stmtfailover"> and <xref
     linkend="stmtmoveset">, will have to wait for this lagging
     node. </para>

     <para> That might not be ideal behaviour at failover time, or at
     the time when you want to run <xref
     linkend="stmtddlscript">. </para></warning>
    </listitem>
   </varlistentry>

  </variablelist>
 </refsect1>
 <refsect1>
  <title>Exit Status</title>
  <para>
   <application>slon</application> returns 0 to the shell if it
   finished normally.  It returns via <function>exit(-1)</function>
   (which will likely provide a return value of either 127 or 255,
   depending on your system) if it encounters any fatal error.
  </para>
 </refsect1>
</refentry>
<!-- 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:"slony.sgml"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->
