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