Cross Reference: /ha-utilities/GDS-template/README

#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the License).
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at SUNCsc_template/CDDL.txt
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at <packagename>/CDDL.txt.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets [] replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#

#
# Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# ident	"@(#)README	1.2	08/02/12 SMI"
#

SUNCsc_template - Template for writing GDS based Suncluster Data Services.

Version 1.0	14.11.2007


Here are just some guidelines for using this template:

1. This SC3.x Data Service template is setup to work with GDS.
   Subsequently this is the callback behavior with SC3.x

   RGM -> GDS -> "control_xxx <options> start" | "control_xxx <options> stop"
                  | "control_xxx <options> probe"

2. There are lots of debug messages within this template that
   are there to help you. The debug message flow is as
   follows, ie here's what a unsuccessful start_xxx does

    daemon.debug "Method: ${MYNAME} - Begin"
    daemon.debug "Function: validate - Begin"
    daemon.err   "Validate - file %s does not exist"
    daemon.debug "Function: validate - End"
    daemon.debug "Method: ${MYNAME} - End (Exit 1)"

3. If possible please try to EXIT (return to caller) from the
   control_xxx script.

   Doing this will ensure that your debug messages
   "Begin" and "End"

4. Turning debug on just requires that you edit the SUNCscxxx/etc/config
   file. Either enter the resource name for debug on just
   the resource, a "," separated list of resources, or ALL for all resources,
   if you are running multiple instances that use this data service.

5. When printing out messages, you'll see in the SUNCscxxx/lib/funtions_static
   file that there is a wrapper function called log_message
   which in turn uses scds_syslog. If using scds_syslog
   try to use %s to substitute any variables. An example
   of this can be found in the function debug_message.

6. If you produce documentation for your data service and also
   want to document the messages and their msgid's you'll need
   need to do this outside of your scripts, eg.

    echo "Validate - file %s does not exist" | msgid

   will generate the following

    600366 Validate - file %s does not exist

   Please be aware that if this msgid is in use, you can check
   the SC3.x Error Message Guide to see if it's in use, then
   you MUST modify your message, ie

    echo "Validate - file %s does not exist " | msgid
                                           ^
   will generate the following (Note the space)

    409456 Validate - file %s does not exist

   This is only feasible in a sun cluster environment, because the necessary
   scds_syslog binary is unavailable if no cluster is installed. In this case,
   the logger command is used which generates the msgid 702911 only.

7. Adding more options to either the
   control_xxx, just requires some more lines from you,

    control_xxx

    while getopts 'R:G:C' opt
    do
        case "${opt}" in
                R)      RESOURCE=${OPTARG};;
                G)      RESOURCEGROUP=${OPTARG};;
                C)      CONFIG_FILE=${OPTARG};;
                *)      logger -p daemon.err \
                        "ERROR: ${MYNAME} Option ${OPTARG} unknown"
                        exit 1;;
        esac
    done


    ./bin/functions - validate_options

    validate_options()
    {
	debug_message "Function: validate_options - Begin"
	${SET_DEBUG}
        #
        # Ensure all options are set
        #

	MYNAME=`basename $0`

	rc_validate_options=0

	for i in RESOURCE RESOURCEGROUP CONFIG_FILE
	do
                case $i in
                        RESOURCE)
                        if [ -z ${RESOURCE} ]; then
                                logger -p daemon.err \
                                "ERROR: ${MYNAME} Option -R not set"
                                rc_validate_options=1
                        fi;;

                        RESOURCEGROUP)
                        if [ -z ${RESOURCEGROUP} ]; then
                                logger -p daemon.err \
                                "ERROR: ${MYNAME} Option -G not set"
                                rc_validate_options=1
                        fi;;

                        CONFIG_FILE)
                        if [ -z ${CONFIG_FILE} ]; then
                                logger -p daemon.err \
                                "ERROR: ${MYNAME} Option -C not set"
                                rc_validate_options=1
                        fi;;

                esac
        done

	debug_message "Function: validate_options - End"
	return ${rc_validate_options}

     }

8. If you want to use the built-in start dependency follow the guidelines
   in the start_xxx() function.

9. If you want to use the built-in restart dependency follow the guidelines
    in the check_xxx() function.

10. Do not change the exit codes. They are there for a purpose and required
    by GDS to function.

11. Personalize the scripts and the functions.
    If your package and the scripts should not be named xxx, execute the rename
    script in the tools directory
    tools/rename <new_name>

    From this moment all reference in this readme to xxx_ or _xxx should be
    read as
    <new_name>_ or _<new_name>

