From: Amitay Isaacs Date: Mon, 7 Mar 2016 08:26:43 +0000 (+1100) Subject: ctdb-doc: Update tunables documentation X-Git-Tag: tdb-1.3.9~451 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e2539088e023ad88d314467a6a42b52c0decba77;p=thirdparty%2Fsamba.git ctdb-doc: Update tunables documentation Signed-off-by: Amitay Isaacs Reviewed-by: Martin Schwenke --- diff --git a/ctdb/doc/ctdb-tunables.7.xml b/ctdb/doc/ctdb-tunables.7.xml index 38f0069f054..10b0340bc37 100644 --- a/ctdb/doc/ctdb-tunables.7.xml +++ b/ctdb/doc/ctdb-tunables.7.xml @@ -39,7 +39,8 @@ When set to 0, clients are not allowed to attach to any databases. This can be used to temporarily block any new processes from - attaching to and accessing the databases. + attaching to and accessing the databases. This is mainly used + for detaching a volatile database using 'ctdb detach'. @@ -65,8 +66,8 @@ DatabaseMaxDead Default: 5 - How many dead records per hashchain in the TDB database do we - allow before the freelist needs to be processed. + Maximum number of dead records per hash chain for the tdb databses + managed by ctdb. @@ -74,10 +75,9 @@ DBRecordCountWarn Default: 100000 - When set to non-zero, ctdb will log a warning when we try - to recover a database with more than this many records. This - will produce a warning if a database grows uncontrollably with - orphaned records. + When set to non-zero, ctdb will log a warning during recovery if + a database has more than this many records. This will produce a + warning if a database grows uncontrollably with orphaned records. @@ -85,10 +85,9 @@ DBRecordSizeWarn Default: 10000000 - When set to non-zero, ctdb will log a warning when we try to - recover a database where a single record is bigger than this. This - will produce a warning if a database record grows uncontrollably - with orphaned sub-records. + When set to non-zero, ctdb will log a warning during recovery + if a single record is bigger than this size. This will produce + a warning if a database record grows uncontrollably. @@ -96,8 +95,8 @@ DBSizeWarn Default: 1000000000 - When set to non-zero, ctdb will log a warning when we try to - recover a database bigger than this. This will produce a warning + When set to non-zero, ctdb will log a warning during recovery if + a database size is bigger than this. This will produce a warning if a database grows uncontrollably. @@ -108,7 +107,7 @@ When databases are frozen we do not allow clients to attach to the databases. Instead of returning an error immediately to the - application the attach request from the client is deferred until + client, the attach request from the client is deferred until the database becomes available again at which stage we respond to the client. @@ -122,10 +121,10 @@ DeterministicIPs Default: 0 - When enabled, this tunable makes ctdb try to keep public IP - addresses locked to specific nodes as far as possible. This makes - it easier for debugging since you can know that as long as all - nodes are healthy public IP X will always be hosted by node Y. + When set to 1, ctdb will try to keep public IP addresses locked + to specific nodes as far as possible. This makes it easier + for debugging since you can know that as long as all nodes are + healthy public IP X will always be hosted by node Y. The cost of using deterministic IP address assignment is that it @@ -140,15 +139,15 @@ DisableIPFailover Default: 0 - When enabled, ctdb will not perform failover or failback. Even - if a node fails while holding public IPs, ctdb will not recover - the IPs or assign them to another node. + When set to non-zero, ctdb will not perform failover or + failback. Even if a node fails while holding public IPs, ctdb + will not recover the IPs or assign them to another node. - When you enable this tunable, CTDB will no longer attempt + When this tunable is enabled, ctdb will no longer attempt to recover the cluster by failing IP addresses over to other nodes. This leads to a service outage until the administrator - has manually performed failover to replacement nodes using the + has manually performed IP failover to replacement nodes using the 'ctdb moveip' command. @@ -157,9 +156,10 @@ ElectionTimeout Default: 3 - When electing a new recovery master, this is how many seconds - we allow the election to take before we either deem the election - finished or we fail the election and start a new one. + The number of seconds to wait for the election of recovery + master to complete. If the election is not completed during this + interval, then that round of election fails and ctdb starts a + new election. @@ -167,7 +167,10 @@ EnableBans Default: 1 - When set to 0, this disables BANNING completely in the cluster + This parameter allows ctdb to ban a node if the node is misbehaving. + + + When set to 0, this disables banning completely in the cluster and thus nodes can not get banned, even it they break. Don't set to 0 unless you know what you are doing. You should set this to the same value on all nodes to avoid unexpected behaviour. @@ -193,25 +196,20 @@ FetchCollapse Default: 1 + + This parameter is used to avoid multiple migration requests for + the same record from a single node. All the record requests for + the same record are queued up and processed when the record is + migrated to the current node. + When many clients across many nodes try to access the same record at the same time this can lead to a fetch storm where the record becomes very active and bounces between nodes very fast. This leads to high CPU utilization of the ctdbd daemon, trying to bounce that record around very fast, and poor performance. - - - This parameter is used to activate a fetch-collapse. A - fetch-collapse is when we track which records we have requests in - flight so that we only keep one request in flight from a certain - node, even if multiple smbd processes are attemtping to fetch - the record at the same time. This can improve performance and - reduce CPU utilization for certain workloads. - - - This timeout controls if we should collapse multiple fetch - operations of the same record into a single request and defer - all duplicates or not. + This can improve performance and reduce CPU utilization for + certain workloads. @@ -219,18 +217,18 @@ HopcountMakeSticky Default: 50 - If the database is set to 'STICKY' mode, using the 'ctdb - setdbsticky' command, any record that is seen as very hot and - migrating so fast that hopcount surpasses 50 is set to become a - STICKY record for StickyDuration seconds. This means that after - each migration the record will be kept on the node and prevented - from being migrated off the node. + For database(s) marked STICKY (using 'ctdb setdbsticky'), + any record that is migrating so fast that hopcount + exceeds this limit is marked as STICKY record for + StickyDuration seconds. This means that + after each migration the sticky record will be kept on the node + StickyPindownmilliseconds and prevented from + being migrated off the node. - This setting allows one to try to identify such records and - stop them from migrating across the cluster so fast. This will - improve performance for certain workloads, such as locking.tdb - if many clients are opening/closing the same file concurrently. + This will improve performance for certain workloads, such as + locking.tdb if many clients are opening/closing the same file + concurrently. @@ -251,12 +249,13 @@ a node wait until marking the peer as DISCONNECTED. - If a node has hung, it can thus take - KeepaliveInterval*(KeepaliveLimit+1) seconds before we determine - that the node is DISCONNECTED and that we require a recovery. This - limitshould not be set too high since we want a hung node to be - detectec, and expunged from the cluster well before common CIFS - timeouts (45-90 seconds) kick in. + If a node has hung, it can take + KeepaliveInterval * + (KeepaliveLimit + 1) seconds before + ctdb determines that the node is DISCONNECTED and performs + a recovery. This limit should not be set too high to enable + early detection and avoid any application timeouts (e.g. SMB1) + to kick in before the fail over is completed. @@ -264,8 +263,7 @@ LCP2PublicIPs Default: 1 - When enabled this switches ctdb to use the LCP2 ip allocation - algorithm. + When set to 1, ctdb uses the LCP2 ip allocation algorithm. @@ -273,11 +271,11 @@ LogLatencyMs Default: 0 - When set to non-zero, this will make the main daemon log any - operation that took longer than this value, in 'ms', to complete. - These include "how long time a lockwait child process needed", - "how long time to write to a persistent database" but also "how - long did it take to get a response to a CALL from a remote node". + When set to non-zero, ctdb will log if certains operations + take longer than this value, in milliseconds, to complete. + These operations include "process a record request from client", + "take a record or database lock", "update a persistent database + record" and "vaccum a database". @@ -285,7 +283,7 @@ MonitorInterval Default: 15 - How often should ctdb run the event scripts in seconds to check + How often should ctdb run the 'monitor' event in seconds to check for a node's health. @@ -294,7 +292,7 @@ MonitorTimeoutCount Default: 20 - How many monitor events in a row need to timeout before a node + How many 'monitor' events in a row need to timeout before a node is flagged as UNHEALTHY. This setting is useful if scripts can not be written so that they do not hang for benign reasons. @@ -305,9 +303,9 @@ Default: 0 When set to 1, ctdb will not perform failback of IP addresses - when a node becomes healthy. Ctdb WILL perform failover of public - IP addresses when a node becomes UNHEALTHY, but when the node - becomes HEALTHY again, ctdb will not fail the addresses back. + when a node becomes healthy. When a node becomes UNHEALTHY, + ctdb WILL perform failover of public IP addresses, but when the + node becomes HEALTHY again, ctdb will not fail the addresses back. Use with caution! Normally when a node becomes available to the @@ -317,7 +315,7 @@ approximately the same number of public addresses it hosts. - When you enable this tunable, CTDB will no longer attempt to + When you enable this tunable, ctdb will no longer attempt to rebalance the cluster by failing IP addresses back to the new nodes. An unbalanced cluster will therefore remain unbalanced until there is manual intervention from the administrator. When @@ -330,11 +328,11 @@ NoIPHostOnAllDisabled Default: 0 - If no nodes are healthy then by default ctdb will happily host + If no nodes are HEALTHY then by default ctdb will happily host public IPs on disabled (unhealthy or administratively disabled) nodes. This can cause problems, for example if the underlying cluster filesystem is not mounted. When set to 1 on a node and - that node is disabled it, any IPs hosted by this node will be + that node is disabled, any IPs hosted by this node will be released and the node will not takeover any IPs until it is no longer disabled. @@ -367,7 +365,9 @@ If the main dameon has not heard a "ping" from the recovery dameon for this many seconds, the main dameon will log a message that - the recovery daemon is potentially hung. + the recovery daemon is potentially hung. This also increments a + counter which is checked against RecdFailCount + for detection of hung recovery daemon. @@ -378,7 +378,7 @@ When using a reclock file for split brain prevention, if set to non-zero this tunable will make the recovery dameon log a message if the fcntl() call to lock/testlock the recovery file - takes longer than this number of ms. + takes longer than this number of milliseconds. @@ -386,9 +386,8 @@ RecoverInterval Default: 1 - How frequently in seconds should the recovery daemon perform - the consistency checks that determine if we need to perform a - recovery or not. + How frequently in seconds should the recovery daemon perform the + consistency checks to determine if it should perform a recovery. @@ -415,7 +414,7 @@ RecoverTimeout - Default: 20 + Default: 120 This is the default setting for timeouts for controls when sent from the recovery daemon. We allow longer control timeouts from @@ -429,12 +428,14 @@ RecoveryBanPeriod Default: 300 - If a node becomes banned causing repetitive recovery failures. The - node will eventually become banned from the cluster. This - controls how long the culprit node will be banned from the - cluster before it is allowed to try to join the cluster again. - Don't set to small. A node gets banned for a reason and it is - usually due to real problems with the node. + The duration in seconds for which a node is banned if the node + fails during recovery. After this time has elapsed the node will + automatically get unbanned and will attempt to rejoin the cluster. + + + A node usually gets banned due to real problems with the node. + Don't set this value too small. Otherwise, a problematic node + will try to re-join cluster too soon causing unnecessary recoveries. @@ -442,8 +443,9 @@ RecoveryDropAllIPs Default: 120 - If we have been stuck in recovery, or stopped, or banned, mode for - this many seconds we will force drop all held public addresses. + If a node is stuck in recovery, or stopped, or banned, for this + many seconds, then ctdb will release all public addresses on + that node. @@ -452,9 +454,9 @@ Default: 120 During recoveries, if a node has not caused recovery failures - during the last grace period, any records of transgressions that - the node has caused recovery failures will be forgiven. This - resets the ban-counter back to zero for that node. + during the last grace period in seconds, any records of + transgressions that the node has caused recovery failures will be + forgiven. This resets the ban-counter back to zero for that node. @@ -463,8 +465,8 @@ Default: 10000 During vacuuming, if the number of freelist records are more than - RepackLimit, then databases are repacked to - get rid of the freelist records to avoid fragmentation. + RepackLimit, then the database is repacked + to get rid of the freelist records to avoid fragmentation. Databases are repacked only if both RepackLimit @@ -477,7 +479,7 @@ Default: 10 Once a recovery has completed, no additional recoveries are - permitted until this timeout has expired. + permitted until this timeout in seconds has expired. @@ -485,14 +487,13 @@ Samba3AvoidDeadlocks Default: 0 - Enable code that prevents deadlocks with Samba (only for Samba - 3.x). - - - This should be set to 1 when using Samba version 3.x to enable - special code in CTDB to avoid deadlock with Samba version 3.x. - This code is not required for Samba version 4.x and must not be - enabled for Samba 4.x. + If set to non-zero, enable code that prevents deadlocks with Samba + (only for Samba 3.x). + + This should be set to 1 only when using Samba version 3.x + to enable special code in ctdb to avoid deadlock with Samba + version 3.x. This code is not required for Samba version 4.x + and must not be enabled for Samba 4.x. @@ -506,9 +507,9 @@ number is increased. - This tunable is used to specify in 'ms' how frequently ctdb - will send out updates to remote nodes to inform them that the - sequence number is increased. + This tunable is used to specify in milliseconds how frequently + ctdb will send out updates to remote nodes to inform them that + the sequence number is increased. @@ -525,9 +526,8 @@ StickyDuration Default: 600 - Once a record has been found to be fetch-lock hot and has been - flagged to become STICKY, this is for how long, in seconds, - the record will be flagged as a STICKY record. + Once a record has been marked STICKY, this is the duration in + seconds, the record will be flagged as a STICKY record. @@ -536,9 +536,9 @@ Default: 200 Once a STICKY record has been migrated onto a node, it will be - pinned down on that node for this number of ms. Any request from - other nodes to migrate the record off the node will be deferred - until the pindown timer expires. + pinned down on that node for this number of milliseconds. Any + request from other nodes to migrate the record off the node will + be deferred. @@ -546,8 +546,8 @@ TakeoverTimeout Default: 9 - This is how many seconds we allow controls to take for IP - failover events. + This is the duration in seconds in which ctdb tries to complete IP + failover. @@ -555,8 +555,8 @@ TickleUpdateInterval Default: 20 - How often will ctdb record and store the "tickle" information - used to kickstart stalled tcp connections after a recovery. + Every TickleUpdateInterval seconds, ctdb + synchronizes the client connection information across nodes. @@ -564,9 +564,9 @@ TraverseTimeout Default: 20 - This setting controls how long we allow a traverse process to run. - After this timeout triggers, the main ctdb daemon will abort - the traverse if it has not yet finished. + This is the duration in seconds for which a database traverse + is allowed to run. If the traverse does not complete during + this interval, ctdb will abort the traverse. @@ -574,12 +574,11 @@ VacuumFastPathCount Default: 60 - When a record is deleted, it is marked for deletion during - vacuuming. Vacuuming process usually processes this list to - purge the records from the database. If the number of records - marked for deletion are more than VacuumFastPathCount, then - vacuuming process will scan the complete database for empty - records instead of using the list of records marked for deletion. + During a vacuuming run, ctdb usually processes only the records + marked for deletion also called the fast path vacuuming. After + finishing VacuumFastPathCount number of fast + path vacuuming runs, ctdb will trigger a scan of complete database + for any empty records that need to be deleted. @@ -620,9 +619,9 @@ VerboseMemoryNames Default: 0 - This feature consumes additional memory. when used the talloc - library will create more verbose names for all talloc allocated - objects. + When set to non-zero, ctdb assigns verbose names for some of + the talloc allocated memory objects. These names are visible + in the talloc memory report generated by 'ctdb dumpmemory'.