4 Network
Learn how to secure your network for Oracle GoldenGate.
This chapter describes endpoint protection such as Network Access Control and Network Connection Adapters along with the steps to configure and use Reverse Proxy.
Topics:
- Network Access Control
The MA configuration of the network connection takes the form of an array or network access control list (ACL). - Network Connection Adapter
Learn about how to specify your network connection configuration. - Configure Reverse Proxy with NGINX to Access Oracle GoldenGate Microservices
- Network Communication
An MA server is the originator of all the response messages sent to the client when a request is sent to the server.
Parent topic: Securing the Microservices Architecture
4.1 Network Access Control
The MA configuration of the network connection takes the form of an array or network access control list (ACL).
All configurable ACLs are represented as an array of ACL specifications. In the JSON configuration this array takes the form:
aclArray := '[' <aclSpec> [, <aclSpec>] ']'
There might be cases where access from specific sides is excluded or access from specific sides is allowed. Within Oracle GoldenGate, you are able to adjust the Application network setting so that you can create black or white lists for access points. Similarly, there might be cases, that you want to have the distribution path working on a specific network adapter only. This is feasible within Oracle GoldenGate.
Each ACL specification minimally consists of a permission statement indicating whether the ACL specification allows or denies client connections from the specified address. ACL specifications are processed in order and terminate when the specified address is qualified. If the specified address does not qualify, processes continue with the next ACL specification. Once the address of the client requesting connection is qualified, the ACLs permissions dictate whether the connection is 'allowed' or 'denied'. If the ACL specifications qualify address of the client requesting connection, a default resolution of 'allow is assumed and the client is allowed to connect. The ACL in the configuration take the following syntactic forms:
ipACL := '[' aclSpec [, aclSpec] ']'
aclSpec := "permission" : [ "deny" | "allow" ] [, "address": [ ipv4Address | ipv4MappedAddress | ipv6Address ] ]
The ipACLs can use IPv4 addresses, ipv6 addresses and IPv4 mapped addresses as described in RFC 4291.
Inbound connection requests are processed uniformly after they are received over a network interface. The network interface configuration dictates the form of addressing. For example, addresses appearing on an IPv6 interface appears as IPv6 addresses. If the IPv6 configuration specifies IPv4 mapping, then the IPv4 client's address is mapped into the IPv6 addressing space. An address appearing on an IPv4 interface appears as an unmapped IPv4 address. Since the ACL qualification focuses on qualifying addresses and all adapters within the host environment have unique addresses, no additional interface information is required.
For hosts that support hot-fail over network interfaces, the fail-over and reassignment of network IP address to adapter MAC addresses is transparent to the application.
Example 4-1 Examples
Deny client connections originating from 192.0.2.254.
"ipACL" : [ { "permission" : "deny", "address" : "192.0.2.254" } ]
Explicitly allow all client connections. The first ACP by default qualifies all addresses. The second ACL is never processed.
"ipACL" : [ { "permission" : "allow" },
{ "permission" : "deny", "address" : "192.0.2.254" } ]
Allow client connections originating from 127.0.0.1, but deny connection originating from 192.0.2.254 appearing on an interface configured for IPv6 addressing.
"ipACL" : [ { "permission" : "allow", "address" : "127.0.0.1" },
{ "permission" : "deny", "address" : "ff::192.0.2.254" } ]
Example 4-2 Example
"ipACL" : [ { "permission" : "allow", "address" : "::1" },
{ "permission" : "allow", "address" : "192.0.2.254" },
{ "permission" : "allow", "address" : "2001:db8:85a3:0:0:8a2e:370:7334" },
{ "permission" : "deny", "address" : "ff::192.0.2.254" } ]
Example 4-3 Example
Using REST API Calls
{
"$schema":"api:standardResponse",
"links":[
{
"href":"http://localhost:11000/services/v2/deployments/Local/services/adminsrvr",
"mediaType":"application/json",
"rel":"canonical"
},
{
"href":"http://localhost:11000/services/v2/deployments/Local/services/adminsrvr",
"mediaType":"application/json",
"rel":"self"
}
],
"messages":[
]
}
Example 4-4 Example
Using cURL:
curl -s -k -u ggsca:ggsca -X GET https://abc.us.oracle.com:9100/services/v2/deployments/depl_01/services/adminsrvr | json_reformat
curl -s -k -u ggsca:ggsca -X PATCH https://abc.us.oracle.com:9100/services/v2/deployments/depl_01/services/adminsrvr' -H Cache-Control: no-cache' -d @"admin_2.json" |
json_reformat
-- 8< -- File Content from admin.json -------
{"config": {
"network": {
"ipACL": [
{
"address": "10.196.9.33 ",
"permission": "allow"
},
{
"address": "10.90.136.97",
"permission": "allow"
},
{
"address": "10.209.243.80",
"permission": "deny"
}
],
"serviceListeningPort": 9101
}
}
}
Example 4-5 Example
oggServiceConfig
:-- Check initial configuration
oggServiceConfig https://abc.us.oracle.com:9100 depl_01 adminsrvr --user ggsca --password ggsca
oggServiceConfig https://abc.us.oracle.com:9100 depl_01 adminsrvr --user ggsca --password ggsca --path /network
oggServiceConfig https://abc.us.oracle.com:9100 depl_01 adminsrvr --user ggsca --password ggsca --path /network/ipACL
-- Modify Service Properties
oggServiceConfig https://abc.us.oracle.com:9100 depl_01 adminsrvr --user ggsca --password ggsca --path /network/ipACL --value '[{ "permission" : "allow", "address" : "10.196.9.33 " },{ "permission" : "allow", "address" : "10.90.136.97" },{ "permission" : "deny", "address" : "10.209.243.80" } ]'
Current value of "/network/ipACL" for "depl_01/adminsrvr" is <not defined>.
Setting new value and restarting service.
New value of "/network/ipACL" for "depl_01/adminsrvr" is
-- Check final configuration
oggServiceConfig https://abc.us.oracle.com:9100 depl_01 adminsrvr --user ggsca --password ggsca
oggServiceConfig https://abc.us.oracle.com:9100 depl_01 adminsrvr --user ggsca --password ggsca --path /network
oggServiceConfig https://abc.us.oracle.com:9100 depl_01 adminsrvr --user ggsca --password ggsca --path /network/ipACL
[
{
"address": "10.196.9.33 ",
"permission": "allow"
},
{
"address": "10.90.136.97",
"permission": "allow"
},
{
"address": "10.209.243.80",
"permission": "deny"
}
]
ipACL := '[' aclSpec [, aclSpec] ']'
aclSpec := "permission" : [ "deny" | "allow" ]
[, "address": [ ipv4Address | ipv4MappedAddress | ipv6Address ] ]
Parent topic: Network
4.2 Network Connection Adapter
Learn about how to specify your network connection configuration.
Network Interface Use Control as Network Connection Adapter is the name of an internal implementation class. When there are more than one network interface that are configured in an environment where the host is multi-homed, then it is known as multiple networks. For example, handling connection requests on different addresses through different network interface adapters.
The NetworkConnectionSpecs
themselves are members of an array
associated with the serviceListeningPort
configuration element.
For example, using the serviceListeningPort
configuration entry,
a network specification may take any of the following syntactic forms:
1. portValue | portValueString
2. networkSpec
3. '[' networkSpec [, networkSpec ...] ']'
You can use the following syntax in your network specification:
portValue := [1234567890]+
portValueString := '"' portValue '"'
networkSpec := '{' portSpec [, ipaddressSpec | nameSpec] [, interfaceSpec] [, networkOptionSpec] '}'
portSpec := "port" : portValue | portValueString
ipaddressSpec := "address" : ipv4Address | ipv6Address | "ANY"
nameSpec := '"' :alphanum: '"'
interfaceSpec := "interface" : '"' :alphanum: '"'
networkOptionSpec := "options" : IPV4_ONLY | IPV6_ONLY
Regardless of the form your specification takes, the internal representation is normalized into the 3rd form:
1. portValue | portValueString == networkSpec
2. portValue == '{' "port" : portValue '}'
3. portValueString == '[' '{' "port" : portValueString '}' ']'
The first form retains compatibility with existing network port specifications where only the portValue
or portValueString
is provided.
The second form assigns the networkSpec
as a single value. This form still only defines a single network specification and allows greater control and flexibility in identifying network values and options.
The third form defines an array of networkSpec
instances. It allows you to specify different network configurations based upon either address or network interface.
Example 4-6 Example
With the following simplified host network interface configuration:
$/sbin/ip addr show
lo: LOOPBACK,UP,LOWER_UP mtu 16436 qdisc noqueue state UNKNOWN
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
eth0: BROADCAST,MULTICAST,UP,LOWER_UP mtu 1500 qdisc pfifo_fast state UP qlen 1000
link/ether 00:16:3e:52:6e:27 brd ff:ff:ff:ff:ff:ff
inet 192.0.2.39/21 brd 10.240.111.255 scope global eth0
inet6 2001:db8:85a3:0:0:8a2e:370:6666 brd ff02::1 scope link eth0
eth1: BROADCAST,MULTICAST mtu 1500 qdisc pfifo_fast state UP qlen 1000
link/ether 00:16:3e:1f:99:bc brd ff:ff:ff:ff:ff:ff
inet 192.0.2.98/21 brd 10.100.99.98 scope link eth1
inet6 2001:db8:85a3:0:0:8a2e:370:7334 brd ff02::1 scope link eth1
inet6 2001:db8:85a3:0:0:8a2e:370:6666
The following specification is derived:
1. "serviceListeningPort: "9000"
2. "serviceListeningPort: 9000
3. "serviceListeningPort: { "port" : 9000 }
4. "serviceListeningPort: { "port" : "9000" }
5. "serviceListeningPort: { "port" : "9000", "address" : "192.0.2.254" }
6. "serviceListeningPort: { "port" : "9000", "name" : "server1" }
7. "serviceListeningPort: { "port" : "9000", "interface" : "eth1"}
8. "serviceListeningPort: [
{ "port" : "9000", "interface" : "lo" }
{ "port" : "9000", "address" : "192.0.2.39", "option" : "IPV4_ONLY" }
{ "port" : "9000", "interface" : "eth1", "option" : "IPV6_ONLY" }
These forms are described as:
- Form 1 - 4
-
Listens on port 9000 on
ANY
address overALL
interfaces. - Form 5
-
Listens on port 9000 on address 192.0.2.254 only.
- Form 6
-
Listens on port 9000 on the address associates with
server1
. - Form 7
-
Listens on port 9000 on the address associates with interface
eth1
and accepts IPV4 address connections using the mapped IPV4. - Form 8
-
Listens on port 9000 on the address associates with interface
lo
, on port 9000 address 192.0.2.39 accepting only IPV4 addresses, and on port 9000 with addresses associated with interfaceeth1
accepting onlyIPV6 addresses.
Most of this logic handles selecting the network interface adapter based on the network interface adapter’s identifying name or the address. The interface can be searched for based on the requested address.
Specifying multiple adapters means that each network specification resolves to only
a subset of adapters. Precedence processing allows the specification of
ANY
address and ALL
interfaces for
the last network specification as a pool specification when the platform
networking interfaces support mapping subset interface matches.
Parent topic: Network
4.3 Configure Reverse Proxy with NGINX to Access Oracle GoldenGate Microservices
Learn how to configure reverse proxy service using NGINX for accessing Oracle GoldenGate Microservices without using port numbers.
Reverse proxy enables accessing microservices using one single port (443) in a deployment. This enables encapsulation of the URL for microservices over an unsecure deployment.
Note:
Reverse proxy is optional, however, Oracle recommends that you ensure easy access to microservices and provide enhanced security.You can run microservices in an unsecure deployment on loopback address and front it with an HTTP reverse proxy using the NGINX installation.
When sending trail files from Oracle GoldenGate Classic to Microservices
environment that is configured with a reverse proxy, use a pump Extract from Oracle GoldenGate
Classic with SOCKSPROXY
option. When sending trail files from Oracle
GoldenGate Microservices to Classic Architecture use the ogg
protocol in the
Distribution Service configuration.
See Connecting Classic to MA and Connecting MA to Classic in Administering Oracle GoldenGate.
Reverse Proxy Support
You can configure Oracle GoldenGate
Microservices Architecture to use a reverse proxy. Oracle GoldenGate
MA includes a script called
ReverseProxySettings
that generates configuration file for only the NGINX
reverse proxy server.
For example, the Administration Service is available on
http://goldengate.example.com:9001
and the Distribution Service is on
http://goldengate.example.com:9002
. With reverse proxy, each of the
microservices can simply be accessed from the single address. For example,
http://goldengate.example.com/distsrvr
for the Distribution Service.
The URL is different for each service and is by name instead of by port.
You can use these options by running the ReverseProxySettings
utility. Here are the options available with this utility:
-
-o
or--output
-
The output file name. The default file name is
ogg.conf
. -
-P
or--password
-
A password for a Service Manager account.
-
-l
or--log
-
Log file name and initiates logging. The default is no logging.
-
--trailOnly
-
Configure only for inbound trail data.
-
-t
or--type
-
The proxy server type. The default is Nginx.
-
-s
or--no-ssl
-
Configure without SSL.
-
-h
or--host
-
The virtual host name for reverse proxy.
-
-p
or--port
-
The reverse proxy port number. The defaults are 80 or 443.
-
-?
or--help
-
Display usage information.
-
-u
or--user
-
Name of the Service Manager account to use.
-
-v
or--version
-
Displays the version.
These values are used when connecting to the Service Manager and are required when authentication is enabled.
Prerequisites
You can use any reverse proxy service with MA. The following example provides a process that you can follow to configure other reverse proxy services in conjunction with the documentation for your proxy server.
The following prerequisites provide details on the minimum requirements to configure an NGINX Reverse Proxy. Similar requirements may be required for your environment and reverse proxy if not using NGINX. Consult the documentation for your reverse proxy.
-
Install NGINX, see Install the NGINX Web Server and Proxy on Oracle Linux. For Oracle Linux, the command to install NGINX is:
yum —y install NGINX
-
Check the JRE version to be JRE 8 or higher.
-
Install Oracle GoldenGate MA.
-
Create one or more active MA deployments.
-
Ensure that the Oracle user has
sudo
permissions. -
Configure the
PATH
environment variable to include the NGINX installation directory path.
Configuring NGINX Reverse Proxy
An Oracle GoldenGate MA installation includes the
ReverseProxySettings
utility. The ReverseProxySettings
utility is located in the $OGG_HOME/lib/utl/reverseproxy
directory.
To identify additional commands that can be used with the
ReverseProxySettings
utility, run the utility with the
--help
option:
$OGG_HOME/lib/utl/reverseproxy/ReverseProxySettings --help
To add the NGINX certificate to the Distribution Service’s client wallet as a trusted certificate, see Trusted Certificates.
-
To generate a configuration file for NGINX Reverse Proxy, navigate to the location of the ReverseProxySettings utility:
cd $OGG_HOME/lib/utl/reverseproxy
-
Run the ReverseProxySetting utility:
ReverseProxySettings -u adminuser -P adminpwd -o ogg.conf http://localhost:9100
In this code snippet,
adminuser
is the deployment user name andadminpwd
is the deployment user password used to login to the deployment. -
Replace the existing NGINX configuration with the configuration that was generated using the
ReverseProxySetting
utility for your MA deployment:sudo mv ogg.conf /etc/nginx/conf.d/nginx.conf
However, this NGINX configuration isn't complete without the
events
section, and enclosing themap
andserver
sections inhttp
.Optionally, you can use the default
nginx.conf
file and add the generatedogg.conf
by adding aninclude
statement similar to this:include /etc/nginx/conf.d/ogg.conf;
In this case, you must comment out the other
servers
section. -
Generate a self-signed certificate for NGINX:
sudo sh /etc/ssl/certs/make-dummy-cert /etc/nginx/ogg.pem
For distribution paths to go through the reverse proxy, you need to use a valid certificate. It's better to specify the same certificate that the deployment is using to process incoming requests, otherwise, starting the path will fail with the next error in Distribution Service:
2019-03-26T11:26:00.324-0700 ERROR| ERROR OGG-10351 Oracle GoldenGate Distribution Service for Oracle: Generic error -1 noticed. Error description - Certificate validation error: Unacceptable certificate from test00abc: application verification failure. (A4)
-
Validate the NGINX configuration:
sudo NGINX -t
The output would show the following, if the command is successful:NGINX: the configuration file /etc/NGINX/NGINX.conf syntax is ok NGINX: configuration file /etc/NGINX/NGINX.conf test is successful
-
Reload NGINX with the new configuration:
sudo NGINX -s reload
If the changes for the configuration file are not loaded, stop and restart the proxy.
-
To test if you can access the microservices after NGINX is set up successfully, open the web browser.
-
Enter the proxy URL for the Service Manager using port number 443, similar to the following:
http://dc.example.com:443
This would open the Service Manager login page, from where you can access the other microservices also. If you want to directly access a microservice, you can enter the proxy URL for that microservice, as given in the
ogg.conf
file, generated previously.
Also see this video on configuring the NGINX reverse proxy.
SSL Termination
When there is an unsecure connection between the reverse proxy, which uses a TLS-based connection, and the origin server, it is referred to as reverse proxy SSL-termination.
Note:
In SSL-Termination the connections between the reverse proxy and the origin servers are unsecure.
However, SSL-bridging is also supported where the connections between the client and reverse proxy is secured and the connection between the reverse proxy and the origin server is also secured.
Parent topic: Network
4.4 Network Communication
An MA server is the originator of all the response messages sent to the client when a request is sent to the server.
An MA server neither serves as a proxy nor supports tunneling of response messages generated by other applications. Secured network communications use TLS 1.2 or DTLS (Datagram Transport Layer Security) libraries. MA Oracle platforms uses the Oracle SSL toolkit (NZ), which includes Oracle Wallet integration.
For heterogeneous platforms, the Oracle SSL toolkit is used where available.
Parent topic: Network