| blob | acfb9d082f87812050d33406af58cabded712ed4 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE refentry
3 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
4 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
6 <refentry id="ctdb-script.options.5">
8 <refmeta>
9 <refentrytitle>ctdb-script.options</refentrytitle>
10 <manvolnum>5</manvolnum>
11 <refmiscinfo class="source">ctdb</refmiscinfo>
12 <refmiscinfo class="manual">CTDB - clustered TDB database</refmiscinfo>
13 </refmeta>
15 <refnamediv>
16 <refname>ctdb-script.options</refname>
17 <refpurpose>CTDB scripts configuration files</refpurpose>
18 </refnamediv>
20 <refsect1>
21 <title>DESCRIPTION</title>
23 <refsect2>
24 <title>Location</title>
25 <para>
26 Each CTDB script has 2 possible locations for its configuration options:
27 </para>
29 <variablelist>
31 <varlistentry>
32 <term>
33 <filename>/usr/local/etc/ctdb/script.options</filename>
34 </term>
35 <listitem>
36 <para>
37 This is a catch-all global file for general purpose
38 scripts and for options that are used in multiple event
39 scripts.
40 </para>
41 </listitem>
42 </varlistentry>
44 <varlistentry>
45 <term>
46 <parameter>SCRIPT</parameter>.options
47 </term>
48 <listitem>
49 <para>
50 That is, options for
51 <filename><parameter>SCRIPT</parameter></filename> are
52 placed in a file alongside the script, with a ".script"
53 suffix added. This style is usually recommended for event
54 scripts.
55 </para>
57 <para>
58 Options in this script-specific file override those in
59 the global file.
60 </para>
61 </listitem>
62 </varlistentry>
64 </variablelist>
65 </refsect2>
67 <refsect2>
68 <title>Contents</title>
70 <para>
71 These files should include simple shell-style variable
72 assignments and shell-style comments.
73 </para>
74 </refsect2>
76 <refsect2>
77 <title>Monitoring Thresholds</title>
79 <para>
80 Event scripts can monitor resources or services. When a
81 problem is detected, it may be better to warn about a problem
82 rather than to immediately fail monitoring and mark a node as
83 unhealthy. CTDB provides support for event scripts to do
84 threshold-based monitoring.
85 </para>
87 <para>
88 A threshold setting looks like
89 <parameter>WARNING_THRESHOLD<optional>:ERROR_THRESHOLD</optional></parameter>.
90 If the number of problems is ≥ WARNING_THRESHOLD then the
91 script will log a warning and continue. If the number
92 problems is ≥ ERROR_THRESHOLD then the script will log an
93 error and exit with failure, causing monitoring to fail. Note
94 that ERROR_THRESHOLD is optional, and follows the optional
95 colon (:) separator.
96 </para>
97 </refsect2>
99 </refsect1>
101 <refsect1>
102 <title>NETWORK CONFIGURATION</title>
104 <refsect2>
105 <title>10.interface</title>
107 <para>
108 This event script handles public IP address release and
109 takeover, as well as monitoring interfaces used by public IP
110 addresses.
111 </para>
113 <variablelist>
115 <varlistentry>
116 <term>
117 CTDB_KILLTCP_USE_SS_KILL=yes|try|no
118 </term>
119 <listitem>
120 <para>
121 Whether to use <command>ss -K/--kill</command> to reset
122 incoming TCP connections to public IP addresses during
123 <command>releaseip</command>.
124 </para>
126 <para>
127 CTDB's standard method of resetting incoming TCP
128 connections during <command>releaseip</command> is via
129 its custom <command>ctdb_killtcp</command> command.
130 This uses network trickery to reset each connection:
131 send a "tickle ACK", capture the reply to extract the
132 TCP sequence number, send a reset (containing the
133 correct sequence number).
134 </para>
136 <para>
137 <command>ss -K</command> has been supported in
138 <command>ss</command> since iproute 4.5 in March 2016
139 and in the Linux kernel since 4.4 in December 2015.
140 However, the required kernel configuration item
141 <code>CONFIG_INET_DIAG_DESTROY</code> is disabled by
142 default. Although enabled in Debian kernels since ~2017
143 and in Ubuntu since at least 18.04, this has only
144 recently been enabled in distributions such as RHEL.
145 There seems to be no way, including running <command>ss
146 -K</command>, to determine if this is supported, so use
147 of this feature needs to be configurable. When
148 available, it should be the fastest, most reliable way
149 of killing connections.
150 </para>
152 <para>
153 Supported values are:
154 <variablelist>
155 <varlistentry>
156 <term>
157 yes
158 </term>
159 <listitem>
160 <para>
161 Use <command>ss -K</command> and make no other
162 attempt to kill any remaining connections. This
163 is sane on modern Linux distributions that are
164 guaranteed to have
165 <code>CONFIG_INET_DIAG_DESTROY</code> enabled.
166 </para>
167 </listitem>
168 </varlistentry>
170 <varlistentry>
171 <term>
172 try
173 </term>
174 <listitem>
175 <para>
176 Attempt to use <command>ss -K</command> and fall
177 back to <command>ctdb_killtcp</command> for any
178 remaining connections. This may be a good value
179 when <command>ss</command> supports the
180 <command>-K</command> option but it is uncertain
181 whether <code>CONFIG_INET_DIAG_DESTROY</code> is
182 enabled.
183 </para>
184 </listitem>
185 </varlistentry>
187 <varlistentry>
188 <term>
189 no
190 </term>
191 <listitem>
192 <para>
193 Never attempt to use <command>ss -K</command>.
194 Rely only on <command>ctdb_killtcp</command>.
195 </para>
196 </listitem>
197 </varlistentry>
198 </variablelist>
199 Default is "no".
200 </para>
201 </listitem>
202 </varlistentry>
204 <varlistentry>
205 <term>
206 CTDB_PARTIALLY_ONLINE_INTERFACES=yes|no
207 </term>
208 <listitem>
209 <para>
210 Whether one or more offline interfaces should cause a
211 monitor event to fail if there are other interfaces that
212 are up. If this is "yes" and a node has some interfaces
213 that are down then <command>ctdb status</command> will
214 display the node as "PARTIALLYONLINE".
215 </para>
217 <para>
218 Note that CTDB_PARTIALLY_ONLINE_INTERFACES=yes is not
219 generally compatible with NAT gateway or LVS. NAT
220 gateway relies on the interface configured by
221 CTDB_NATGW_PUBLIC_IFACE to be up and LVS replies on
222 CTDB_LVS_PUBLIC_IFACE to be up. CTDB does not check if
223 these options are set in an incompatible way so care is
224 needed to understand the interaction.
225 </para>
227 <para>
228 Default is "no".
229 </para>
230 </listitem>
231 </varlistentry>
233 </variablelist>
234 </refsect2>
236 <refsect2>
237 <title>11.natgw</title>
239 <para>
240 Provides CTDB's NAT gateway functionality.
241 </para>
243 <para>
244 NAT gateway is used to configure fallback routing for nodes
245 when they do not host any public IP addresses. For example,
246 it allows unhealthy nodes to reliably communicate with
247 external infrastructure. One node in a NAT gateway group will
248 be designated as the NAT gateway leader node and other (follower)
249 nodes will be configured with fallback routes via the NAT
250 gateway leader node. For more information, see the
251 <citetitle>NAT GATEWAY</citetitle> section in
252 <citerefentry><refentrytitle>ctdb</refentrytitle>
253 <manvolnum>7</manvolnum></citerefentry>.
254 </para>
256 <variablelist>
258 <varlistentry>
259 <term>CTDB_NATGW_DEFAULT_GATEWAY=<parameter>IPADDR</parameter></term>
260 <listitem>
261 <para>
262 IPADDR is an alternate network gateway to use on the NAT
263 gateway leader node. If set, a fallback default route
264 is added via this network gateway.
265 </para>
266 <para>
267 No default. Setting this variable is optional - if not
268 set that no route is created on the NAT gateway leader
269 node.
270 </para>
271 </listitem>
272 </varlistentry>
274 <varlistentry>
275 <term>CTDB_NATGW_NODES=<parameter>FILENAME</parameter></term>
276 <listitem>
277 <para>
278 FILENAME contains the list of nodes that belong to the
279 same NAT gateway group.
280 </para>
281 <para>
282 File format:
283 <screen>
284 <parameter>IPADDR</parameter> <optional>follower-only</optional>
285 </screen>
286 </para>
287 <para>
288 IPADDR is the private IP address of each node in the NAT
289 gateway group.
290 </para>
291 <para>
292 If "follower-only" is specified then the corresponding node
293 can not be the NAT gateway leader node. In this case
294 <varname>CTDB_NATGW_PUBLIC_IFACE</varname> and
295 <varname>CTDB_NATGW_PUBLIC_IP</varname> are optional and
296 unused.
297 </para>
298 <para>
299 No default, usually
300 <filename>/usr/local/etc/ctdb/natgw_nodes</filename> when enabled.
301 </para>
302 </listitem>
303 </varlistentry>
305 <varlistentry>
306 <term>CTDB_NATGW_PRIVATE_NETWORK=<parameter>IPADDR/MASK</parameter></term>
307 <listitem>
308 <para>
309 IPADDR/MASK is the private sub-network that is
310 internally routed via the NAT gateway leader node. This
311 is usually the private network that is used for node
312 addresses.
313 </para>
314 <para>
315 No default.
316 </para>
317 </listitem>
318 </varlistentry>
320 <varlistentry>
321 <term>CTDB_NATGW_PUBLIC_IFACE=<parameter>IFACE</parameter></term>
322 <listitem>
323 <para>
324 IFACE is the network interface on which the
325 CTDB_NATGW_PUBLIC_IP will be configured.
326 </para>
327 <para>
328 No default.
329 </para>
330 </listitem>
331 </varlistentry>
333 <varlistentry>
334 <term>CTDB_NATGW_PUBLIC_IP=<parameter>IPADDR/MASK</parameter></term>
335 <listitem>
336 <para>
337 IPADDR/MASK indicates the IP address that is used for
338 outgoing traffic (originating from
339 CTDB_NATGW_PRIVATE_NETWORK) on the NAT gateway leader
340 node. This <emphasis>must not</emphasis> be a
341 configured public IP address.
342 </para>
343 <para>
344 No default.
345 </para>
346 </listitem>
347 </varlistentry>
349 <varlistentry>
350 <term>CTDB_NATGW_STATIC_ROUTES=<parameter>IPADDR/MASK[@GATEWAY]</parameter> ...</term>
351 <listitem>
352 <para>
353 Each IPADDR/MASK identifies a network or host to which
354 NATGW should create a fallback route, instead of
355 creating a single default route. This can be used when
356 there is already a default route, via an interface that
357 can not reach required infrastructure, that overrides
358 the NAT gateway default route.
359 </para>
360 <para>
361 If GATEWAY is specified then the corresponding route on
362 the NATGW leader node will be via GATEWAY. Such routes
363 are created even if
364 <varname>CTDB_NATGW_DEFAULT_GATEWAY</varname> is not
365 specified. If GATEWAY is not specified for some
366 networks then routes are only created on the NATGW
367 leader node for those networks if
368 <varname>CTDB_NATGW_DEFAULT_GATEWAY</varname> is
369 specified.
370 </para>
371 <para>
372 This should be used with care to avoid causing traffic
373 to unnecessarily double-hop through the NAT gateway
374 leader, even when a node is hosting public IP addresses.
375 Each specified network or host should probably have a
376 corresponding automatically created link route or static
377 route to avoid this.
378 </para>
379 <para>
380 No default.
381 </para>
382 </listitem>
383 </varlistentry>
385 </variablelist>
387 <refsect3>
388 <title>Example</title>
389 <screen>
390 CTDB_NATGW_NODES=/usr/local/etc/ctdb/natgw_nodes
391 CTDB_NATGW_PRIVATE_NETWORK=192.168.1.0/24
392 CTDB_NATGW_DEFAULT_GATEWAY=10.0.0.1
393 CTDB_NATGW_PUBLIC_IP=10.0.0.227/24
394 CTDB_NATGW_PUBLIC_IFACE=eth0
395 </screen>
397 <para>
398 A variation that ensures that infrastructure (ADS, DNS, ...)
399 directly attached to the public network (10.0.0.0/24) is
400 always reachable would look like this:
401 </para>
402 <screen>
403 CTDB_NATGW_NODES=/usr/local/etc/ctdb/natgw_nodes
404 CTDB_NATGW_PRIVATE_NETWORK=192.168.1.0/24
405 CTDB_NATGW_PUBLIC_IP=10.0.0.227/24
406 CTDB_NATGW_PUBLIC_IFACE=eth0
407 CTDB_NATGW_STATIC_ROUTES=10.0.0.0/24
408 </screen>
409 <para>
410 Note that <varname>CTDB_NATGW_DEFAULT_GATEWAY</varname> is
411 not specified.
412 </para>
413 </refsect3>
415 </refsect2>
417 <refsect2>
418 <title>13.per_ip_routing</title>
420 <para>
421 Provides CTDB's policy routing functionality.
422 </para>
424 <para>
425 A node running CTDB may be a component of a complex network
426 topology. In particular, public addresses may be spread
427 across several different networks (or VLANs) and it may not be
428 possible to route packets from these public addresses via the
429 system's default route. Therefore, CTDB has support for
430 policy routing via the <filename>13.per_ip_routing</filename>
431 eventscript. This allows routing to be specified for packets
432 sourced from each public address. The routes are added and
433 removed as CTDB moves public addresses between nodes.
434 </para>
436 <para>
437 For more information, see the <citetitle>POLICY
438 ROUTING</citetitle> section in
439 <citerefentry><refentrytitle>ctdb</refentrytitle>
440 <manvolnum>7</manvolnum></citerefentry>.
441 </para>
443 <variablelist>
444 <varlistentry>
445 <term>CTDB_PER_IP_ROUTING_CONF=<parameter>FILENAME</parameter></term>
446 <listitem>
447 <para>
448 FILENAME contains elements for constructing the desired
449 routes for each source address.
450 </para>
452 <para>
453 The special FILENAME value
454 <constant>__auto_link_local__</constant> indicates that no
455 configuration file is provided and that CTDB should
456 generate reasonable link-local routes for each public IP
457 address.
458 </para>
460 <para>
461 File format:
462 <screen>
463 <parameter>IPADDR</parameter> <parameter>DEST-IPADDR/MASK</parameter> <optional><parameter>GATEWAY-IPADDR</parameter></optional>
464 </screen>
465 </para>
467 <para>
468 No default, usually
469 <filename>/usr/local/etc/ctdb/policy_routing</filename>
470 when enabled.
471 </para>
472 </listitem>
473 </varlistentry>
475 <varlistentry>
476 <term>
477 CTDB_PER_IP_ROUTING_RULE_PREF=<parameter>NUM</parameter>
478 </term>
479 <listitem>
480 <para>
481 NUM sets the priority (or preference) for the routing
482 rules that are added by CTDB.
483 </para>
485 <para>
486 This should be (strictly) greater than 0 and (strictly)
487 less than 32766. A priority of 100 is recommended, unless
488 this conflicts with a priority already in use on the
489 system. See
490 <citerefentry><refentrytitle>ip</refentrytitle>
491 <manvolnum>8</manvolnum></citerefentry>, for more details.
492 </para>
493 </listitem>
494 </varlistentry>
496 <varlistentry>
497 <term>
498 CTDB_PER_IP_ROUTING_TABLE_ID_LOW=<parameter>LOW-NUM</parameter>,
499 CTDB_PER_IP_ROUTING_TABLE_ID_HIGH=<parameter>HIGH-NUM</parameter>
500 </term>
501 <listitem>
502 <para>
503 CTDB determines a unique routing table number to use for
504 the routing related to each public address. LOW-NUM and
505 HIGH-NUM indicate the minimum and maximum routing table
506 numbers that are used.
507 </para>
509 <para>
510 <citerefentry><refentrytitle>ip</refentrytitle>
511 <manvolnum>8</manvolnum></citerefentry> uses some
512 reserved routing table numbers below 255. Therefore,
513 CTDB_PER_IP_ROUTING_TABLE_ID_LOW should be (strictly)
514 greater than 255.
515 </para>
517 <para>
518 CTDB uses the standard file
519 <filename>/etc/iproute2/rt_tables</filename> to maintain
520 a mapping between the routing table numbers and labels.
521 The label for a public address
522 <replaceable>ADDR</replaceable> will look like
523 ctdb.<replaceable>addr</replaceable>. This means that
524 the associated rules and routes are easy to read (and
525 manipulate).
526 </para>
528 <para>
529 No default, usually 1000 and 9000.
530 </para>
531 </listitem>
532 </varlistentry>
533 </variablelist>
535 <refsect3>
536 <title>Example</title>
537 <screen>
538 CTDB_PER_IP_ROUTING_CONF=/usr/local/etc/ctdb/policy_routing
539 CTDB_PER_IP_ROUTING_RULE_PREF=100
540 CTDB_PER_IP_ROUTING_TABLE_ID_LOW=1000
541 CTDB_PER_IP_ROUTING_TABLE_ID_HIGH=9000
542 </screen>
543 </refsect3>
545 </refsect2>
547 <refsect2>
548 <title>91.lvs</title>
550 <para>
551 Provides CTDB's LVS functionality.
552 </para>
554 <para>
555 For a general description see the <citetitle>LVS</citetitle>
556 section in <citerefentry><refentrytitle>ctdb</refentrytitle>
557 <manvolnum>7</manvolnum></citerefentry>.
558 </para>
560 <variablelist>
562 <varlistentry>
563 <term>
564 CTDB_LVS_NODES=<parameter>FILENAME</parameter>
565 </term>
566 <listitem>
567 <para>
568 FILENAME contains the list of nodes that belong to the
569 same LVS group.
570 </para>
571 <para>
572 File format:
573 <screen>
574 <parameter>IPADDR</parameter> <optional>follower-only</optional>
575 </screen>
576 </para>
577 <para>
578 IPADDR is the private IP address of each node in the LVS
579 group.
580 </para>
581 <para>
582 If "follower-only" is specified then the corresponding node
583 can not be the LVS leader node. In this case
584 <varname>CTDB_LVS_PUBLIC_IFACE</varname> and
585 <varname>CTDB_LVS_PUBLIC_IP</varname> are optional and
586 unused.
587 </para>
588 <para>
589 No default, usually
590 <filename>/usr/local/etc/ctdb/lvs_nodes</filename> when enabled.
591 </para>
592 </listitem>
593 </varlistentry>
595 <varlistentry>
596 <term>
597 CTDB_LVS_PUBLIC_IFACE=<parameter>INTERFACE</parameter>
598 </term>
599 <listitem>
600 <para>
601 INTERFACE is the network interface that clients will use
602 to connection to <varname>CTDB_LVS_PUBLIC_IP</varname>.
603 This is optional for follower-only nodes.
604 No default.
605 </para>
606 </listitem>
607 </varlistentry>
609 <varlistentry>
610 <term>
611 CTDB_LVS_PUBLIC_IP=<parameter>IPADDR</parameter>
612 </term>
613 <listitem>
614 <para>
615 CTDB_LVS_PUBLIC_IP is the LVS public address. No
616 default.
617 </para>
618 </listitem>
619 </varlistentry>
621 </variablelist>
622 </refsect2>
624 </refsect1>
626 <refsect1>
627 <title>SERVICE CONFIGURATION</title>
629 <para>
630 CTDB can be configured to manage and/or monitor various NAS (and
631 other) services via its eventscripts.
632 </para>
634 <para>
635 In the simplest case CTDB will manage a service. This means the
636 service will be started and stopped along with CTDB, CTDB will
637 monitor the service and CTDB will do any required
638 reconfiguration of the service when public IP addresses are
639 failed over.
640 </para>
642 <refsect2>
643 <title>20.multipathd</title>
645 <para>
646 Provides CTDB's Linux multipathd service management.
647 </para>
649 <para>
650 It can monitor multipath devices to ensure that active paths
651 are available.
652 </para>
654 <variablelist>
655 <varlistentry>
656 <term>
657 CTDB_MONITOR_MPDEVICES=<parameter>MP-DEVICE-LIST</parameter>
658 </term>
659 <listitem>
660 <para>
661 MP-DEVICE-LIST is a list of multipath devices for CTDB to monitor?
662 </para>
663 <para>
664 No default.
665 </para>
666 </listitem>
667 </varlistentry>
668 </variablelist>
669 </refsect2>
671 <refsect2>
672 <title>31.clamd</title>
674 <para>
675 This event script provide CTDB's ClamAV anti-virus service
676 management.
677 </para>
679 <para>
680 This eventscript is not enabled by default. Use <command>ctdb
681 enablescript</command> to enable it.
682 </para>
684 <variablelist>
686 <varlistentry>
687 <term>
688 CTDB_CLAMD_SOCKET=<parameter>FILENAME</parameter>
689 </term>
690 <listitem>
691 <para>
692 FILENAME is the socket to monitor ClamAV.
693 </para>
694 <para>
695 No default.
696 </para>
697 </listitem>
698 </varlistentry>
700 </variablelist>
702 </refsect2>
704 <refsect2>
705 <title>40.vsftpd</title>
707 <para>
708 Provides CTDB's vsftpd service management.
709 </para>
711 <variablelist>
712 <varlistentry>
713 <term>
714 CTDB_VSFTPD_MONITOR_THRESHOLDS=<parameter>THRESHOLDS</parameter>
715 </term>
716 <listitem>
717 <para>
718 THRESHOLDS indicates how many consecutive monitoring
719 attempts need to report that vsftpd is not listening on
720 TCP port 21 before a warning is logged and before
721 monitoring fails. See the <citetitle>Monitoring
722 Thresholds</citetitle> for a description of how
723 monitoring thresholds work.
724 </para>
725 <para>
726 Default is 1:2.
727 </para>
728 </listitem>
729 </varlistentry>
731 </variablelist>
733 </refsect2>
735 <refsect2>
736 <title>48.netbios</title>
738 <para>
739 Provides CTDB's NetBIOS service management.
740 </para>
742 <variablelist>
743 <varlistentry>
744 <term>
745 CTDB_SERVICE_NMB=<parameter>SERVICE</parameter>
746 </term>
747 <listitem>
748 <para>
749 Distribution specific SERVICE for managing nmbd.
750 </para>
751 <para>
752 Default is distribution-dependant.
753 </para>
754 </listitem>
755 </varlistentry>
757 </variablelist>
759 </refsect2>
761 <refsect2>
762 <title>49.winbind</title>
764 <para>
765 Provides CTDB's Samba winbind service management.
766 </para>
768 <variablelist>
770 <varlistentry>
771 <term>
772 CTDB_SERVICE_WINBIND=<parameter>SERVICE</parameter>
773 </term>
774 <listitem>
775 <para>
776 Distribution specific SERVICE for managing winbindd.
777 </para>
778 <para>
779 Default is "winbind".
780 </para>
781 </listitem>
782 </varlistentry>
784 <varlistentry>
785 <term>
786 CTDB_SAMBA_INTERFACES_FILE=<parameter>FILENAME</parameter>
787 </term>
788 <listitem>
789 <para>
790 Generates FILENAME, containing an smb.conf snippet with
791 an interfaces setting that includes interfaces for
792 configured CTDB public IP addresses. This file then
793 needs to be explicitly included in smb.conf.
794 </para>
795 <para>
796 For example, if public IP addresses are defined on
797 interfaces eth0 and eth1, and this is set to
798 <filename>/etc/samba/interfaces.conf</filename>, then
799 that file will contain the following before smbd is
800 started:
801 </para>
802 <screen>
803 bind interfaces only = yes
804 interfaces = lo eth0 eth1
805 </screen>
806 <para>
807 This can be useful for limiting the interfaces used by
808 SMB multichannel.
809 </para>
810 <para>
811 Default is to not generate a file.
812 </para>
813 </listitem>
814 </varlistentry>
816 <varlistentry>
817 <term>
818 CTDB_SAMBA_INTERFACES_EXTRA=<parameter>INTERFACE-LIST</parameter>
819 </term>
820 <listitem>
821 <para>
822 A space separated list to provide additional interfaces to bind.
823 </para>
824 <para>
825 Default is empty - no extra interfaces are added.
826 </para>
827 </listitem>
828 </varlistentry>
829 </variablelist>
831 </refsect2>
833 <refsect2>
834 <title>50.samba</title>
836 <para>
837 Provides the core of CTDB's Samba file service management.
838 </para>
840 <variablelist>
842 <varlistentry>
843 <term>
844 CTDB_SAMBA_CHECK_PORTS=<parameter>PORT-LIST</parameter>
845 </term>
846 <listitem>
847 <para>
848 When monitoring Samba, check TCP ports in
849 space-separated PORT-LIST.
850 </para>
851 <para>
852 Default is to monitor ports that Samba is configured to listen on.
853 </para>
854 </listitem>
855 </varlistentry>
857 <varlistentry>
858 <term>
859 CTDB_SAMBA_SKIP_SHARE_CHECK=yes|no
860 </term>
861 <listitem>
862 <para>
863 As part of monitoring, should CTDB skip the check for
864 the existence of each directory configured as share in
865 Samba. This may be desirable if there is a large number
866 of shares.
867 </para>
868 <para>
869 Default is no.
870 </para>
871 </listitem>
872 </varlistentry>
874 <varlistentry>
875 <term>
876 CTDB_SERVICE_SMB=<parameter>SERVICE</parameter>
877 </term>
878 <listitem>
879 <para>
880 Distribution specific SERVICE for managing smbd.
881 </para>
882 <para>
883 Default is distribution-dependant.
884 </para>
885 </listitem>
886 </varlistentry>
888 </variablelist>
890 </refsect2>
892 <refsect2>
893 <title>60.nfs</title>
895 <para>
896 This event script provides CTDB's NFS service management.
897 </para>
899 <para>
900 This includes parameters for the kernel NFS server.
901 Alternative NFS subsystems (such as <ulink
902 url="https://github.com/nfs-ganesha/nfs-ganesha/wiki">NFS-Ganesha</ulink>)
903 can be integrated using <varname>CTDB_NFS_CALLOUT</varname>.
904 </para>
906 <variablelist>
908 <varlistentry>
909 <term>
910 CTDB_NFS_CALLOUT=<parameter>COMMAND</parameter>
911 </term>
912 <listitem>
913 <para>
914 COMMAND specifies the path to a callout to handle
915 interactions with the configured NFS system, including
916 startup, shutdown, monitoring.
917 </para>
918 <para>
919 Default is the included
920 <command>nfs-linux-kernel-callout</command>.
921 </para>
922 </listitem>
923 </varlistentry>
925 <varlistentry>
926 <term>
927 CTDB_NFS_CHECKS_DIR=<parameter>DIRECTORY</parameter>
928 </term>
929 <listitem>
930 <para>
931 Specifies the path to a DIRECTORY containing files that
932 describe how to monitor the responsiveness of NFS RPC
933 services. See the README file for this directory for an
934 explanation of the contents of these "check" files.
935 </para>
936 <para>
937 CTDB_NFS_CHECKS_DIR can be used to point to different
938 sets of checks for different NFS servers.
939 </para>
940 <para>
941 One way of using this is to have it point to, say,
942 <filename>/usr/local/etc/ctdb/nfs-checks-enabled.d</filename>
943 and populate it with symbolic links to the desired check
944 files. This avoids duplication and is upgrade-safe.
945 </para>
946 <para>
947 Default is
948 <filename>/usr/local/etc/ctdb/nfs-checks.d</filename>,
949 which contains NFS RPC checks suitable for Linux kernel
950 NFS.
951 </para>
952 </listitem>
953 </varlistentry>
955 <varlistentry>
956 <term>
957 CTDB_NFS_EXPORTS_FILE=<parameter>FILE</parameter>
958 </term>
959 <listitem>
960 <para>
961 Set FILE as the path of the file containing NFS exports,
962 for use by the NFS callout (see CTDB_NFS_CALLOUT,
963 above). This is used for share checks when
964 CTDB_NFS_SKIP_SHARE_CHECK is not set to "yes". This is
965 most useful with NFS-Ganesha, since it supports
966 configuration include files and exports may be stored in
967 a separate file.
968 </para>
969 <para>
970 Default is <filename>/var/lib/nfs/etab</filename> for
971 <filename>nfs-linux-kernel-callout</filename>,
972 <filename>/etc/ganesha/ganesha.conf</filename> for
973 <filename>nfs-ganesha-callout</filename>.
974 </para>
975 </listitem>
976 </varlistentry>
978 <varlistentry>
979 <term>
980 CTDB_NFS_SHARED_STATE_DIR=<parameter>DIRECTORY</parameter>
981 </term>
982 <listitem>
983 <para>
984 DIRECTORY where clustered NFS shared state will be
985 located. DIRECTORY should be in a cluster filesystem
986 that is shared between the nodes. No default.
987 </para>
988 </listitem>
989 </varlistentry>
991 <varlistentry>
992 <term>
993 CTDB_NFS_SKIP_SHARE_CHECK=yes|no
994 </term>
995 <listitem>
996 <para>
997 As part of monitoring, should CTDB skip the check for
998 the existence of each directory exported via NFS. This
999 may be desirable if there is a large number of exports.
1000 </para>
1001 <para>
1002 Default is no.
1003 </para>
1004 </listitem>
1005 </varlistentry>
1007 <varlistentry>
1008 <term>
1009 CTDB_RPCINFO_LOCALHOST=<parameter>IPADDR</parameter>|<parameter>HOSTNAME</parameter>
1010 </term>
1011 <listitem>
1012 <para>
1013 IPADDR or HOSTNAME indicates the address that
1014 <command>rpcinfo</command> should connect to when doing
1015 <command>rpcinfo</command> check on IPv4 RPC service during
1016 monitoring. Optimally this would be "localhost".
1017 However, this can add some performance overheads.
1018 </para>
1019 <para>
1020 Default is "127.0.0.1".
1021 </para>
1022 </listitem>
1023 </varlistentry>
1025 <varlistentry>
1026 <term>
1027 CTDB_RPCINFO_LOCALHOST6=<parameter>IPADDR</parameter>|<parameter>HOSTNAME</parameter>
1028 </term>
1029 <listitem>
1030 <para>
1031 IPADDR or HOSTNAME indicates the address that
1032 <command>rpcinfo</command> should connect to when doing
1033 <command>rpcinfo</command> check on IPv6 RPC service
1034 during monitoring. Optimally this would be "localhost6"
1035 (or similar). However, this can add some performance
1036 overheads.
1037 </para>
1038 <para>
1039 Default is "::1".
1040 </para>
1041 </listitem>
1042 </varlistentry>
1044 <varlistentry>
1045 <term>
1046 CTDB_STATD_CALLOUT_SHARED_STORAGE=<parameter>LOCATION</parameter>
1047 </term>
1048 <listitem>
1049 <para>
1050 LOCATION where NFSv3 statd state will be stored. Valid
1051 values are:
1052 </para>
1053 <variablelist>
1054 <varlistentry>
1055 <term>
1056 persistent_db<optional>:<parameter>TDB</parameter></optional>
1057 </term>
1058 <listitem>
1059 <para>
1060 Data is queued to local storage and then dequeued
1061 to TDB during monitor events. This means there is
1062 a window where locking state may be lost.
1063 However, this works around performance limitations
1064 in CTDB's persistent database handling.
1065 </para>
1066 <para>
1067 If :TDB is omitted then TDB defaults to
1068 <filename>ctdb.tdb</filename>.
1069 </para>
1070 </listitem>
1071 </varlistentry>
1072 <varlistentry>
1073 <term>
1074 shared_dir<optional>:<parameter>DIRECTORY</parameter></optional>
1075 </term>
1076 <listitem>
1077 <para>
1078 DIRECTORY is a directory in a cluster filesystem
1079 that is shared between the nodes. If DIRECTORY is
1080 relative (i.e. does not start with '/') then it is
1081 appended to CTDB_NFS_SHARED_STATE_DIR. If
1082 :DIRECTORY is omitted then DIRECTORY defaults to
1083 <filename>statd</filename>.
1084 </para>
1085 <para>
1086 Using a shared directory may result in performance
1087 and/or stability problems. rpc.statd is
1088 single-threaded and its HA callout is called
1089 synchronously, causing any latency introduced by
1090 the callout to be cumulative. Stability issues
1091 are most likely if thousands of clients reclaim
1092 locks after failover and use of the cluster
1093 filesystem introduces too much additional
1094 latency. Too much latency in in the HA callout
1095 may cause rpc.statd to fail health monitoring.
1096 </para>
1097 </listitem>
1098 </varlistentry>
1099 </variablelist>
1100 </listitem>
1101 </varlistentry>
1103 </variablelist>
1105 </refsect2>
1107 <refsect2>
1108 <title>70.iscsi</title>
1110 <para>
1111 Provides CTDB's Linux iSCSI tgtd service management.
1112 </para>
1114 <variablelist>
1116 <varlistentry>
1117 <term>
1118 CTDB_START_ISCSI_SCRIPTS=<parameter>DIRECTORY</parameter>
1119 </term>
1120 <listitem>
1121 <para>
1122 DIRECTORY on shared storage containing scripts to start
1123 tgtd for each public IP address.
1124 </para>
1125 <para>
1126 No default.
1127 </para>
1128 </listitem>
1129 </varlistentry>
1130 </variablelist>
1131 </refsect2>
1133 </refsect1>
1135 <refsect1>
1136 <title>
1137 DATABASE HANDLING
1138 </title>
1140 <para>
1141 CTDB checks the consistency of databases during startup and
1142 provides a facility to backup persistent databases.
1143 </para>
1145 <refsect2>
1146 <title>95.database</title>
1148 <variablelist>
1150 <varlistentry>
1151 <term>CTDB_MAX_CORRUPT_DB_BACKUPS=<parameter>NUM</parameter></term>
1152 <listitem>
1153 <para>
1154 NUM is the maximum number of volatile TDB database
1155 backups to be kept (for each database) when a corrupt
1156 database is found during startup. Volatile TDBs are
1157 zeroed during startup so backups are needed to debug
1158 any corruption that occurs before a restart.
1159 </para>
1160 <para>
1161 Default is 10.
1162 </para>
1163 </listitem>
1164 </varlistentry>
1166 <varlistentry>
1167 <term>CTDB_PERSISTENT_DB_BACKUP_DIR=<parameter>DIRECTORY</parameter></term>
1168 <listitem>
1169 <para>
1170 Create a daily backup tarball for all persistent TDBs
1171 in DIRECTORY. Note that DIRECTORY must exist or no
1172 backups will be created.
1173 </para>
1174 <para>
1175 Given that persistent databases are fully replicated,
1176 duplication is avoid by only creating backups on the
1177 current leader node. To maintain a complete, single
1178 set of backups, it makes sense for DIRECTORY to be in
1179 a cluster filesystem.
1180 </para>
1181 <para>
1182 This creates the backup from the
1183 <command>monitor</command> event, which should be fine
1184 because backing up persistent databases is a local
1185 operation. Users who do not wish do create backups
1186 during the <command>monitor</command> event can choose
1187 not to use this option and instead run
1188 <command>/usr/local/etc/ctdb/ctdb-backup-persistent-tdbs.sh
1189 -l <parameter>DIRECTORY</parameter></command> on all
1190 nodes using a
1191 <citerefentry><refentrytitle>cron</refentrytitle>
1192 <manvolnum>8</manvolnum></citerefentry> job, which
1193 will also need to manually manage backup pruning.
1194 </para>
1195 <para>
1196 No default. No daily backups are created.
1197 </para>
1198 </listitem>
1199 </varlistentry>
1201 <varlistentry>
1202 <term>CTDB_PERSISTENT_DB_BACKUP_LIMIT=<parameter>COUNT</parameter></term>
1203 <listitem>
1204 <para>
1205 Keep at most COUNT backups in
1206 CTDB_PERSISTENT_DB_BACKUP_DIR. Note that if
1207 additional manual backups are created in this
1208 directory then these will count towards the limit.
1209 </para>
1210 <para>
1211 Default is 14.
1212 </para>
1213 </listitem>
1214 </varlistentry>
1216 </variablelist>
1217 </refsect2>
1219 </refsect1>
1221 <refsect1>
1222 <title>SYSTEM RESOURCE MONITORING</title>
1224 <refsect2>
1225 <title>
1226 05.system
1227 </title>
1229 <para>
1230 Provides CTDB's filesystem and memory usage monitoring.
1231 </para>
1233 <para>
1234 CTDB can experience seemingly random (performance and other)
1235 issues if system resources become too constrained. Options in
1236 this section can be enabled to allow certain system resources
1237 to be checked. They allows warnings to be logged and nodes to
1238 be marked unhealthy when system resource usage reaches the
1239 configured thresholds.
1240 </para>
1242 <para>
1243 Some checks are enabled by default. It is recommended that
1244 these checks remain enabled or are augmented by extra checks.
1245 There is no supported way of completely disabling the checks.
1246 </para>
1248 <variablelist>
1250 <varlistentry>
1251 <term>
1252 CTDB_MONITOR_FILESYSTEM_USAGE=<parameter>FS-LIMIT-LIST</parameter>
1253 </term>
1254 <listitem>
1255 <para>
1256 FS-LIMIT-LIST is a space-separated list of
1257 <parameter>FILESYSTEM</parameter>:<parameter>WARN_LIMIT</parameter><optional>:<parameter>UNHEALTHY_LIMIT</parameter></optional>
1258 triples indicating that warnings should be logged if the
1259 space used on FILESYSTEM reaches WARN_LIMIT%. If usage
1260 reaches UNHEALTHY_LIMIT then the node should be flagged
1261 unhealthy. Either WARN_LIMIT or UNHEALTHY_LIMIT may be
1262 left blank, meaning that check will be omitted.
1263 </para>
1265 <para>
1266 Default is to warn for each filesystem containing a
1267 database directory
1268 (<literal>volatile database directory</literal>,
1269 <literal>persistent database directory</literal>,
1270 <literal>state database directory</literal>)
1271 with a threshold of 90%.
1272 </para>
1273 </listitem>
1274 </varlistentry>
1276 <varlistentry>
1277 <term>
1278 CTDB_MONITOR_MEMORY_USAGE=<parameter>MEM-LIMITS</parameter>
1279 </term>
1280 <listitem>
1281 <para>
1282 MEM-LIMITS takes the form
1283 <parameter>WARN_LIMIT</parameter><optional>:<parameter>UNHEALTHY_LIMIT</parameter></optional>
1284 indicating that warnings should be logged if memory
1285 usage reaches WARN_LIMIT%. If usage reaches
1286 UNHEALTHY_LIMIT then the node should be flagged
1287 unhealthy. Either WARN_LIMIT or UNHEALTHY_LIMIT may be
1288 left blank, meaning that check will be omitted.
1289 </para>
1290 <para>
1291 Default is 80, so warnings will be logged when memory
1292 usage reaches 80%.
1293 </para>
1294 </listitem>
1295 </varlistentry>
1297 </variablelist>
1298 </refsect2>
1300 </refsect1>
1303 <refsect1>
1304 <title>EVENT SCRIPT DEBUGGING</title>
1306 <refsect2>
1307 <title>
1308 debug-hung-script.sh
1309 </title>
1311 <variablelist>
1313 <varlistentry>
1314 <term>CTDB_DEBUG_HUNG_SCRIPT_STACKPAT=<parameter>REGEXP</parameter></term>
1315 <listitem>
1316 <para>
1317 REGEXP specifies interesting processes for which stack
1318 traces should be logged when debugging hung eventscripts
1319 and those processes are matched in pstree output.
1320 REGEXP is an extended regexp so choices are separated by
1321 pipes ('|'). However, REGEXP should not contain
1322 parentheses. See also the <citerefentry><refentrytitle>ctdb.conf</refentrytitle>
1323 <manvolnum>5</manvolnum></citerefentry>
1324 [event] "debug script" option.
1325 </para>
1326 <para>
1327 Default is "exportfs|rpcinfo".
1328 </para>
1329 </listitem>
1330 </varlistentry>
1332 </variablelist>
1333 </refsect2>
1335 </refsect1>
1337 <refsect1>
1338 <title>FILES</title>
1340 <simplelist>
1341 <member><filename>/usr/local/etc/ctdb/script.options</filename></member>
1342 </simplelist>
1343 </refsect1>
1345 <refsect1>
1346 <title>SEE ALSO</title>
1347 <para>
1348 <citerefentry><refentrytitle>ctdbd</refentrytitle>
1349 <manvolnum>1</manvolnum></citerefentry>,
1351 <citerefentry><refentrytitle>ctdb</refentrytitle>
1352 <manvolnum>7</manvolnum></citerefentry>,
1354 <ulink url="http://ctdb.samba.org/"/>
1355 </para>
1356 </refsect1>
1358 <refentryinfo>
1359 <author>
1360 <contrib>
1361 This documentation was written by
1362 Amitay Isaacs,
1363 Martin Schwenke
1364 </contrib>
1365 </author>
1367 <copyright>
1368 <year>2007</year>
1369 <holder>Andrew Tridgell</holder>
1370 <holder>Ronnie Sahlberg</holder>
1371 </copyright>
1372 <legalnotice>
1373 <para>
1374 This program is free software; you can redistribute it and/or
1375 modify it under the terms of the GNU General Public License as
1376 published by the Free Software Foundation; either version 3 of
1377 the License, or (at your option) any later version.
1378 </para>
1379 <para>
1380 This program is distributed in the hope that it will be
1381 useful, but WITHOUT ANY WARRANTY; without even the implied
1382 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
1383 PURPOSE. See the GNU General Public License for more details.
1384 </para>
1385 <para>
1386 You should have received a copy of the GNU General Public
1387 License along with this program; if not, see
1388 <ulink url="http://www.gnu.org/licenses"/>.
1389 </para>
1390 </legalnotice>
1391 </refentryinfo>
1393 </refentry>