Oracle Integration Cloud (OIC) is the integration platform as a service. It is used to integrate the applications which may be running on public cloud or private cloud or on-prime network.
Objective: At the end of this blog you will learn
- What are Agent and terminologies used
- Types of Agent or components of an agent
- Agent architecture
- How to Install the Agent with or without HA mode and its folder structure
- How to start and stop agent
- How to configure Proxy and bypass proxy
- How to import the certificate
- How to check logs and monitor agents
- Know issues
- Linux commands related to agents
- How to automate the start agent process using shell script and cron job
PreRequisite
1. Java --> Install the java and set the path
2. Check internet connectivity on the agent machine
3. OS users should have Read, write, and execute permissions
What are Agent and terminologies used?
An agent is one of the OIC components which is used to establish the communication or exchange of messages between OIC integrations and on-premise or private cloud-hosted applications.
First, you should have an understanding of terminologies used in agent
Public Cloud means anybody can access anything from anywhere over the internet, where anything represents the resources like API, documents, emails, photos, files, etc.
Private Cloud means only some specific users can access these resources either over the internet or a private internal network
On-prime network means applications that are running behind the firewall
A firewall is a network security device that monitors and filters incoming and outgoing network traffic based on some policies or rules. It may block the port that tries to gain unauthorized access to your servers. It will prevent unauthorized access to or from a private network by denying the traffic
A proxy server is a server that provides internet access on behalf of the user i.e. it provides the indirect connection to network services
Generally in the organization, on-prime applications are restricted using a firewall and the internet is accessed using the proxy server
Now the question is how to establish the communication between OIC and on-prime applications?
As you have seen, communication with on-prime applications may be restricted using firewalls. To enable the communication or message exchange you need to open the port or use the VPN tunnel and it's a bit lengthy process. Oracle has simplified this complete process by providing one component called OIC Agent.
Benefits of OIC Agent
No port opening will be required for communication
All communication will be secured using SSL
The on-premises connectivity agent checks for work by making outbound requests through the firewall
The on-premises connectivity agent can use a proxy to access the internet
All communication will be initiated by the on-premises connectivity agent
Components of OIC Agent or Types of Agent
SaaS Agent: Runs on the OIC Platform and helps for communication with on-premises applications and there will be only one SaaS agent per OIC instance. No configuration is required, its managed by Oracle
On-premise Agent: This agent will be installed and runs in an on-premise environment on the same network where the on-premise application like DB, EBS, etc. is running.
Agent Architecture
OIC agent is the executable java jar file that contains java classes. All communications are initiated by the OIC agent itself over HTTPS using a REST call. It uses an existing proxy for internet access. No need to open firewalls. Both inbound and outbound requests are supported for inbound no open port required, Outbound requests work on 443 i.e. HTTPS.
It sends a continuous signal to the OIC that it is alive and this is reflected as green on the monitoring dashboard. If the agent is Red on the OIC monitoring dashboard it means that it is down
High-level steps of Agent Installation
1. Create a connectivity agent group
2. Download the connectivity agent installer
3. Push the installer file on the same network where the on-premise application is running
4. Configure the agent config file
Let's start the installation
1. Create a connectivity agent group
- You must create an agent group in OIC before running the agent installer
- After creating the agent group you will have a unique agent group identifier and you have to associate it with the connectivity agent while configuring the agent
- A maximum of two agents can be associated with a single agent group
- Note: A maximum of five agent groups can be created per OIC instance
To Create an agent group login to OIC and navigate to Integrations and then click on Agents
Once you will click on Create, the agent group identifier will create which status is Configured and no agent is associated with it
Now download the agent installer by choosing any options below
1. Download from OIC Agent Console by navigating to Home > Integrations then click Agents
Click Download > Connectivity
2. Download using Curl Command
This is useful when you do not have access to move the file from the local machine to the on-premise server as well don't have access to any browser on this server.
This way you can download the file directly on the on-premise server
curl -k -v -X GET -u OIC-UserName:OIC-Password -H 'Content-Type:application/json' https://oicdev-OICAccount.integration.ocp.oraclecloud.com/ic/api/integration/v1/agents/binaries/connectivity -o Downloads/oic_connectivity_agent.zip
3. Push the installer file on the same network where the on-premise application is running
Create the directory where you want to push the file and create the folder like OIC_Dev
then extract the oic_connectivity_agent.zip, after extract folder structure will look like below
agenthome: Will contain multiple subfolders like an agent, bin, lib, logs, third party, etc.
connectivityagent.jar --> This is the jar file that you have to run after configuring InstallerProfile.cfg to start the OIC agent
cpi_upgradeutility.jar --> This jar file runs automatically to upgrade the agent
InstallerProfile.cfg --> This file contains actual configuration details like OIC URL, OIC user name, password, and the agent group identifier you have created in step 1.
Optionally you may also provide proxy details if the internet is accessible through the proxy
Some more import folders and files
Inside agnethome, there will agent folder which will again contain three folders
- cert --> If any certificate is required to import then this is the place
- config -->In this folder two files will be one of them is CpiAgent.properties which contain all the configuration details that we have provided into InstallerProfile.cfg
- data --> all the operations related files that have been configured in the connection will be available as WSDL related artifacts
4. Configure the agent config file "InstallerProfile.cfg"
Edit the file with the following details
# Required Parameters
# oic_URL format should be https://hostname:sslPort
oic_URL=https://oicdev-OICAccount.integration.ocp.oraclecloud.com:443
oic_USER=OIC-UserName
oic_PASSWORD=OIC-Passwrod
#agent_GROUP_IDENTIFIER --> Enter the Group Identifier that you have created on OIC in step 1 i.e. Connectivity agent group
agent_GROUP_IDENTIFIER=AGENTGROUPDEMO
# Proxy Parameters are a list of hosts that should be reached directly, bypassing the proxy. This is a list of patterns separated by '|'.
# proxy_NON_PROXY_HOSTS:
proxy_HOST=
proxy_PORT=
proxy_USER=
proxy_PASSWORD=
proxy_NON_PROXY_HOSTS=
If you have to install the agent in HA mode, the agent will run on two different VM in an active-active manner. To achieve this, you have to push the agent binary file on another VM and install the same java on the second VM. Post that set the java path and uses the same group identifier in the InstallerProfile.cfg
Now Installation is done on both the machine its time to start if no proxy configuration and certificate is required
5. Start and stop the agent, this process is also known as the bounce of agent
To start the agent first set the Java Path and run the agent binary file as below
To Set the Java path in Window Machine
setx JAVA_HOME "C:\Program Files\Java\jdk1.8.0_311\"
setx PATH "%PATH%;%JAVA_HOME%\bin";
To Set the Java in Linux Machine
export JAVA_HOME=/home/Daakshya/JavaSetup/jdk1.8.0_311
export PATH=$JAVA_HOME/bin:$PATH
java -version
To start the agent fire the below command
nohup java -jar connectivityagent.jar > OICAgentlog.out &
nohup --> will keep executing the command even if the user logout
& --> will keep running the program in the background
To stop the agent fire the below command
1. First collect the PID of the running agent
ps -ef | grep -i connectivityagent
root 301 103 0 14:24 pts/1 00:00:00 connectivityagent
root 165 93 0 14:24 pts/1 00:00:00 grep -i connectivityagent
Here 301 is the process id of the agent
165 is the process id of the grep command, you have to kill the process of an agent which is 301
then run the below command
Command Syntax kill -9 PID
kill -9 301
Validate it from the OIC console
Verify from OIC Monitoring > Agent
How to delete the agent
Navigate to OIC HOME > Integrations > Agent then click on the action menu right side
Empty the agent by clicking on Agents
An agent with an active state cannot be deleted first you have to stop it
Now its time to remove the agent group As there is no agent associated so we can delete it
How to configure Proxy and bypass proxy
If your organization is using the proxy then provide the proxy host and port and credentials if required
collect these details from the proxy team and enter these values as below
proxy_HOST=187.80.35.90
proxy_PORT=-2030
proxy_USER=daakshya
proxy_PASSWORD=************
To bypass the proxy assign the hosts which should be directly communicated i.e. without using the proxy and the host will be assigned to the parameter proxy_NON_PROXY_HOSTS. Multiple hosts will be separated by '|'.
How to import the certificate
SSL certificate is a way to create trust by establishing a secure connection. It works on key-value pairs i.e. public key and private key. These keys are used to encrypt the connection.
In the below scenario you might need to import the certificate into the Keystore
- when a connectivity agent is used with an SSL proxy
- when on-prime applications expose a Secure(SSL) endpoint and this endpoint need to invoke using an OIC agent
To import the certificate move to
agenthome/agent/cert and run the keytool command as follow
Syntax keytool -importcert -keystore keystore.jks -storepass storepassword -alias aliasName -noprompt -file certificate_file/with/location
Example keytool -importcert -keystore keystore.jks -storepass changeit -alias sslcertificate -noprompt -file sslcertificate.crt
How to view the certificate
keytool -list -v -Keystore Keystore. jks
Sometimes you may need to resolve the domain name with IP for this you may need to configure hosts under /etc/hosts and in this file, you may need to provide the domain name against the IP
How to check logs and monitor agents
There are two places to check logs
1. In the nohup.out file, if you have started the agent with the nohup command
2. Go to the agenthome/agent/logs there might be agent-alert, agent-upgrade, agent-audit, and agent-diagnostic. Agent transaction-related log details will be in the agent-diagnostic file. This file will help to debug the agent related issue
To monitor agent navigate to Home > Monitoring > Integrations > Agents
or navigate to dashboard then either Agents under system health or Agent Health section
Known Issue
- 240 second time out: OIC waits a maximum of 240 seconds for the invoke operation, if a response is not received within 240 seconds then it will throw a 240 time out an error saying that a Message not received within 240 seconds of the wait interval
- Response not generated or received within the time frame
- 10 MB limitation: A maximum of 10 MB of data can be processed by OIC
- Unable to start the universal connection pool i.e. can not get connection from Data source
- Timeout of 270 seconds occurred while waiting for the adapter to respond corresponding to the message Id
- Could not create/access the Toplink session. The connection to the database has been refused. Kindly check the connection parameters, ensure the database is reachable, and review the firewall
Linux command related to OIC
Will be added soon
How to automate the start agent process using shell script and cron job
Shell script to start the agent
vi startOICAgentScript.sh
#Set Java Path
export JAVA_HOME=/home/Daakshya/JavaSetup/jdk1.8.0_311
export PATH=$JAVA_HOME/bin:$PATH
#Define var AgentStatus
echo "$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$"
echo "checking agent status"
echo "$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$"
PIDCount= `ps -ef | grep -i connectvityagent | wc -l`;
if [ $PIDCount -gt "1" ]; then
AgentStatus="Agent is running"
echo "Agent status is $AgentStatus"
else
echo "Agent is not running... Please wait... Starting"
#Navigate to installation directory
cd /home/Daakshya/OICAgent
nohup java -jar connectivityagent.jar > OICAgentlog.out &
sleep 80 #sleep for 80 second ... wait for 80 second
PIDCount= `ps -ef | grep -i connectvityagent | wc -l`;
if [ $PIDCount -gt "1" ]; then
AgentStatus="Agent Started"
echo "$AgentStatus"
else
echo "Error encountered during start"
fi
fi
Note: Cron job details will be added soon !!! Keep connected ....
References
No comments:
Post a Comment