<article id="runtime-config">
  <title>Run-time Configuration</title>
<indexterm>
    <primary>configuration</primary>
    <secondary>of the slon daemon</secondary>
  </indexterm>

  <para>
    There are several configuration parameters that affect the
    behavior of the replication system.  In this section, we describe
    how to set the <application>slon</application> daemon's
    configuration parameters; the following subsections discuss each
    parameter in detail.
  </para>

  <para>
    All parameter names are case-insensitive. Every parameter takes a value of 
    one of four types: boolean, integer, floating point, or string.
    Boolean values may be written as <literal>ON</literal>, <literal>OFF</literal>,<literal>TRUE</literal>,
    <literal>FALSE</literal>, <literal>YES</literal>, <literal>NO</literal>, 
    <literal>1</literal>, <literal>0</literal> (all case-insensitive) or any 
    unambiguous prefix of these.
  </para>

  <para>
    One parameter is specified per line. The equal sign between name and 
    value is optional. Whitespace is insignificant and blank lines are
    ignored. Hash marks (<literal>#</literal>) introduce comments
    anywhere.  Parameter values that are not simple identifiers or
    numbers must be single-quoted.
  </para>

  <para>
    Some options may be set through the Command-line, these options
    override any conflicting settings in the configuration file.
  </para>



<sect1 id="slon-config-logging">
  <title>Logging</title>
<indexterm><primary>slon configuration: logging</primary></indexterm>

  <variablelist>
    <varlistentry id="slon-config-logging-syslog" xreflabel="slon_conf_syslog">
      <term><varname>syslog</varname> (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>syslog</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Sets up logging to syslog. If this parameter is 1, messages go both 
          to syslog and the standard output. A value of 2 sends output only to syslog 
          (some messages will still go to the standard output/error).  The default 
          is 0, which means syslog is off.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-logging-syslog-facility" xreflabel="slon_conf_syslog_facility">
      <term><varname>syslog_facility</varname> (<type>string</type>)</term>
      <indexterm>
        <primary><varname>syslog_facility</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Sets the syslog <quote>facility</quote> to be used when
        syslog enabled.  Valid values are LOCAL0, LOCAL1, LOCAL2,
        LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.  The default is
        LOCAL0.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-logging-syslog-ident" xreflabel="slon_conf_syslog_ident">
      <term><varname>syslog_ident</varname> (<type>string</type>)</term>
      <indexterm>
        <primary><varname>syslog_ident</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>
          Sets the program name used to identify slon messages in syslog. 
          The default is slon.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-logging-log-level" xreflabel="lon_conf_log_level">
      <term><varname>log_level</varname> (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>log_level</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Debug log level (higher value ==> more output).  Range: [0,4], default 0</para>

	<para> There are <link linkend="nineloglevels">nine log
	message types</link>; using this option, some or all of the
	<quote>debugging</quote> levels may be left out of the slon
	logs.  In &slony1; version 2, a lot of log message levels have
	been revised in an attempt to ensure the <quote>interesting
	stuff</quote> comes in at CONFIG/INFO levels, so that you
	could run at level 0, omitting all of the <quote>DEBUG</quote>
	messages, and still have meaningful contents in the
	logs. </para>

      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-logging-log-pid" xreflabel="slon_conf_log_pid">
      <term><varname>log_pid</varname> (<type>boolean</type>)</term>
      <indexterm>
        <primary><varname>log_pid</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Determins, if you would like the pid of the (parent) slon process to
          appear in each log line entry.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-logging-log-timestamp" xreflabel="slon_conf_log_timestamp">
      <term><varname>log_timestamp</varname> (<type>boolean</type>)</term>
      <indexterm>          
        <primary><varname>log_timestamp</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Determines if you would like the timestamp of the event being logged to 
          appear in each log line entry.
        </para>

        <para> Note that if <envar>syslog</envar> usage is configured,
        then this is ignored; it is assumed that
        <application>syslog</application> will be supplying
        timestamps, and timestamps are therefore suppressed.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-logging-log-timestamp-format" xreflabel="slon_conf_log_timestamp_format">
      <term><varname>log_timestamp_format</varname> (<type>string</type>)</term>
      <indexterm>          
        <primary><varname>explain_interval</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>An interval in seconds at which the remote worker thread will
		output the query, used to select log rows from the data provider, together
		with it's EXPLAIN query plan. The default value of 0 turns this feature off.
		The allowed range is 0 (off) to 86400 (once per day).
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-logging-explain-interval" xreflabel="slon_conf_explain_interval">
      <term><varname>explain_interval</varname> (<type>integer</type>)</term>
      <indexterm>          
        <primary><varname>log_timestamp_format</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>A <function>strftime()</function>-conformant format
        string for use if <envar>log_timestamp</envar> is enabled. The
        default is <quote>%Y-%m-%d %H:%M:%S %Z</quote>
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-logging-pid-file" xreflabel="slon_conf_log_pid_file">
      <term><varname>pid_file</varname> (<type>string</type>)</term>
      <indexterm>
        <primary><varname>pid_file</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Location and filename you would like for a file
        containing the Process ID of the slon process. The default is
        not defined in which case no file is written.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-monitor-interval" xreflabel="slon_conf_monitor_interval">
      <term><varname>monitor_interval</varname> (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>monitor_interval</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Indicates the number of milliseconds the monitoring thread waits to queue up status entries before dumping 
        such updates into the components table.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-monitor-threads" xreflabel="slon_conf_monitor_threads">
      <term><varname>monitor_threads</varname> (<type>bool</type>)</term>
      <indexterm>
        <primary><varname>monitor_threads</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Indicates whether or not the monitoring thread is to be
              run.  The default is to do so.
        </para>
      </listitem>
    </varlistentry>

  </variablelist>
</sect1>

<sect1 id="slon-config-connection">
  <title>Connection settings</title>
<indexterm><primary>slon configuration: connections</primary></indexterm>

  <variablelist>
    <varlistentry id="slon-config-connection-cluster-name" xreflabel="slon_conf_cluster_name">
      <term><varname>cluster_name</varname>  (<type>string</type>) </term>
      <indexterm>
        <primary><varname>cluster_name</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>
          Set the cluster name that this instance of
          <application>slon</application> is running against. The
          default is to read it off the command line.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-connection-conn-info" xreflabel="slon_conf_conn_info">
      <term><varname>conn_info</varname>  (<type>string</type>)</term>
      <indexterm>
        <primary><varname>conn_info</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>
          Set <application>slon</application>'s connection info;
          default is to read it off the command line.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-sql-on-connection" xreflabel="slon_conf_sql_on_connection">
      <term><varname>sql_on_connection</varname>  (<type>string</type>)</term>
      <indexterm>
        <primary><varname>sql_on_connection</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>
          Execute this SQL on each node at
          <application>slon</application> connect time. Useful to set
          logging levels, or to tune the planner/memory settings.  You
          can specify multiple statements by separating them with a ;
        </para>
      </listitem>
    </varlistentry>

	<varlistentry id="slon-config-keepalive" xreflabel="slon_conf_keepalive">
	  <term><varname>tcp_keepalive</varname> (<type>bool</type>) </term>
	 <indexterm> <primary><varname>tcp_keepalive</varname></primary></indexterm>
	  <listitem>
		<para>
		  Enables sending of TCP KEEP alive requests between slon and the
		  PostgreSQL backends. Defaults to true.
		  </para>
		</listitem>
	  </varlistentry>
		<varlistentry id="slon-config-keepalive-idle" xreflabel="slon_conf_keepalive_idle">
 <term><varname>tcp_keepalive_idle</varname> (<type>integer</type>) </term>
	 <indexterm> <primary><varname>tcp_keepalive_idle</varname></primary></indexterm>
	  <listitem>
		<para>
		 The number of seconds of idle activity after which a TCP KEEPALIVE
		 will be sent across the network.  The tcp_keepalive parameter
		 must be enabled for this to take effect.  The default value is 0
		 which means use the operating systems default. Setting this parameter
		 has no effect on Win32 systems.
		  </para>
		</listitem>
	  </varlistentry>

	<varlistentry id="slon-config-keepalive-count" xreflabel="slon_conf_keepalive_count">
	  <term><varname>tcp_keepalive_count</varname> (<type> integer</type>) </term>
	 <indexterm> <primary><varname>tcp_keepalive_count</varname></primary></indexterm>
	  <listitem>
		<para>
		 The number of keep alive requests to the server that need to be lost
		 before the connection is declared dead. tcp_keep_alive must be turned
		 on for this parameter to take effect.  The default value is 0
		 which means use the operating systems default.  Setting this parameter
		 has no effect on Win32 systems.
		  </para>
		</listitem>
	  </varlistentry>

	<varlistentry id="slon-config-keepalive-interval" xreflabel="slon_conf_keepalive_interval">
	  <term><varname>tcp_keepalive_interval</varname> (<type>integer</type>)</term>
	 <indexterm> <primary><varname>tcp_keepalive_interval</varname></primary></indexterm>
	  <listitem>
		<para>
		  The number of seconds between TCP keep alive requests. tcp_keepalive
		  must be enabled for this parameter to take effect.  The default 
		  value is 0 which means use the operating systems default. 
		  Setting this parameter has no effect on Win32 systems.
		  </para>
		</listitem>
	  </varlistentry>

  </variablelist>
</sect1>
<sect1 id="slon-archive-logging">
  <title> Archive Logging Options </title>
<indexterm><primary>slon configuration: log shipping</primary></indexterm>
  <variablelist>
    <varlistentry id="slon-config-archive-dir" xreflabel="slon_conf_archive_dir">
      <term><varname>archive_dir</varname> (<type>text</type>)</term>
      <indexterm>
        <primary><varname>archive_dir</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>This indicates in what directory sync archive files should be stored.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-command-on-logarchive" xreflabel="slon_conf_command_on_log_archive">
      <term><varname>command_on_logarchive</varname> (<type>text</type>)</term>
      <indexterm>
        <primary><varname>command_on_logarchive</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>This indicates a Unix command to be submitted each time
        an archive log is successfully generated.
        </para>

        <para> The command will be passed one parameter, namely the
        full pathname of the archive file.  Thus, supposing we have
        the settings...</para>

        <para>
        <command>command_on_logarchive = <filename>/usr/local/bin/logstuff</filename></command>
        </para>
        <para>
        <command>archive_dir = <filename>/var/log/slony1/archivelogs/payroll</filename></command>
        </para>

        <para> A typical log file might be named something like
        <filename>/var/log/slony1/archivelogs/payroll/slony1_log_1_00000000000000000036.sql</filename></para>

        <para> The command run after that SYNC was generated would be: </para>

        <para>
        <command><filename>/usr/local/bin/logstuff</filename> <filename>/var/log/slony1/archivelogs/payroll/slony1_log_1_00000000000000000036.sql</filename></command>
        </para>

        <warning> <para> Note that this is run via
        <function>system(const char *COMMAND)</function>; if the
        program that is run takes five minutes to run, that will defer
        the next <command>SYNC</command> by five minutes.  You
        probably don't want the archiving command to do much
        <quote>in-line</quote> work.</para></warning>

      </listitem>
    </varlistentry>
    
  </variablelist>
</sect1>
<sect1 id="slon-config-interval">
  <title>Event Tuning</title>
<indexterm><primary>slon configuration: event tuning</primary></indexterm>

  <variablelist>
    <varlistentry id="slon-config-sync-interval" xreflabel="slon_conf_sync_interval">
      <term><varname>sync_interval</varname> (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>sync_interval</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Check for updates at least this often in milliseconds. 
          Range: [10-60000], default 100
        </para>

        <para> This parameter is primarily of concern on nodes that
          originate replication sets.  On a non-origin node, there
          will never be update activity that would induce a SYNC;
          instead, the timeout value described below will induce a
          SYNC every so often <emphasis>despite absence of changes to
          replicate.</emphasis> </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-sync-interval-timeout" xreflabel="slon_conf_sync_interval_timeout">
      <term><varname>sync_interval_timeout</varname> (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>sync_interval_timeout</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>
          Maximum amount of time in milliseconds before issuing a
          <command>SYNC</command> event, This prevents a possible race
          condition in which the action sequence is bumped by the
          trigger while inserting the log row, which makes this bump
          is immediately visible to the sync thread, but the resulting
          log rows are not visible yet.  If the
          <command>SYNC</command> is picked up by the subscriber,
          processed and finished before the transaction commits, this
          transaction's changes will not be replicated until the next
          <command>SYNC</command>.  But if all application activity
          suddenly stops, there will be no more sequence bumps, so the
          high frequent <option>-s</option> check won't detect that.
          Thus, the need for
          <envar>sync_interval_timeout</envar>. Range: [0-120000],
          default 1000
        </para>

        <para> This parameter is likely to be primarily of concern on
          nodes that originate replication sets, though it does affect
          how often events are generated on other nodes.</para>

	<para>
          On a non-origin node, there never is activity to cause a
          SYNC to get generated; as a result, there will be a SYNC
          generated every <envar>sync_interval_timeout</envar>
          milliseconds.  There are no subscribers looking for those
          SYNCs, so these events do not lead to any replication
          activity.  They will, however, clutter sl_event up a little,
          so it would be undesirable for this timeout value to be set
          too terribly low.  120000ms represents 2 minutes, which is
          not a terrible value.
        </para>

	<para> The two values function together in varying ways: </para>

	<para> On an origin node, <envar>sync_interval</envar> is
	the <emphasis>minimum</emphasis> time period that will be
	covered by a SYNC, and during periods of heavy application
	activity, it may be that a SYNC is being generated
	every <envar>sync_interval</envar> milliseconds. </para>

	<para> On that same origin node, there may be quiet intervals,
	when no replicatable changes are being submitted.  A SYNC will
	be induced, anyways,
	every <envar>sync_interval_timeout</envar>
	milliseconds. </para>

	<para> On a subscriber node that does not originate any sets,
	only the <quote>timeout-induced</quote> SYNCs will
	occur.  </para>

      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-sync-group-maxsize" xreflabel="slon_conf_sync_group_maxsize">
      <term><varname>sync_group_maxsize</varname> (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>sync_group_maxsize</varname> configuration parameter</primary>
      </indexterm>
      <listitem>

        <para>
          Maximum number of <command>SYNC</command> events that a
          subscriber node will group together when/if a subscriber
          falls behind.  <command>SYNC</command>s are batched only if
          there are that many available and if they are
          contiguous.  Every other event type in between leads to a
          smaller batch.  And if there is only
          one <command>SYNC</command> available, even though you used
          <option>-g600</option>, the &lslon; will apply just the one
          that is available.  As soon as a subscriber catches up, it
          will tend to apply each
          <command>SYNC</command> by itself, as a singleton, unless
          processing should fall behind for some reason.  Range:
          [0,10000], default: 20
        </para>

      </listitem>
    </varlistentry>
    
    <varlistentry id="slon-config-vac-frequency" xreflabel="slon_conf_vac_frequency">
      <term><varname>vac_frequency</varname> (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>vac_frequency</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>
          Sets how many cleanup cycles to run before a vacuum is done.
          0 disables the builtin vacuum, intended to be used with the
          <application>pg_autovacuum</application> daemon.  Range:
          [0,100], default: 3
        </para>
      </listitem>
    </varlistentry>


    <varlistentry id="slon-config-cleanup-interval" xreflabel="slon_config_cleanup_interval">
      <term><varname>cleanup_interval</varname> (<type>interval</type>)</term>
      <indexterm>
        <primary><varname>cleanup_interval</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>
          Controls how quickly old events are trimmed out.  That
          subsequently controls when the data in the log tables,
          <envar>sl_log_1</envar> and <envar>sl_log_2</envar>, get
          trimmed out.  Default: '10 minutes'.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-cleanup-deletelogs" xreflabel="slon_conf_cleanup_deletelogs">
      <term><varname>cleanup_deletelogs</varname> (<type>boolean</type>)</term>
      <indexterm>
        <primary><varname>cleanup_deletelogs</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>
          Controls whether or not we use DELETE to trim old data from the log tables,
          <envar>sl_log_1</envar> and <envar>sl_log_2</envar>.
          Default: false
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-desired-sync-time" xreflabel="desired_sync_time">
      <term><varname>desired_sync_time</varname>  (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>desired_sync_time</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Maximum time planned for grouped
        <command>SYNC</command>s. If replication is behind,
        <application>slon</application> will try to increase numbers
        of syncs done targeting that they should take this quantity
        of time to process.  This is in Range [10000,600000] ms,
        default 60000. </para> 

	<para>If the value is set to 0, this logic will be ignored.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-quit-sync-provider" xreflabel="quit_sync_provider">
      <term><varname>quit_sync_provider</varname>  (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>quit_sync_provider</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para> This must be used in conjunction with <xref linkend="slon-config-quit-sync-finalsync">, and indicates
        which provider node's worker thread should be watched to see
        if the slon should terminate due to reaching some desired
        <quote>final</quote> event number.</para>

	<para>If the value is set to 0, this logic will be ignored.</para>
      </listitem>
    </varlistentry>
    <varlistentry id="slon-config-quit-sync-finalsync" xreflabel="quit_sync_finalsync">
      <term><varname>quit_sync_finalsync</varname>  (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>quit_sync_finalsync</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Final event number to process.  This must be used in
        conjunction with <xref linkend="slon-config-quit-sync-finalsync">, and
        allows the <application>slon</application> to terminate itself
        once it reaches a certain event for the specified
        provider. </para>

	<para>If the value is set to 0, this logic will be ignored.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-lag-interval" xreflabel="lag_interval">
      <term><varname>lag_interval</varname>  (<type>string/interval</type>)</term>
      <indexterm>
        <primary><varname>lag_interval</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Indicates an interval by which this node should lag its
        providers.  If set, this is used in the event processing loop
        to modify what events are to be considered for queueing; those
        events newer than <command> now() - lag_interval::interval
        </command> are left out, to be processed later.  </para>

	<para>If the value is left empty, this logic will be ignored.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-max-rowsize" xreflabel="sync_max_rowsize">
      <term><varname>sync_max_rowsize</varname>  (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>sync_max_rowsize</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Size above which an sl_log_?  row's
        <envar>log_cmddata</envar> is considered large.  Up to 500
        rows of this size are allowed in memory at once. Rows larger
        than that count into the <envar>sync_max_largemem</envar>
        space allocated and <function>free()</function>'ed on demand.
        </para>

	<para>The default value is 8192, meaning that your expected
	memory consumption (for the LOG cursor) should not exceed 8MB.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry id="slon-config-max-largemem" xreflabel="sync_max_largemem">
      <term><varname>sync_max_largemem</varname>  (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>sync_max_largemem</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>Maximum memory allocated for large rows, where
        <envar>log_cmddata</envar> are larger than
        <envar>sync_max_rowsize</envar>.  </para>

	<para>Note that the algorithm reads rows until
	<emphasis>after</emphasis> this value is exceeded.  Otherwise,
	a tuple larger than this value would stall replication.  As a
	result, don't assume that memory consumption will remain
	smaller than this value.
        </para>

        <para> The default value is 5242880.</para>
      </listitem>
    </varlistentry>
    <varlistentry id="slon-config-remote-listen-timeout" xreflabel="slon_conf_remote_listen_timeout">
      <term><varname>remote_listen_timeout</varname> (<type>integer</type>)</term>
      <indexterm>
        <primary><varname>remote_listen_timeout</varname> configuration parameter</primary>
      </indexterm>
      <listitem>
        <para>How long, in milliseconds, should the remote listener wait before treating the event selection criteria as having timed out?
          Range: [30-30000], default 300ms
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
</sect1>

</article  


<!-- 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:
-->
