These are based upon Honza's original man pages edited for better english :)
Regards -steve
Index: man/sam_register.3 =================================================================== --- man/sam_register.3 (revision 0) +++ man/sam_register.3 (revision 0) @@ -0,0 +1,88 @@ +.\"/* +.\" * Copyright (c) 2009 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Jan Friesse ([email protected]) +.\" * +.\" * 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 "SAM_REGISTER" 3 "12/01/2009" "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" + +.SH NAME +.P +sam_rehister \- Register component for health checking + +.SH SYNOPSIS +.P +\fB#include <corosync/sam.h>\fR + +.P +\fBcs_error_t sam_register (unsigned int *\fIinstance_id\fR);\fR + +.SH DESCRIPTION +.P +The \fBsam_register\fR function is used to register a process for healthchecking. +If recovery policy is set to \fISAM_RECOVERY_POLICY_RESTART\fR and recovery +action will be taken, the new process instance will begin execution at the next +code line after this function is called. + +.P +This function can be called only once and SAM must be initialized by +\fBsam_initialize(3)\fR function. + +.P +The \fIinstance_id\fR argument is a pointer to a value storing the current +iteration instance. If this parameter is NULL, no \fIinstance_id\fR is returned. +and then, no \fIinstance_id\fR will be returned. This value starts at 0 for the +first iteration instance, and increases by 1 each time a recovery restart is +executed. After reaching MAX_INT, the instance_id will reset to 0. + +.P +The placement of this function is important because after it is called, the +process id will change. + +.P +After registration, event driven health checking is not running. + +.SH RETURN VALUE +.P +This call return CS_OK value if successful, otherwise and error is returned. + +.SH ERRORS +.TP +CS_ERR_BAD_HANDLE +health checking was not started by calling \fBsam_start(3)\fR function. +.TP +CS_ERR_LIBRARY +internal library call failed. This can be one of pipe creation or fork. +It's possible to get more information from errno. + +.SH "SEE ALSO" +.BR sam_start (3), +.BR sam_initialize (3), +.BR sam_hc_callback_register (3) Index: man/sam_stop.3 =================================================================== --- man/sam_stop.3 (revision 0) +++ man/sam_stop.3 (revision 0) @@ -0,0 +1,67 @@ +.\"/* +.\" * Copyright (c) 2009 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Jan Friesse ([email protected]) +.\" * +.\" * 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 "SAM_STOP" 3 "12/01/2009" "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" + +.SH NAME +.P +sam_stop \- Stop health checking + +.SH SYNOPSIS +.P +\fB#include <corosync/sam.h>\fR + +.P +\fBcs_error_t sam_stop (void);\fR + +.SH DESCRIPTION +.P +The \fBsam_stop\fR function is used to stop health checking of an active +process. After calling this function, the application no longer should send +helathchecks. In the case of event driven healthchecking, the healthchecking +thread will be stopped. + +.P +A process can always start health checking again by calling \fBsam_start(3)\fR function. + +.SH RETURN VALUE +.P +This call return CS_OK value if successful, otherwise and error is returned. + +.SH ERRORS +.TP +CS_ERR_BAD_HANDLE +health checking was not started by calling \fBsam_start(3)\fR function. + +.SH "SEE ALSO" +.BR sam_start (3) Index: man/sam_initialize.3 =================================================================== --- man/sam_initialize.3 (revision 0) +++ man/sam_initialize.3 (revision 0) @@ -0,0 +1,105 @@ +.\"/* +.\" * Copyright (c) 2009 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Jan Friesse ([email protected]) +.\" * +.\" * 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 "SAM_INITIALIZE" 3 "12/01/2009" "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" + +.SH NAME +.P +sam_initialize \- Initialize health checking + +.SH SYNOPSIS +.P +\fB#include <corosync/sam.h>\fR + +.P +\fBcs_error_t sam_initialize (int\fR \fItime_interval\fR\fB, sam_recovery_policy_t \fIrecovery_policy\fR);\fR + +.SH DESCRIPTION +.P +The \fBsam_initialize\fR function is used to initialize health checking of a process. + +.P +Application can have only one instance of SAM. This function must be called +before any other of SAM functions. It is recommended to initialize before the +process begins any process initialization. + +.P +The \fItime_interval\fR parameter is a timeout in milliseconds before taking +recovery action after having not received a healthcheck. + +If \fItime_interval\fR parameter is zero, there is no time limit and no +healthcheck must be sent by the process. In this operational mode, a process +failure will continue to execute the recovery policy. + +.P +The \fIrecovery_policy\fR is defined as type: + +.nf + typedef enum { + SAM_RECOVERY_POLICY_QUIT = 1, + SAM_RECOVERY_POLICY_RESTART = 2, + } sam_recovery_policy_t; +.fi + +.P +where + +.TP +SAM_RECOVERY_POLICY_QUIT +on failure, the process will terminate. +.TP +SAM_RECOVERY_POLICY_RESTART +on failure, the process will restart. + +.P +To perform event driven healthchecking, \fBsam_register(3)\fR and +\fBsam_start(3)\fR functions must called. Event driven healthchecking causes +the duplicate standby process running the SAM serve rto periodically request +healthchecks from the active process. + +.SH RETURN VALUE +.P +This call return CS_OK value if successful, otherwise and error is returned. + +.SH ERRORS +.TP +CS_ERR_BAD_HANDLE +can happened in case of double initialization. +.TP +CS_ERR_INVALID_PARAM +\fIrecovery_policy\fR has invalid value. + +.SH "SEE ALSO" +.BR sam_register (3), +.BR sam_start (3), +.BR sam_hc_callback_register (3) Index: man/sam_hc_send.3 =================================================================== --- man/sam_hc_send.3 (revision 0) +++ man/sam_hc_send.3 (revision 0) @@ -0,0 +1,68 @@ +.\"/* +.\" * Copyright (c) 2009 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Jan Friesse ([email protected]) +.\" * +.\" * 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 "SAM_HC_SEND" 3 "12/01/2009" "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" + +.SH NAME +.P +sam_hc_send \- Send health check confirmation + +.SH SYNOPSIS +.P +\fB#include <corosync/sam.h>\fR + +.P +\fBcs_error_t sam_hc_send (void);\fR + +.SH DESCRIPTION +.P +The \fBsam_hc_send\fR function is used to send healthcheck confirmation from +the applicatoin. This function should be called reguarly when configured for +application driven healthchecking, otherwise recovery actoin will be taken. + +When using event driven healthchecking, this function should not be used. + +.SH RETURN VALUE +.P +This call return CS_OK value if successful, otherwise and error is returned. + +.SH ERRORS +.TP +CS_ERR_BAD_HANDLE +health checking is not in running state (\fBsam_start(3)\fR has not been +executed) or function is called after stop/finalization of SAM. + +.SH "SEE ALSO" +.BR sam_start (3), +.BR sam_stop (3), +.BR sam_hc_callback_register (3) Index: man/sam_hc_callback_register.3 =================================================================== --- man/sam_hc_callback_register.3 (revision 0) +++ man/sam_hc_callback_register.3 (revision 0) @@ -0,0 +1,89 @@ +.\"/* +.\" * Copyright (c) 2009 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Jan Friesse ([email protected]) +.\" * +.\" * 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 "SAM_HC_CALLBACK_REGISTER" 3 "12/01/2009" "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" + +.SH NAME +.P +sam_hc_callback_register \- Register health check callback + +.SH SYNOPSIS +.P +\fB#include <corosync/sam.h>\fR + +.P +\fBcs_error_t sam_hc_callback_register (sam_hc_callback_t cb);\fR + +.SH DESCRIPTION +.P +The \fBsam_hc_callback_register\fR function is used to register a user provided +healthcheck callback. After calling of this function, the SAM is switched +from application driven healthchecking to event driven healthchecking. In this +mode, \fBsam_hc_send(3)\fR does not need to be executed. + +.P +The parameter \fIcb\fR is callback function of type \fIsam_hc_callback_t\fR +defined as: + +.nf + typedef int (*sam_hc_callback_t)(void); +.fi + +.P +This function will be regulargly called and must return 0 if the process is +functioning normally, or -1 if the process is executing abnormally. When -1 is +returned, the SAM server execute the registered recovery policy. + +.P +A value of NULL can be passed into this function to switch into application +driven healthchecking. +\fIcb\fR to NULL. + +.SH RETURN VALUE +.P +This call return CS_OK value if successful, otherwise and error is returned. + +.SH ERRORS +.TP +CS_ERR_BAD_HANDLE +SAM was not initialized and registered or health checking is in running state +.TP +CS_ERR_LIBRARY +internal library call failed. This can occur during fork() or pipe () system +calls and the errno variable can be read to retrieve more information. + +.SH "SEE ALSO" +.BR sam_start (3), +.BR sam_stop (3), +.BR sam_hc_send (3), +.BR sam_register (3), Index: man/sam_finalize.3 =================================================================== --- man/sam_finalize.3 (revision 0) +++ man/sam_finalize.3 (revision 0) @@ -0,0 +1,63 @@ +.\"/* +.\" * Copyright (c) 2009 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Jan Friesse ([email protected]) +.\" * +.\" * 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 "SAM_FINALIZE" 3 "12/01/2009" "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" + +.SH NAME +.P +sam_finalize \- Terminate SAM service + +.SH SYNOPSIS +.P +\fB#include <corosync/sam.h>\fR + +.P +\fBcs_error_t sam_finalize (void);\fR + +.SH DESCRIPTION +.P +The \fBsam_finalize\fR function is used to terminate SAM API. Once the connection is finalized, +the SAM may not be used again by application. Whole functionality (health checking) will be +stopped and after application fail, recovery action will not be taken. + +.SH RETURN VALUE +.P +This call return CS_OK value if successful, otherwise and error is returned. + +.SH ERRORS +.TP +CS_ERR_BAD_HANDLE +library was not initialized by \fBsam_init(3)\fR function or was finished already. + +.SH "SEE ALSO" +.BR sam_initialize (3) Index: man/sam_overview.8 =================================================================== --- man/sam_overview.8 (revision 0) +++ man/sam_overview.8 (revision 0) @@ -0,0 +1,126 @@ +.\"/* +.\" * Copyright (c) 2009 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Jan Friesse ([email protected]) +.\" * Author: Steven Dake ([email protected]) +.\" * +.\" * 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 "SAM_OVERVIEW" 8 "12/01/2009" "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" + +.SH NAME +.P +sam_overview \- Overview of the Simple Availability Manager + +.SH OVERVIEW +.P +The SAM library provide a tool to check the health of an application. +The main purpose of SAM is to restart a local process when it fails to respond +to a healthcheck request in a configured time interval. + +.P +During \fBsam_initialize(3)\fR, a duplicate copy of the process is created using +the \fBfork(3)\fR system call. This duplicate process copy contains the logic +for executing the SAM server. The SAM server is responsible for requesting +healthchecks from the active process, and controlling the lifecycle of the +active process when it fails. If the active process fails to respond to the +healthcheck request sent by the SAM server, it will be sent a SIGTERM signal +to request shutdown of the application. After a configured time interval, the +process will be forcibly killed by being sent a SIGKILL signal. Once the +active process terminates, the SAM server will create a new active process. + +.P +The Simple Availability Manager is meant to be used in conjunction with the +cpg service. Used together, it is possible to restart a cpg process that fails +healthchecking during operation. + +.P +The main features of SAM include: + +.RS +.IP \(bu 3 +A configurable recovery policy. +.IP \(bu 3 +A configurable time interval for health check operations. +.IP \(bu 3 +A notification via signal before recovery action is taken. +.IP \(bu 3 +A mechanism to indicate to the application the number of times an active +process has been created by the SAM server. +.IP \(bu 3 +Both application driven health checking and event driven health checking. +.RE + +.SH Initializing SAM +.P +The SAM library is initialized by \fBsam_initialize(3)\fR. +\fBsam_initalize(3)\fR may only be called once per process. Calling it more +then once has undefined results and is not recommended or tested. + +.SH Setting warning callback +.P +A \fISIGTERM\fR signal is sent to the application when a recovery action is +planned. The application can use the \fBsignal(3)\fR system call to monitor +for this signal. + +.P +There are no special constraints on what SAM apis may be called in a warning +callback. After \fItime_interval\fR expires, a SIGKILL signal is sent to the +active process to force its termination. + +.SH Registering the active process +.P +The active process is registered with SAM by calling \fBsam_register(3)\fR. +This function should only be called one time in a process. After a recovery +action is taken, the new active process will begin execution at the next line +of code in a user process after \fBsam_register(3)\fR. + +.SH Enabling event driven healthchecking +.P +Two types of healthchecking are available to the user. The first model is one +where the user application healthchecks during its normal operation. It is +never requested to healtcheck, and if the active process doesn't respond within +the time interval, the process will be restarted. + +.P +A more useful mechanism for healthchecking is event driven healthchecking. +Because this model is directed by the SAM server, It isn't necessary to guess +or add timers to the active process to signal a healthcheck operation is +successful. To use event driven healthchecking, +the \fBsam_hc_callback_register(3)\fR function should be executed. + +.SH BUGS +.SH "SEE ALSO" +.BR sam_initialize (3), +.BR sam_finalize (3), +.BR sam_start (3), +.BR sam_stop (3), +.BR sam_register (3), +.BR sam_hc_send (3), +.BR sam_hc_callback_register (3) Index: man/sam_start.3 =================================================================== --- man/sam_start.3 (revision 0) +++ man/sam_start.3 (revision 0) @@ -0,0 +1,77 @@ +.\"/* +.\" * Copyright (c) 2009 Red Hat, Inc. +.\" * +.\" * All rights reserved. +.\" * +.\" * Author: Jan Friesse ([email protected]) +.\" * +.\" * 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 "SAM_START" 3 "12/01/2009" "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" + +.SH NAME +.P +sam_start \- Start health checking + +.SH SYNOPSIS +.P +\fB#include <corosync/sam.h>\fR + +.P +\fBcs_error_t sam_start (void);\fR + +.SH DESCRIPTION +.P +The \fBsam_start\fR function is used to start health checking of application. +After calling this function, the active process needs to send healthchecks +within the registered time interval by calling \fBsam_hc_send(3)\fR. If +event driven healthchecking is configured by calling \fBsam_register(3)\fR, +an internal thread will be created and send health check confirmations four +times per \fItime_interval\fR. + +.P +Application must be registered by calling \fBsam_register(3)\fR before this +function can be called. + +.P +An application can always stop health checking by calling the \fBsam_stop(3)\fR +function. + +.SH RETURN VALUE +.P +This call return CS_OK value if successful, otherwise and error is returned. + +.SH ERRORS +.TP +CS_ERR_BAD_HANDLE +component was not registered by calling \fBsam_register(3)\fR function. + +.SH "SEE ALSO" +.BR sam_hc_send (3), +.BR sam_stop (3), +.BR sam_register (3), +.BR sam_hc_callback_register (3) Index: man/Makefile.am =================================================================== --- man/Makefile.am (revision 2573) +++ man/Makefile.am (working copy) @@ -99,8 +99,16 @@ votequorum_qdisk_register.3 \ votequorum_qdisk_unregister.3 \ votequorum_setexpected.3 \ - votequorum_setvotes.3 - + votequorum_setvotes.3 \ + sam_finalize.3 \ + sam_hc_callback_register.3 \ + sam_hc_send.3 \ + sam_initialize.3 \ + sam_overview.8 \ + sam_register.3 \ + sam_start.3 \ + sam_stop.3 + if BUILD_HTML_DOCS HTML_DOCS = $(dist_man_MANS:%=%.html)
_______________________________________________ Openais mailing list [email protected] https://lists.linux-foundation.org/mailman/listinfo/openais
