"Fossies" - the Fresh Open Source Software Archive

Member "opensaf-5.21.09/src/smf/README" (31 May 2021, 11527 Bytes) of package /linux/misc/opensaf-5.21.09.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 #
    2 #      -*- OpenSAF  -*-
    3 #
    4 # (C) Copyright 2008 The OpenSAF Foundation
    5 #
    6 # This program is distributed in the hope that it will be useful, but
    7 # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    8 # or FITNESS FOR A PARTICULAR PURPOSE. This file and program are licensed
    9 # under the GNU Lesser General Public License Version 2.1, February 1999.
   10 # The complete license can be accessed from the following location:
   11 # http://opensource.org/licenses/lgpl-license.php
   12 # See the Copying file included with the OpenSAF distribution for full
   13 # licensing terms.
   14 #
   15 # Author(s): Ericsson AB
   16 #
   17 
   18 GENERAL
   19 =======
   20 This directory (smfsv) contains an implementation of the SAF SMF service
   21 version A.01.02.
   22 
   23 The SMF service is implemented as a director process (smfd) executing on the controllers
   24 using a 2N redundancy model and a node director (smfnd) process executing on all nodes 
   25 without redundancy. The node director is a helper process used by the director when
   26 a command needs to be executed on a specific node (e.g. bundle install/remove scripts).
   27 The smfnd component does also support handling of SMF callbacks through the SMF API.
   28 
   29 The smfd is the process that is the IMM-OI for the campaigns and executes the actual 
   30 upgrade campaign. Only one campaign can be executed at the time.
   31 When the admin operation execute is called on a campaign object a campaign thread is 
   32 started that will execute the campaign. The campaign thread will parse the campaign 
   33 xml file and create upgrade procedure threads for each procedure in the campaign. 
   34 The procedure threads will in turn be executed by sending an execute message to them. 
   35 Within the procedure thread each upgrade step will be executed in sequence. Between
   36 each step in the procedure the execution is interrupted and a message is sent to the 
   37 procedure thread to execute the next step. This is done so that it'll be possible to 
   38 send a suspend message to the procedure thread to interrupt the execution. 
   39 
   40 The design is intended to handle cases where the smfd needs to move between the two
   41 controllers in the middle of an campaign execution e.g. when upgrading opensaf itself.
   42 It's even thought to handle an upgrade where the whole cluster is rebooting in the
   43 middle of the campaign e.g. OS upgrade on all nodes at the same time.
   44 This is acheived by storing information in the IMM instead of using e.g. the CKPT 
   45 service.
   46 
   47 
   48 DEPENDENCIES
   49 ============
   50 smfsv depends of the following other OpenSAF services:
   51 - IMM
   52 - NTF
   53 - AMF
   54 - MDS
   55 - BASE
   56 - logtrace
   57 
   58 DIRECTORY STRUCTURE
   59 ===================
   60 services/saf/smfsv/config		Configuration files
   61 services/saf/smfsv/doc			SMF code documentation
   62 services/saf/smfsv/schema		XML schema files
   63 services/saf/smfsv/scripts		SMF script files
   64 services/saf/smfsv/smfd			SMF director implementation
   65 services/saf/smfsv/smfnd		SMF node director implementation
   66 libs/agents/saf/smfa			SMF Agent implementation
   67 libs/common/smfsv/include/		Common include files between smfd and smfnd
   68 
   69 FILE STRUCTURE
   70 ==============
   71 Not yet ...
   72 
   73 DATA STRUCTURES
   74 ===============
   75 smfd uses the following data structures:
   76 
   77 - Control block. Statically allocated, one instance. Access through a global
   78 pointer variable.
   79 
   80 smfnd uses the following data structures:
   81 
   82 - Control block. Statically allocated. Access through a global variable. 
   83 The control block contains list of registered SMF callbacks (future).
   84 
   85 
   86 STATE MACHINES
   87 ==============
   88 There are three state machines defined in the SMF specification.
   89 -Campaign state machine
   90 -Procedure state machine
   91 -Step state machine
   92 
   93 Implemented campaign states (all) :
   94    SA_SMF_CMPG_INITIAL =1,
   95    SA_SMF_CMPG_EXECUTING = 2,
   96    SA_SMF_CMPG_SUSPENDING_EXECUTION = 3,
   97    SA_SMF_CMPG_EXECUTION_SUSPENDED = 4,
   98    SA_SMF_CMPG_EXECUTION_COMPLETED = 5,
   99    SA_SMF_CMPG_CAMPAIGN_COMMITTED = 6,
  100    SA_SMF_CMPG_ERROR_DETECTED = 7,
  101    SA_SMF_CMPG_SUSPENDED_BY_ERROR_DETECTED = 8,
  102    SA_SMF_CMPG_ERROR_DETECTED_IN_SUSPENDING = 9,
  103    SA_SMF_CMPG_EXECUTION_FAILED = 10,
  104    SA_SMF_CMPG_ROLLING_BACK = 11,
  105    SA_SMF_CMPG_SUSPENDING_ROLLBACK = 12,
  106    SA_SMF_CMPG_ROLLBACK_SUSPENDED = 13,
  107    SA_SMF_CMPG_ROLLBACK_COMPLETED = 14,
  108    SA_SMF_CMPG_ROLLBACK_COMMITTED = 15,
  109    SA_SMF_CMPG_ROLLBACK_FAILED = 16
  110 
  111 Implemented procedure states (all) :
  112    SA_SMF_PROC_INITIAL =1,
  113    SA_SMF_PROC_EXECUTING = 2,
  114    SA_SMF_PROC_SUSPENDED = 3,
  115    SA_SMF_PROC_COMPLETED = 4,
  116    SA_SMF_PROC_STEP_UNDONE = 5,
  117    SA_SMF_PROC_FAILED = 6,
  118    SA_SMF_PROC_ROLLING_BACK = 7,
  119    SA_SMF_PROC_ROLLBACK_SUSPENDED = 8,
  120    SA_SMF_PROC_ROLLED_BACK = 9,
  121    SA_SMF_PROC_ROLLBACK_FAILED = 10
  122 
  123 Implemented step states (all) :
  124    SA_SMF_STEP_INITIAL =1,
  125    SA_SMF_STEP_EXECUTING = 2,
  126    SA_SMF_STEP_UNDOING = 3,
  127    SA_SMF_STEP_COMPLETED = 4,
  128    SA_SMF_STEP_UNDONE = 5,
  129    SA_SMF_STEP_FAILED = 6,
  130    SA_SMF_STEP_ROLLING_BACK = 7,
  131    SA_SMF_STEP_UNDOING_ROLLBACK = 8,
  132    SA_SMF_STEP_ROLLED_BACK = 9,
  133    SA_SMF_STEP_ROLLBACK_UNDONE = 10,
  134    SA_SMF_STEP_ROLLBACK_FAILED = 11
  135 
  136 State machines follows the state design pattern described in "Design Patterns,
  137 ISBN 0-201-63361-2".
  138 
  139 
  140 ADMINISTRATIVE API
  141 ==================
  142 The SaSmfCampaign object accepts administrative operations.
  143 The follwing admin operations are implemented:
  144    SA_SMF_ADMIN_EXECUTE = 1,
  145    SA_SMF_ADMIN_ROLLBACK = 2,
  146    SA_SMF_ADMIN_SUSPEND = 3,
  147    SA_SMF_ADMIN_COMMIT = 4,
  148    SA_SMF_ADMIN_VERIFY = 10
  149 
  150 SA_SMF_ADMIN_VERIFY is an extension to the SMF standard. It's used to verify
  151 that a campaign is OK to be executed without actually starting the execution.
  152 
  153 
  154 SMF ADAPTATION COMMANDS
  155 =======================
  156 SMF expects some commands to be available during execution. These commands are 
  157 called SMF adaptation commands.
  158 
  159 Smf is delivered with default implementations of these adaptation commands
  160   smf_backup_create
  161   smf_repository_check
  162   smf_bundle_check
  163   smf_node_check
  164   smf_cluster_reboot
  165 
  166 The default implementations are simple examples working on an OpenSAF reference configuration.
  167 These commands must typically be reimplemented to fit a specific system running OpenSAF. 
  168 
  169 The default implementation of the commands needed by SMF at runtime are located as below:
  170 /usr/local/lib/opensaf/smf_repository_check
  171 /usr/local/lib/opensaf/smf_node_check
  172 /usr/local/lib/opensaf/smf_cluster_reboot
  173 /usr/local/lib/opensaf/smf_bundle_check
  174 /usr/local/lib/opensaf/smf_backup_create
  175 
  176 The locations of the specific implementations are pointed out by the SMF configuration
  177 object described below. To override the default implementations appropriate attributes must be 
  178 set to point to the new locations (see chapter SMF CONFIGURATION).
  179 
  180 SMF CONFIGURATION
  181 =================
  182 SMF configuration data is kept by the SMF configuration class "smfConfig". The DN of the 
  183 configuration object is "smfConfig=1,safApp=safSmfService".
  184 
  185 Example below:
  186 # immlist smfConfig=1,safApp=safSmfService
  187 Name                                               Type         Value(s)
  188 ========================================================================
  189 smfVerifyTimeout                                   SA_TIME_T    100000000000 (0x174876e800, Thu Jan  1 01:01:40 1970)
  190 smfVerifyEnable                                    SA_UINT32_T  0 (0x0)
  191 smfSiSwapSiName                                    SA_STRING_T  safSi=SC-2N,safApp=OpenSAF 
  192 smfSiSwapMaxRetry                                  SA_UINT32_T  200 (0xc8)
  193 smfRepositoryCheckCmd                              SA_STRING_T  /usr/local/lib/opensaf/smf-repository-check 
  194 smfRebootTimeout                                   SA_TIME_T    600000000000 (0x8bb2c97000, Thu Jan  1 01:10:00 1970)
  195 smfNodeRebootCmd                                   SA_STRING_T  reboot 
  196 smfNodeCheckCmd                                    SA_STRING_T  /usr/local/lib/opensaf/smf-node-check 
  197 smfNodeBundleActCmd                                SA_STRING_T   
  198 smfInactivatePbeDuringUpgrade                      SA_UINT32_T  1 (0x1)
  199 smfImmPersistCmd                                   SA_STRING_T  immdump /etc/opensaf/imm.xml 
  200 smfConfig                                          SA_STRING_T  smfConfig=1 
  201 smfClusterRebootCmd                                SA_STRING_T  /usr/local/lib/opensaf/smf-cluster-reboot 
  202 smfClusterControllers                              SA_STRING_T  safNode=SC-1,safCluster=myClmCluster safNode=SC-2,safCluster=myClmCluster
  203 smfCliTimeout                                      SA_TIME_T    600000000000 (0x8bb2c97000, Thu Jan  1 01:10:00 1970)
  204 smfCampMaxRestart                                  SA_UINT32_T  10 (0xa)
  205 smfBundleCheckCmd                                  SA_STRING_T  /usr/local/lib/opensaf/smf-bundle-check 
  206 smfBackupCreateCmd                                 SA_STRING_T  /usr/local/lib/opensaf/smf-backup-create 
  207 smfAdminOpTimeout                                  SA_TIME_T    600000000000 (0x8bb2c97000, Thu Jan  1 01:10:00 1970)
  208 SaImmAttrImplementerName                           SA_STRING_T  safSmfService
  209 SaImmAttrClassName                                 SA_STRING_T  OpenSafSmfConfig
  210 SaImmAttrAdminOwnerName                            SA_STRING_T  <Empty>
  211 
  212 RPM
  213 ===
  214 SMF is included in the following RPM's
  215 opensaf-smf-libs-x.x.x
  216 opensaf-smf-director-x.x.x
  217 opensaf-smf-nodedirector-x.x.x
  218 
  219 COMMAND LINE INTERFACE
  220 ======================
  221 SMF delivers the following commands :
  222 smf-state
  223 smf-adm
  224 smf-find
  225 
  226 DEBUG
  227 =====
  228 To enable/disable log server traces in a running system, send signal USR2 to the
  229 smfd/smfnd process. Every time the trace state is toggled.
  230 
  231 Traces are written to the file:
  232 
  233 	$pkglogdir/osafsmfd.log
  234 	$pkglogdir/osafsmfnd.log
  235 
  236 To enable traces from the very start of the smf server, uncomment the line:
  237 
  238         #args="--tracemask=0xffffffff"
  239 
  240 in smfd.conf and/or smfnd.conf (see CONFIGURATION above) and restart the system.
  241 
  242 For fatal errors and notices about the execution the syslog is used.
  243 
  244 
  245 TEST
  246 ====
  247 To run campaigns in UML environment see the README file in
  248 directory "samples/smfsv"
  249 
  250 
  251 CONTRIBUTORS/MAINTAINERS
  252 ========================
  253 Bertil Engelholm <bertil.engelholm@ericsson.com>
  254 Ingvar Bergstr�m <ingvar.bergstrom@ericsson.com>
  255 
  256 The SMF service was originally cloned from the immsv and log services.
  257 
  258 MAINTAINER NOTES
  259 ================
  260 
  261 Applier for monitoring long Dn allowed setting
  262 ----------------------------------------------
  263 SMF is dependent on knowing the longDnsAllowed setting in the IMM configuration
  264 object. This setting may change at any time and to monitor changes an IMM
  265 applier is used.
  266 
  267 SmfImmApplierHdl:
  268 Contains a wrapper for the IMM APIs and callback functions used with an applier.
  269 A C++ class is used to create an interface for handling an applier e.g. create,
  270 start (initialize and set), stop (clear), get value etc.
  271 See SmfImmApplierHdl.hh for more information.
  272 
  273 SmfLongDnApplier:
  274 Runs an applier in a thread using the SmfImmApplierHdl.
  275 A C++ class is used to create an interface for running an applier.
  276 See SmfLongDnApplier.hh for more information.
  277 
  278 Installation in SMF:
  279 
  280 In smfd_main.cc the applier is constructed and created. A pointer to the applier
  281 object is stored in a global variable. The applier is started and stopped in the
  282 same place as the SMF object implementer when SMF gets a CSI set callback, see
  283 smfd_amf.cc. In previous versions of SMF a global variable in the smfd_cb struct
  284 , maxDnLength, was used to store the maximum allowed length of a Dn depending on
  285 the IMM config long Dn setting. This length information is used in many places
  286 in the SMF code. The global variable is replaced by a function call to
  287 GetSmfMaxDnLength() which returns the same length information. This function
  288 can be found in smfd_long_dn.hh