ctdb-docs: Document system options and resource controls

The existing configuration file is disappearing so these configuration
options need a new home that is not handled by ctdbd_wrapper.

Signed-off-by: Martin Schwenke <martin@meltin.net>
Reviewed-by: Amitay Isaacs <amitay@gmail.com>

diff --git a/ctdb/doc/ctdb.7.xml b/ctdb/doc/ctdb.7.xml
index 7de9455d5e8aac359ffdf10da51938b4c008a1dd..9e56aa5506f3bfd7312fc533ea719d53c493aaf1 100644 (file)
--- a/ctdb/doc/ctdb.7.xml
+++ b/ctdb/doc/ctdb.7.xml
@@ -1080,6 +1080,9 @@ CTDB_CAPABILITY_RECMASTER=no
       <citerefentry><refentrytitle>ctdb-script.options</refentrytitle>
       <manvolnum>5</manvolnum></citerefentry>,
 
+      <citerefentry><refentrytitle>ctdb.sysconfig</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry>,
+
       <citerefentry><refentrytitle>ctdb-statistics</refentrytitle>
       <manvolnum>7</manvolnum></citerefentry>,
 

diff --git a/ctdb/doc/ctdb.sysconfig.5.xml b/ctdb/doc/ctdb.sysconfig.5.xml
new file mode 100644 (file)
index 0000000..a7e5d49
--- /dev/null
+++ b/ctdb/doc/ctdb.sysconfig.5.xml
@@ -0,0 +1,258 @@
+<?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="ctdb.sysconfig.5">
+
+  <refmeta>
+    <refentrytitle>ctdb.sysconfig</refentrytitle>
+    <manvolnum>5</manvolnum>
+    <refmiscinfo class="source">ctdb</refmiscinfo>
+    <refmiscinfo class="manual">CTDB - clustered TDB database</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>ctdb.sysconfig</refname>
+    <refpurpose>CTDB daemon configuration file</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>DESCRIPTION</title>
+
+    <para>
+      This file contains configuration that affects the operation of
+      CTDB.  This is a distribution-specific service configuration
+      file such as <filename>/etc/sysconfig/ctdb</filename> (Red Hat)
+      or <filename>/etc/default/ctdb</filename> (Debian) and is a
+      shell script (see
+      <citerefentry><refentrytitle>sh</refentrytitle>
+      <manvolnum>1</manvolnum></citerefentry>).
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>
+      GLOBAL CONFIGURATION
+    </title>
+
+    <variablelist>
+
+      <varlistentry>
+       <term>CTDB_INIT_STYLE=debian|redhat|suse</term>
+       <listitem>
+         <para>
+           This is the init style used by the Linux distribution (or
+           other operating system) being used.  This is usually
+           determined dynamically by checking the system.  This
+           variable is used by the initscript to determine which init
+           system primitives to use.  It is also used by some
+           eventscripts to choose the name of initscripts for certain
+           services, since these can vary between distributions.
+         </para>
+         <para>
+           If using CTDB's event scripts are unable to determine an
+           appropriate default then this option can also be placed in
+           a relevant
+           <citerefentry><refentrytitle>ctdb-script.options</refentrytitle>
+           <manvolnum>5</manvolnum></citerefentry> file.
+         </para>
+         <para>
+           Default: NONE.  Guessed, based on features of
+           distribution.
+         </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>CTDB_STARTUP_TIMEOUT=<parameter>NUM</parameter></term>
+       <listitem>
+         <para>
+           NUM is the number of seconds to wait for
+           <citerefentry><refentrytitle>ctdbd</refentrytitle>
+           <manvolnum>1</manvolnum></citerefentry> complete early
+           initialisation up to a point where it is unlikely to
+           abort.  If <command>ctdbd</command> doesn't complete the
+           "setup" event before this timeout then it is killed.
+         </para>
+
+         <para>
+           Defaults: 10
+         </para>
+       </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>
+      RESOURCE LIMITS
+    </title>
+
+    <refsect2>
+      <title>
+       Maximum number of open files
+      </title>
+
+      <para>
+       CTDB can use a lot of file descriptors, especially when used
+       with Samba.  If there are thousands of smbd processes
+       connected to CTDB when this can mean that thousands of file
+       descriptors are used.  For CTDB, it is often necessary to
+       increase limit on the maximum number of open files.
+      </para>
+
+      <para>
+       The maximum number of open files should be configured using an
+       operating system mechanism.
+      </para>
+
+      <variablelist>
+
+       <varlistentry>
+         <term>
+           systemd
+         </term>
+         <listitem>
+           <para>
+             The
+             <literal>LimitNOFILE=<option>LIMIT</option></literal>
+             option can be used in a unit/service file increase the
+             maximum number of open files.  See
+             <citerefentry><refentrytitle>systemd.exec</refentrytitle>
+             <manvolnum>5</manvolnum></citerefentry> for details.
+           </para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>
+           SYSV init
+         </term>
+         <listitem>
+           <para>
+             Use a command like <command>ulimit -n
+             <option>LIMIT</option></command> to increase the maximum
+             number of open files.  This command can be put in the
+             relevant distribution-specific service configuration file.
+           </para>
+         </listitem>
+       </varlistentry>
+
+      </variablelist>
+
+    </refsect2>
+
+    <refsect2>
+      <title>
+       Allowing core dumps
+      </title>
+
+      <para>
+       Many distributions do not allow core dump files to be
+       generated by default.  To assist with debugging, core files
+       can be enabled.  This should be configured using an operating
+       system mechanism.
+      </para>
+
+      <variablelist>
+
+       <varlistentry>
+         <term>
+           systemd
+         </term>
+         <listitem>
+           <para>
+             The <literal>LimitCORE=0|unlimited</literal> option can
+             be used in a unit/service file.  <literal>0</literal>
+             disallows core files, <literal>unlimited</literal>
+             allows them.  maximum number of open files.  See
+             <citerefentry><refentrytitle>systemd.exec</refentrytitle>
+             <manvolnum>5</manvolnum></citerefentry> for details.
+           </para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>
+           SYSV init
+         </term>
+         <listitem>
+           <para>
+             Use a command like <command>ulimit -c 0|unlimited</command>
+             to disable or enable core files as required.  This
+             command can be put in the relevant distribution-specific
+             service configuration file.
+           </para>
+         </listitem>
+       </varlistentry>
+
+      </variablelist>
+
+    </refsect2>
+
+  </refsect1>
+
+  <refsect1>
+    <title>FILES</title>
+
+    <simplelist>
+      <member><filename>/etc/sysconfig/ctdb</filename></member>
+      <member><filename>/etc/default/ctdb</filename></member>
+      <member><filename>/usr/local/etc/ctdb/script.options</filename></member>
+    </simplelist>
+  </refsect1>
+
+  <refsect1>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry><refentrytitle>ctdbd</refentrytitle>
+      <manvolnum>1</manvolnum></citerefentry>,
+
+      <citerefentry><refentrytitle>ctdb-script.options</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry>,
+
+      <citerefentry><refentrytitle>ctdb</refentrytitle>
+      <manvolnum>7</manvolnum></citerefentry>,
+
+      <ulink url="http://ctdb.samba.org/"/>
+    </para>
+  </refsect1>
+
+  <refentryinfo>
+    <author>
+      <contrib>
+       This documentation was written by
+       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>