12. When creating the package edit the Make_package/etc/pkginfo file and
    change PKG, NAME and DESC entries in that file.

    If you don't want your package to be named as SUNCscxxx change the
    directory SUNCscxxx to SUNCsc<new_name>.

    Run the Make_package in the directory Make_package/bin.
    You have to be in that directory when running the command.

13. In order to work properly on Solaris 10 with Zones, if you use
    /usr/bin/ps or /usr/bin/pgrep within the agent, you should
    call the function zone_function() and call ps/pgrep like

	zone_function

	/usr/bin/pgrep ${PZONEOPT} <whatever you else want to call>

    This will set option "-z <zonename>" if the agent is used on
    a Solaris 10 system, else ${PZONEOPT} is empty.
    If you have additional code special to Solaris 10, you can set it
    within zone_function() as well.

14. If your application does not leave a process behind, you need to remove
    the hashes between the lines "### "disabling pmf" code begin" and
    "### "disabling pmf" code end".

    An occurrence of this scenario are applications which just trigger an
    pre-spawned daemon to start and stop something or "Applications" which just
    manipulate flat files.

15. How to make your agent runnable in a local zone.

    It is important, that the zone inherits at least the /opt/agent_name
    directory of the global zone, otherwise it will not have the agent code.
    IMPORTANT this can only be defined at zone creation, so it may be better to
    inherit /opt.

    Having the code in the local zone is not enough. The necessary resources
    needs to be configured in the global zone. You have two options:

    1. use the zsh script component of the Sun Cluster HA Container agent.
    2. use the smf component with an optional boot script.

    The zsh component is the simplest approach, it has the drawback/benefit,
    that it does not react on pmf restarts.
    In this case configure the start stop and probe script with the options -S
    and -P. The tradeoff, is that a failure detection happens only after the
    probe interval.
    Another tradeoff is that you have to disable your resource every time you
    want to to change an option of the start, stop and probe script.
    Handling the resource manager project has to be done in the code of the
    start, stop and probe script.

    If you need a process based restart use the smf component. SMF offers an
    immediate process restart and in addition online configurable properties.
    The tradeoff is the additional complexity of the smf manifest, the benefit
    is the additional flexibility you get with smf and the faster detection of
    vanishing process trees.

    Handeling user credentials and the resource manager project for start and
    stop is a built in capability of smf services. The probe runs under the
    root user, but the probe_smf_xxx script is fired under the right project.

    The template delivers the xxx_smf_register script, the xxx_smf_remove and
    the control_xxx method.

    The control_xxx script is the start and stop method for all the instances
    of your agent. You need to modify the control_xxx to extract the properties
    you specified in the manifest. These properties needs to be used as options
    for the start stop and probe command.

    The xxx_smf_register script generates the manifest file under:
    /local/svc/manifest/application/sczone-agents/$RS.xml and imports the
    manifest under

    svc:/application/sczone-agents:$RS

    $RS is the resource name, so you will have one smf manifast/resource per
    cluster resource.

    The values for properties are sourced from the config file you need to
    register for a resource in a global zone. These properties are stored in
    the smf repository for the service svc:/application/sczone-agents:$RS.

    To specify the properties you need to modify the property group parameters.

        <property_group name='parameters' type='general'>
        <propval name='Resource' type='astring' value='$RS'/>
        <propval name='Resource_group' type='astring' value='$RG'/>
        </property_group>

    You can amend the manifest with all the options useful for your agent. To
    achieve this you need to modify the SUNCscxxx/util/xxx_smf_register file.

    The xxx_smf_register script can be called directly. It takes the -f option
    for an alternate config file.

    The xxx_smf_remove script removes the manifest and the smf service in the
    specified zone.

    Summary:
    To use the zsh component, modify the local_zone function in the xxx_register
    script and configure the start stop and probe command of your agent with
    all the necessary options.
    It is done via xxx_register -z zsh, it registers the smf_xxx method as the
    start stop and probe command with the necessary options.

    To use the smf component, rename and modify the xxx_smf_register and the
    xxx_smf_remove script, then call xxx_register script with -z smf in the
    global zone to configure the smf component in the global zone.

    To remove the smf manifest and its related smf service call xxx_smf_remove
    after the shutdown of the Sun Cluster Container smf resource. Specify the
    -f filename option if you used an alternate config file.

    A validation of your configuration can be done for a smf service with
    control_xxx validate FMRI or with control_xxx -R resource .. validate.

    All the three scripts use the xxx_config file if no -f option is specified.


16. Optional config file
    the xxx_register, xxx_smf_register and xxx_smf_remove script take the -f
    option. Use -f filename to specify an alternate config file.

17. This template is supplied as-is, if you have any comments please
    email ha-clusters-discuss@opensolaris.org.