path: root/ctdb/doc/ctdb-script.options.5.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry
	PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<refentry id="ctdb-script.options.5">

  <refmeta>
    <refentrytitle>ctdb-script.options</refentrytitle>
    <manvolnum>5</manvolnum>
    <refmiscinfo class="source">ctdb</refmiscinfo>
    <refmiscinfo class="manual">CTDB - clustered TDB database</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>ctdb-script.options</refname>
    <refpurpose>CTDB scripts configuration files</refpurpose>
  </refnamediv>

  <refsect1>
    <title>DESCRIPTION</title>

    <refsect2>
      <title>Location</title>
      <para>
	Each CTDB script has 2 possible locations for its configuration options:
      </para>

      <variablelist>

	<varlistentry>
	  <term>
	    <filename>/usr/local/etc/ctdb/script.options</filename>
	  </term>
	  <listitem>
	    <para>
	      This is a catch-all global file for general purpose
	      scripts and for options that are used in multiple event
	      scripts.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    <parameter>SCRIPT</parameter>.options
	  </term>
	  <listitem>
	    <para>
	      That is, options for
	      <filename><parameter>SCRIPT</parameter></filename> are
	      placed in a file alongside the script, with a ".script"
	      suffix added.  This style is usually recommended for event
	      scripts.
	    </para>

	    <para>
	      Options in this script-specific file override those in
	      the global file.
	    </para>
	  </listitem>
	</varlistentry>

      </variablelist>
    </refsect2>

    <refsect2>
      <title>Contents</title>

      <para>
	These files should include simple shell-style variable
	assignments and shell-style comments.
      </para>
    </refsect2>

    <refsect2>
      <title>Monitoring Thresholds</title>

      <para>
	Event scripts can monitor resources or services.  When a
	problem is detected, it may be better to warn about a problem
	rather than to immediately fail monitoring and mark a node as
	unhealthy.  CTDB provides support for event scripts to do
	threshold-based monitoring.
      </para>

      <para>
	A threshold setting looks like
	<parameter>WARNING_THRESHOLD<optional>:ERROR_THRESHOLD</optional></parameter>.
	If the number of problems is ≥ WARNING_THRESHOLD then the
	script will log a warning and continue.  If the number
	problems is ≥ ERROR_THRESHOLD then the script will log an
	error and exit with failure, causing monitoring to fail.  Note
	that ERROR_THRESHOLD is optional, and follows the optional
	colon (:) separator.
      </para>
    </refsect2>

  </refsect1>

  <refsect1>
    <title>NETWORK CONFIGURATION</title>

    <refsect2>
      <title>10.interface</title>

      <para>
	This event script handles public IP address release and
	takeover, as well as monitoring interfaces used by public IP
	addresses.
      </para>

      <variablelist>

	<varlistentry>
	  <term>
	    CTDB_KILLTCP_USE_SS_KILL=yes|try|no
	  </term>
	  <listitem>
	    <para>
	      Whether to use <command>ss -K/--kill</command> to reset
	      incoming TCP connections to public IP addresses during
	      <command>releaseip</command>.
	    </para>

	    <para>
	      CTDB's standard method of resetting incoming TCP
	      connections during <command>releaseip</command> is via
	      its custom <command>ctdb_killtcp</command> command.
	      This uses network trickery to reset each connection:
	      send a "tickle ACK", capture the reply to extract the
	      TCP sequence number, send a reset (containing the
	      correct sequence number).
	    </para>

	    <para>
	      <command>ss -K</command> has been supported in
	      <command>ss</command> since iproute 4.5 in March 2016
	      and in the Linux kernel since 4.4 in December 2015.
	      However, the required kernel configuration item
	      <code>CONFIG_INET_DIAG_DESTROY</code> is disabled by
	      default.  Although enabled in Debian kernels since ~2017
	      and in Ubuntu since at least 18.04, this has only
	      recently been enabled in distributions such as RHEL.
	      There seems to be no way, including running <command>ss
	      -K</command>, to determine if this is supported, so use
	      of this feature needs to be configurable.  When
	      available, it should be the fastest, most reliable way
	      of killing connections.
	    </para>

	    <para>
	      Supported values are:
	      <variablelist>
		<varlistentry>
		  <term>
		    yes
		  </term>
		  <listitem>
		    <para>
		      Use <command>ss -K</command> and make no other
		      attempt to kill any remaining connections.  This
		      is sane on modern Linux distributions that are
		      guaranteed to have
		      <code>CONFIG_INET_DIAG_DESTROY</code> enabled.
		    </para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>
		    try
		  </term>
		  <listitem>
		    <para>
		      Attempt to use <command>ss -K</command> and fall
		      back to <command>ctdb_killtcp</command> for any
		      remaining connections.  This may be a good value
		      when <command>ss</command> supports the
		      <command>-K</command> option but it is uncertain
		      whether <code>CONFIG_INET_DIAG_DESTROY</code> is
		      enabled.
		    </para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term>
		    no
		  </term>
		  <listitem>
		    <para>
		      Never attempt to use <command>ss -K</command>.
		      Rely only on <command>ctdb_killtcp</command>.
		    </para>
		  </listitem>
		</varlistentry>
	      </variablelist>
	      Default is "no".
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
	    CTDB_PARTIALLY_ONLINE_INTERFACES=yes|no
	  </term>
	  <listitem>
	    <para>
	      Whether one or more offline interfaces should cause a
	      monitor event to fail if there are other interfaces that
	      are up.  If this is "yes" and a node has some interfaces
	      that are down then <command>ctdb status</command> will
	      display the node as "PARTIALLYONLINE".
	    </para>

	    <para>
	      Note that CTDB_PARTIALLY_ONLINE_INTERFACES=yes is not
	      generally compatible with NAT gateway or LVS.  NAT
	      gateway relies on the interface configured by
	      CTDB_NATGW_PUBLIC_IFACE to be up and LVS replies on
	      CTDB_LVS_PUBLIC_IFACE to be up.  CTDB does not check if
	      these options are set in an incompatible way so care is
	      needed to understand the interaction.
	    </para>

	    <para>
	      Default is "no".
	    </para>
	  </listitem>
	</varlistentry>

      </variablelist>
    </refsect2>

    <refsect2>
      <title>11.natgw</title>

      <para>
	Provides CTDB's NAT gateway functionality.
      </para>

      <para>
	NAT gateway is used to configure fallback routing for nodes
	when they do not host any public IP addresses.  For example,
	it allows unhealthy nodes to reliably communicate with
	external infrastructure.  One node in a NAT gateway group will
	be designated as the NAT gateway leader node and other (follower)
	nodes will be configured with fallback routes via the NAT
	gateway leader node.  For more information, see the
	<citetitle>NAT GATEWAY</citetitle> section in
	<citerefentry><refentrytitle>ctdb</refentrytitle>
	<manvolnum>7</manvolnum></citerefentry>.
      </para>

      <variablelist>

	<varlistentry>
	  <term>CTDB_NATGW_DEFAULT_GATEWAY=<parameter>IPADDR</parameter></term>
	  <listitem>
	    <para>
	      IPADDR is an alternate network gateway to use on the NAT
	      gateway leader node.  If set, a fallback default route
	      is added via this network gateway.
	    </para>
	    <para>
	      No default.  Setting this variable is optional - if not
	      set that no route is created on the NAT gateway leader
	      node.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>CTDB_NATGW_NODES=<parameter>FILENAME</parameter></term>
	  <listitem>
	    <para>
	      FILENAME contains the list of nodes that belong to the
	      same NAT gateway group.
	    </para>
	    <para>
	      File format:
	      <screen>
<parameter>IPADDR</parameter> <optional>follower-only</optional>
	      </screen>
	    </para>
	    <para>
	      IPADDR is the private IP address of each node in the NAT
	      gateway group.
	    </para>
	    <para>
	      If "follower-only" is specified then the corresponding node
	      can not be the NAT gateway leader node.  In this case
	      <varname>CTDB_NATGW_PUBLIC_IFACE</varname> and
	      <varname>CTDB_NATGW_PUBLIC_IP</varname> are optional and
	      unused.
	    </para>
	    <para>
	      No default, usually
	      <filename>/usr/local/etc/ctdb/natgw_nodes</filename> when enabled.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>CTDB_NATGW_PRIVATE_NETWORK=<parameter>IPADDR/MASK</parameter></term>
	  <listitem>
	    <para>
	      IPADDR/MASK is the private sub-network that is
	      internally routed via the NAT gateway leader node.  This
	      is usually the private network that is used for node
	      addresses.
	    </para>
	    <para>
	      No default.
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>CTDB_NATGW_PUBL