Document the procedure to remove/change the NATGW configuration at
[metze/ctdb/wip.git] / doc / ctdbd.1
index 73536a2c12b38b5fe360f389fd003691f19d9175..95734efc9200bbfd30f39faaa318ef4e4f6b7c98 100644 (file)
@@ -1,11 +1,11 @@
 .\"     Title: ctdbd
 .\"    Author: 
 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
-.\"      Date: 06/25/2009
+.\"      Date: 12/04/2009
 .\"    Manual: 
 .\"    Source: 
 .\"
-.TH "CTDBD" "1" "06/25/2009" "" ""
+.TH "CTDBD" "1" "12/04/2009" "" ""
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
@@ -16,7 +16,7 @@ ctdbd - The CTDB cluster daemon
 .HP 6
 \fBctdbd\fR
 .HP 6
-\fBctdbd\fR [\-?\ \-\-help] [\-d\ \-\-debug=<INTEGER>] {\-\-dbdir=<directory>} {\-\-dbdir\-persistent=<directory>} [\-\-event\-script\-dir=<directory>] [\-i\ \-\-interactive] [\-\-listen=<address>] [\-\-logfile=<filename>] [\-\-lvs] {\-\-nlist=<filename>} [\-\-no\-lmaster] [\-\-no\-recmaster] [\-\-nosetsched] [\-\-public\-addresses=<filename>] [\-\-public\-interface=<interface>] {\-\-reclock=<filename>} [\-\-single\-public\-ip=<address>] [\-\-socket=<filename>] [\-\-start\-as\-disabled] [\-\-syslog] [\-\-torture] [\-\-transport=<STRING>] [\-\-usage]
+\fBctdbd\fR [\-?\ \-\-help] [\-d\ \-\-debug=<INTEGER>] {\-\-dbdir=<directory>} {\-\-dbdir\-persistent=<directory>} [\-\-event\-script\-dir=<directory>] [\-i\ \-\-interactive] [\-\-listen=<address>] [\-\-logfile=<filename>] [\-\-lvs] {\-\-nlist=<filename>} [\-\-no\-lmaster] [\-\-no\-recmaster] [\-\-nosetsched] {\-\-notification\-script=<filename>} [\-\-public\-addresses=<filename>] [\-\-public\-interface=<interface>] {\-\-reclock=<filename>} [\-\-single\-public\-ip=<address>] [\-\-socket=<filename>] [\-\-start\-as\-disabled] [\-\-start\-as\-stopped] [\-\-syslog] [\-\-torture] [\-\-transport=<STRING>] [\-\-usage]
 .SH "DESCRIPTION"
 .PP
 ctdbd is the main ctdb daemon\.
@@ -113,6 +113,15 @@ Normally ctdb will change its scheduler to run as a real\-time process\. This is
 This option is used to tell ctdbd to NOT 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 dont want to attach valgrind or gdb to a real\-time process\.)
 .RE
 .PP
+\-\-notification\-script=<filename>
+.RS 4
+This specifies a script which will be invoked by ctdb when certain state changes occur in ctdbd and when you may want to trigger this to run certain scripts\.
+.sp
+This file is usually /etc/ctdb/notify\.sh \.
+.sp
+See the NOTIFICATION SCRIPT section below for more information\.
+.RE
+.PP
 \-\-public_addresses=<filename>
 .RS 4
 When used with IP takeover this specifies a file containing the public ip addresses to use on the cluster\. This file contains a list of ip addresses netmasks and interfaces\. When ctdb is operational it will distribute these public ip addresses evenly across the available nodes\.
@@ -154,6 +163,17 @@ When used, the administrator must keep track of when nodes start and manually en
 A node that is DISABLED will not host any services and will not be reachable/used by any clients\.
 .RE
 .PP
+\-\-start\-as\-stopped
+.RS 4
+This makes the ctdb daemon to be STOPPED when it starts up\.
+.sp
+A node that is STOPPED does not host any public addresses\. It is not part of the VNNMAP so it does act as an LMASTER\. It also has all databases locked in recovery mode until restarted\.
+.sp
+To restart and activate a STOPPED node, the command "ctdb continue" is used\.
+.sp
+A node that is STOPPED will not host any services and will not be reachable/used by any clients\.
+.RE
+.PP
 \-\-syslog
 .RS 4
 Send all log messages to syslog instead of to the ctdb logfile\.
@@ -269,6 +289,8 @@ DISABLED \- This node has been administratively disabled\. This node is still fu
 UNHEALTHY \- A service provided by this node is malfunctioning and should be investigated\. The CTDB daemon itself is operational and participates in the cluster\. Its public IP address has been taken over by a different node and no services are currently being hosted\. All unhealthy nodes should be investigated and require an administrative action to rectify\.
 .PP
 BANNED \- This node failed too many recovery attempts and has been banned from participating in the cluster for a period of RecoveryBanPeriod seconds\. Any public IP address has been taken over by other nodes\. This node does not provide any services\. All banned nodes should be investigated and require an administrative action to rectify\. This node does not perticipate in the CTDB cluster but can still be communicated with\. I\.e\. ctdb commands can be sent to it\.
