nice job
Reviewed-by: Steven Dake <sdake@xxxxxxxxxx>
dOn 04/05/2012 04:57 AM, Jan Friesse wrote:
> 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)
_______________________________________________
discuss mailing list
discuss@xxxxxxxxxxxx
http://lists.corosync.org/mailman/listinfo/discuss
