path: root/ctdb/doc/ctdbd.1.xml

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

<refentry id="ctdbd.1">

  <refmeta>
    <refentrytitle>ctdbd</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source">ctdb</refmiscinfo>
    <refmiscinfo class="manual">CTDB - clustered TDB database</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>ctdbd</refname>
    <refpurpose>The CTDB cluster daemon</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>ctdbd</command>
      <arg rep="repeat"><replaceable>OPTION</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>
      ctdbd is the main CTDB daemon.
    </para>

    <para>
      Note that ctdbd is not usually invoked directly.  It is invoked
      via <citerefentry><refentrytitle>ctdbd_wrapper</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry> or via the initscript.
    </para>

    <para>
      See <citerefentry><refentrytitle>ctdb</refentrytitle>
      <manvolnum>7</manvolnum></citerefentry> for an overview of CTDB.
    </para>
  </refsect1>

  <refsect1>
    <title>GENERAL OPTIONS</title>

    <variablelist>
      <varlistentry>
	<term>-d, --debug=<parameter>DEBUGLEVEL</parameter></term>
	<listitem>
	  <para>
	    This option sets the debug level to DEBUGLEVEL, which
	    controls what will be written by the logging
	    subsystem. The default is 0 which will only log important
	    events and errors. A larger number will provide additional
	    logging.
	  </para>
	  <para>
	    See the <citetitle>DEBUG LEVELS</citetitle> section in
	    <citerefentry><refentrytitle>ctdb</refentrytitle>
	    <manvolnum>7</manvolnum></citerefentry> for more
	    information.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--dbdir=<parameter>DIRECTORY</parameter></term>
	<listitem>
	  <para>
	    DIRECTORY on local storage where ctdbd keeps a local copy of
	    TDB databases.  This directory is local for each node and
	    should not be stored on the shared cluster filesystem.
	  </para>
	  <para>
	    This directory would usually be <filename>/var/lib/ctdb</filename>
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--dbdir-persistent=<parameter>DIRECTORY</parameter></term>
	<listitem>
	  <para>
	    DIRECTORY on local storage where ctdbd keeps a local copy of
	    persistent TDB databases.  This directory is local for each
	    node and should not be stored on the shared cluster
	    filesystem.
	  </para>
	  <para>
	    This directory would usually be
	    <filename>/var/lib/ctdb/persistent</filename>
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--dbdir-state=<parameter>DIRECTORY</parameter></term>
	<listitem>
	  <para>
	    DIRECTORY on local storage where ctdbd keep internal state
	    TDB files.  This directory is local for each node and
	    should not be stored on the shared cluster filesystem.
	  </para>
	  <para>
	    This directory would usually be
	    <filename>/var/lib/ctdb/state</filename>
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--event-script-dir=<parameter>DIRECTORY</parameter></term>
	<listitem>
	  <para>
	    DIRECTORY where the CTDB event scripts are stored.  See the
	    <citetitle>EVENT SCRIPTS</citetitle> section in
	    <citerefentry><refentrytitle>ctdb</refentrytitle>
	    <manvolnum>7</manvolnum></citerefentry> for more information.
	  </para>
	  <para>
	    Default is <envar>CTDB_BASE</envar>/events.d, so usually
	    <filename>/etc/ctdb/events.d</filename>, which is part of
	    the CTDB installation.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--logging=<parameter>STRING</parameter></term>
	<listitem>
	  <para>
	    STRING specifies where ctdbd will write its log. The
	    default is file:<filename>/var/log/log.ctdb</filename> or
	    similar - the prefix may differ depending on how CTDB was
	    built.
	  </para>
	  <para>
	    Valid values are:
	  </para>
	  <variablelist>
	    <varlistentry>
	      <term>file:<parameter>FILENAME</parameter></term>
	      <listitem>
		<para>
		  FILENAME where ctdbd will write its log. This is usually
		  <filename>/var/log/log.ctdb</filename>.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>syslog<optional>:<parameter>METHOD</parameter></optional></term>
              <listitem>
                <para>
		  CTDB will log to syslog.  By default this will use
		  the syslog(3) API.
                </para>
		<para>
		  Under heavy loads syslog(3) can block if the syslog
		  daemon processes messages too slowly.  This can
		  cause CTDB to block when logging.
		</para>
		<para>
		  If METHOD is specified then it specifies an
		  extension that causes logging to be done in a
		  non-blocking mode.  Note that <emphasis>this may
		  cause messages to be dropped</emphasis>.  METHOD
		  must be one of:
		</para>
		<variablelist>
		  <varlistentry>
		    <term>nonblocking</term>
		    <listitem>
		      <para>
			CTDB will log to syslog via
			<filename>/dev/log</filename> in non-blocking
			mode.
		      </para>
		    </listitem>
		  </varlistentry>
		</variablelist>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--lvs</term>
	<listitem>
	  <para>
	    This option is used to activate the LVS capability on a CTDB
	    node.  Please see the <citetitle>LVS</citetitle> section in
	    <citerefentry><refentrytitle>ctdb</refentrytitle>
	    <manvolnum>7</manvolnum></citerefentry> for more
	    information.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--max-persistent-check-errors=<parameter>NUM</parameter></term>
	<listitem>
	  <para>
	    NUM specifies the maximum number of health check failures
	    allowed for persistent databases during startup.
	  </para>
	  <para>
	    The default value is 0.  Setting this to non-zero allows a
	    node with unhealthy persistent databases to startup and
	    join the cluster as long as there is another node with
	    healthy persistent databases.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--nlist=<parameter>FILENAME</parameter></term>
	<listitem>
	  <para>
	    FILENAME containing a list of the private IP addresses, one
	    per line, for each node in the cluster.  This file
	    <emphasis>must be the same on each node</emphasis> in the
	    cluster.
	  </para>
	  <para>
	    Default is <envar>CTDB_BASE</envar>/nodes, so usually
	    <filename>/etc/ctdb/nodes</filename>.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--no-lmaster</term>
	<listitem>
	  <para>
	    This argument specifies that this node can NOT become an lmaster
	    for records in the database. This means that it will never show up
	    in the vnnmap. This feature is primarily used for making a cluster
	    span across a WAN link and use CTDB as a WAN-accelerator.
	  </para>
	  <para>
	    Please see the <citetitle>REMOTE CLUSTER NODES</citetitle>
	    section in <citerefentry><refentrytitle>ctdb</refentrytitle>
	    <manvolnum>7</manvolnum></citerefentry> for more
	    information.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--no-recmaster</term>
	<listitem>
	  <para>
	    This argument specifies that this node can NOT become a recmaster
	    for the database. This feature is primarily used for making a cluster
	    span across a WAN link and use CTDB as a WAN-accelerator.
	  </para>
	  <para>
	    Please see the <citetitle>REMOTE CLUSTER NODES</citetitle>
	    section in <citerefentry><refentrytitle>ctdb</refentrytitle>
	    <manvolnum>7</manvolnum></citerefentry> for more
	    information.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--notification-script=<parameter>FILENAME</parameter></term>
	<listitem>
	  <para>
	    FILENAME specifying a script to be invoked by ctdbd when
	    certain state changes occur.
	  </para>
	  <para>
	    This file is usually
	    <filename>/etc/ctdb/notify.sh</filename>.
	  </para>
	  <para>
	    Please see the <citetitle>NOTIFICATION SCRIPT</citetitle>
	    section in <citerefentry><refentrytitle>ctdb</refentrytitle>
	    <manvolnum>7</manvolnum></citerefentry> for more
	    information.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--pidfile=<parameter>FILENAME</parameter></term>
	<listitem>
	  <para>
	    FILENAME for file containing process ID of main CTDB
	    daemon.  This file is automatically created and removed by
	    CTDB.
	  </para>
	  <para>
	    The default is to not create a PID file.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--public_addresses=<parameter>FILENAME</parameter></term>
	<listitem>
	  <para>
	    FILENAME specifying a file containing the public IP
	    addresses to use on the cluster when CTDB should use IP
	    takeover. This file contains a list of IP addresses,
	    netmasks and interfaces.  CTDB will distribute these public
	    IP addresses appropriately across the available nodes.
	  </para>
	  <para>
	    The IP addresses specified in this file can differ across
	    nodes.
	  </para>
	  <para>
	    This is usually the file
	    <filename>/etc/ctdb/public_addresses</filename>
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--public-interface=<parameter>INTERFACE</parameter></term>
	<listitem>
	  <para>
	    INTERFACE on which to attach public IP addresses or on which
	    to attach the single-public-ip when used.
	  </para>
	  <para>
	    When using public IP addresses, this is only required if
	    interfaces are not explicitly specified in the public
	    addresses file.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--reclock=<parameter>FILENAME</parameter></term>
	<listitem>
	  <para>
	    FILENAME is the name of the recovery lock file stored in
	    <emphasis>shared storage</emphasis> that ctdbd uses to
	    prevent split brains from occuring.
	  </para>
	  <para>
	    It is possible to run CTDB without a recovery lock file, but
	    then there will be no protection against split brain if the
	    cluster/network becomes partitioned. Using CTDB without a
	    reclock file is strongly discouraged.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--single-public-ip=<parameter>IPADDR</parameter></term>
	<listitem>
	  <para>
	    IPADDR specifies the single IP that CTDB will use in
	    conjuction with LVS.
	  </para>
	  <para>
	    Please see the <citetitle>LVS</citetitle> section in
	    <citerefentry><refentrytitle>ctdb</refentrytitle>
	    <manvolnum>7</manvolnum></citerefentry> for more
	    information.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--start-as-disabled</term>
	<listitem>
	  <para>
	    This makes ctdbd start in the DISABLED state.
	  </para>
	  <para>
	    To allow the node to host public IP addresses and
	    services, it must be manually enabled using the
	    <command>ctdb enable</command> command.
	  </para>
	  <para>
	    Please see the <citetitle>NODE STATES</citetitle> section
	    in <citerefentry><refentrytitle>ctdb</refentrytitle>
	    <manvolnum>7</manvolnum></citerefentry> for more
	    information about the DISABLED state.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--start-as-stopped</term>
	<listitem>
	  <para>
	    This makes ctdbd start in the STOPPED state.
	  </para>
	  <para>
	    To allow the node to take part in the cluster it must be
	    manually continued with the the <command>ctdb
	    enable</command> command.
	  </para>
	  <para>
	    Please see the <citetitle>NODE STATES</citetitle> section
	    in <citerefentry><refentrytitle>ctdb</refentrytitle>
	    <manvolnum>7</manvolnum></citerefentry> for more
	    information about the STOPPED state.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--syslog</term>
	<listitem>
	  <para>
	    Send log messages to syslog instead of the CTDB logfile.
	    This option overrides --logfile.  The default is to log to
	    a file.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--transport=tcp|infiniband</term>
	<listitem>
	  <para>
	    This option specifies which transport to use for ctdbd
	    internode communications. The default is "tcp".
	  </para>
	  <para>
	    The "infiniband" support is not regularly tested.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>-?, --help</term>
	<listitem>
	  <para>
	    Display a summary of options.
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>DEBUGGING OPTIONS</title>

    <variablelist>

      <varlistentry>
	<term>-i, --interactive</term>
	<listitem>
	  <para>
	    Enable interactive mode.  This will make ctdbd run in the
	    foreground and not detach from the terminal.  By default
	    ctdbd will detach itself and run in the background as a
	    daemon.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--listen=<parameter>IPADDR</parameter></term>
	<listitem>
	  <para>
	    This specifies which IP address that ctdbd will bind to.
	  </para>
	  <para>
	    By default ctdbd will bind to the first address it finds in
	    the <filename>/etc/ctdb/nodes</filename> file that is also
	    present on the local system.
	  </para>
	  <para>
	    This option is only required when you want to run multiple
	    ctdbd daemons/nodes on the same physical host in which case
	    there would be multiple entries in
	    <filename>/etc/ctdb/nodes</filename> that would match a
	    local interface.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--nopublicipcheck</term>
	<listitem>
	  <para>
	    This option is used when testing with multiple local
	    daemons on a single machine.  It disables checks related
	    to public IP addresses.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--nosetsched</term>
	<listitem>
	  <para>
	    This is a debugging option. This option is only used when
	    debugging ctdbd.
	  </para>
	  <para>
	    Normally ctdbd will change its scheduler to run as a
	    real-time process. This is the default mode for a normal
	    ctdbd operation to gurarantee that ctdbd always gets the CPU
	    cycles that it needs.
	  </para>
	  <para>
	    This option is used to tell ctdbd to
	    <emphasis>not</emphasis> run as a real-time process and
	    instead run ctdbd as a normal userspace process.  This is
	    useful for debugging and when you want to run ctdbd under
	    valgrind or gdb. (You don't want to attach valgrind or gdb
	    to a real-time process.)
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--socket=<parameter>FILENAME</parameter></term>
	<listitem>
	  <para>
	    FILENAME specifies the name of the Unix domain socket that
	    ctdbd will create. This socket is used by local clients to
	    communicate with ctdbd.
	  </para>
	  <para>
	    The default is <filename>/tmp/ctdb.socket</filename> . You
	    only need to use this option if you plan to run multiple
	    ctdbd daemons on the same physical host, usually for
	    testing.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--script-log-level=<parameter>DEBUGLEVEL</parameter></term>
	<listitem>
	  <para>
	    This option sets the debug level of event script output to
	    DEBUGLEVEL.  The default is ERR (0).
	  </para>
	  <para>
	    See the <citetitle>DEBUG LEVELS</citetitle> section in
	    <citerefentry><refentrytitle>ctdb</refentrytitle>
	    <manvolnum>7</manvolnum></citerefentry> for more
	    information.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--sloppy-start</term>
	<listitem>
	  <para>
	    This is debugging option.  This speeds up the initial
	    recovery during startup at the expense of some consistency
	    checking.  <emphasis>Don't use this option in
	    production</emphasis>.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--torture</term>
	<listitem>
	  <para>
	    This option is only used for development and testing of
	    CTDB.  It adds artificial errors and failures to the
	    common codepaths in ctdbd to verify that ctdbd can recover
	    correctly from failures.
	  </para>
	  <para>
	    <emphasis>Do not use this option</emphasis> unless you are
	    developing and testing new functionality in CTDB.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>--valgrinding</term>
	<listitem>
	  <para>
	    This is a debugging option. This option is only used when
	    debugging ctdbd.  This enables additional debugging
	    capabilities and implies --nosetsched.
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry><refentrytitle>ctdb</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>ctdbd_wrapper</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>onnode</refentrytitle>
      <manvolnum>1</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>ctdb</refentrytitle>
      <manvolnum>7</manvolnum></citerefentry>,

      <citerefentry><refentrytitle>ctdb-tunables</refentrytitle>
      <manvolnum>7</manvolnum></citerefentry>,

      <ulink url="http://ctdb.samba.org/"/>
    </para>
  </refsect1>

  <refentryinfo>
    <author>
      <contrib>
	This documentation was written by
	Ronnie Sahlberg,
	Amitay Isaacs,
	Martin Schwenke
      </contrib>
    </author>

    <copyright>
      <year>2007</year>
      <holder>Andrew Tridgell</holder>
      <holder>Ronnie Sahlberg</holder>
    </copyright>
    <legalnotice>
      <para>
	This program is free software; you can redistribute it and/or
	modify it under the terms of the GNU General Public License as
	published by the Free Software Foundation; either version 3 of
	the License, or (at your option) any later version.
      </para>
      <para>
	This program is distributed in the hope that it will be
	useful, but WITHOUT ANY WARRANTY; without even the implied
	warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
	PURPOSE.  See the GNU General Public License for more details.
      </para>
      <para>
	You should have received a copy of the GNU General Public
	License along with this program; if not, see
	<ulink url="http://www.gnu.org/licenses"/>.
      </para>
    </legalnotice>
  </refentryinfo>

</refentry>