Current priorities are: 1. man pages for every binary 2. man pages for every api 3. update docs to match code base 4. document error codes 5. Remove AIS references Volunteers are welcomed. Problem finder scripts are included.Complete results included bellow, for now, I can split work into few major parts:
- CFG - need complete description, nothing done there - CPG - need document few functions + changes (default async mode, ...) - SAM - describe cmap flag (Honza) - *QUORUM* - describe few functions - CFG, CPG, *QUORUM*, EVS - error code descriptions- IPC - one page with common IPC errors description. At least overview has link to that page
- AIS reference removal Current results: 1 - man pages for every binary ------------------------------ bash mp-check-bin.sh corosync-1.99.1-1.11.7d06.el6.x86_64.rpm @@ -4,0 +5 @@ +corosync.conf @@ -8,0 +10 @@ +corosync_overview @@ -10,0 +13 @@ +votequorumIn other words, all binaries are documented and after brief look they looks ok and up to date.
2 and 3 - man pages for every api and document error codes ---------------------------------------------------------- bash mp-check-api.sh ~/corosync No overview for cfg No description for COROSYNC_CFG_ADMINISTRATIVESTATE_LOCKED No description for COROSYNC_CFG_ADMINISTRATIVESTATE_STOPPING No description for COROSYNC_CFG_ADMINISTRATIVESTATE_UNLOCKEDNo description for COROSYNC_CFG_ADMINISTRATIVETARGET_COMPONENTSERVICEINSTANCE
No description for COROSYNC_CFG_ADMINISTRATIVETARGET_NODE No description for COROSYNC_CFG_ADMINISTRATIVETARGET_SERVICEGROUP No description for COROSYNC_CFG_ADMINISTRATIVETARGET_SERVICEUNIT No description for COROSYNC_CFG_OPERATIONALSTATE_DISABLED No description for COROSYNC_CFG_OPERATIONALSTATE_ENABLED No description for COROSYNC_CFG_PRESENCESTATE_INSTANTIATED No description for COROSYNC_CFG_PRESENCESTATE_INSTANTIATING No description for COROSYNC_CFG_PRESENCESTATE_INSTANTIATION_FAILED No description for COROSYNC_CFG_PRESENCESTATE_RESTARTING No description for COROSYNC_CFG_PRESENCESTATE_TERMINATING No description for COROSYNC_CFG_PRESENCESTATE_TERMINATION_FAILED No description for COROSYNC_CFG_PRESENCESTATE_UNINSTANTIATED No description for COROSYNC_CFG_READINESSSTATE_INSERVICE No description for COROSYNC_CFG_READINESSSTATE_OUTOFSERVICE No description for COROSYNC_CFG_READINESSSTATE_STOPPING No description for COROSYNC_CFG_SHUTDOWN_FLAG_IMMEDIATE No description for COROSYNC_CFG_SHUTDOWN_FLAG_NO No description for COROSYNC_CFG_SHUTDOWN_FLAG_REGARDLESS No description for COROSYNC_CFG_SHUTDOWN_FLAG_REQUEST No description for COROSYNC_CFG_SHUTDOWN_FLAG_YES No description for COROSYNC_CFG_STATETYPE_ADMINISTRATIVE No description for COROSYNC_CFG_STATETYPE_HA No description for COROSYNC_CFG_STATETYPE_OPERATIONAL No description for COROSYNC_CFG_STATETYPE_PRESENCE No description for COROSYNC_CFG_STATETYPE_READINESS No description for corosync_cfg_crypto_set No description for corosync_cfg_dispatch No description for corosync_cfg_fd_get No description for corosync_cfg_finalize No description for corosync_cfg_get_node_addrs No description for corosync_cfg_initialize No description for corosync_cfg_kill_node No description for corosync_cfg_local_get No description for corosync_cfg_replyto_shutdown No description for corosync_cfg_ring_reenable No description for corosync_cfg_ring_status_get No description for corosync_cfg_service_load No description for corosync_cfg_service_unload No description for corosync_cfg_state_track No description for corosync_cfg_state_track_stop No description for corosync_cfg_try_shutdown No description for CPG_FLOW_CONTROL_DISABLED No description for CPG_FLOW_CONTROL_ENABLED No description for CPG_ITERATION_ALL No description for CPG_ITERATION_NAME_ONLY No description for CPG_ITERATION_ONE_GROUP No description for cpg_flow_control_state_get No description for cpg_iteration_finalize No description for cpg_iteration_initialize No description for cpg_iteration_nextNo errors documented in man/evs_context_get.3 man/evs_context_set.3 man/evs_dispatch.3 man/evs_fd_get.3 man/evs_finalize.3 man/evs_initialize.3 man/evs_join.3 man/evs_leave.3 man/evs_mcast_groups.3 man/evs_mcast_joined.3 man/evs_membership_get.3
No description for SAM_RECOVERY_POLICY_CMAP No overview for quorum No description for quorum_trackstart No description for quorum_trackstopNo errors documented in man/quorum_context_get.3 man/quorum_context_set.3 man/quorum_dispatch.3 man/quorum_fd_get.3 man/quorum_finalize.3 man/quorum_getquorate.3 man/quorum_initialize.3
No description for votequorum_trackstart No description for votequorum_trackstopNo errors documented in man/votequorum_context_get.3 man/votequorum_context_set.3 man/votequorum_dispatch.3 man/votequorum_fd_get.3 man/votequorum_finalize.3 man/votequorum_getinfo.3 man/votequorum_initialize.3 man/votequorum_qdevice_getinfo.3 man/votequorum_qdevice_poll.3 man/votequorum_qdevice_register.3 man/votequorum_qdevice_unregister.3 man/votequorum_setexpected.3 man/votequorum_setvotes.3
So pretty bad results here, shortly: - CFG engine is not documented at all - Almost no man pages (except cmap and sam) has error codes documented- It would be nice to have one man page describing typical IPC errors (CS_ERR_TRY_AGAIN, ...)
5 - Remove AIS references ------------------------- bash mp-check-ais.sh ~/corosync man/corosync.conf.5-.B compatibility.man/corosync.conf.5-This directive indicates the level of compatibility requested by the user. The man/corosync.conf.5-option whitetank can be specified to remain backward compatable with man/corosync.conf.5:openais-0.80.z. The option none can be specified to only be compatable man/corosync.conf.5-with corosync-1.Y.Z. Extra processing during configuration changes is
man/corosync.conf.5-required to remain backward compatable. man/corosync.conf.5- -- man/corosync.conf.5-.TP man/corosync.conf.5-clear_node_high_bitman/corosync.conf.5-This configuration option is optional and is only relevant when no nodeid is man/corosync.conf.5:specified. Some openais clients require a signed 32 bit nodeid that is greater man/corosync.conf.5:than zero however by default openais uses all 32 bits of the IPv4 address space man/corosync.conf.5-when generating a nodeid. Set this option to yes to force the high bit to be man/corosync.conf.5-zero and therefor ensure the nodeid is a positive signed 32 bit integer.
man/corosync.conf.5- -- man/corosync.conf.5-man/corosync.conf.5-Enabling this option adds a 36 byte header to every message sent by totem which man/corosync.conf.5-reduces total throughput. Encryption and authentication consume 75% of CPU
man/corosync.conf.5:cycles in aisexec as measured with gprof when enabled. man/corosync.conf.5- man/corosync.conf.5-For 100mbit networks with 1500 MTU frame transmissions:man/corosync.conf.5-A throughput of 9mb/sec is possible with 100% cpu utilization when this
-- man/corosync_overview.8-man/corosync_overview.8-The major focus of high availability in the past has been to mask hardware man/corosync_overview.8-faults. Faults in other components of the system have gone unsolved until man/corosync_overview.8:AIS. AIS can mask many types of faults in applications, middleware, man/corosync_overview.8-operating systems, or even hardware by providing a simple framework man/corosync_overview.8-for allowing developers to create redundant applications. These redundant man/corosync_overview.8-applications can be distributed over multiple nodes such that if any one
--man/corosync_overview.8-may be set to start on system start. It may also be turned off by default in man/corosync_overview.8-which case the init script for corosync must be enabled.
man/corosync_overview.8-man/corosync_overview.8:After running aisexec, a list of all processors IP addresses running the corosync man/corosync_overview.8-executive and configured on the same multicast address will appear. If they man/corosync_overview.8-don't appear, there may be a problem with multicast in the distro or hardware. man/corosync_overview.8-If this happens, participation in the corosync mailing list may help solve the man/corosync_overview.8:problem. The email address is openais@xxxxxxxxxxxxxx.
man/corosync_overview.8- man/corosync_overview.8-.SH USING LIBRARIESman/corosync_overview.8:The corosync AIS libraries have header files which must be included in the man/corosync_overview.8-developer's application. Once the header file is included, the developer can
man/corosync_overview.8:reference the AIS interfaces. man/corosync_overview.8-man/corosync_overview.8-The corosync project recommends to distros to place include files in man/corosync_overview.8-/usr/include/corosync. The following include lines must be added to
-- man/corosync_overview.8-.PPman/corosync_overview.8-#include <corosync/saEvt.h> For the Eventing B.01.01 service.
man/corosync_overview.8-.PPman/corosync_overview.8:#include <corosync/ais_amf.h> For the AMF A.01.01 service.
man/corosync_overview.8-.PP man/corosync_overview.8-man/corosync_overview.8-The corosync project recommends to distros to place library files in
-- man/corosync_overview.8-.PP man/corosync_overview.8--lsaAmf For the AMF A.01.01 service man/corosync_overview.8-.PPman/corosync_overview.8:-lais Specify this to get access to all AIS libraries without specifying
man/corosync_overview.8-each library individually. man/corosync_overview.8- man/corosync_overview.8-.SH IPv6 -- man/corosync_overview.8-IPv6 traffic. man/corosync_overview.8- man/corosync_overview.8-.SH ARCHITECTUREman/corosync_overview.8:The AIS libraries are a thin IPC interface to the corosync executive. The man/corosync_overview.8:corosync executive provides services for the SA Forum AIS libraries as well
man/corosync_overview.8-as the EVS and CPG libraries. man/corosync_overview.8-man/corosync_overview.8-The corosync executive uses the Totem extended virtual synchrony protocol. The
-- man/corosync_overview.8-.PP man/corosync_overview.8-.SH SAFTEST COMPLIANCEman/corosync_overview.8-The corosync libraries are now nearly compliant with every aspect of the SA man/corosync_overview.8:Forum's AIS specification. The AMF service, however, is not compliant with the man/corosync_overview.8-B.01.01 specification. The remaining services pass most of the tests of the
man/corosync_overview.8-saftest suite against the B.01.01 specification. man/corosync_overview.8- -- man/cpg_overview.8-.PP man/cpg_overview.8-.SH SECURITYman/cpg_overview.8-If encryption is enabled in corosync.conf, the CPG library will encrypt and man/cpg_overview.8:authenticate message contents. Applications must run as the ais user to be man/cpg_overview.8-validated by corosync on IPC connection, otherwise they will be unable to
man/cpg_overview.8-access the corosync services. man/cpg_overview.8- --man/evs_overview.8-the application can alter its behavior based upon the configuration changes.
man/evs_overview.8-.SH ARCHITECTURE AND ALGORITHMman/evs_overview.8-The EVS library is a thin IPC interface to the corosync executive. The corosync executive man/evs_overview.8:provides services for the SA Forum AIS libraries as well as the EVS library.
man/evs_overview.8-.PPman/evs_overview.8-The corosync executive uses a ring protocol and membership protocol to send messages man/evs_overview.8-according to the semantics required by extended virtual synchrony. The ring protocol
Only few problems there. Honza
Attachment:
mp-check-ais.sh
Description: application/shellscript
Attachment:
mp-check-api.sh
Description: application/shellscript
Attachment:
mp-check-bin.sh
Description: application/shellscript
_______________________________________________ discuss mailing list discuss@xxxxxxxxxxxx http://lists.corosync.org/mailman/listinfo/discuss
