0001 Building Enduro/X On GNU/Linux Platform
0002 =======================================
0003 :doctype: book
0004
0005 == About manual
0006
0007 This manual describes how to build 'Enduro/X' on fresh installed Ubuntu 14.04 and Centos 6.x.
0008 Process includes description of kernel configuration, required package installation
0009 and finally finishing all with unit test completion.
0010
0011 This installation manual assumes that OS user for installation is 'user1',
0012 located at '/home/user1'. The Enduro/X system will build at path '/home/user1/endurox'.
0013
0014 == Operating System configuration
0015
0016 To get Enduro/X unit tested and running, environmental configuration is required
0017 see ex_adminman(guides)(Enduro/X Administration Manual, Setup System) section.
0018
0019 == Getting the source & building
0020
0021 This chapter describes how to install dependencies on different GNU/Linux
0022 flavors and later does get the source code and builds it.
0023
0024 === OS dependency installation
0025
0026 This chapter describes package installation commands on different Linux
0027 distributions.
0028
0029 ==== System level dependencies - for Gentoo Linux
0030 ---------------------------------------------------------------------
0031 $ su - root
0032 # emerge sync
0033 # emerge -av indent asciidoc libxml2 cmake dia \
0034 flex bison zlib openssl dev-vcs/git
0035 ---------------------------------------------------------------------
0036
0037 ==== System level dependencies - for Debian 8.2
0038
0039 The same goes on Raspbian (Raspberry Pi OS)
0040 ---------------------------------------------------------------------
0041 $ sudo apt-get update
0042 $ sudo apt-get install indent asciidoc libxml2-dev \
0043 cmake dia flex bison gcc g++ zlib1g-dev \
0044 libssl-dev libcrypto++-dev libxml2-dev git
0045 ---------------------------------------------------------------------
0046
0047 Note if having issues like:
0048
0049 ---------------------------------------------------------------------
0050 dpkg: error processing package tex-common (--configure)
0051 ---------------------------------------------------------------------
0052
0053 If running unit tests with PostgreSQL, then following additional package shall
0054 be installed:
0055
0056 ---------------------------------------------------------------------
0057 $ sudo apt-get install postgresql postgresql-client libecpg-dev \
0058 libpq-dev postgresql-server-dev-all
0059
0060 $ sudo systemctl enable postgresql
0061 $ sudo systemctl start postgresql
0062 ---------------------------------------------------------------------
0063
0064 ==== System level dependencies - for Ubuntu 14.04
0065
0066 ---------------------------------------------------------------------
0067 $ sudo apt-get update
0068 $ sudo apt-get install indent asciidoc libxml2-dev \
0069 cmake dia flex bison gcc g++ zlib1g-dev \
0070 libssl-dev libcrypto++9 libcrypto++-dev libxml2-dev git
0071 ---------------------------------------------------------------------
0072
0073 ==== System level dependencies - for Ubuntu 16.04 (Mint 18), 18.04, 20.04, 22.04
0074
0075 ---------------------------------------------------------------------
0076 $ sudo apt-get update
0077 $ sudo apt-get install indent asciidoc libxml2-dev \
0078 cmake dia flex bison gcc g++ zlib1g-dev \
0079 libssl-dev libcrypto++-dev libxml2-dev libxml2-utils git
0080 ---------------------------------------------------------------------
0081
0082 If running unit tests with PostgreSQL, then following additional package shall
0083 be installed:
0084
0085 ---------------------------------------------------------------------
0086 $ sudo apt-get install postgresql postgresql-client libecpg-dev \
0087 libpq-dev postgresql-server-dev-all
0088 ---------------------------------------------------------------------
0089
0090 If building in 32bit mode on 64bit distro, then additional libs shall be installed
0091
0092 ---------------------------------------------------------------------
0093 $ sudo dpkg --add-architecture i386
0094 $ sudo apt-get install gcc-multilib g++-multilib libicu-dev:i386 libxml32-dev:i386 libxml3-dev:i386
0095 ---------------------------------------------------------------------
0096
0097 ==== System level dependencies - for Centos 6.x
0098
0099 As some packages like `dia' does not exists in base Centos install,
0100 then few of them we will borrow from Fedora project via epel-release.
0101 Which should be installed in following way:
0102 Download the latest epel-release rpm from (e.g. epel-release-6-8.noarch.rpm or later)
0103 http://dl.fedoraproject.org/pub/epel/6/x86_64/
0104 Install epel-release rpm:
0105
0106 ---------------------------------------------------------------------
0107 $ su - root
0108 # wget http://dl.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm
0109 # rpm -Uvh epel-release*rpm
0110 ---------------------------------------------------------------------
0111
0112 Now install system dependencies
0113
0114 ---------------------------------------------------------------------
0115 # yum update
0116 # yum groupinstall 'Development Tools'
0117 # yum install git cmake asciidoc \
0118 openssl openssl-devel dia libxml2-devel
0119 # exit
0120 $
0121 ---------------------------------------------------------------------
0122
0123 If running unit tests with PostgreSQL, then following additional package shall
0124 be installed. Note that default PostgreSQL version 8.x have issues with ECPG
0125 transactions - transaction management in ECPG works incorrectly. ECPG tries
0126 to perform auto-commit (even instructed not to do so). Thus only PQ mode
0127 driver is released.
0128
0129 ---------------------------------------------------------------------
0130 $ su - root
0131 # yum install postgresql postgresql-devel postgresql-server postgresql-contrib
0132 # service postgresql initdb
0133 # chkconfig postgresql on
0134 # service postgresql start
0135 ---------------------------------------------------------------------
0136
0137 ==== System level dependencies - for Centos/RHEL/Oracle Linux 7.x
0138
0139 Now install system dependencies
0140
0141 On *Oracle Linux*, needs to enable optional repositories
0142 for asciidoc.
0143
0144 ---------------------------------------------------------------------
0145 # yum install yum-utils
0146 # yum-config-manager --enable ol7_optional_latest
0147 ---------------------------------------------------------------------
0148
0149 ---------------------------------------------------------------------
0150 # yum groupinstall 'Development Tools'
0151 # yum install git cmake asciidoc openssl openssl-devel redhat-lsb libxml2-devel
0152 ---------------------------------------------------------------------
0153
0154 Centos 7 does not ship with `dia' package. Thus we will install
0155 Fodra Core package: dia-0.97.2-5.fc19.x86_64.rpm. Also we need to install
0156 additional deps to run dia.
0157
0158 ---------------------------------------------------------------------
0159 # yum install -y cairo-gobject-devel gtk2 gtk2-devel gdk-pixbuf2-devel \
0160 libglade2-devel libgnomeui.x86_64 wget libgnomeui
0161 # wget http://ftp.scientificlinux.org/linux/fedora/releases/19/Fedora/x86_64/os/Packages/d/dia-0.97.2-5.fc19.x86_64.rpm
0162 # rpm -i --nodeps dia-0.97.2-5.fc19.x86_64.rpm
0163 ---------------------------------------------------------------------
0164
0165 Seems that RHEL/Centos/Oracle Linux 7 ship with old CMake package which generates
0166 defective RPMs. Thus it The installation might give you following errors
0167
0168 ---------------------------------------------------------------------
0169 $ sudo rpm -i *.rpm
0170 file /usr/share/man from install of endurox-3.5.1-1.x86_64 conflicts with file from package filesystem-3.2-21.el7.x86_64
0171 file /usr/share/man/man3 from install of endurox-3.5.1-1.x86_64 conflicts with file from package filesystem-3.2-21.el7.x86_64
0172 file /usr/share/man/man5 from install of endurox-3.5.1-1.x86_64 conflicts with file from package filesystem-3.2-21.el7.x86_64
0173 file /usr/share/man/man8 from install of endurox-3.5.1-1.x86_64 conflicts with file from package filesystem-3.2-21.el7.x86_64
0174
0175 $ cmake --version
0176 cmake version 2.8.12.2
0177 ---------------------------------------------------------------------
0178
0179 Install new CMake from sources:
0180 ---------------------------------------------------------------------
0181 $ su - root
0182 # yum remove cmake
0183 # exit
0184 $ cd
0185 $ wget https://cmake.org/files/v3.7/cmake-3.7.2.tar.gz
0186 $ tar -xzf cmake-3.7.2.tar.gz
0187 $ cd cmake-3.7.2
0188 $ ./configure
0189 $ make
0190 $ su - root
0191 # make install
0192 # cmake --version
0193 cmake version 3.7.2
0194
0195 CMake suite maintained and supported by Kitware (kitware.com/cmake).
0196 ---------------------------------------------------------------------
0197
0198 If running unit tests with PostgreSQL, then following additional package shall
0199 be installed:
0200
0201 ---------------------------------------------------------------------
0202 $ su - root
0203 # yum install postgresql postgresql-devel postgresql-server postgresql-contrib
0204 # postgresql-setup initdb
0205 # systemctl start postgresql
0206 # systemctl enable postgresql
0207 ---------------------------------------------------------------------
0208
0209 ==== System level dependencies - for Suse Linux Enterprise Server 12.3, 15
0210
0211 To install all required dependencies, you need following sets of DVDs (or
0212 other sources), or later
0213
0214 - SLE SERVER, DVD1 (e.g. SLE-12-SP3-Server-DVD-x86_64-GM-DVD1.iso)
0215 - SLE SERVER, DVD2 (e.g. SLE-12-SP3-Server-DVD-x86_64-GM-DVD2.iso)
0216 - SLE SDK, DVD1 (e.g. SLE-12-SP2-SDK-DVD-x86_64-GM-DVD1.iso)
0217 - SLE SDK, DVD2 (e.g. SLE-12-SP2-SDK-DVD-x86_64-GM-DVD2.iso)
0218
0219 Add these in the "Configured Software Repositories dialog" in YaST tool. Also
0220 ensure that RPM database is updated of available packages. One way to do this is
0221 Open the "Software Management" in the YaST, it will re-scan the available software
0222 sources.
0223
0224 installation of packages:
0225
0226 ---------------------------------------------------------------------
0227 # zypper install git-core cmake flex bison gcc libxml2 gcc-c++ \
0228 libxml2-devel asciidoc cmake dia rpm-build
0229 ---------------------------------------------------------------------
0230
0231 PostgreSQL can be installed in following way:
0232
0233 ---------------------------------------------------------------------
0234 # zypper install postgresql postgresql-devel postgresql-server postgresql-contrib
0235 # systemctl start postgresql
0236 # systemctl enable postgresql
0237 # systemctl status postgresql
0238
0239 ---------------------------------------------------------------------
0240
0241
0242 ==== System level dependencies - for Centos/RHEL/Oracle Linux 8.x
0243
0244 To install Enduro/X build dependencies.
0245
0246 ---------------------------------------------------------------------
0247
0248 $ su - root
0249 # yum install yum-utils
0250 # yum groupinstall 'Development Tools'
0251 # yum install git libarchive cmake asciidoc openssl openssl-devel redhat-lsb libxml2-devel
0252 ---------------------------------------------------------------------
0253
0254 The "dia" package is not available on this system, thus
0255 it will be user from Fedora Core OS:
0256
0257 ---------------------------------------------------------------------
0258
0259 # wget https://www.mavimax.com/sites/default/files/libart_lgpl-2.3.21-20.fc29.x86_64.rpm
0260 # rpm -i libart_lgpl-2.3.21-20.fc29.x86_64.rpm
0261 # wget https://www.mavimax.com/sites/default/files/dia-0.97.3-10.fc29.x86_64.rpm
0262 # rpm -i --nodeps dia-0.97.3-10.fc29.x86_64.rpm
0263
0264 ---------------------------------------------------------------------
0265
0266 If running unit tests with PostgreSQL, then following additional package shall
0267 be installed. Enduro/X standard build on RHEL 8.x uses PostgreSQL version 13.
0268 Additionally to build ECPG library "CodeReady Builder" repo shall be enabled.
0269
0270 ---------------------------------------------------------------------
0271 $ su - root
0272 # dnf module reset postgresql
0273 # dnf module enable postgresql:13
0274 # mkdir -p /etc/yum/repos.d
0275 # cat << EOF > /etc/yum/repos.d/codeready_builder.repo
0276 [OL8_codeready_builder]
0277 name= checkmk dependencies
0278 baseurl=http://yum.oracle.com/repo/OracleLinux/OL8/codeready/builder/x86_64
0279 enabled=1
0280 gpgcheck=0
0281 EOF
0282 # dnf install postgresql postgresql-devel postgresql-server postgresql-contrib libecpg-devel
0283 # postgresql-setup initdb
0284 # systemctl start postgresql
0285 # systemctl enable postgresql
0286 ---------------------------------------------------------------------
0287
0288
0289 ==== System level dependencies - for Centos/RHEL/Oracle Linux 9.x
0290
0291 To install Enduro/X build dependencies.
0292
0293 ---------------------------------------------------------------------
0294
0295 $ su - root
0296 # dnf install yum-utils
0297 # dnf groupinstall 'Development Tools'
0298 # dnf install git cmake asciidoc openssl openssl-devel libxml2-devel
0299
0300 ---------------------------------------------------------------------
0301
0302 The "dia" package is not available on this system, thus
0303 it will be user from Fedora Core OS:
0304
0305 ---------------------------------------------------------------------
0306
0307 # wget https://www.mavimax.com/sites/default/files/libart_lgpl-2.3.21-25.el9.x86_64.rpm
0308 # rpm -i libart_lgpl-2.3.21-25.el9.x86_64.rpm
0309 # wget https://www.mavimax.com/sites/default/files/dia-0.97.3-19.el9.x86_64.rpm
0310 # rpm -i dia-0.97.3-19.el9.x86_64.rpm
0311
0312 ---------------------------------------------------------------------
0313
0314 If running unit tests with PostgreSQL, then following additional package shall
0315 be installed. For ECPG "CodeReady Builder" shall be enabled.
0316
0317 ---------------------------------------------------------------------
0318 $ su - root
0319 # mkdir -p /etc/yum/repos.d
0320 # cat << EOF > /etc/yum/repos.d/codeready_builder.repo
0321 [OL9_codeready_builder]
0322 name= checkmk dependencies
0323 baseurl=http://yum.oracle.com/repo/OracleLinux/OL9/codeready/builder/x86_64
0324 enabled=1
0325 gpgcheck=0
0326 EOF
0327 # dnf install postgresql postgresql-devel postgresql-server postgresql-contrib libecpg-devel
0328 # postgresql-setup initdb
0329 # systemctl start postgresql
0330 # systemctl enable postgresql
0331 ---------------------------------------------------------------------
0332
0333 If ECPG precompiler for PostgreSQL is not available, the usage of it can
0334 be disabled by -DDISABLE_ECPG build flag.
0335
0336 ==== AsciiDoc Integration with Dia
0337
0338 Also Enduro/X includes documentation in sources, thus additional config is needed
0339 so that `Dia` package can build illustrations needed for manuals.
0340
0341 ---------------------------------------------------------------------
0342 $ sudo -s
0343 # mkdir /etc/asciidoc/filters/dia
0344 # cat << EOF > /etc/asciidoc/filters/dia/dia-filter.conf
0345 #
0346 # AsciiDoc Dia filter configuration file.
0347 #
0348 # Version: 0.1
0349
0350 [blockdef-listing]
0351 dia-style=template="dia-block",subs=(),posattrs=("style","file","target","size"),filter='dia -t png -e "{outdir={indir}}/{imagesdir=}{imagesdir?/}{target}" "{outdir}/{file}" {size?-s {size}} > /dev/null'
0352
0353 [dia-block]
0354 template::[image-blockmacro]
0355 EOF
0356 ---------------------------------------------------------------------
0357
0358 === Getting the Source code
0359
0360 ---------------------------------------------------------------------
0361 # useradd -m user1
0362 # su - user1
0363 $ cd /home/user1
0364 $ git clone https://github.com/endurox-dev/endurox endurox
0365 ---------------------------------------------------------------------
0366
0367 === Enduro/X basic Environment configuration for HOME directory
0368
0369 This code bellow creates 'ndrx_home' executable file which loads basic environment,
0370 so that you can use sample configuration provided by Enduro/X in 'sampleconfig' directory.
0371 This also assumes that you are going to install to '$HOME/endurox/dist' folder.
0372
0373 ---------------------------------------------------------------------
0374 $ cat << EOF > $HOME/ndrx_home
0375 #!/bin/bash
0376
0377 # Where app domain lives
0378 export NDRX_APPHOME=\$HOME/endurox
0379 # Where NDRX runtime lives
0380 export NDRX_HOME=\$HOME/endurox/dist
0381 # Debug config too
0382 export NDRX_DEBUG_CONF=\$HOME/endurox/sampleconfig/debug.conf
0383
0384 # NDRX config too.
0385 export NDRX_CONFIG=\$HOME/endurox/sampleconfig/ndrxconfig.xml
0386
0387 # Access for binaries
0388 export PATH=\$PATH:\$HOME/endurox/dist/bin
0389
0390 # LIBPATH for .so
0391 export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:\$HOME/endurox/dist/lib:\$HOME/endurox/dist/lib64
0392
0393 # UBF/FML field tables
0394 export FLDTBLDIR=\$HOME/endurox/ubftest/ubftab
0395
0396 # To complete unit tests:
0397 export NDRX_MSGSIZEMAX=1049600
0398
0399 ################################################################################
0400 # In case if building with Oracle DB database testing support
0401 # i.e. having flag -DENABLE_TEST47=ON
0402 # or building endurox-java with Oracle DB tests (02_xaoracle), then
0403 # configure bellow setting (demo values provided):
0404 # If so - uncomment bellow
0405 ################################################################################
0406 #export EX_ORA_HOST=localhost
0407 #export EX_ORA_USER=exdbtest
0408 #export EX_ORA_PASS=exdbtest1
0409 #export EX_ORA_PORT=1521
0410 #export EX_ORA_SID=XASVC
0411 #export EX_ORA_OCILIB=/opt/oracle/product/18c/dbhomeXE/lib/libclntsh.so
0412 #export ORACLE_HOME=/opt/oracle/product/18c/dbhomeXE
0413 #export PATH=\$PATH:\$ORACLE_HOME/bin
0414 #export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:/opt/oracle/product/18c/dbhomeXE/lib
0415 #export TNS_ADMIN=\$ORACLE_HOME/network/admin
0416 #Used for TCP Recon testing if tcpkill is installed (optional for Ora):
0417 #export EX_ORA_IF=enp0s3
0418 #export EX_ORA_PORT=1521
0419 ################################################################################
0420 # In case if building with Postgresql DB database testing support
0421 # or building endurox-java with Oracle DB tests (03_xapostgres), then
0422 # configure bellow setting (demo values provided):
0423 # If so - uncomment bellow
0424 ################################################################################
0425 #export EX_PG_HOST=localhost
0426 #export EX_PG_USER=exdbtest
0427 #export EX_PG_PASS=exdbtest1
0428 # currently uses default port
0429 #export EX_PG_PORT=5432
0430 #export EX_PG_DB=xe
0431
0432
0433 EOF
0434
0435 $ chmod +x $HOME/ndrx_home
0436 ---------------------------------------------------------------------
0437
0438 NOTE: If you develop in Gnome (e.g. Mate) session, then
0439 do `export DESKTOP_SESSION=gnome' before run IDE (e.g. NetBeans).
0440
0441 === Building the code
0442
0443 *NOTE:* If building with PostgreSQL support (-DENABLE_POSTGRES=ON) for
0444 RHEL/OL/Centos 8.x you need to specify Postgresql include folder manually, e.g.
0445 add "-DPostgreSQL_TYPE_INCLUDE_DIR=/usr/include/pgsql/internal" string to cmake
0446 line, otherwise error "Could NOT find PostgreSQL (missing: PostgreSQL_TYPE_INCLUDE_DIR)"
0447 will be given at configure.
0448
0449 ---------------------------------------------------------------------
0450 $ cd /home/user1/endurox
0451 -- If you want to have install folder to /home/user1/endurox/dist
0452 -- if you want system level install then run just $ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr .
0453 $ cmake -DCMAKE_INSTALL_PREFIX:PATH=`pwd`/dist .
0454 $ make
0455 $ make install
0456 ---------------------------------------------------------------------
0457
0458 == Unit Testing
0459
0460 Enduro/X basically consists of two parts:
0461 . XATMI runtime;
0462 . UBF/FML buffer processing.
0463 Each of these two sub-systems have own units tests.
0464
0465 === UBF/FML Unit testing
0466
0467 ---------------------------------------------------------------------
0468 $ cd /home/user1/endurox/ubftest
0469 $ ./ubfunit1 2>/dev/null
0470 Running "main"...
0471 Completed "main": 5751 passes, 0 failures, 0 exceptions.
0472 ---------------------------------------------------------------------
0473
0474 === XATMI Unit testing
0475 ATMI testing might take some time. Also ensure that you have few Gigabytes of free
0476 disk space, as logging requires some space. To run the ATMI tests do following:
0477 ---------------------------------------------------------------------
0478 $ cd /home/user1/endurox/atmitest
0479 $ nohup ./run.sh &
0480 $ tail -f /home/user1/endurox/atmitest/test.out
0481 ...
0482 Setting domain 2
0483 Server executable = tpbridge Id = 101 : Shutdown succeeded.
0484 Server executable = convsv21 Id = 50 : Shutdown succeeded.
0485 Server executable = atmi.sv21 Id = 30 : Shutdown succeeded.
0486 Server executable = tmsrv Id = 10 : Shutdown succeeded.
0487 Shutdown finished. 4 processes stopped.
0488 atmiclt21: no process found
0489 ************ FINISHED TEST: [test021_xafull/run.sh] with 0 ************
0490 Running "main"...
0491 Running "main"...
0492 Completed "main": 21 passes, 0 failures, 0 exceptions.
0493 ---------------------------------------------------------------------
0494
0495 === Testing Oracle DB (Optional)
0496
0497 If EX_ORA_ settings are loaded int the ndrx_home environment file and project
0498 is started with *-DENABLE_TEST47=ON* setting, then before running the tests,
0499 user and tables needs to be created for testing.
0500
0501 User scheme can be created in following way (may differ if you have other
0502 procedures):
0503
0504 ---------------------------------------------------------------------
0505
0506 # su - oracle
0507 $ sqlplus / nolog
0508 SQL> connect / as sysdba
0509 SQL> alter session set "_ORACLE_SCRIPT"=true;
0510 SQL> CREATE USER exdbtest IDENTIFIED BY exdbtest1;
0511 SQL> GRANT CONNECT, RESOURCE, DBA TO exdbtest;
0512 SQL> COMMIT;
0513 SQL> QUIT;
0514
0515 ---------------------------------------------------------------------
0516
0517 The testing user must have access to tnsnames.ora, thus user "user1" must be
0518 added to "oinstall" group. On linux that can be done in this way:
0519
0520 ---------------------------------------------------------------------
0521
0522 # gpasswd -a user1 oinstall
0523
0524 ---------------------------------------------------------------------
0525
0526
0527 Tables can be loaded in with help of Oracle sqlplus tool:
0528
0529 ---------------------------------------------------------------------
0530 $ cd /home/user1/endurox/atmitest/test047_oradb
0531 $ ./sqlplus.run
0532
0533 SQL*Plus: Release 18.0.0.0.0 - Production on Sun May 26 16:46:53 2019
0534 Version 18.4.0.0.0
0535
0536 Copyright (c) 1982, 2018, Oracle. All rights reserved.
0537
0538 Last Successful login time: Sun May 26 2019 16:42:36 +03:00
0539
0540 Connected to:
0541 Oracle Database 18c Express Edition Release 18.0.0.0.0 - Production
0542 Version 18.4.0.0.0
0543
0544 SQL> @tables.sql
0545
0546 Table created.
0547
0548 SQL> quit
0549
0550 ---------------------------------------------------------------------
0551
0552 Once this is done, the test shall execute without the problems.
0553
0554 ==== Testing RECON functionality with Oracle DB (Optional)
0555
0556 This is advanced test to check the reconnect functionality of Enduro/X
0557 XA sub-system (i.e. test of flag *RECON* flag in *NDRX_XA_FLAGS*).
0558
0559 Test basically periodically kills the connections while in the background
0560 distributed transactions are executed. The positive outcome from the
0561 test is that system is not hanged and periodically is able to continue
0562 the transaction testing.
0563
0564 To enable this test, special configuration must be enabled. Which consists
0565 of following steps:
0566
0567 - *tcpkill* binary is installed.
0568
0569 - *tcpkill* and *xadmin* are enabled for *user1* to perform sudo.
0570
0571 - OS Kernel TCP *keepalive* must be configured for fast broken connection
0572 detection.
0573
0574 - *tnsname.ora* service shall be configured with enabled broken connection
0575 detection.
0576
0577 The test is activated if *-DENABLE_TEST47=ON* build flag is set and
0578 *tcpkill* binary exists in the system.
0579
0580 Currently instructions are prepared for Oracle Linux 7.x. Test is
0581 executed as part of *test047_oradb* execution.
0582
0583 ===== Installing tcpkill (on Oracle Linux 7.x)
0584
0585 ---------------------------------------------------------------------
0586
0587 $ su - root
0588 # yum install oraclelinux-developer-release-el7
0589 # yum install oracle-epel-release-el7
0590 # yum install dsniff
0591
0592 ---------------------------------------------------------------------
0593
0594 After install update the *~/ndrx_home* so that following parameters
0595 are set to correspond the Oracle DB server and Oracle DB port number:
0596
0597 For example:
0598
0599 ---------------------------------------------------------------------
0600
0601 export EX_ORA_IF=enp0s3
0602 export EX_ORA_PORT=1521
0603
0604 ---------------------------------------------------------------------
0605
0606
0607 ===== Enable sudo
0608
0609 ---------------------------------------------------------------------
0610
0611 $ su - root
0612 # sudoedit /etc/sudoers
0613
0614 -- At the end of the file add
0615
0616 #
0617 # For Enduro/X RECON testing
0618 #
0619 user1 ALL=(ALL) NOPASSWD:SETENV: /sbin/tcpkill,/bin/xadmin,/home/user1/endurox/dist/bin/xadmin
0620
0621 ---------------------------------------------------------------------
0622
0623
0624 ===== Apply TCP keepalive settings
0625
0626 ---------------------------------------------------------------------
0627
0628 $ su - root
0629
0630 # cat << EOF >> /etc/sysctl.conf
0631
0632 net.ipv4.tcp_keepalive_time = 15
0633 net.ipv4.tcp_keepalive_intvl = 15
0634 net.ipv4.tcp_keepalive_probes = 1
0635
0636
0637 EOF
0638
0639 # sysctl -f /etc/sysctl.conf
0640
0641 ---------------------------------------------------------------------
0642
0643 ===== Ensure tnsnames.ora configuration
0644
0645 Ensure that *tnsnames.ora* test service have *(ENABLE=broken)* flag
0646 set.
0647
0648 For example:
0649
0650 ---------------------------------------------------------------------
0651
0652 XASVC =
0653 (DESCRIPTION=
0654 (FAILOVER=on)
0655 (ENABLE=broken)
0656 (ADDRESS=(PROTOCOL=tcp)(HOST=rac1-vip)(PORT=1521))
0657 (ADDRESS=(PROTOCOL=tcp)(HOST=rac2-vip)(PORT=1521))
0658 (CONNECT_DATA=
0659 (SERVICE_NAME=XASVC)
0660 (FAILOVER_MODE=
0661 (TYPE=SESSION)
0662 (METHOD=BASIC)
0663 (RETRIES=10)
0664 (DELAY=15)
0665 )
0666 )
0667
0668 ---------------------------------------------------------------------
0669
0670
0671 === Testing PostgreSQL (Optional)
0672
0673 Enduro/X supports PosgreSQL Two Phase commit mode. In general PosgreSQL have
0674 'light' version of two phase commit. I.e. only that session which did work
0675 can leave the work in prepared state with some 'id'. Thus to working in XA mode
0676 when process calls xa_end(), it needs to prepare the transaction. As Enduro/X
0677 writes the transaction manager logs at start of every active transaction, thus
0678 tmsrv will know about this transaction, thus it will be able to reverse it in
0679 case of crashes. There is slight chance that this might slip in case if
0680 transaction times out, tmsrv reverts it (no XID found, thus assume committed/reverted),
0681 but after a while process performs the xa_end()/xa_prepare(). In that case
0682 transaction will be left in prepare state. These cases can be resolved manually
0683 by performing `xadmin recoverlocal' and perform `xadmin abortlocal' on these.
0684
0685 To configure PosgreSQL, for tests, following need to be done:
0686
0687 1. Create user / password / database
0688
0689 2. Enable prepared transactions
0690
0691 To create the user for tests, perform following
0692
0693 --------------------------------------------------------------------------------
0694
0695 $ sudo -s
0696 # su - postgres
0697 $ createuser exdbtest
0698 $ createdb xe
0699 $ psql
0700
0701 > alter user exdbtest with encrypted password 'exdbtest1';
0702 > grant all privileges on database xe to exdbtest;
0703 > \q
0704
0705 --------------------------------------------------------------------------------
0706
0707 To enable prepared transactions, edit postgresql.conf and set `max_prepared_transactions'
0708 greater than 0, e.g. 1000.
0709
0710 --------------------------------------------------------------------------------
0711
0712 -- for debian/ubuntu
0713 # vi /etc/postgresql/*/main/postgresql.conf
0714 -- for RedHat, SLES
0715 # vi /var/lib/pgsql/data/postgresql.conf
0716
0717 -- Edit the max_prepared_transactions
0718
0719 max_prepared_transactions = 1000 # zero disables the feature
0720
0721 --------------------------------------------------------------------------------
0722
0723 Network connection shall be enabled too for Posgres auth, edit the *pg_hba.conf*
0724 (for RHEL, SLES /var/lib/pgsql/data/pg_hba.conf. For debian/ubuntu these shall be already
0725 correctly set by default (according to ubuntu 20.04))
0726
0727 Ensure that it contains following lines (for password auth):
0728
0729 --------------------------------------------------------------------------------
0730 local all all peer
0731 host all all 127.0.0.1/32 md5
0732 host all all ::1/128 md5
0733 --------------------------------------------------------------------------------
0734
0735 After that restart PostgreSQL (according to OS):
0736
0737 --------------------------------------------------------------------------------
0738 # systemctl restart postgresql
0739 --------------------------------------------------------------------------------
0740
0741 If Postgresql does not boot, then try "trust" for the "local/all".
0742
0743 After these steps test database table shall be created. That could be done in
0744 following way:
0745
0746 ---------------------------------------------------------------------
0747 $ source ~/ndrx_home
0748 $ cd /home/user1/endurox/atmitest/test067_postgres
0749 $ cat tables.sql | ./psql.run
0750 CREATE TABLE
0751
0752 ---------------------------------------------------------------------
0753
0754 Now PostgreSQL is ready for Enduro/X testing.
0755
0756
0757 == Conclusions
0758
0759 At finish you have a configured system which is read to process the transactions
0760 by Enduro/X runtime. It is possible to copy the binary version ('dist') folder
0761 to other same architecture machine and run it there without need of building.
0762 This process is described in <<BINARY_INSTALL>> guide.
0763
0764 :numbered!:
0765
0766 [bibliography]
0767 Additional documentation
0768 ------------------------
0769 This section lists additional related documents.
0770
0771 [bibliography]
0772 .Resources
0773 - [[[BINARY_INSTALL]]] See Enduro/X 'binary_install' manual.
0774
0775
0776 ////////////////////////////////////////////////////////////////
0777 The index is normally left completely empty, it's contents being
0778 generated automatically by the DocBook toolchain.
0779 ////////////////////////////////////////////////////////////////
