Provided by: cman_3.1.7-0ubuntu2_amd64 bug

NAME

       cman_tool - Cluster Management Tool

SYNOPSIS

       cman_tool  join  |  leave  |  kill  | expected | votes | version | wait | status | nodes |
       services | debug [options]

DESCRIPTION

       cman_tool is a program that manages the cluster management subsystem CMAN.  cman_tool  can
       be  used  to  join  the node to a cluster, leave the cluster, kill another cluster node or
       change the value of expected votes of a cluster.
       Be careful that you understand the consequences of the commands issued  via  cman_tool  as
       they  can  affect  all  nodes in your cluster. Most of the time the cman_tool will only be
       invoked from your startup and shutdown scripts.

SUBCOMMANDS

       join   This is the main use of cman_tool. It instructs the cluster manager to  attempt  to
              join  an existing cluster or (if no existing cluster exists) then to form a new one
              on its own.
              If no options are given to this command then it will take the cluster configuration
              information  from  cluster.conf.  However,  it  is  possible  to  provide  all  the
              information on the command-line or to override cluster.conf  values  by  using  the
              command line.

       leave  Tells  CMAN  to  leave  the cluster. You cannot do this if there are subsystems (eg
              DLM, GFS) active. You should dismount all GFS filesystems,  shutdown  CLVM,  fenced
              and  anything else using the cluster manager before using cman_tool leave.  Look at
              'cman_tool status' and group_tool to  see  how  many  (and  which)  subsystems  are
              active.
              When a node leaves the cluster, the remaining nodes recalculate quorum and this may
              block cluster activity if the required number of votes is  not  present.   If  this
              node  is to be down for an extended period of time and you need to keep the cluster
              running, add the remove option, and the remaining  nodes  will  recalculate  quorum
              such that activity can continue.

       kill   Tells  CMAN  to kill another node in the cluster. This will cause the local node to
              send a "KILL" message to that node and it will shut down.  Recovery will occur  for
              the  killed  node  as if it had failed.  This is a sort of remote version of "leave
              force" so only use if if you really know what you are doing.

       expected
              Tells CMAN a new value of expected votes and instructs  it  to  recalculate  quorum
              based on this value.
              The  recalculation takes into account the number of currently active nodes, so this
              option should not be used in an attempt to artificially lower the quorum  value  in
              advance  of  a  planned  shutdown  of cluster nodes.  Instead, the 'cman_tool leave
              remove' command should be used (see the 'leave' subcommand above).
              Use this option if your cluster has lost quorum due to nodes failing and  you  need
              to get it running again in a hurry.

       version
              Used  alone  this  will  report the major, minor, patch and config versions used by
              CMAN (also displayed in 'cman_tool status'). It can also be used with  -r  to  tell
              cluster members to update the cluster configuration.
              If  -r is specified, cman will read the configuration file, validate it, distribute
              it around the cluster (if necessary) an  activate  it.   See  the  VERSION  OPTIONS
              section below for additional options to the version command.

       wait   Waits until the node is a member of the cluster and then returns.

       status Displays the local view of the cluster status.

       nodes  Displays the local view of the cluster nodes.

       services
              Displays  the local view of subsystems using cman (deprecated, group_tool should be
              used instead).

       debug  Sets the debug level of the running cman daemon.  Debug  output  will  be  sent  to
              syslog  level LOG_DEBUG. the -d switch specifies the new logging level. This is the
              same bitmask used for cman_tool join -d

LEAVE OPTIONS

       -w     Normally, "cman_tool leave" will fail if the cluster is in transition  (ie  another
              node is joining or leaving the cluster). By adding the -w flag, cman_tool will wait
              and retry the leave operation repeatedly until it succeeds or a more serious  error
              occurs.

       -t <seconds>
              If  -w  is  also specified then -t dictates the maximum amount of time cman_tool is
              prepared to wait. If the operation times out then a status of 2 is returned.

       force  Shuts down the cluster manager without first telling any of the subsystems to close
              down. Use this option with extreme care as it could easily cause data loss.

       remove Tells the rest of the cluster to recalculate quorum such that activity can continue
              without this node.

EXPECTED OPTIONS

       -e <expected-votes>
              The new value of expected votes to use. This will usually be enough  to  bring  the
              cluster back to life. Values that would cause incorrect quorum will be rejected.

KILL OPTIONS

       -n <nodename>
              The node name of the node to be killed. This should be the unqualified node name as
              it appears in 'cman_tool nodes'.

