Oracle API Gateway Installation and Configuration as Cluster/Single Node

    By: Osama Mustafa on Dec 18, 2018

    Oracle API Gateway Header Image.png

    By Osama Mustafa | Edited by Tim Boles

    This article explains how to configure Oracle API Gateway as a cluster on Solaris SPARC. The software can be download from the Oracle Technology Network. Before installing the API Gateway, you need to consider which components you require. Some components — for example, API Gateway Analytics — have additional requirements, such as a database. There are different components that could be installed, too, such as Policy Studio. There is not much documentation that discusses how to configure the Cluster for this product, so I chose to write one and be the first. The version of the API Gateway used in this article is Release, which is the latest at the time of writing.

    Before we start:

    The operating system I used was Solaris SPARC 11.3. Those using this operating system may have the same issue I had (see Figure 1). The media was downloaded from Oracle Technology Network, during the installation for OAG I faced the described error below in Figure 1. After trying to troubleshoot a couple of times I found out the error related to the downloaded media. Oracle did provide a patch, which basically is the correct media for the API Gateway. The patch can be found on the My Oracle Support website under the following number: and of size 1.9 GB.

    Also, for more information about this bug please refer to this document:


    Figure 1.png

    (Figure 1)

    In the below (Figure 2), the command line that will start the installation on Linux without extraction.

    Figure 2.png

    (Figure 2)

    System requirements:

    • Check the operating system.
    • Minimum 2 GB free disk space, 50 GB recommended.
    • Minimum 4 GB physical memory. 

    API Gateway Analytics supports the following databases:

    • MySQL Server 5.1, 5.6
    • Microsoft SQL Server 2005, 2008, 2012
    • Oracle,
    • IBM DB2 9.7, 10.5

    Cluster Setup:

    During the cluster setup errors (see below) related to IPV6 filled the logs:

    From Node #1 :

    ERROR 17/Oct/2018:14:24:24.936 [137f:5bc71be817fd0b541aecb3aa] cannot
    connect to ::1:8085: Network is unreachable 
    ERROR 17/Oct/2018:14:24:24.948 [136f:5bc71be81804bb2b2b9e3112] cannot
    connect to ::1:8085: Network is unreachable 

    From Node #2 :

    ERROR 17/Oct/2018:14:18:19.293 [020b:5bc71a7b0f4a13641192b803] cannot
    connect to ::1:8085: Network is unreachable 
    ERROR 17/Oct/2018:14:18:23.543 [020f:5bc71a7f0f5171a3c66d65dc] cannot
    connect to ::1:8085: Network is unreachable 
    ERROR 17/Oct/2018:14:18:26.015 [020e:000000000000000000000000]
    [SSL_accept, 2180]: failed - SSLv3 read client certificate A. 

    These errors have no effect on the functionality of OAG.  To silence these errors, I disabled IPv6 by commenting out the following line /etc/hosts: 

    #::1 localhost localhost.localdomain localhost6 localhost6.localdomain6

    The concept of OAG cluster is very simple, we installed and configure the OAG as Single node first on node #1 after we complete that, we have to register the remaining nodes (in our case only two nodes) with the first node.

    1. Since it’s a cluster, we need to modify the /etc/host to include the both nodes see below example:   soaapiprn1.localdomain      soaapiprn1   soaapiprn2.localdomain      soaapiprn2

    To test that everything is working, use ping command as shown below on each node:

    ping soaapiprn1
    ping soaapiprn2

    While doing research on the internet about this product I noticed that that many instructions provided used the root user to perform the software installation. This not recommended for any Oracle products that I have seen, therefore I choose to create and use the Oracle user to be the software owner.

    2. Create Oracle user, in case still fresh operating system.

    groupadd -g 1000 oinstall
    groupadd -g 1300 dba
    groupadd -g 1301 oper

    useradd -m -u 1101 -g oinstall \
    -G dba,oper \
    -d /export/home/oracle \
    -s /bin/bash \
    -c "Oracle Software Owner" oracle

    passwd oracle à for the password
    mkdir -p /u01/app/oracle
    chown -R oracle:oinstall /u01/app/oracle
    chmod -R 775 /u01


    3. Locate and run the setup file for your operating system. For example:

    •  Windows


    •  Linux/Unix

    The above command is how to run the installation on the different operating systems.  In this case the software provided in the patch supplied by MOS p26933700 for Solaris (Linux/Unix) is used.

    4. NOTE: You can skip this step in case you have any Operating system other than Solaris SPARC. 
    Extract the files under /u01/app/oracle: -

    $ tar -xvzf

    The posix/bin directory is main path and directory to run any executable file (comamndline) for OAG so change to that directory.

    $ cd /u01/app/oracle/apigateway/posix/bin/

    5. Run the following command. It will generate files (only for the first time) as shown below in Figure 3.

    $ ./managedomain –menu

    Figure 3.png

      (Figure 3)

    After the above extraction is complete, the user will be prompted to insert the username and password. Listed below is the default and can be changed later:

    Username: admin
    Password: changeme 

    6. Now the menu will appear (Figure 4), since it’s fresh install without any prior configuration, we need to register the host.

    Select option 1.

    Figure 4.png

    (Figure 4)

    After you have select Option 1 complete the configuration through the question and answer dialog (see Figure 5).
    Note: Don’t change the answer of the default value if you are not sure what you are doing. This will affect the api gateway later.

    Figure 5.png

    (Figure 5)

     7. You will next start the node manager. Until this step, you only configured the OAG for one node. If the node manager is started using command  ./nodemanager  under the command directory (See Step 4), it will work without any issue.

    Start the node manager as shown in below in Figure 6:

    Figure 6.png

      (Figure 6)

    From the above figure and after checking the topology from node #1.  At this time this is single node configuration.  Similar steps performed on Node 2 will create the cluster configuration.

    8. After uploading the OAG software to node #2, perform step #4 and step #5 (above). The question answer dialog will appear but some of the answers will be different than on Node #1. See Figure 7 below as an example: I marked the differences in bold font with green color to highlight the changes.

    Figure 7.png

    (Figure 7)

    9. Check the topology again with the managedomain command (see Figure 8). The configuration contains only one admin Node, which means if node #1 is down the OAG will remain working, but you will not be able to manage from the console. (We will solve this issue later.) Figure 8.png

    (Figure 8)

    From Figure 8, it can be seen that there are two Hosts, Admin Node Manager and Node Manager.

     10. As shown in Figure 9 below, After starting the node manager (mentioned in Step #7) on the both nodes, we can access the OAG Dashboard Using (https://soaapiprn1:8090) and check if it’s running. The post configuration which allows the sync of the nodes is not created yet. That is accomplished by creating the instance. The instance is responsible for gathering the traffic for each node, as shared below:

    Figure 9.png

    (Figure 9)

    11. From the console/Dashboard again https://soaapiprn1:8090  (The username and password by default are: admin/changeme), select Menu à New Group ,

     Figure 10.png
    (Figure 10)

    12. Create the instance and connect it to the group created in the previous step (Figure 10) by executing.


    You will choose option 5 “Create Gateway Server Instance”, then choose the appropriate service group then accept the defaults.  Example of the dialog is show in Figure 11 and Figure 12 below. 

    Note: Execute this step on both nodes to create instances for node #1 and node #2, if you have more than two nodes then you the command should be run on all nodes.

     Figure 11.png
    (Figure 11)

    Figure 12.png
    (Figure 12)

    13. After creating instances on both nodes, go back to console and start the instances by pressing start (see Figure 13).
    Figure 13.png
    (Figure 13)

    14. Referring to Figure 8, if you check the topology you will notice there is only one admin server which is running on node #1 only. This means if anything happened to node #1 such as hardware failure, human interruption or mis-configuration, the user or admin will not be able to access to the OAG console (Dashboard) from the web browser. They will not be able to monitor the traffic. To solve this issue, there is additional command should be run from node #2 from the command directory (see step 4) which will allow node #2 to become Admin server too.

    ./managedomain --edit_host --host --is_admin 

    15. Check the topology again by executing the ./managedomain script again (see Figure 14).

    Figure 14.png

    (Figure 14)


    This article covered installing the Oracle API Gateway (OAG) in a cluster environment.  This is one part of implementing the Oracle SOA Security Solution, which additionally includes the Oracle SOA Suite.  When installing the OAG, Oracle recommends deploying it in the demilitarized zone (DMZ) as the first line of defense.  There are other considerations to consider when designing the architecture for the Oracle SOA Security Solution.  In typical environment, the connection between OAG and the client is protected by a firewall.  Additionally, a Load Balancer is deployed in the DMZ to control and distribute the traffic thru the OAG nodes.  I would encourage the reader to research and understand the role of the API Gateway and the Oracle SOA Suite in providing additional an security layer while improving the integration, acceleration, and securing of Web Services and Web API.  With the Oracle SOA Security Solution, application traffic can be routed based on content and sender, or by performing message content screening.  Additionally, the OAG can apply different policies on incoming messages by running a message filtering on request. Understanding of integrated and overlapping of functionality between SOA and OAG is key in implementing the Oracle SOA Security Solution.



    Osama Mustafa headshot.jpg
    Osama Mustafa
    is the founder of Gurus Solutions Company, an Oracle ACE Director, and creator/director of Jordan Amman Oracle User Group - the first group in Jordan related to Oracle technology. Osama is author of the book Oracle Penetration Testing. He has been working on project and customer support in the EMEA Region, providing different Oracle solutions related to cloud, DevOps, fusion middleware and database. Osama Is frequently a speaker in Oracle User Groups around the world and a RAC ATTACK event organizer, as well as a Fusion middleware ATTACK Organizer. Osama has published articles in Oracle Magazine, OTECH magazine and UKOUG Oracle Scene magazine. He is also a blogger and Certified Oracle Database and Fusion middleware professional. Osama assists with sharing his knowledge at conferences, webinars, white papers, slide share and blog posts with the Oracle community and is very passionate about all things Oracle.

    Released: December 18, 2018, 8:10 am | Updated: April 3, 2019, 1:09 pm
    Keywords: Feature | SELECT Journal | SELECT | SELECT Journal

    Copyright © 2019 Communication Center. All Rights Reserved
    All material, files, logos and trademarks within this site are properties of their respective organizations.
    Terms of Service - Privacy Policy - Contact

    Independent Oracle Users Group
    330 N. Wabash Ave., Suite 2000, Chicago, IL 60611
    phone: 312-245-1579 | email:

    IOUG Logo

    Copyright © 1993-2019 by the Independent Oracle Users Group
    Terms of Use | Privacy Policy