"Fossies" - the Fresh Open Source Software Archive

Member "opensaf-5.21.09/README" (14 Sep 2021, 39110 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. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 5.21.06_vs_5.21.09.

    1 This directory contains the 5.21.09 release of `OpenSAF'.
    2 
    3 `OpenSAF' is an open source project designed to implement a complete highly
    4 available operating environment based on Service Availability Forum (SA Forum)
    5 standards. The objective of the `OpenSAF' project is to accelerate broad
    6 adoption of a SA Forum compliant operating environment. OpenSAF also offers
    7 complementary services which are required in a complete high-availability system
    8 solution.
    9 
   10 `OpenSAF' has been originally contributed by Motorola ECC, by open sourcing its
   11 HA middleware suite Netplane Core Services (NCS).
   12 
   13 `OpenSAF' has a web site at http://opensaf.sourceforge.net/
   14 
   15 See file `COPYING.LIB' for copying conditions.
   16 See file `INSTALL' for compilation and installation instructions.
   17 See file `NEWS' for a list of major changes in the current release.
   18 See file `ChangeLog' for a list of detailed changes.
   19 See file `AUTHORS' for the names of maintainers.
   20 See file `THANKS' for a list of contributors.
   21 
   22 Please check the `Linux' distribution-specific notes below for any caveats
   23 related to your operating system.
   24 
   25 
   26 `OpenSAF' Architecture Overview
   27 ===============================
   28 
   29 `OpenSAF' software is distributed in nature. In the HA cluster there are two
   30 types of nodes: System Controllers and Payloads. One system controller will be
   31 running in Active mode, another system controller will be running in Standby
   32 mode, and the rest of the system controllers (if any) will be spares that are
   33 ready to take over as Active or Standby in case of a fault.
   34 
   35 The `OpenSAF' software is divided in to following classes of Modules:
   36 
   37     * Directors:
   38       The Service directors run on the Controller node. They interact with Node
   39       Directors running on the Payload nodes and provide service specific
   40       functionality.
   41 
   42     * Node Directors:
   43       Node directors distribute the service responsibilities with directors.
   44       Node directors interact with Agents to provide service functionality to
   45       the user applications. Node directors run both on System Controller node
   46       and Payload nodes.
   47 
   48     * Servers:
   49       Servers run on the System Controller and they talk to Agents to provide
   50       service functionality to the users. If the service is having servers then
   51       it doesn't have directors, node director pieces. If the service doesn't
   52       have node local functionality then "Server - Agent" architectural approach
   53       is used.
   54 
   55     * Agents: Agents are the service libraries which are linked with user
   56       applications and provide service to the user applications by interacting
   57       with other service parts.
   58 
   59 User applications can run on either System Controller node or Payload node. But
   60 it is advisable to run the user applications on the Payload nodes, so your
   61 applications are not impacted when System Controller failover happens due to any
   62 failures in `OpenSAF' Modules.
   63 
   64 The OpenSAF infrastructure is made highly available by modeling the individual
   65 services as AMF components. All the Node Directors use no redundancy model and
   66 are restart capable with component capability 1_ACTIVE. All the Directors and
   67 Servers use 2N redundancy model with "1_ACTIVE_OR_1_STANDBY".
   68 
   69 By default (in 4.2) OpenSAF processes will run as the UNIX system user "opensaf"
   70 which is a member of the "opensaf" UNIX group. Only two processes are running as
   71 root, amfnd and smfnd. Reason is that amfnd need todo that for backwards
   72 compatible reasons and the programs it starts might be designed to require root
   73 access. The reason for smfnd for running as root is that it typically installs
   74 rpms which requires root access. The rpms built by opensaf will create these
   75 users using rpm scriptlets.
   76 
   77 When using a "make install" system, either manually do the same as the rpm post
   78 install scriptlet (create group and user, configure sudo etc) or configure
   79 opensaf to run as root.
   80 
   81 See the build section how to revert to old all root behaviour.
   82 
   83 
   84 Downloading
   85 ===========
   86 
   87 `OpenSAF' release archives can be obtained from here:
   88 
   89     http://sourceforge.net/projects/opensaf/files/releases/
   90 
   91 
   92 Documentation
   93 =============
   94 
   95 `OpenSAF' implements various `SAF AIS' services. The Service Availability Forum
   96 Specifications can be downloaded from here:
   97 
   98     http://www.saforum.org/specification/download/
   99 
  100 The `OpenSAF' Programmer's Reference Manuals can be obtained from here:
  101 
  102     http://sourceforge.net/projects/opensaf/files/docs/
  103 
  104     * OpenSAF Overview
  105     * OpenSAF Availability Service
  106     * OpenSAF Cluster Membership Service
  107     * OpenSAF Checkpoint Service
  108     * OpenSAF Event Distribution Service
  109     * OpenSAF Global Lock Service
  110     * OpenSAF Information Model Management Service
  111     * OpenSAF LOG Service
  112     * OpenSAF Message Queue Service
  113     * OpenSAF Notification Service
  114     * OpenSAF Platform Management Service
  115     * OpenSAF Software Management Framework Service
  116 
  117 Development
  118 ===========
  119 
  120 `OpenSAF' development is hosted by SourceForge, the main project portal can be
  121 found here:
  122 
  123   http://sourceforge.net/projects/opensaf/
  124 
  125 You can find most information concerning the development of `OpenSAF' at this
  126 site.
  127 
  128 `OpenSAF' is using `Git' as its Source Control Management system tool. `Git' is
  129 a fast, lightweight Source Control Management system designed for efficient
  130 handling of very large distributed projects and can be obtained from here:
  131 
  132     http://git-scm.com/
  133 
  134 
  135 Building from `Git'
  136 ===================
  137 
  138 If you don't want to use one of the `OpenSAF' release archive, you can get a
  139 clone and bootstrap it by doing the following steps:
  140 
  141     % git clone git://git.code.sf.net/p/opensaf/git opensaf-git
  142     % cd opensaf-git
  143     % ./bootstrap.sh
  144 
  145 After bootstraping follow the standard build instructions.
  146 
  147 
  148 Bug Reporting
  149 =============
  150 
  151 You can send `OpenSAF' bug reports to <opensaf-devel@lists.sourceforge.net>.
  152 You can subscribe to the development mailing list from here:
  153 
  154     https://lists.sourceforge.net/lists/listinfo/opensaf-devel
  155 
  156 If you need help using `OpenSAF', try <opensaf-users@lists.sourceforge.net>
  157 instead. You can subscribe to the user mailing list from here:
  158 
  159     https://lists.sourceforge.net/lists/listinfo/opensaf-users
  160 
  161 You can also use the online bug tracking system in the `OpenSAF' project to
  162 submit new problem reports or search for existing ones:
  163 
  164     http://sourceforge.net/p/opensaf/tickets/
  165 
  166 When reporting bug, make sure you provide various useful informations about your
  167 Linux environment:
  168 
  169     * Distribution used (e.g. Fedora, Ubuntu, SUSE, PNE-LE etc.)
  170     * The revision of your Linux distribution
  171     * Package revisions of the prerequisites (e.g. net-snmp, tipc etc.)
  172     * If using the package prerequisites from the Linux distribution?
  173     * Build tool revisions (e.g. gcc, automake, autoconf, libtool)
  174     * If using cross-compiling + target information
  175 
  176 
  177 Source Tree Structure
  178 =====================
  179 
  180 .
  181 +-- bin  (Built executables)
  182 +-- java  (Java source code)
  183 |   +-- ais_api
  184 |   |   +-- src
  185 |   |       +-- org
  186 |   |           +-- saforum
  187 |   |               +-- ais
  188 |   |                   +-- amf
  189 |   |                   +-- clm
  190 |   +-- ais_api_impl  (Java AIS API mapping Implementation for AMF,CLM)
  191 |   |   +-- src
  192 |   |       +-- org
  193 |   |           +-- opensaf
  194 |   |               +-- ais
  195 |   |                   +-- amf
  196 |   |                   +-- clm
  197 |   +-- am4j_sailfin
  198 |   |   +-- amf-configuration
  199 |   |   +-- clc-cli-scripts
  200 |   +-- amf_agent
  201 |   |   +-- src
  202 |   |       +-- com
  203 |   |           +-- ericsson
  204 |   |               +-- saf
  205 |   |                   +-- amf
  206 |   +-- apitest  (OpenSAF Test suites)
  207 |       +-- configandscript
  208 |       +-- src
  209 |           +-- org
  210 |               +-- opensaf
  211 |                   +-- ais
  212 |                       +-- amf
  213 |                       |   +-- test
  214 |                       +-- clm
  215 |                       |   +-- test
  216 |                       +-- test
  217 +-- lib  (Built libraries)
  218 +-- m4  (Extra M4 macros for the build)
  219 +-- pkgconfig  (OpenSAF Pkgconfig file)
  220 +-- python  (Python source code)
  221 |   +-- pyosaf
  222 |   |   +-- utils
  223 |   |       +-- clm
  224 |   |       +-- immoi
  225 |   |       +-- immom
  226 |   |       +-- log
  227 |   |       +-- ntf
  228 |   +-- samples
  229 +-- rpms  (Built RPMs)
  230 +-- samples  (OpenSAF sample applications for SAF services)
  231 |   +-- amf
  232 |   |   +-- campaigns
  233 |   |   +-- non_sa_aware
  234 |   |   +-- proxy
  235 |   |   +-- sa_aware
  236 |   |   +-- wrapper
  237 |   +-- cpsv
  238 |   |   +-- ckpt_demo
  239 |   |   +-- ckpt_track_demo
  240 |   +-- edsv
  241 |   +-- glsv
  242 |   +-- immsv
  243 |   |   +-- immom_python
  244 |   |   +-- immutils
  245 |   +-- m4
  246 |   +-- mqsv
  247 |   +-- smfsv
  248 |       +-- campaigns
  249 +-- scripts  (OpenSAF scripts)
  250 +-- src  (C and C++ source code)
  251 |   +-- ais
  252 |   |   +-- include  (AIS header files)
  253 |   |   |   +-- opensaf  (OpenSAF public headers)
  254 |   |   +-- lib  (AIS shared libraries)
  255 |   +-- amf
  256 |   |   +-- agent  (sources for OpenSAF agents)
  257 |   |   +-- amfd
  258 |   |   |   +-- tests
  259 |   |   +-- amfnd
  260 |   |   +-- amfwd
  261 |   |   +-- common
  262 |   |   +-- config
  263 |   |   +-- tools
  264 |   +-- base  (OpenSAF base library)
  265 |   |   +-- tests
  266 |   +-- ckpt
  267 |   |   +-- agent  (sources for OpenSAF agents)
  268 |   |   +-- apitest  (OpenSAF Test suites)
  269 |   |   +-- ckptd
  270 |   |   +-- ckptnd
  271 |   |   +-- common
  272 |   |   +-- config
  273 |   +-- clm
  274 |   |   +-- agent  (sources for OpenSAF agents)
  275 |   |   +-- apitest  (OpenSAF Test suites)
  276 |   |   +-- clmd
  277 |   |   +-- clmnd
  278 |   |   +-- common
  279 |   |   +-- config
  280 |   +-- dtm
  281 |   |   +-- dtmnd
  282 |   |   +-- transport
  283 |   |       +-- tests
  284 |   +-- evt
  285 |   |   +-- agent  (sources for OpenSAF agents)
  286 |   |   +-- apitest  (OpenSAF Test suites)
  287 |   |   +-- common
  288 |   |   +-- config
  289 |   |   +-- evtd
  290 |   +-- fm
  291 |   |   +-- config
  292 |   |   +-- fmd
  293 |   +-- imm
  294 |   |   +-- agent  (sources for OpenSAF agents)
  295 |   |   +-- apitest  (OpenSAF Test suites)
  296 |   |   |   +-- implementer
  297 |   |   |   +-- management
  298 |   |   +-- common
  299 |   |   +-- config
  300 |   |   +-- immd
  301 |   |   +-- immloadd
  302 |   |   +-- immnd
  303 |   |   +-- immpbed
  304 |   |   +-- tools  (IMM commandline utilities and IMM XML merge tool)
  305 |   +-- lck
  306 |   |   +-- agent  (sources for OpenSAF agents)
  307 |   |   +-- apitest  (OpenSAF Test suites)
  308 |   |   +-- common
  309 |   |   +-- config
  310 |   |   +-- lckd
  311 |   |   +-- lcknd
  312 |   +-- libjava
  313 |   +-- log
  314 |   |   +-- agent  (sources for OpenSAF agents)
  315 |   |   +-- apitest  (OpenSAF Test suites)
  316 |   |   +-- common
  317 |   |   +-- config
  318 |   |   +-- logd
  319 |   |   +-- tools  (SAFLOG command line utility)
  320 |   +-- mbc
  321 |   |   +-- apitest  (OpenSAF Test suites)
  322 |   +-- mds
  323 |   |   +-- apitest  (OpenSAF Test suites)
  324 |   +-- msg
  325 |   |   +-- agent  (sources for OpenSAF agents)
  326 |   |   +-- apitest  (OpenSAF Test suites)
  327 |   |   +-- common
  328 |   |   +-- config
  329 |   |   +-- msgd
  330 |   |   +-- msgnd
  331 |   +-- nid
  332 |   |   +-- agent  (sources for OpenSAF agents)
  333 |   +-- ntf
  334 |   |   +-- agent  (sources for OpenSAF agents)
  335 |   |   +-- apitest  (OpenSAF Test suites)
  336 |   |   +-- common
  337 |   |   +-- config
  338 |   |   +-- ntfd
  339 |   |   +-- ntfimcnd
  340 |   |   +-- tools  (SAFNTF command line utility)
  341 |   +-- osaf
  342 |   |   +-- apitest  (OpenSAF Test suites)
  343 |   |   +-- config
  344 |   |   +-- immutil
  345 |   |   +-- saflog
  346 |   +-- plm
  347 |   |   +-- agent  (sources for OpenSAF agents)
  348 |   |   +-- apitest  (OpenSAF Test suites)
  349 |   |   +-- common
  350 |   |   +-- config
  351 |   |   +-- plmcd
  352 |   |   +-- plmd
  353 |   +-- rde
  354 |   |   +-- agent  (sources for OpenSAF agents)
  355 |   |   +-- common
  356 |   |   +-- config
  357 |   |   +-- rded
  358 |   |   +-- tools
  359 |   +-- smf
  360 |       +-- agent  (sources for OpenSAF agents)
  361 |       +-- common
  362 |       +-- config
  363 |       +-- scripts
  364 |       +-- smfd
  365 |       +-- smfnd
  366 |       +-- tools
  367 +-- tools  (OpenSAF developer tools and UML devel environment)
  368     +-- cluster_sim_uml
  369     |   +-- archive
  370     |   |   +-- scripts
  371     |   +-- etc
  372     |   |   +-- init.d
  373     |   +-- uml
  374     |       +-- bin
  375     |       +-- config
  376     |       +-- root_template
  377     |           +-- bin
  378     |           +-- dev
  379     |           |   +-- pts
  380     |           |   +-- shm
  381     |           +-- etc
  382     |           |   +-- init.d
  383     |           +-- home
  384     |           +-- lib
  385     |           |   +-- modules
  386     |           +-- lib64
  387     |           +-- opt
  388     |           +-- proc
  389     |           +-- root
  390     |           |   +-- www
  391     |           |       +-- cgi-bin
  392     |           +-- sbin
  393     |           +-- sys
  394     |           +-- tmp
  395     |           +-- usr
  396     |           |   +-- bin
  397     |           |   +-- sbin
  398     |           +-- var
  399     |               +-- lib
  400     |               |   +-- opensaf
  401     |               +-- log
  402     |               |   +-- opensaf
  403     |               +-- run
  404     |                   +-- opensaf
  405     +-- devel
  406         +-- dot
  407         +-- doxygen
  408         +-- indent
  409         +-- model
  410         +-- review
  411 
  412 Prerequisites
  413 =============
  414 
  415 The following software is required to build OpenSAF:
  416 
  417     * libc6-dev (2.11 or later)
  418     * libxml2-dev (2.7 or later)
  419     * automake (1.11.1 or later)
  420     * m4
  421     * autoconf (2.64 or later)
  422     * libtool (2.2.6 or later)
  423     * pkg-config
  424     * gcc/g++ (4.8.1 or later)
  425     * GNU make
  426     * python-dev(el)
  427     * Optionally:
  428         * The Linux Kernel with TIPC support enabled. This is required when
  429         opensaf is built with the option --enable-tipc. OpenSAF requires Linux
  430         version 4.4.22 or later when configured with the --enable-tipc option.
  431 
  432         * When PLM is enabled, an HPI implementation (e.g. OpenHPI)
  433         * When IMM PBE feature is enabled, libsqlite3-dev (3.6 or later)
  434 
  435     If enabling optional Java support:
  436         - A Java 1.5+ capable JDK (e.g. OpenJDK 1.7)
  437         - Apache Ant
  438 
  439 If a specific prerequisite package revision isn't working for you, please let us
  440 know about it following the instructions from the Bug Reporting section.
  441 
  442 
  443 Building `OpenSAF'
  444 ==================
  445 
  446 Some features needs to be configured at build time but don't have configure
  447 support, these are explained here.
  448 
  449 1) Configure a non flat MDS addressing scheme (deprecated)
  450 
  451 In the default (from OpenSAF 4.3 onwards) addressing scheme, TIPC node addresses
  452 looks like 1.1.1, 1.1.2 etc, and the slot_id can be in the range from 1 and up
  453 to 4095 (though note that prior to OpenSAF 5.0, the maximum supported slot_id
  454 was 255).
  455 
  456 To re-enable the old (pre OpenSAF 4.3) non flat addressing, configure the
  457 constant MDS_USE_SUBSLOT_ID=1 at configure time as in:
  458 
  459     % ./configure CPPFLAGS="-DMDS_USE_SUBSLOT_ID=1 ..."
  460 
  461 In the non flat scheme, the slot ID is shifted up 4 bits and subslot ID is added
  462 in the 4 LSB. The consequence of this is reduced number of addressable nodes in
  463 the cluster. This scheme is more likely to be used in xTCA type of systems and
  464 produces TIPC addresses like 1.1.31, 1.1.47 etc.
  465 
  466 More configuration is needed, see nid.conf in 00-README.conf
  467 
  468 
  469 2) Run as root (optional)
  470 
  471 If the old (<4.2) behaviour of running all processes as root is desired, use the
  472 following configure command:
  473 
  474     % ./configure CPPFLAGS=-DRUNASROOT
  475 
  476 
  477 3) Configure TIPC importance (optional)
  478 
  479 The default TIPC importance is LOW for all services except for AVND which is
  480 HIGH.  In some cases the default importance must be changed if e.g. an
  481 application starves the LOW importance communication level.  To change the
  482 default importance, use the following configure command
  483 
  484    % ./configure CPPFLAGS=-DTIPCIMPORTANCE=level
  485    where level is any of TIPC_LOW_IMPORTANCE, TIPC_MEDIUM_IMPORTANCE or
  486    TIPC_HIGH_IMPORTANCE
  487    e.g. configure CPPFLAGS=-DTIPCIMPORTANCE=TIPC_HIGH_IMPORTANCE
  488 
  489 Note: Giving same importance to AVND & all other Opensaf models is not preferred
  490 option. The behavior is unsupported.
  491 
  492 
  493 4) Configure GCC hardening options (optional)
  494 
  495 By default, the options "-fstack-protector -D_FORTIFY_SOURCE=2" are passed to
  496 GCC for improved security. You can override these options by setting the
  497 OSAF_HARDEN_FLAGS when configuring OpenSAF. For example:
  498 
  499    % ./configure OSAF_HARDEN_FLAGS="-fstack-protector-all -D_FORTIFY_SOURCE=2"
  500 
  501 If you are using a released archive (dist tarball) follow the simple common
  502 steps:
  503 
  504     % ./configure && make
  505 
  506     OR
  507 
  508     % ./configure && make rpm
  509 
  510 Note: `OpenSAF' can safely be built with parallel jobs using -jX, where X should
  511       be the number of CPU you want to dedicate + 1
  512 
  513 If you are Building from `Git', make sure you followed the required steps before
  514 trying to `configure' (i.e. bootsrapping).
  515 
  516     % ./bootstrap.sh
  517     % ./configure && make
  518     OR
  519     % ./configure && make rpm
  520 
  521 By default, OpenSAF is built with TCP as the transport.
  522 
  523 By default, all 'OpenSAF' services are enabled to be built and `OpenSAF' will
  524 assume the following `configure' options by default:
  525 
  526     --disable-java --disable-imm-pbe --disable-tests
  527 
  528 Some OpenSAF services/features can be disabled through configure options.  To
  529 alter the default configure options, the following configure options are
  530 available w.r.t enabling/disabling the build for a particular OpenSAF service:
  531 (The below options can also be known from the command % ./configure --help)
  532 
  533   --disable-rpath         Patches libtool to not use rpath in the libraries
  534                           produced.
  535   --disable-rpm-target    disable support for the "make rpm" target
  536                           [default=no]
  537   --enable-gcov           enable code coverage [default=no]
  538   --enable-experimental   enable experimental code [default=no]
  539   --enable-python         enable the Python AIS bindings [default=yes]
  540   --enable-java           enable the Java AIS interface mapping [default=no]
  541   --enable-am4j           enable the AM4J agent [default=no]
  542   --enable-tipc           enable building the TIPC [default=no]
  543   --enable-tests          enable building the OpenSAF testing programs
  544                           [default=no]
  545   --enable-imm-pbe        enable the IMM Persistent Backend Interface
  546                           [default=yes]
  547   --enable-ntf-imcn       enable the NTF Information Model Notification
  548                           producer [default=no]
  549   --disable-ais-ckpt      disable building the SAI-AIS-CKPT service
  550                           [default=no]
  551   --disable-ais-evt       disable building the SAI-AIS-EVT service
  552                           [default=no]
  553   --disable-ais-lck       disable building the SAI-AIS-LCK service
  554                           [default=no]
  555   --disable-ais-msg       disable building the SAI-AIS-MSG service
  556                           [default=no]
  557   --disable-ais-smf       disable building the SAI-AIS-SMF service
  558                           [default=no]
  559   --disable-ais-plm       disable building the SAI-AIS-PLM service
  560                           [default=no]
  561   --disable-dependency-tracking  speeds up one-time build
  562   --enable-dependency-tracking   do not reject slow dependency extractors
  563   --enable-shared[=PKGS]  build shared libraries [default=yes]
  564   --enable-static[=PKGS]  build static libraries [default=yes]
  565   --enable-fast-install[=PKGS]
  566                           optimize for fast installation [default=yes]
  567   --disable-libtool-lock  avoid locking (might break parallel builds)
  568 
  569   --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
  570   --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
  571   --with-rpm-release=[ARG]
  572                           set the RPM release value to be current timestamp
  573                           (ARG=timestamp); set the RPM release value to be the
  574                           global revision (ARG=global-rev); set the RPM
  575                           release value to be the local revision
  576                           (ARG=local-rev); set the RPM release value to be
  577                           <val> (ARG=<val>, [default=1])
  578   --with-hpi-interface=[ARG]
  579                           autodetect the SAHPI_INTERFACE_VERSION (ARG=check
  580                           [default]); set the SAHPI_INTERFACE_VERSION to
  581                           A.01.01 (ARG=A01); set the SAHPI_INTERFACE_VERSION
  582                           to B.01.01 (ARG=B01); set the
  583                           SAHPI_INTERFACE_VERSION to B.02.01 (ARG=B02); set
  584                           the SAHPI_INTERFACE_VERSION to B.03.01 (ARG=B03)
  585   --with-initscriptdir=[DIR]
  586                           use DIR as the directory containing the init.d
  587                           scripts. [default=/etc/init.d]
  588   --with-pic              try to use only PIC/non-PIC objects [default=use
  589                           both]
  590   --with-gnu-ld           assume the C compiler uses GNU ld [default=no]
  591   --with-jdk=DIR          use JDK from DIR
  592   --with-ant=DIR          Use ant from DIR
  593 
  594 Use one of the following forms to enable an option:
  595 
  596     --with-<mumble>        OR --enable-<mumble>
  597     --with-<mumble>=yes         OR      --enable-<mumble>=yes
  598     --without-<mumble>=no       OR      --disable-<mumble>=no
  599 
  600 For eg:- To enable building the IMM PBE feature, use the following option:
  601 
  602     % ./configure --enable-imm-pbe
  603 
  604 Use one of the following forms to disable an option:
  605 
  606     --without-<mumble>          OR      --disable-<mumble>
  607     --without-<mumble>=yes      OR      --disable-<mumble>=yes
  608     --with-<mumble>=no          OR      --enable-<mumble>=no
  609 
  610 For eg:- To disable building the LOCK service, use the following option:
  611 
  612      % ./configure --disable-ais-lck
  613 
  614 The `--with-<mumble>' option forms are used for external package support and the
  615 `--enable-<mumble>' option forms are used for internal component state.
  616 
  617 Note: When PLM is enabled, `OpenSAF' relies on <SaHpi.h>, even if the user
  618 thinks he's not using a specific HPI implementation. This is a build dependency
  619 and the user still needs to tell the build system to be using the proper
  620 CPPFLAGS/CFLAGS/CXXFLAGS where to find a dummy <SaHpi.h>
  621 
  622 By using `./configure --enable-tipc', you are building OpenSAF to support TIPC
  623 also as the transport. Upon enabling this option, the OpenSAF binaries support
  624 both TIPC and TCP as the transport and to use TIPC, you have to change the
  625 variable MDS_TRANSPORT to TIPC in the nid.conf file (see nid.conf in
  626 00-README.conf). By choosing this option you have the flexibility to change from
  627 using tipc to tcp without having to rebuild.
  628 
  629 By using `./configure --enable-java', you are enabling the Java AIS mapping
  630 support in the build system. Specials M4 macros will be used to autodetect what
  631 `JDK' and `Ant' program you are using. By default this options is disabled.
  632 
  633 By using `./configure --with-jdk=DIR', you can force the build system to use a
  634 specific JDK installed in a non-standard location on your system.
  635 
  636 By using `./configure --with-ant=DIR', you can force the build system to use a
  637 specific Ant version installed in a non-standard location on your system.
  638 
  639 By using `./configure --with-rpm-release', you can change the default release
  640 token in the generated rpm filename. Predefined values exist like the build
  641 timestamp, the `Git' revision used to when building the code, and also you can
  642 add your own free text token.
  643 
  644 By using `./configure --with-hpi-interface', you can force the HPI interface
  645 version used. By default it's autodetected by scanning the SaHpi.h header, but
  646 when cross-compiling is used it's not possible to run the test code for that
  647 autodetection.
  648 
  649 By using `./configure --disable-rpm-target', you are masking out the `make rpm'
  650 target, some build systems provide their own `make rpm` rule, it would then be
  651 clashing with the OpenSAF rule.
  652 
  653 
  654 Building `OpenSAF' RPMs
  655 =======================
  656 
  657 As shown in the Building `OpenSAF' section, generating RPMs can be done using:
  658 
  659     % ./configure && make rpm
  660 
  661 The special `make rpm' target will generate a dist archive, create the `OpenSAF'
  662 SRPM using the opensaf.spec file, and finally launch the rpmbuild process. You
  663 can find the generated RPMs under `./rpms/RPMS/<build_arch>/':
  664 
  665 RPMs per OpenSAF Service are generated. For eg:-
  666 
  667 * opensaf-<svcname-director>-<Release>.<build_arch>.rpm:
  668   RPM containing the particular OpenSAF service director/server's binaries,
  669   libraries, CLC scripts, and the immxml classes and objects owned/implemented
  670   by the service.
  671 
  672 * opensaf-<svcname-nodedirector>-<Release>.<build_arch>.rpm:
  673   RPM containing the particular OpenSAF service NodeDirector's binaries, CLC
  674   scripts.
  675 
  676 * opensaf-<svcname-libs>-<version>.<Release>.<build_arch>.rpm:
  677   RPM containing the particular OpenSAF service libraries to be linked by User
  678   and any User Program (command line tool/utility) provided the service.
  679 
  680 With the default configure options, the following RPMs are generated:
  681 
  682 opensaf-<Release>.<arch>.rpm
  683 opensaf-controller-<Release>.<arch>.rpm
  684 opensaf-devel-<Release>.<arch>.rpm
  685 opensaf-samples-<Release>.<arch>.rpm
  686 opensaf-payload-<Release>.<arch>.rpm
  687 opensaf-amf-libs-<Release>.<arch>.rpm
  688 opensaf-clm-libs-<Release>.<arch>.rpm
  689 opensaf-imm-director-<Release>.<arch>.rpm
  690 opensaf-imm-libs-<Release>.<arch>.rpm
  691 opensaf-imm-nodedirector-<Release>.<arch>.rpm
  692 opensaf-libs-<Release>.<arch>.rpm
  693 opensaf-log-libs-<Release>.<arch>.rpm
  694 opensaf-log-server-<Release>.<arch>.rpm
  695 opensaf-ntf-libs-<Release>.<arch>.rpm
  696 opensaf-ntf-server-<Release>.<arch>.rpm
  697 opensaf-plm-coordinator-<Release>.<arch>.rpm
  698 opensaf-plm-hpi-<Release>.<arch>.rpm
  699 opensaf-plm-libs-<Release>.<arch>.rpm
  700 opensaf-plm-server-<Release>.<arch>
  701 opensaf-smf-director-<Release>.<arch>.rpm
  702 opensaf-smf-libs-<Release>.<arch>.rpm
  703 opensaf-smf-nodedirector-<Release>.<arch>.rpm
  704 opensaf-ckpt-director-<Release>.<arch>.rpm
  705 opensaf-ckpt-libs-<Release>.<arch>.rpm
  706 opensaf-ckpt-nodedirector-<Release>.<arch>.rpm
  707 opensaf-evt-libs-<Release>.<arch>.rpm
  708 opensaf-evt-server-<Release>.<arch>.rpm
  709 opensaf-lck-director-<Release>.<arch>.rpm
  710 opensaf-lck-libs-<Release>.<arch>.rpm
  711 opensaf-lck-nodedirector-<Release>.<arch>.rpm
  712 opensaf-msg-director-<Release>.<arch>.rpm
  713 opensaf-msg-libs-<Release>.<arch>.rpm
  714 opensaf-msg-nodedirector-<Release>.<arch>.rpm
  715 
  716 
  717 opensaf-controller: (Meta Package)
  718 Contains the controller specifc config, script files, the IMM classes and
  719 objects for OpenSAF infrastructure services, And the dependencies for installing
  720 the controller rpm.
  721 
  722 opensaf-payload: (Meta Package)
  723 Contains the payload specific config file And the dependencies for installing
  724 the payload rpm.
  725 
  726 opensaf-<Release>.<arch>.rpm
  727 Contains configuration and script file that are common to both a
  728 controller/payload node configuration.
  729 
  730 opensaf-devel: (Optional)
  731 Contains the development headers and static & shared libs for user application
  732 development/linkage.
  733 
  734 opensaf-java: (Optional)
  735 Contains the Java AIS mapping jars and native libs.
  736 
  737 opensaf-samples: (Optional)
  738 Contains the sample applications source code.
  739 
  740 
  741 Installing `OpenSAF'
  742 ====================
  743 
  744 `OpenSAF' can be installed in several ways. When doing development, a user might
  745 prefer using the classic `make install' way to using RPMs.  It can be achieved
  746 like this:
  747 
  748     % make install
  749 
  750     OR
  751 
  752     % make install DESTDIR=<staged_install_directory>
  753 
  754 After installing `OpenSAF' you will need to run `ldconfig' because `OpenSAF'
  755 places internal libs in the `$pkglibdir' (e.g. /usr/lib/opensaf/). This ldconfig
  756 operation is handled automatically by using rpm installation.
  757 
  758 In production systems, RPMs should be preferred to classic `make install`.
  759 
  760 To setup a development environment for a given OpenSAF service, install
  761 following RPMs:
  762     % rpm -ivh opensaf-<svc_name>-libs-<Release>.<build_arch>.rpm
  763     % rpm -ivh opensaf-devel-<Release>.<build_arch>.rpm
  764     % rpm -ivh opensaf-samples-<Release>.<build_arch>.rpm
  765 
  766 If Java AIS mapping was enabled, install the following RPM:
  767 
  768     % rpm -ivh opensaf-java-<version>.<build_arch>.rpm
  769 
  770 If you are installing `OpenSAF' from a supported `yum' server, it will resolve
  771 the proper dependencies for you:
  772 
  773     % yum install opensaf-controller
  774 
  775     OR
  776 
  777     % yum install opensaf-payload
  778 
  779 Here is where individual `OpenSAF' components get installed:
  780 
  781     * Documentation: `$docdir' (e.g /usr/share/doc/packages/opensaf/)
  782     * Samples, Templates: `$pkgdatadir'/samples (e.g.
  783       /usr/share/opensaf/samples)
  784     * IMM XML Merge tool: `pkgimmxmldir' (e.g. /usr/share/opensaf/samples/immxml
  785     * SAF libraries: `$libdir' (e.g. /usr/lib/)
  786     * SAF headers: `$includedir' (e.g. /usr/include/)
  787     * Configuration: `$pkgsysconfdir' (e.g. /etc/opensaf/)
  788     * OpenSAF headers: `$pkgincludedir' (e.g. /usr/include/opensaf/)
  789     * Runtime Misc.: `$pkglocalstate' (e.g. /var/lib/opensaf/)
  790     * OpenSAF internals(binaries,clc-scripts): `$pkglibdir' (e.g.
  791       /usr/lib/opensaf/)
  792     * User programs: `$bindir' (e.g. /usr/bin/)
  793     * SysV scripts: `$sysconfdir/init.d/' (e.g. /etc/init.d/)
  794     * Logs: `$localstatedir/log/opensaf' (e.g. /var/log/opensaf/)
  795     * PID: `$localstatedir/run/opensaf/' (e.g. /var/run/opensaf/)
  796 
  797 
  798 
  799 Linking with `OpenSAF' AIS Services
  800 ===================================
  801 
  802 `OpenSAF' provides `pkgconfig' files for each AIS services.  These files are
  803 installed with the other system `*.pc' files in `$(libdir)/pkgconfig':
  804 
  805    * opensaf-amf.pc
  806    * opensaf-ckpt.pc
  807    * opensaf-clm.pc
  808    * opensaf-evt.pc
  809    * opensaf-imm.pc
  810    * opensaf-lck.pc
  811    * opensaf-log.pc
  812    * opensaf-msg.pc
  813    * opensaf-ntf.pc
  814    * opensaf-plm.pc
  815 
  816 
  817 There are two easy ways to use `pkgconfig'. The first one is to call it directly
  818 from a `Makefile' and assign its content to make variables e.g.:
  819 
  820    AMF_LIBS=`pkg-config opensaf-amf --libs`
  821    AMF_CFLAGS=`pkg-config opensaf-amf --cflags`
  822 
  823 Or if your application is using the `GNU Build System' with `autotools', you can
  824 use a special `autoconf' macro provided by `pkgconfig' e.g.:
  825 
  826    -- in configure.ac --
  827    PKG_CHECK_MODULES(AMF, opensaf-amf)
  828 
  829 It will then provides two special variables available to `automake':
  830 
  831    -- in Makefile.am --
  832    mumble_CFLAGS = @AMF_CFLAGS@
  833    mumble_LDADD = @AMF_LIBS@
  834 
  835 
  836 How to Configure `OpenSAF'
  837 ==========================
  838 
  839 See file `00-README.conf' for the configuration file syntax/format.
  840 
  841 How to Run `OpenSAF'
  842 ====================
  843 When PLM is enabled, The 'plmcd' SysV init script is installed in
  844 `$sysconfdir/rc.d/init.d' (e.g. /etc/rc.d/init.d/) directory.
  845 
  846 The `OpenSAF' SysV init script is installed in `$sysconfdir/rc.d/init.d'
  847 (e.g. /etc/rc.d/init.d/)
  848 
  849 Commands to Start OpenSAF When PLM is disabled:
  850 ===============================================
  851 After a minimum configuration of
  852 
  853  - slot_id (only required when using IPv6 addresses), nodeinit.conf.controller,
  854    node_name, imm.xml(Generated) and configure_tipc(if needbe), for the
  855    controller
  856   (OR)
  857  - slot_id (only required when using IPv6 addresses), nodeinit.conf.payload and
  858    node_name, for the payload.
  859 
  860 the following command shall start the OpenSAF services:
  861 
  862 % /etc/init.d/opensafd start [start|stop|status]
  863 
  864 If your distro uses systemd (e.g. OpenSUSE 12.1 or greater, Fedora 15 or
  865 greater) use the following command to start the OpenSAF services:
  866 
  867 % systemctl [start|stop|status] opensafd.service
  868 
  869 Commands to Start OpenSAF When PLM is enabled:
  870 ==============================================
  871 After a minimum configuration of
  872 
  873  - slot_id (only required when using IPv6 addresses), nodeinit.conf.controller,
  874    node_name, imm.xml(Generated) and configure_tipc(if needbe) and the
  875    plmcd.conf, for the controller
  876   (OR)
  877  - slot_id (only required when using IPv6 addresses), nodeinit.conf.payload,
  878    node_name and the plmcd.conf, for the payload
  879 
  880 The following commands shall be executed:
  881 
  882 % /etc/init.d/plmcd start
  883 
  884 % /etc/init.d/opensafd start [start|stop|status]
  885 
  886 If your distro uses systemd (e.g. OpenSUSE 12.1 or greater, Fedora 15 or
  887 greater) use the following commands:
  888 
  889 % systemctl start plmcd.service
  890 % systemctl [start|stop|status] opensafd.service
  891 
  892 Note: Its not necessary to start OpenSAF if an entry to start OpenSAF is
  893 set/specified in the plmcd.conf file.
  894 
  895 More TODO on status command.
  896 
  897 Command To Trigger a Administrative Switchover of the Controller Nodes:
  898 =======================================================================
  899 amf-adm si-swap safSi=SC-2N,safApp=OpenSAF
  900 
  901 Building `OpenSAF' Samples
  902 ==========================
  903 
  904 The sources of the `OpenSAF' sample applications will get installed in
  905 `$pkgdatadir/samples' (e.g. /usr/share/opensaf/samples/).
  906 
  907 The following steps shall be done to build the sample applications:
  908     % ./bootstrap.sh
  909     % ./configure
  910     % make
  911       OR
  912     % make install
  913 
  914 The `Makefile' looks for installed `SAF AIS' headers and `OpenSAF' libs in
  915 standard system wide locations (e.g. /usr/include/ & /usr/lib/):
  916 
  917     INCLUDES = -I.
  918     LDFLAGS = -lSaAmf
  919 
  920 If you have `OpenSAF' development packages installed somewhere else, override
  921 the default values e.g.:
  922 
  923     % make INCLUDES="-I. -I/tmp/usr/local/include" \
  924         LDFLAGS="-L/tmp/usr/local/lib -lSaAmf -lopensaf_core"
  925 
  926 To run an application you will need a configured `OpenSAF' node running.
  927 
  928 See file `00-README.samples' for more information on each of the application.
  929 
  930 
  931 Using the Simulation Environment
  932 ================================
  933 
  934 See file `00-README.uml' for more information about User Mode Linux and
  935 `OpenSAF'
  936 
  937 Upgrading OpenSAF
  938 =================
  939 
  940 Before installing or upgrading to OpenSAF 5.21.09, make sure your system meets
  941 the minimum version requirements of the following system components:
  942 
  943 - Linux kernel, version 2.6.39 or later. Recommended version is Linux 3.18 or
  944   later when using the TCP transport, and Linux 4.4.22 or later when using the
  945   TIPC transport. Linux versions older than the recommended ones contain bugs
  946   that are known to affect the proper function of OpenSAF. Use of Linux versions
  947   older than the recommended ones together with OpenSAF is strongly discouraged.
  948 - GNU C Library (Glibc), version 2.11 or later
  949 - GNU Compiler Collection (GCC), version 4.8.1 or later
  950 - Libxml2, version 2.7 or later
  951 - Python, version 2.7 or later (only needed when configuring with
  952   --enable-python)
  953 - Libopenssl, version 0.9.8 or later (optional)
  954 - Systemd, version 219 or later (optional)
  955 - Libsqlite3, version 3.6 or later (only needed when configuring with
  956   --enable-imm-pbe)
  957 - OpenHPI, version 2.17.0 or later (only needed when configuring with
  958   --enable-ais-plm)
  959 - Libvirt, version 0.9.7 or later (only needed when configuring with
  960   --enable-ais-plm)
  961 
  962 When upgrading from OpenSAF version 5.1 or older, be aware that SMF upgrade
  963 campaigns can behave differently compared to earlier OpenSAF releases in case of
  964 component failures. This is because Section 4.2.1.3 of SMF spec A.01.02 was
  965 implemented in OpenSAF 5.2.0. You can now disable this new feature in OpenSAF
  966 5.17.07 by setting the attribute osafAmfRestrictAutoRepairEnable to 0 in the AMF
  967 configuration object amfConfig=1,safApp=safAmfService.
  968 
  969 When upgrading from OpenSAF version 5.1 or older, please review the setting of
  970 OSAF_CKPT_SHM_ALLOC_GUARANTEE in /etc/opensaf/ckptnd.conf. To avoid a
  971 performance regression compared to OpenSAF 5.1.0, the default setting disables
  972 the protection against situations when the POSIX shared memory is full. You must
  973 change the setting of OSAF_CKPT_SHM_ALLOC_GUARANTEE if you wish to enable this
  974 protection.
  975 
  976 Pay special attention to the fact that we have increased the minimum required
  977 version of GCC to 4.8.1 in OpenSAF 4.7.0, due to the use of the C++11 standard.
  978 In OpenSAF 4.7.2, the minimum Linux version was increased to 2.6.37 due to the
  979 use of TCP_USER_TIMEOUT, and in OpenSAF 5.17.11 the minimum Linux version was
  980 increased to 2.6.39 due to the use of CLOCK_BOOTTIME.
  981 
  982 New configuration attributes have been added to the class OpensafImm in OpenSAF
  983 4.5, which means that the class schema has to be updated when upgrading from an
  984 older release of OpenSAF. An IMM XML file containing the extended class
  985 definition for OpensafImm has been added at
  986 samples/immsv/OpensafImm_Upgrade_4.5.xml
  987 
  988 In OpenSAF 4.3, some new configuration attributes have been added to the SMF
  989 configuration class. To make it possible to use these new attributes the new
  990 class description needs to be added using the IMM schema change support.  This
  991 can be done after the 4.3 OpenSAF release have been activated.
  992 
  993 1) Enable the schema change support in the IMM:
  994 immadm -o 1 -p opensafImmNostdFlags:SA_UINT32_T:1 \
  995   opensafImm=opensafImm,safApp=safImmService
  996 
  997 2) Read in the new class descriptions :
  998 immcfg --ignore-duplicates -f \
  999   /usr/share/opensaf/immxml/services/smfsv_classes.xml
 1000 
 1001 3) Disable the schema change support in the IMM:
 1002 immadm -o 2 -p opensafImmNostdFlags:SA_UINT32_T:1 \
 1003   opensafImm=opensafImm,safApp=safImmService
 1004 
 1005 In OpenSAF 4.2, the non-standard DTSv (Distributed Tracing Service) has been
 1006 retired/removed.  Fresh installations (new users) of 4.2 shall generate a new
 1007 imm.xml(see file 00-README.conf).
 1008 
 1009 Users of OpenSAF 4.0.2 or OpenSAF 4.1.1 releases, who wish to perform an
 1010 In-Service Upgrade to OpenSAF 4.2 using SMF based upgrade campaigns should do
 1011 the following:
 1012 
 1013 1) Download OpenSAF 4.2 release source tar from
 1014    http://sourceforge.net/projects/opensaf/files/releases/
 1015 2) Apply the patch 4.2_upgrade_dummydtsv.patch from
 1016    http://sourceforge.net/projects/opensaf/files/
 1017    <FIXME: Patch name, link>
 1018 3) Build OpenSAF 4.2 rpms
 1019 4) Execute your SMF upgrade campaigns.
 1020 
 1021 The capability to modify the OpenSAF services' information model at run time has
 1022 been added now in OpenSAF 4.2 and also in maintenance changesets of the 4.0.2
 1023 and 4.1.1 releases.  You should track this section for information on steps to
 1024 be done to permenantly delete the DTSv from the information model, in future
 1025 releases.
 1026 
 1027 Note: When an OpenSAF installation(< 4.2) running with 'root' privileges and
 1028 that may have configured IMM persistent storage and/or contains old/generated
 1029 trace files, is now being upgraded to OpenSAF 4.2 as the 'opensaf' user
 1030 (i.e. non-root user), Then it is the responsibility of the user/integrator to
 1031 manage (through rpm scriptlets or upgrade scripts) the permissions of the
 1032 file/directory of the immsv persistent store (see IMMSV_PBE_FILE in the
 1033 $pkgsysconfdir/immnd.conf.  e.g. /etc/opensaf/immnd.conf file) and/or the
 1034 permissions of any previous trace files present under the $pkglogdir
 1035 (e.g. /var/log/opensaf) directory, accordingly, if applicable.
 1036 
 1037 Admin Operations on OpenSAF SUs
 1038 ===============================
 1039 From OpenSAF release 4.4 onwards, the AMF admin operations lock, lock-in,
 1040 unlock, unlock-in is allowed to be performed on the OpenSAF SUs (i.e.
 1041 safSu=<nodename>,safSg=2N,safApp=OpenSAF
 1042 safSu=<nodename>,safSg=NoRed,safApp=OpenSAF) However, these commands should be
 1043 restrictively used, like running them from a SMF campaign. When running this
 1044 from an SMF campaign, OpenSAF shall support the behaviour only when used under
 1045 the supported usecases of OpenSAF. At this point of time, there is no evident
 1046 usecase to support this. Also note that locking of the 2N SU is currently not
 1047 supported when the system is configured with more than two system controller
 1048 nodes.
 1049 
 1050 Linux Distro-Specific Notes
 1051 ===========================
 1052 
 1053 `OpenSAF' is known to run on the following Linux installations:
 1054 
 1055     * Red Hat Enterprise Linux 4 (RHEL4)
 1056     * Red Hat Enterprise Linux 5.2 (RHEL5)
 1057     * Wind River Platform for Network Equipment, Linux Edition (PNE-LE)
 1058     * MontaVista Carrier Grade Edition 4.0
 1059     * Fedora Core 9
 1060     * SUSE Linux Enterprise 10 SP2
 1061     * SLES11
 1062     *...
 1063 
 1064 More TODO
 1065 
 1066 <RHEL firewall rules, SELinux, SUSE crashes with -02, missing decent tipc.h
 1067 etc.>
 1068 
 1069 -------------------------------------------------------------------------------
 1070 
 1071 Copyright (C) 2016 The OpenSAF Foundation