VERSION OPTIONS

       -r     Update config version. You don't need to use this when adding a new node,  the  new
              cman  node  will  tell  the  rest  of the cluster to read the latest version of the
              config file automatically.  The version present in the new  configuration  must  be
              higher than the one currently in use by cman.

              cman_tool  version  on its own will always show the current version and not the one
              being looked for. So be aware that the display will possibly not update immediately
              after you have run cman_tool version -r.

       -D<option>
              see "JOIN" options

       -S     By default cman_tool version will try to distribute the new cluster.conf file using
              ccs_sync and ricci. If you have distributed the file yourself and/or  do  not  have
              ricci  installed  then  the  -S  option  will  skip  this  step.  NOTE: it is still
              important that all nodes in the cluster have the same version  of  the  file.  Make
              sure that this is the case before using this option.

WAIT OPTIONS

       -q     Waits  until  the  cluster  is quorate before returning.  -t <seconds> Dictates the
              maximum amount of time cman_tool is prepared to wait.  If the operation  times  out
              then a status of 2 is returned.

JOIN OPTIONS

       -c <clustername>
              Provides  a text name for the cluster. You can have several clusters on one LAN and
              they are distinguished by this name. Note that the name  is  hashed  to  provide  a
              unique  number  which is what actually distinguishes the cluster, so it is possible
              that two different names can clash. If this happens, the node will not  be  allowed
              into  the  existing cluster and you will have to pick another name or use different
              port number for cluster communication.

       -p <port>
              UDP port number used for cluster communication. This defaults to 5405.

       -v <votes>
              Number of votes this node has in the cluster. Defaults to 1.

       -e <expected votes>
              Number of expected  votes  for  the  whole  cluster.  If  different  nodes  provide
              different  values  then  the  highest  is  used. The cluster will only operate when
              quorum is reached - that is more than half the available votes are available to the
              cluster.  The  default for this value is the total number of votes for all nodes in
              the configuration file.

       -2     Sets the cluster up for a special "two node  only"  mode.  Because  of  the  quorum
              requirements  mentioned  above,  a  two-node  cluster cannot be valid.  This option
              tells the cluster manager that there will only ever be two nodes in the cluster and
              relies  on fencing to ensure cluster integrity.  If you specify this you cannot add
              more nodes without taking down the existing cluster and reconfiguring it.  Expected
              votes should be set to 1 for a two-node cluster.

       -n <nodename>
              Overrides  the  node name. By default the unqualified hostname is used. This option
              is also used to specify which interface is used for cluster communication.

       -N <nodeid>
              Overrides the node ID for this node. Normally, nodes are  assigned  a  node  id  in
              cluster.conf.  If  you  specify  an  incorrect  node ID here, the node might not be
              allowed to join the cluster. Setting node IDs in the configuration is a far  better
              way  to  do  this.     Note  that the node's application to join the cluster may be
              rejected if you try to set the nodeid to one that has already been used, or if  the
              node was previously a member of the cluster but with a different nodeid.

       -o <nodename>
              Override  the  name  this  node will have in the cluster. This will normally be the
              hostname or the first name specified by -n.  Note how  this  differs  from  -n:  -n
              tells  cman_tool how to find the host address and/or the entry in the configuration
              file. -o simply changes the name the node will have  in  the  cluster  and  has  no
              bearing on the actual name of the machine. Use this option will extreme caution.

       -m <multicast-address>
              Specifies  a  multicast  address to use for cluster communication. This is required
              for IPv6 operation. You should also specify an ethernet interface to bind  to  this
              multicast address using the -i option.

       -w     Join and wait until the node is a cluster member.

       -q     Join  and  wait until the cluster is quorate.  If the cluster join fails and -w (or
              -q) is specified, then it will be retried. Note that cman_tool cannot tell  whether
              the  cluster  join  was rejected by another node for a good reason or that it timed
              out for some benign reason; so it is strongly recommended that a  timeout  is  also
              given with the wait options to join. If you don't want join to retry on failure but
              do want to wait, use the cman_tool join command without -w  followed  by  cman_tool
              wait.

       -k <keyfile>
              All  traffic  sent  out  by cman/corosync is encrypted. By default the security key
              used is simply the cluster name. If you need more security you can  specify  a  key
              file  that contains the key used to encrypt cluster communications.  Of course, the
              contents of the key file must be the same on all nodes in the cluster. It is up  to
              you to securely copy the file to the nodes.

       -t <seconds>
              If -w or -q is also specified then -t dictates the maximum amount of time cman_tool
              is prepared to wait. If the operation times out then a status  of  2  is  returned.
              Note  that  just because cman_tool has given up, does not mean that cman itself has
              stopped trying to join a cluster.

       -X     Tells cman not to use the configuration file to get cluster information. If you use
              this  option  then cman will apply several defaults to the cluster to get it going.
              The cluster name will be "RHCluster", node IDs will default to the  IP  address  of
              the  node  and  remote node names will show up as Node<nodeid>. All of these, apart
              from the node names can be overridden on the cman_tool command-line if required.
              If you have to set up fence devices, services or anything else in cluster.conf then
              this  option  is probably not worthwhile to you - the extra readability of sensible
              node names and numbers will make it worth using cluster.conf for the  cluster  too.
              But for a simple failover cluster this might save you some effort.
              On  each node using this configuration you will need to have the same authorization
              key installed. To create this key run
              corosync-keygen
              mv /etc/ais/authkey /etc/cluster/cman_authkey
              then copy that file to all nodes you want to join the cluster.

       -C     Overrides  the  default  configuration  module.   Usually   cman   uses   xmlconfig
              (cluster.conf)  to  load its configuration. If you have your configuration database
              held elsewhere (eg LDAP) and have a configuration plugin for it,  then  you  should
              specify  the  name of the module (see the documentation for the module for the name
              of it - it's not necessarily the same as the filename) here.
              It is possible to chain configuration modules by separating them with colons. So to
              add two modules (eg) 'ldapconfig' and 'ldappreproc' to the chain start cman with -C
              ldapconfig:ldappreproc
              The default value for this is 'xmlconfig'. Note that if the -X is on  the  command-
              line then -C will be ignored.

       -A     Don't  load  openais  services. Normally cman_tool join will load the configuration
              module 'openaisserviceenablestable' which  will  load  the  services  installed  by
              openais.   If  you  don't  want to use these services or have not installed openais
              then this switch will disable them.

       -D     Tells cman_tool whether to validate the configuration before loading  or  reloading
              it.  By default the configuration is validated, which is equivalent to -Dfail.
              -Dwarn  will  validate  the  configuration and print any messages arising, but will
              attempt to use it regardless of its validity.
              -Dnone (or just -D) will skip the validation completely.
              The -D switch does not take a space between -D and the parameter. so '-D fail' will
              cause an error. Use -Dfail.

NODES OPTIONS

       -a     Shows the IP address(es) the nodes are communicating on.

       -n <nodename>
              Shows  node  information  for  a specific node. This should be the unqualified node
              name as it appears in 'cman_tool nodes'.

       -F <format>
              Specify the format of the output. The format string may contain one or more  format
              options,  each  separated by a comma. Valid format options include: id, name, type,
              and addr.

DEBUG OPTIONS

       -d<value>
              The value is a bitmask of
              2 Barriers
              4 Membership messages
              8 Daemon operation, including command-line interaction
              16 Interaction with Corosync
              32 Startup debugging (cman_tool join operations only)

NOTES

       the nodes subcommand shows a list of nodes  known  to  cman.  the  state  is  one  of  the
       following:
       M    The node is a member of the cluster
       X    The node is not a member of the cluster
       d    The node is known to the cluster but disallowed access to it.

ENVIRONMENT VARIABLES

       cman_tool  removes most environment variables before forking and running Corosync, as well
       as adding some of its own for setting up configuration parameters that were overridden  on
       the  command-line,  the  exception  to this is that variable with names starting COROSYNC_
       will be passed down intact as they are assumed to be used for configuring the daemon.

DISALLOWED NODES

       Occasionally (but very infrequently I hope) you may see nodes marked  as  "Disallowed"  in
       cman_tool  status  or "d" in cman_tool nodes.  This is a bit of a nasty hack to get around
       mismatch between what the upper layers expect of the cluster manager and corosync.

       If a node experiences a momentary lack of connectivity, but one that  is  long  enough  to
       trigger the token timeouts, then it will be removed from the cluster. When connectivity is
       restored corosync will happily let it rejoin the cluster with no  fuss.  Sadly  the  upper
       layers  don't like this very much. They may (indeed probably will have) have changed their
       internal state while the other node was away and there is no straightforward way to  bring
       the  rejoined  node  up-to-date  with  that  state.  When  this happens the node is marked
       "Disallowed" and is not permitted to take part in cman operations.

       If the remainder of the cluster is quorate the the node will be sent a kill message and it
       will  be  forced to leave the cluster that way. Note that fencing should kick in to remove
       the node permanently anyway, but it may take longer than the network outage  for  this  to
       complete.

       If  the  remainder  of  the cluster is inquorate then we have a problem. The likelihood is
       that we will have two (or more) partitioned clusters and we cannot  decide  which  is  the
       "right"  one.  In  this  case  we  need  to  defer  to the system administrator to kill an
       appropriate selection of nodes to restore the cluster to sensible operation.

       The latter scenario should be very rare and may indicate a bug somewhere in the  code.  If
       the  local  network  is  very  flaky  or  busy it may be necessary to increase some of the
       protocol timeouts for corosync. We are  trying  to  think  of  better  solutions  to  this
       problem.

       Recovering  from  this  state  can,  unfortunately,  be  complicated.  Fortunately, in the
       majority of cases, fencing will do the job for you, and the disallowed state will only  be
       temporary.  If  it persists, the recommended approach it is to do a cman tool nodes on all
       systems in the cluster and determine the largest common subset of  nodes  that  are  valid
       members  to  each other. Then reboot the others and let them rejoin correctly. In the case
       of a single-node disconnection this should be straightforward, with a large  cluster  that
       has experienced a network partition it could get very complicated!

       Example:

       In this example we have a five node cluster that has experienced a network partition. Here
       is the output of cman_tool nodes from all systems:
       Node  Sts   Inc   Joined               Name
          1   M   2372   2007-11-05 02:58:55  node-01.example.com
          2   d   2376   2007-11-05 02:58:56  node-02.example.com
          3   d   2376   2007-11-05 02:58:56  node-03.example.com
          4   M   2376   2007-11-05 02:58:56  node-04.example.com
          5   M   2376   2007-11-05 02:58:56  node-05.example.com

       Node  Sts   Inc   Joined               Name
          1   d   2372   2007-11-05 02:58:55  node-01.example.com
          2   M   2376   2007-11-05 02:58:56  node-02.example.com
          3   M   2376   2007-11-05 02:58:56  node-03.example.com
          4   d   2376   2007-11-05 02:58:56  node-04.example.com
          5   d   2376   2007-11-05 02:58:56  node-05.example.com

       Node  Sts   Inc   Joined               Name
          1   d   2372   2007-11-05 02:58:55  node-01.example.com
          2   M   2376   2007-11-05 02:58:56  node-02.example.com
          3   M   2376   2007-11-05 02:58:56  node-03.example.com
          4   d   2376   2007-11-05 02:58:56  node-04.example.com
          5   d   2376   2007-11-05 02:58:56  node-05.example.com

       Node  Sts   Inc   Joined               Name
          1   M   2372   2007-11-05 02:58:55  node-01.example.com
          2   d   2376   2007-11-05 02:58:56  node-02.example.com
          3   d   2376   2007-11-05 02:58:56  node-03.example.com
          4   M   2376   2007-11-05 02:58:56  node-04.example.com
          5   M   2376   2007-11-05 02:58:56  node-05.example.com

       Node  Sts   Inc   Joined               Name
          1   M   2372   2007-11-05 02:58:55  node-01.example.com
          2   d   2376   2007-11-05 02:58:56  node-02.example.com
          3   d   2376   2007-11-05 02:58:56  node-03.example.com
          4   M   2376   2007-11-05 02:58:56  node-04.example.com
          5   M   2376   2007-11-05 02:58:56  node-05.example.com
       In this scenario we should kill the node node-02  and  node-03.  Of  course,  the  3  node
       cluster  of node-01, node-04 & node-05 should remain quorate and be able to fenced the two
       rejoined nodes anyway, but it is  possible  that  the  cluster  has  a  qdisk  setup  that
       precludes this.

CONFIGURATION SYSTEMS

       This  section  details  how the configuration systems work in cman. You might need to know
       this if you are using the -C option  to  cman_tool,  or  writing  your  own  configuration
       subsystem.
       By  default cman uses two configuration plugins to corosync. The first, 'xmlconfig', reads
       the configuration information  stored  in  cluster.conf  and  stores  it  in  an  internal
       database,   in  the  same  schema  as  it  finds  in  cluster.conf.   The  second  plugin,
       'cmanpreconfig', takes the information in that the database, adds several  cman  defaults,
       determines  the  corosync  node  name  and nodeID and formats the information in a similar
       manner to corosync.conf(5). Corosync then reads those keys to start the cluster  protocol.
       cmanpreconfig  also  reads  several  environment  variables that might be set by cman_tool
       which can override information in the configuration.
       In the absence of xmlconfig, ie when 'cman_tool join' is run with -X switch (this  removes
       xmlconfig from the module list), cmanpreconfig also generates several defaults so that the
       cluster can be got running without any configuration  information  -  see  above  for  the
       details.
       Note  that  cmanpreconfig  will not overwrite corosync keys that are explicitly set in the
       configuration file, allowing you to provide custom values for  token  timeouts  etc,  even
       though  cman  has  its own defaults for some of those values. The exception to this is the
       node name/address and multicast values, which are always taken from the cman configuration
       keys.
       Most  of the extra keys that cmanpreconfig adds are outside of the /cluster/ tree and will
       only be seen if you dump the whole of corosync's object database. However it does add some
       keys  into  /cluster/cman  that  you would not normally see in a normal cluster.conf file.
       These are harmless, though could be confusing. The most obvious of these is the "nodename"
       option  which  is  passed  from  cmanpreconfig  to  the  name  cman  module,  to  save  it
       recalculating the node name again.