diff --git a/ctdb/doc/ctdbd.conf.5.xml b/ctdb/doc/ctdbd.conf.5.xml
index 95a8ae7e251b2227871f0e8a4cbde5cc3ee5afcc..b7010ef8c8c0be4a644163005230bc2995f1fb16 100644 (file)
--- a/ctdb/doc/ctdbd.conf.5.xml
+++ b/ctdb/doc/ctdbd.conf.5.xml
@@ -50,49 +50,6 @@
 
   </refsect1>
 
-  <refsect1>
-    <title>
-      GLOBAL CONFIGURATION
-    </title>
-
-    <para>
-      These options may be used in the initscripts, daemon and
-      scripts.  If any of these options are required then they should
-      be set in the distribution-specific initscript configuration,
-      such as <filename>/etc/sysconfig/ctdb</filename> or
-      <filename>/etc/default/ctdb</filename>.
-    </para>
-
-    <variablelist>
-
-      <varlistentry>
-       <term>CTDB_INIT_STYLE=debian|redhat|suse</term>
-       <listitem>
-         <para>
-           This is the init style used by the Linux distribution (or
-           other operating system) being used.  This is usually
-           determined dynamically by checking the system.  This
-           variable is used by the initscript to determine which init
-           system primitives to use.  It is also used by some
-           eventscripts to choose the name of initscripts for certain
-           services, since these can vary between distributions.
-         </para>
-         <para>
-           No fixed default.
-         </para>
-         <para>
-           If this option needs to be changed from the calculated
-           default for the initscript to function properly, then it
-           must be set in the distribution-specific initscript
-           configuration, such as
-           <filename>/etc/sysconfig/ctdb</filename>
-         </para>
-       </listitem>
-      </varlistentry>
-
-    </variablelist>
-  </refsect1>
-
   <refsect1>
     <title>
       DAEMON CONFIGURATION