+.PP
+STOPPED \- A node that is stopped does not host any public ip addresses, nor is it part of the VNNMAP\. A stopped node can not become LVSMASTER, RECMASTER or NATGW\. This node does not perticipate in the CTDB cluster but can still be communicated with\. I\.e\. ctdb commands can be sent to it\.
 .SH "PUBLIC TUNABLES"
 .PP
 These are the public tuneables that can be used to control how ctdb behaves\.
@@ -346,7 +368,7 @@ LVS is a mode where CTDB presents one single IP address for the entire cluster\.
 .PP
 This is similar to using a layer\-4 loadbalancing switch but with some restrictions\.
 .PP
-In this mode the cluster select a set of nodes in the cluster and loadbalance all client access to the LVS address across this set of nodes\. This set of nodes are all LVS capable nodes that are HEALTHY, or if no HEALTHY nodes exists all LVS capable nodes regardless of health status\. LVS will however never loadbalance traffic to nodes that are BANNED, DISABLED or DISCONNECTED\. The "ctdb lvs" command is used to show which nodes are currently load\-balanced across\.
+In this mode the cluster select a set of nodes in the cluster and loadbalance all client access to the LVS address across this set of nodes\. This set of nodes are all LVS capable nodes that are HEALTHY, or if no HEALTHY nodes exists all LVS capable nodes regardless of health status\. LVS will however never loadbalance traffic to nodes that are BANNED, STOPPED, DISABLED or DISCONNECTED\. The "ctdb lvs" command is used to show which nodes are currently load\-balanced across\.
 .PP
 One of the these nodes are elected as the LVSMASTER\. This node receives all traffic from clients coming in to the LVS address and multiplexes it across the internal network to one of the nodes that LVS is using\. When responding to the client, that node will send the data back directly to the client, bypassing the LVSMASTER node\. The command "ctdb lvsmaster" will show which node is the current LVSMASTER\.
 .PP
@@ -488,13 +510,55 @@ Format of this parameter is IPADDRESS/NETMASK
 This is the list of all nodes that belong to the same NATGW group as this node\. The default is /etc/ctdb/natgw_nodes\.
 .SS "Operation"
 .PP
-When the NAT\-GW fiunctionality is used, one of the nodes is elected to act as a NAT router for all the other nodes in the group when they need to originate traffic to the external public network\.
+When the NAT\-GW functionality is used, one of the nodes is elected to act as a NAT router for all the other nodes in the group when they need to originate traffic to the external public network\.
 .PP
 The NAT\-GW node is assigned the CTDB_NATGW_PUBLIC_IP to the designated interface and the provided default route\. The NAT\-GW is configured to act as a router and to masquerade all traffic it receives from the internal private network and which is destined to the external network(s)\.
 .PP
 All other nodes in the group are configured with a default route of metric 10 pointing to the designated NAT GW node\.
 .PP
 This is implemented in the 11\.natgw eventscript\. Please see the eventscript for further information\.
+.SS "Removing/Changing NATGW at runtime"
+.PP
+The following are the procedures to change/remove a NATGW configuration at runtime, without having to restart ctdbd\.
+.PP
+If you want to remove NATGW completely from a node, use these steps:
+.sp
+.RS 4
+.nf
+1, Run \'CTDB_BASE=/etc/ctdb /etc/ctdb/events\.d/11\.natgw removenatgw\'
+2, Then remove the configuration from /etc/sysconfig/ctdb
+    
+.fi
+.RE
+.PP
+If you want to change the NATGW configuration on a node :
+.sp
+.RS 4
+.nf
+1, Run \'CTDB_BASE=/etc/ctdb /etc/ctdb/events\.d/11\.natgw removenatgw\'
+2, Then change the configuration in /etc/sysconfig/ctdb
+3, Run \'CTDB_BASE=/etc/ctdb /etc/ctdb/events\.d/11\.natgw updatenatgw\'
+    
+.fi
+.RE
+.SH "NOTIFICATION SCRIPT"
+.PP
+Notification scripts are used with ctdb to have a call\-out from ctdb to a user\-specified script when certain state changes occur in ctdb\. This is commonly to set up either sending SNMP traps or emails when a node becomes unhealthy and similar\.
+.PP
+This is activated by setting CTDB_NOTIFY_SCRIPT=<your script> in the sysconfig file, or by adding \-\-notification\-script=<your script>\.
+.PP
+See /etc/ctdb/notify\.sh for an example script\.
+.PP
+CTDB currently generates notifications on these state changes:
+.SS "unhealthy"
+.PP
+This call\-out is triggered when the node changes to UNHEALTHY state\.
+.SS "healthy"
+.PP
+This call\-out is triggered when the node changes to HEALTHY state\.
+.SS "startup"
+.PP
+This call\-out is triggered when ctdb has started up and all managed services are up and running\.
 .SH "CLAMAV DAEMON"
 .PP
 CTDB has support to manage the popular anti\-virus daemon ClamAV\. This support is implemented through the eventscript : /etc/ctdb/events\.d/31\.clamd\.
@@ -511,11 +575,11 @@ CTDB_CLAMD_SOCKET="/path/to/clamd\.socket"
 .fi
 .RE
 .PP
-Second, activate the eventscript by making it executable:
+Second, activate the eventscript
 .sp
 .RS 4
 .nf
-chmod +x /etc/ctdb/events\.d/31\.clamd
+ctdb enablescript 31\.clamd
 .fi
 .RE
 .PP