diff --git a/doc/sphinx/Pacemaker_Explained/ap-samples.rst b/doc/sphinx/Pacemaker_Explained/ap-samples.rst index cbebe404be..641affc96e 100644 --- a/doc/sphinx/Pacemaker_Explained/ap-samples.rst +++ b/doc/sphinx/Pacemaker_Explained/ap-samples.rst @@ -1,156 +1,148 @@ Sample Configurations --------------------- -.. Convert_to_RST: +Empty +##### - [appendix] - - - === Empty === - - .An Empty Configuration - ======= - [source,XML] - ------- - - - - - - - - - - ------- - ======= +.. topic:: An Empty Configuration + + .. code-block:: xml + + + + + + + + + + - === Simple === +Simple +###### - .A simple configuration with two nodes, some cluster options and a resource - ======= - [source,XML] - ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ------- - ======= +.. topic:: A simple configuration with two nodes, some cluster options and a resource + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - In the above example, we have one resource (an IP address) that we check - every five minutes and will run on host +c001n01+ until either the - resource fails 10 times or the host shuts down. +In the above example, we have one resource (an IP address) that we check +every five minutes and will run on host ``c001n01`` until either the +resource fails 10 times or the host shuts down. - === Advanced Configuration === +Advanced Configuration +###################### - .An advanced configuration with groups, clones and STONITH - ======= - [source,XML] - ------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ------- - ======= +.. topic:: An advanced configuration with groups, clones and STONITH + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/sphinx/Pacemaker_Explained/status.rst b/doc/sphinx/Pacemaker_Explained/status.rst index de55642515..800426752d 100644 --- a/doc/sphinx/Pacemaker_Explained/status.rst +++ b/doc/sphinx/Pacemaker_Explained/status.rst @@ -1,375 +1,375 @@ +.. index:: + single: status + single: XML element, status + Status -- Here be dragons ------------------------- -.. Convert_to_RST: - - Most users never need to understand the contents of the status section - and can be happy with the output from `crm_mon`. - - However for those with a curious inclination, this section attempts to - provide an overview of its contents. +Most users never need to understand the contents of the status section +and can be happy with the output from ``crm_mon``. + +However for those with a curious inclination, this section attempts to +provide an overview of its contents. + +.. index:: + single: node; status - == Node Status == - - indexterm:[Node,Status] - indexterm:[Status of a Node] - - In addition to the cluster's configuration, the CIB holds an - up-to-date representation of each cluster node in the +status+ section. - - .A bare-bones status entry for a healthy node *cl-virt-1* - ====== - [source,XML] - ----- - - - - - ----- - ====== - - Users are highly recommended _not_ to modify any part of a node's - state _directly_. The cluster will periodically regenerate the entire - section from authoritative sources, so any changes should be done - with the tools appropriate to those sources. - - .Authoritative Sources for State Information - [width="95%",cols="1m,<1",options="header",align="center"] - |========================================================= - - | CIB Object | Authoritative Source - - |node_state|pacemaker-controld - - |transient_attributes|pacemaker-attrd +Node Status +########### - |lrm|pacemaker-execd - - |========================================================= - - The fields used in the +node_state+ objects are named as they are - largely for historical reasons and are rooted in Pacemaker's origins - as the resource manager for the older Heartbeat project. They have remained - unchanged to preserve compatibility with older versions. +In addition to the cluster's configuration, the CIB holds an +up-to-date representation of each cluster node in the ``status`` section. + +.. topic:: A bare-bones status entry for a healthy node **cl-virt-1** + + .. code-block:: xml + + + + + + +Users are highly recommended *not* to modify any part of a node's +state *directly*. The cluster will periodically regenerate the entire +section from authoritative sources, so any changes should be done +with the tools appropriate to those sources. - .Node Status Fields - [width="95%",cols="1m,<4",options="header",align="center"] - |========================================================= - - |Field |Description - - - | id | - indexterm:[id,Node Status] - indexterm:[Node,Status,id] - Unique identifier for the node. Corosync-based clusters use a numeric counter. - - | uname | - indexterm:[uname,Node Status] - indexterm:[Node,Status,uname] - The node's name as known by the cluster - - | in_ccm | - indexterm:[in_ccm,Node Status] - indexterm:[Node,Status,in_ccm] - Is the node a member at the cluster communication layer? Allowed values: - +true+, +false+. - - | crmd | - indexterm:[crmd,Node Status] - indexterm:[Node,Status,crmd] - Is the node a member at the pacemaker layer? Allowed values: +online+, - +offline+. - - | crm-debug-origin | - indexterm:[crm-debug-origin,Node Status] - indexterm:[Node,Status,crm-debug-origin] - The name of the source function that made the most recent change (for debugging - purposes). - - | join | - indexterm:[join,Node Status] - indexterm:[Node,Status,join] - Does the node participate in hosting resources? Allowed values: +down+, - +pending+, +member+, +banned+. - - | expected | - indexterm:[expected,Node Status] - indexterm:[Node,Status,expected] - Expected value for +join+. - - |========================================================= - - The cluster uses these fields to determine whether, at the node level, the - node is healthy or is in a failed state and needs to be fenced. - - == Transient Node Attributes == - - Like regular <>, the name/value - pairs listed in the +transient_attributes+ section help to describe the - node. However they are forgotten by the cluster when the node goes offline. - This can be useful, for instance, when you want a node to be in standby mode - (not able to run resources) just until the next reboot. +.. table:: **Authoritative Sources for State Information** + + +----------------------+----------------------+ + | CIB Object | Authoritative Source | + +======================+======================+ + | node_state | pacemaker-controld | + +----------------------+----------------------+ + | transient_attributes | pacemaker-attrd | + +----------------------+----------------------+ + | lrm | pacemaker-execd | + +----------------------+----------------------+ + +The fields used in the ``node_state`` objects are named as they are +largely for historical reasons and are rooted in Pacemaker's origins +as the resource manager for the older Heartbeat project. They have remained +unchanged to preserve compatibility with older versions. - In addition to any values the administrator sets, the cluster will - also store information about failed resources here. +.. table:: **Node Status Fields** + + +------------------+----------------------------------------------------------+ + | Field | Description | + +==================+==========================================================+ + | id | .. index: | + | | single: id; node status | + | | single: node; status, id | + | | | + | | Unique identifier for the node. Corosync-based clusters | + | | use a numeric counter. | + +------------------+----------------------------------------------------------+ + | uname | .. index:: | + | | single: uname; node status | + | | single: node; status, uname | + | | | + | | The node's name as known by the cluster | + +------------------+----------------------------------------------------------+ + | in_ccm | .. index:: | + | | single: in_ccm; node status | + | | single: node; status, in_ccm | + | | | + | | Is the node a member at the cluster communication later? | + | | Allowed values: ``true``, ``false``. | + +------------------+----------------------------------------------------------+ + | crmd | .. index:: | + | | single: crmd; node status | + | | single: node; status, crmd | + | | | + | | Is the node a member at the pacemaker layer? Allowed | + | | values: ``online``, ``offline``. | + +------------------+----------------------------------------------------------+ + | crm-debug-origin | .. index:: | + | | single: crm-debug-origin; node status | + | | single: node; status, crm-debug-origin | + | | | + | | The name of the source function that made the most | + | | recent change (for debugging purposes). | + +------------------+----------------------------------------------------------+ + | join | .. index:: | + | | single: join; node status | + | | single: node; status, join | + | | | + | | Does the node participate in hosting resources? | + | | Allowed values: ``down``, ``pending``, ``member``. | + | | ``banned``. | + +------------------+----------------------------------------------------------+ + | expected | .. index:: | + | | single: expected; node status | + | | single: node; status, expected | + | | | + | | Expected value for ``join``. | + +------------------+----------------------------------------------------------+ + +The cluster uses these fields to determine whether, at the node level, the +node is healthy or is in a failed state and needs to be fenced. + +Transient Node Attributes +######################### + +Like regular :ref:`Node Attributes`, the name/value +pairs listed in the ``transient_attributes`` section help to describe the +node. However they are forgotten by the cluster when the node goes offline. +This can be useful, for instance, when you want a node to be in standby mode +(not able to run resources) just until the next reboot. + +In addition to any values the administrator sets, the cluster will +also store information about failed resources here. - .A set of transient node attributes for node *cl-virt-1* - ====== - [source,XML] - ----- - - - - - - - - - ----- - ====== - - In the above example, we can see that a monitor on the +pingd:0+ resource has - failed once, at 09:22:22 UTC 6 April 2009. - footnote:[ - You can use the standard `date` command to print a human-readable version of - any seconds-since-epoch value, for example `date -d @1239009742`. - ] - We also see that the node is connected to three *pingd* peers and that - all known resources have been checked for on this machine (+probe_complete+). +.. topic:: A set of transient node attributes for node **cl-virt-1** + + .. code-block:: xml + + + + + + + + + + +In the above example, we can see that a monitor on the ``pingd:0`` resource has +failed once, at 09:22:22 UTC 6 April 2009. [#]_. + +We also see that the node is connected to three **pingd** peers and that +all known resources have been checked for on this machine (``probe_complete``). - == Operation History == - indexterm:[Operation History] - - A node's resource history is held in the +lrm_resources+ tag (a child - of the +lrm+ tag). The information stored here includes enough - information for the cluster to stop the resource safely if it is - removed from the +configuration+ section. Specifically, the resource's - +id+, +class+, +type+ and +provider+ are stored. - - .A record of the +apcstonith+ resource - ====== - [source,XML] - - ====== - - Additionally, we store the last job for every combination of - +resource+, +action+ and +interval+. The concatenation of the values in - this tuple are used to create the id of the +lrm_rsc_op+ object. - - .Contents of an +lrm_rsc_op+ job - [width="95%",cols="2m,<5",options="header",align="center"] - |========================================================= - - |Field - |Description - - | id | - indexterm:[id,Action Status] - indexterm:[Action,Status,id] - - Identifier for the job constructed from the resource's +id+, - +operation+ and +interval+. - - | call-id | - indexterm:[call-id,Action Status] - indexterm:[Action,Status,call-id] - - The job's ticket number. Used as a sort key to determine the order in - which the jobs were executed. - - | operation | - indexterm:[operation,Action Status] - indexterm:[Action,Status,operation] - - The action the resource agent was invoked with. - - | interval | - indexterm:[interval,Action Status] - indexterm:[Action,Status,interval] - - The frequency, in milliseconds, at which the operation will be - repeated. A one-off job is indicated by 0. - - | op-status | - indexterm:[op-status,Action Status] - indexterm:[Action,Status,op-status] - - The job's status. Generally this will be either 0 (done) or -1 - (pending). Rarely used in favor of +rc-code+. - - | rc-code | - indexterm:[rc-code,Action Status] - indexterm:[Action,Status,rc-code] - - The job's result. Refer to the 'Resource Agents' chapter of 'Pacemaker - Administration' for details on what the values here mean and how they are - interpreted. - - | last-run | - indexterm:[last-run,Action Status] - indexterm:[Action,Status,last-run] - - Machine-local date/time, in seconds since epoch, - at which the job was executed. For diagnostic purposes. - - | last-rc-change | - indexterm:[last-rc-change,Action Status] - indexterm:[Action,Status,last-rc-change] - - Machine-local date/time, in seconds since epoch, - at which the job first returned the current value of +rc-code+. - For diagnostic purposes. - - | exec-time | - indexterm:[exec-time,Action Status] - indexterm:[Action,Status,exec-time] - - Time, in milliseconds, that the job was running for. - For diagnostic purposes. - - | queue-time | - indexterm:[queue-time,Action Status] - indexterm:[Action,Status,queue-time] - - Time, in seconds, that the job was queued for in the LRMd. - For diagnostic purposes. - - | crm_feature_set | - indexterm:[crm_feature_set,Action Status] - indexterm:[Action,Status,crm_feature_set] - - The version which this job description conforms to. Used when - processing +op-digest+. - - | transition-key | - indexterm:[transition-key,Action Status] - indexterm:[Action,Status,transition-key] - - A concatenation of the job's graph action number, the graph number, - the expected result and the UUID of the controller instance that scheduled - it. This is used to construct +transition-magic+ (below). - - | transition-magic | - indexterm:[transition-magic,Action Status] - indexterm:[Action,Status,transition-magic] - - A concatenation of the job's +op-status+, +rc-code+ and - +transition-key+. Guaranteed to be unique for the life of the cluster - (which ensures it is part of CIB update notifications) and contains - all the information needed for the controller to correctly analyze and - process the completed job. Most importantly, the decomposed elements - tell the controller if the job entry was expected and whether it failed. - - | op-digest | - indexterm:[op-digest,Action Status] - indexterm:[Action,Status,op-digest] - - An MD5 sum representing the parameters passed to the job. Used to - detect changes to the configuration, to restart resources if - necessary. - - | crm-debug-origin | - indexterm:[crm-debug-origin,Action Status] - indexterm:[Action,Status,crm-debug-origin] - - The origin of the current values. - For diagnostic purposes. - - |========================================================= - - === Simple Operation History Example === - - .A monitor operation (determines current state of the +apcstonith+ resource) - ====== - [source,XML] - ----- - - - - ----- - ====== - - In the above example, the job is a non-recurring monitor operation - often referred to as a "probe" for the +apcstonith+ resource. +.. index:: + single: Operation History + +Operation History +################# + +A node's resource history is held in the ``lrm_resources`` tag (a child +of the ``lrm`` tag). The information stored here includes enough +information for the cluster to stop the resource safely if it is +removed from the ``configuration`` section. Specifically, the resource's +``id``, ``class``, ``type`` and ``provider`` are stored. + +.. topic:: A record of the ``apcstonith`` resource + + .. code-block:: xml + + - The cluster schedules probes for every configured resource on a node when - the node first starts, in order to determine the resource's current state - before it takes any further action. +Additionally, we store the last job for every combination of +``resource``, ``action`` and ``interval``. The concatenation of the values in +this tuple are used to create the id of the ``lrm_rsc_op`` object. + +.. table:: **Contents of an lrm_rsc_op job** + + +------------------+----------------------------------------------------------+ + | Field | Description | + +==================+==========================================================+ + | id | .. index:: | + | | single: id; action status | + | | single: action; status, id | + | | | + | | Identifier for the job constructed from the resource's | + | | ``operation`` and ``interval``. | + +------------------+----------------------------------------------------------+ + | call-id | .. index:: | + | | single: call-id; action status | + | | single: action; status, call-id | + | | | + | | The job's ticket number. Used as a sort key to determine | + | | the order in which the jobs were executed. | + +------------------+----------------------------------------------------------+ + | operation | .. index:: | + | | single: operation; action status | + | | single: action; status, operation | + | | | + | | The action the resource agent was invoked with. | + +------------------+----------------------------------------------------------+ + | interval | .. index:: | + | | single: interval; action status | + | | single: action; status, interval | + | | | + | | The frequency, in milliseconds, at which the operation | + | | will be repeated. A one-off job is indicated by 0. | + +------------------+----------------------------------------------------------+ + | op-status | .. index:: | + | | single: op-status; action status | + | | single: action; status, op-status | + | | | + | | The job's status. Generally this will be either 0 (done) | + | | or -1 (pending). Rarely used in favor of ``rc-code``. | + +------------------+----------------------------------------------------------+ + | rc-code | .. index:: | + | | single: rc-code; action status | + | | single: action; status, rc-code | + | | | + | | The job's result. Refer to the *Resource Agents* chapter | + | | of *Pacemaker Administration* for details on what the | + | | values here mean and how they are interpreted. | + +------------------+----------------------------------------------------------+ + | last-run | .. index:: | + | | single: last-run; action status | + | | single: action; status, last-run | + | | | + | | Machine-local date/time, in seconds since epoch, at | + | | which the job was executed. For diagnostic purposes. | + +------------------+----------------------------------------------------------+ + | last-rc-change | .. index:: | + | | single: last-rc-change; action status | + | | single: action; status, last-rc-change | + | | | + | | Machine-local date/time, in seconds since epoch, at | + | | which the job first returned the current value of | + | | ``rc-code``. For diagnostic purposes. | + +------------------+----------------------------------------------------------+ + | exec-time | .. index:: | + | | single: exec-time; action status | + | | single: action; status, exec-time | + | | | + | | Time, in milliseconds, that the job was running for. | + | | For diagnostic purposes. | + +------------------+----------------------------------------------------------+ + | queue-time | .. index:: | + | | single: queue-time; action status | + | | single: action; status, queue-time | + | | | + | | Time, in seconds, that the job was queued for in the | + | | LRMd. For diagnostic purposes. | + +------------------+----------------------------------------------------------+ + | crm_feature_set | .. index:: | + | | single: crm_feature_set; action status | + | | single: action; status, crm_feature_set | + | | | + | | The version which this job description conforms to. Used | + | | when processing ``op-digest``. | + +------------------+----------------------------------------------------------+ + | transition-key | .. index:: | + | | single: transition-key; action status | + | | single: action; status, transition-key | + | | | + | | A concatenation of the job's graph action number, the | + | | graph number, the expected result and the UUID of the | + | | controller instance that scheduled it. This is used to | + | | construct ``transition-magic`` (below). | + +------------------+----------------------------------------------------------+ + | transition-magic | .. index:: | + | | single: transition-magic; action status | + | | single: action; status, transition-magic | + | | | + | | A concatenation of the job's ``op-status``, ``rc-code`` | + | | and ``transition-key``. Guaranteed to be unique for the | + | | life of the cluster (which ensures it is part of CIB | + | | update notifications) and contains all the information | + | | needed for the controller to correctly analyze and | + | | process the completed job. Most importantly, the | + | | decomposed elements tell the controller if the job | + | | entry was expected and whether it failed. | + +------------------+----------------------------------------------------------+ + | op-digest | .. index:: | + | | single: op-digest; action status | + | | single: action; status, op-digest | + | | | + | | An MD5 sum representing the parameters passed to the | + | | job. Used to detect changes to the configuration, to | + | | restart resources if necessary. | + +------------------+----------------------------------------------------------+ + | crm-debug-origin | .. index:: | + | | single: crm-debug-origin; action status | + | | single: action; status, crm-debug-origin | + | | | + | | The origin of the current values. For diagnostic | + | | purposes. | + +------------------+----------------------------------------------------------+ + +Simple Operation History Example +________________________________ - From the +transition-key+, we can see that this was the 22nd action of - the 2nd graph produced by this instance of the controller - (2668bbeb-06d5-40f9-936d-24cb7f87006a). - - The third field of the +transition-key+ contains a 7, which indicates - that the job expects to find the resource inactive. By looking at the +rc-code+ - property, we see that this was the case. - - As that is the only job recorded for this node, we can conclude that - the cluster started the resource elsewhere. +.. topic:: A monitor operation (determines current state of the ``apcstonith`` resource) + + .. code-block:: xml + + + + + +In the above example, the job is a non-recurring monitor operation +often referred to as a "probe" for the ``apcstonith`` resource. + +The cluster schedules probes for every configured resource on a node when +the node first starts, in order to determine the resource's current state +before it takes any further action. + +From the ``transition-key``, we can see that this was the 22nd action of +the 2nd graph produced by this instance of the controller +(2668bbeb-06d5-40f9-936d-24cb7f87006a). + +The third field of the ``transition-key`` contains a 7, which indicates +that the job expects to find the resource inactive. By looking at the ``rc-code`` +property, we see that this was the case. + +As that is the only job recorded for this node, we can conclude that +the cluster started the resource elsewhere. - === Complex Operation History Example === +Complex Operation History Example +_________________________________ - .Resource history of a +pingd+ clone with multiple jobs - ====== - [source,XML] - ----- - - - - - - - ----- - ====== - - When more than one job record exists, it is important to first sort - them by +call-id+ before interpreting them. - - Once sorted, the above example can be summarized as: - - . A non-recurring monitor operation returning 7 (not running), with a +call-id+ of 3 - . A stop operation returning 0 (success), with a +call-id+ of 32 - . A start operation returning 0 (success), with a +call-id+ of 33 - . A recurring monitor returning 0 (success), with a +call-id+ of 34 - - - The cluster processes each job record to build up a picture of the - resource's state. After the first and second entries, it is - considered stopped, and after the third it considered active. - - Based on the last operation, we can tell that the resource is - currently active. - - Additionally, from the presence of a +stop+ operation with a lower - +call-id+ than that of the +start+ operation, we can conclude that the - resource has been restarted. Specifically this occurred as part of - actions 11 and 31 of transition 11 from the controller instance with the key - +2668bbeb...+. This information can be helpful for locating the - relevant section of the logs when looking for the source of a failure. +.. topic:: Resource history of a ``pingd`` clone with multiple jobs + + .. code-block:: xml + + + + + + + + +When more than one job record exists, it is important to first sort +them by ``call-id`` before interpreting them. + +Once sorted, the above example can be summarized as: + +#. A non-recurring monitor operation returning 7 (not running), with a ``call-id`` of 3 +#. A stop operation returning 0 (success), with a ``call-id`` of 32 +#. A start operation returning 0 (success), with a ``call-id`` of 33 +#. A recurring monitor returning 0 (success), with a ``call-id`` of 34 + +The cluster processes each job record to build up a picture of the +resource's state. After the first and second entries, it is +considered stopped, and after the third it considered active. + +Based on the last operation, we can tell that the resource is +currently active. + +Additionally, from the presence of a ``stop`` operation with a lower +``call-id`` than that of the ``start`` operation, we can conclude that the +resource has been restarted. Specifically this occurred as part of +actions 11 and 31 of transition 11 from the controller instance with the key +``2668bbeb...``. This information can be helpful for locating the +relevant section of the logs when looking for the source of a failure. + +.. [#] You can use the standard ``date`` command to print a human-readable version + of any seconds-since-epoch value, for example ``date -d @1239009742``.