Signed-off-by: Jan Friesse <jfriesse@xxxxxxxxxx>
---
corosync.spec.in | 1 +
man/Makefile.am | 3 +-
man/cmap_keys.8 | 326 +++++++++++++++++++++++++++++++++++++++++++++++++++
man/cmap_overview.8 | 5 +-
4 files changed, 333 insertions(+), 2 deletions(-)
create mode 100644 man/cmap_keys.8
diff --git a/corosync.spec.in b/corosync.spec.in
index 7539c32..bac2995 100644
--- a/corosync.spec.in
+++ b/corosync.spec.in
@@ -284,6 +284,7 @@ The Corosync Cluster Engine APIs.
%{_mandir}/man8/sam_overview.8*
%{_mandir}/man3/cmap_*3*
%{_mandir}/man8/cmap_overview.8*Reviewed-by: Steven Dake <sdReviewed-by: Steven Dake <sdake@xxxxxxxxxx>jo bake@xxxxxxxxxx>
+%{_mandir}/man8/cmap_keys.8*
%{_mandir}/man8/quorum_overview.8*
%changelog
diff --git a/man/Makefile.am b/man/Makefile.am
index b4be1c6..c146a97 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -104,7 +104,8 @@ autogen_man = cpg_context_get.3 \
cmap_track_add.3 \
cmap_context_set.3 \
cmap_fd_get.3 \
- cmap_track_delete.3
+ cmap_track_delete.3 \
+ cmap_keys.8
autogen_common = ipc_common.sh.errors
diff --git a/man/cmap_keys.8 b/man/cmap_keys.8
new file mode 100644
index 0000000..77411f8
--- /dev/null
+++ b/man/cmap_keys.8
@@ -0,0 +1,326 @@
+.\"/*
+.\" * Copyright (c) 2012 Red Hat, Inc.
+.\" *
+.\" * All rights reserved.
+.\" *
+.\" * Author: Jan Friesse (jfriesse@xxxxxxxxxx)
+.\" *
+.\" * This software licensed under BSD license, the text of which follows:
+.\" *
+.\" * Redistribution and use in source and binary forms, with or without
+.\" * modification, are permitted provided that the following conditions are met:
+.\" *
+.\" * - Redistributions of source code must retain the above copyright notice,
+.\" * this list of conditions and the following disclaimer.
+.\" * - Redistributions in binary form must reproduce the above copyright notice,
+.\" * this list of conditions and the following disclaimer in the documentation
+.\" * and/or other materials provided with the distribution.
+.\" * - Neither the name of the Red Hat, Inc. nor the names of its
+.\" * contributors may be used to endorse or promote products derived from this
+.\" * software without specific prior written permission.
+.\" *
+.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" * THE POSSIBILITY OF SUCH DAMAGE.
+.\" */
+.TH "CMAP_KEYS" 8 "05/04/2012" "corosync Man Page" "Corosync Cluster Engine Programmer's Manual"
+
+.SH NAME
+.P
+cmap_keys \- Overview of keys stored in the Configuration Map
+
+.SH OVERVIEW
+.P
+There are roughly 3 types of keys stored in CMAP:
+.PP
+* Mapping of values stored in config file.
+.PP
+* Runtime statistics.
+.PP
+* Other user created values.
+
+In this man page, wild-cards are used with usual meaning.
+
+.SH KEYS
+.TP
+internal_configuration.*
+Internal configuration data. This keys (whole prefix) is read only.
+It's only useful for getting list of loaded services.
+
+.TP
+logging.*
+Values read from configuration file. It's possible to change them at runtime.
+If subsystem specific configuration is needed, key must be in form
+logging.logger_subsys.SERVICE.key, where SERVICE is upper case name of service and
+key is same as in configuration file. All values are of string type.
+
+.TP
+nodelist.*
+Values read from configuration file. Each node element in configuration file gets
+assigned it's position starting from zero. So first node from config file has
+nodelist.node.0. prefix. To be valid entry, each node must have
+.B ring0_addr
+key.
+For change of
+.B nodeid
+key, use u32 data type.
+
+Local node position is stored in
+.B local_node_pos
+key (RO), so it's easy to find
+out nodeid/ring addresses of local node directly from cmap.
+
+.TP
+runtime.blackbox.*
+Trigger keys for store fplay data. It's recommended to use corosync-blackbox command
+to change keys in this prefix.
+
+.TP
+runtime.connections.*
+There are informations about total number of active connections in given moment in
+.B active
+key, number of closed connections during whole runtime of corosync in
+.B closed
+key and informations about each active IPC connection. All keys in this prefix are read-only.
+
+.TP
+runtime.connections.ID.*
+Each IPC connection has unique ID. This is in form [[short_name:][PID:]internal_id. On some
+platforms, short_name and PID are not filled and only internal_id is used.
+
+Typical keys in prefix are:
+
+.B client_pid
+containing PID of IPC connection (unavailable on some platforms).
+
+.B dispatched
+with number of dispatched messages.
+
+.B invalid_request
+is number of requests made by IPC which are invalid (calling non-existing call, ...).
+
+.B name
+containing short name of IPC connection (unavailable on some platforms).
+
+.B overload
+is number of requests which were not processed because of overload.
+
+.B queue_size
+contains number of messages in queue waiting for send.
+
+.B recv_retries
+is total number of interrupted receives.
+
+.B requests
+contains number of requests made by IPC.
+
+.B responses
+is number of responses sent to IPC client.
+
+.B send_retries
+contains total number of interrupted sends.
+
+.B service_id
+contains ID of service which IPC is connected to.
+
+.TP
+runtime.services.*
+Prefix with statistics for service engines. Each service has it's own
+.B service_id
+key in prefix with name runtime.services.SERVICE., where SERVICE is lower case
+name of service. Inside service prefix is number of received and send messages
+by corosync engine in format runtime.services.SERVICE.EXEC_CALL.rx and
+runtime.services.SERVICE.EXEC_CALL.tx, where EXEC_CALL is internal id of service
+call (so for example 3 in cpg service is receive of multicast message from other
+nodes).
+
+.TP
+runtime.totem.pg.mrp.srp.*
+Prefix with statistics about totem. All keys there are read only.
+Typical key prefixes:
+
+.B commit_entered
+Number of times processor entered COMMIT state.
+
+.B commit_token_lost
+Number of times processor lost token in COMMIT state.
+
+.B consensus_timeouts
+How many times processor timeouted making consensus about membership.
+
+.B continuous_gather
+How many times was processor not able to reach consensus.
+
+.B firewall_enabled_or_nic_failure
+Set to 1 when processor was not able to reach consensus for long time. Usual
+reason is badly configured firewall or connection failure.
+
+.B gather_entered
+Number of times processor entered GATHER state.
+
+.B gather_token_lost
+Number of times processor lost token in GATHER state.
+
+.B mcast_retx
+Number of retransmitted messages.
+
+.B mcast_rx
+Number of received multicast messages.
+
+.B mcast_tx
+Number of transmitted multicast messages.
+
+.B memb_commit_token_rx
+Number of received commit tokens.
+
+.B memb_commit_token_tx
+Number of transmitted commit tokens.
+
+.B memb_join_rx
+Number of received join messages.
+
+.B memb_join_tx
+Number of transmitted join messages.
+
+.B memb_merge_detect_rx
+Number of received member merge messages.
+
+.B memb_merge_detect_tx
+Number of transmitted member merge messages.
+
+.B orf_token_rx
+Number of received orf tokens.
+
+.B orf_token_tx
+Number of transmitted orf tokens.
+
+.B recovery_entered
+Number of times processor entered recovery.
+
+.B recovery_token_lost
+Number of times token was lost in recovery state.
+
+.B rx_msg_dropped
+Number of received messages which was dropped because they were not expected
+(as example multicast message in commit state).
+
+.B token_hold_cancel_rx
+Number of received token hold cancel messages.
+
+.B token_hold_cancel_tx
+Number of transmitted token hold cancel messages.
+
+.TP
+runtime.totem.pg.mrp.srp.members.*
+Prefix containing members of totem single ring protocol. Each member
+keys has format runtime.totem.pg.mrp.srp.members.NODEID.KEY, where key is
+one of:
+
+.B ip
+IP address of member. It's stored in format r(RING_ID) ip(IP_ADDRESS).
+
+.B join_count
+Number of times processor joined membership with local processor. When
+processor fails and rejoins again, this value is incremented.
+
+.B status
+Status of processor. Can be one of joined and left.
+
+.TP
+resources.process.PID.*
+Prefix created by applications using SAM with CMAP integration.
+It contains following keys:
+
+.B recovery
+Recovery policy of process. Can be one of quit or restart.
+
+.B poll_period
+Value passed in sam_initialize as time_interval.
+
+.B last_updated
+Last time when SAM received heartbeat from client.
+
+.B state
+State of client. Can be one of failed, stopped, running and waiting for quorum.
+
+.TP
+uidgid.*
+Informations about users/groups which are allowed to do IPC connection to
+corosync.
+
+.SH DYNAMIC CHANGE USER/GROUP PERMISSION TO USE COROSYNC IPC
+Is very same as in configuration file. To add UID 500 use
+
+.br
+# corosync-cmapctl -s uidgid.uid.500 u8 1
+
+GID is similar, so to add GID use
+
+.br
+# corosync-cmapctl -s uidgid.gid.500 u8 1
+
+For removal of permission, simply delete key
+
+.br
+# corosync-cmapctl -d uidgid.gid.500
+
+.SH DYNAMIC ADD/REMOVE OF UDPU NODE
+We will need to add node with address 10.34.38.108
+and nodeid 3. This node is called NEW and it's not running corosync yet.
+
+.PP
+* Find a node position in node list which is not used yet. It's recommended to
+use highest_number + 1. Let's say output of corosync-cmapctl looks like:
+
+.br
+nodelist.local_node_pos (u32) = 1
+.br
+nodelist.node.0.nodeid (u32) = 1
+.br
+nodelist.node.0.ring0_addr (str) = 10.34.38.106
+.br
+nodelist.node.1.nodeid (u32) = 2
+.br
+nodelist.node.1.ring0_addr (str) = 10.34.38.107
+
+So next node position will be 2.
+.PP
+* Add all entries needed for node on all running nodes, as:
+
+.br
+# corosync-cmapctl -s nodelist.node.2.nodeid u32 3
+.br
+# corosync-cmapctl -s nodelist.node.2.ring0_addr str 10.34.38.108
+
+Always add ring0_addr key as last. Corosync engine on all nodes should reply
+with
+.I notice [TOTEM ] adding new UDPU member {10.34.38.108}
+message.
+.PP
+* Add node information to configuration file on all nodes so it
+will survive restart of corosync.
+.PP
+* Copy and edit configuration file to NEW node.
+.PP
+* Start corosync on NEW node.
+
+Removal of UDPU node is very similar slightly reversed action, so
+.PP
+* Stop corosync old OLD node.
+.PP
+* Remove relevant entries from cmap on all nodes.
+.PP
+* Change configuration file on all nodes.
+
+.SH "SEE ALSO"
+.BR corosync_overview (8),
+.BR corosync.conf (5),
+.BR corosync-cmapctl (8)
diff --git a/man/cmap_overview.8 b/man/cmap_overview.8
index eb8b99b..2b43ae9 100644
--- a/man/cmap_overview.8
+++ b/man/cmap_overview.8
@@ -54,6 +54,8 @@ The library provides a mechanism to:
.PP
* Track changes on keys
+Description of most keys created by corosync itself can be found in cmap_keys (8).
+
.SH BUGS
.SH "SEE ALSO"
.BR cmap_initialize (3),
@@ -71,4 +73,5 @@ The library provides a mechanism to:
.BR cmap_iter_next (3),
.BR cmap_iter_finalize (3),
.BR cmap_track_add (3),
-.BR cmap_track_delete (3)
+.BR cmap_track_delete (3),
+.BR cmap_keys (8)