@@ -428,36 +385,6 @@
 
     </variablelist>
 
-    <para>
-      While the following variables do not translate into daemon
-      options they are used by
-      <citerefentry><refentrytitle>ctdbd_wrapper</refentrytitle>
-      <manvolnum>1</manvolnum></citerefentry> when starting and
-      stopping <citerefentry><refentrytitle>ctdbd</refentrytitle>
-      <manvolnum>1</manvolnum></citerefentry>.
-    </para>
-
-    <variablelist>
-
-      <varlistentry>
-       <term>CTDB_STARTUP_TIMEOUT=<parameter>NUM</parameter></term>
-       <listitem>
-         <para>
-           NUM is the number of seconds to wait for
-           <citerefentry><refentrytitle>ctdbd</refentrytitle>
-           <manvolnum>1</manvolnum></citerefentry> complete early
-           initialisation up to a point where it is unlikely to
-           abort.  If <command>ctdbd</command> doesn't complete the
-           "setup" event before this timeout then it is killed.
-         </para>
-
-         <para>
-           Defaults is 10.
-         </para>
-       </listitem>
-      </varlistentry>
-
-    </variablelist>
   </refsect1>
 
   <refsect1>

diff --git a/ctdb/doc/ctdbd_wrapper.1.xml b/ctdb/doc/ctdbd_wrapper.1.xml
index b119681a93a4f2efcdedcb9dc341095d05076aab..d717b84d2bda9bfbc1ee805b66c467abf5d556a4 100644 (file)
--- a/ctdb/doc/ctdbd_wrapper.1.xml
+++ b/ctdb/doc/ctdbd_wrapper.1.xml
@@ -58,6 +58,9 @@
       <citerefentry><refentrytitle>ctdbd</refentrytitle>
       <manvolnum>1</manvolnum></citerefentry>,
 
+      <citerefentry><refentrytitle>ctdb.sysconfig</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry>,
+
       <citerefentry><refentrytitle>ctdbd.conf</refentrytitle>
       <manvolnum>5</manvolnum></citerefentry>,
 

diff --git a/ctdb/packaging/RPM/ctdb.spec.in b/ctdb/packaging/RPM/ctdb.spec.in
index f2d71333b77d6d6602f74583db34b7ba592c907b..c277c4a597b9c04c0e106fdb0b797a4620a66f7f 100644 (file)
--- a/ctdb/packaging/RPM/ctdb.spec.in
+++ b/ctdb/packaging/RPM/ctdb.spec.in
@@ -224,6 +224,7 @@ rm -rf $RPM_BUILD_ROOT
 %{_mandir}/man1/ltdbtool.1.gz
 %{_mandir}/man1/ping_pong.1.gz
 %{_mandir}/man5/ctdb-script.options.5.gz
+%{_mandir}/man5/ctdb.sysconfig.5.gz
 %{_mandir}/man5/ctdbd.conf.5.gz
 %{_mandir}/man7/ctdb.7.gz
 %{_mandir}/man7/ctdb-statistics.7.gz

diff --git a/ctdb/wscript b/ctdb/wscript
index 95091ce0564649a43a6853111842e29d8408c646..89020c5d122de64a96159a32acf830ee187781d9 100644 (file)
--- a/ctdb/wscript
+++ b/ctdb/wscript
@@ -49,6 +49,7 @@ manpages_misc = [
     'ctdbd_wrapper.1',
     'onnode.1',
     'ctdb-script.options.5',
+    'ctdb.sysconfig.5',
     'ctdbd.conf.5',
     'ctdb.7',
     'ctdb-statistics.7',