Configuring Oracle Traffic Director 12c with WebGate

At a recent customer install, I was faced with configuring Oracle Traffic Director (OTD) 12.2.1.2.0 Webgate with Oracle Access Manager.

Deploying Webgate on OD 12c is very well described in the documentation. See A Configuring OAM Agent (WebGate) for Oracle Traffic Director 12.2.1.2

There is however a flaw in the documentation. I came across that when I reached the point where Webgate get's configured in the conf files of OTD.

When you configure Webgate for OTD 12c, the OTD Conf files such as magnus.conf and virtual-server-*-obj.conf  are updated. (on a collocated installation)
If you follow the documentation completely, you will end up with conf files that either have no WebGate configuration in them or with the configuration dedicated to the first OTD instance on both servers. In the latter case, the second instance will no longer start.
I created a Service Request at Oracle support to address the issue. They didn't have a solution for the problem and I ended up being bounced between the OTD and the WebGate support teams. Finally one of the guys from the WebGate team really tried to help me, but couldn't resolve the issue. So I went along and solved the problem myself. As I will describe below.

When you reach pt.5 of the documentation A.2 Configuring Oracle Traffic Director 12c WebGate

Change the EditObjConf line as follows

./EditObjConf -f Domain_Home/config/fmwconfig/components/OTD/otd_configuration_name/config/virtual_server_name-obj.conf -w webgate_instanceDirectory [-oh Oracle_Home] -ws otd

For example

OTD Configuration Name: TST1
OTD Instance 1: otd_TST1_host1.domain.local
OTD Instance 2: otd_TST1_ host1.domain.local
Domainhome: /u01/app/oracle/config/domains/otd_domain_tst

./EditObjConf -f /u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/ OTD/TST1/config/virtual-server-tst1-obj.conf -w /u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/ OTD/instances/otd_TST1_ host1.domain.local -oh $ORACLE_HOME -ws otd

Where TST1 is the name of the configuration and host1.domain.local is the name of the first server.
This will change the magnus.conf and virtual-server-tst1-obj.conf for Webgate.
In virtual-server-tst1-obj.conf there are no instance specific references.
However in the magnus.conf there are references to the first instance, since this is the one that we used with EditObjConf.

This is what the magnus.conf in the OTD configuration section (on global level) looks like after EditObjConf command.
Notice the hardcoded instance name in four places.

/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/ OTD/TST1/config/magnus.conf

# 
# Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
# 

Init fn="load-modules" shlib="libwebapp-firewall.so"

# Oracle WebGate Init FNs start #WGINITFN 
Init fn="load-modules"
funcs="OBWebGate_Init,OBWebGate_Authent,OBWebGate_Control,
OBWebGate_Err,OBWebGate_Handle401, OBWebGate_Response" 
shlib="/u01/app/oracle/product/otd1221/webgate/otd/lib/webgate.so" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/
components/OTD/instances/otd_TST1_host1.domain.local"
#ESSO#Init fn="load-modules"
funcs="EssoBasicAuthInit,EssoBasicAuth,EssoClean" 
shlib="/u01/app/oracle/product/otd1221/webgate/otd/lib/webgate.so" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/
components/OTD/instances/otd_TST1_host1.domain.local"
Init fn="OBWebGate_Init" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/
components/OTD/instances/otd_TST1_host1.domain.local" Mode="PEER"
#WebGateLockFileDir="<some_local_dir>"

# WebGateLockFileDir: Optional directive specifying the location to create 
# webgate lock files. 
# 
# If configured, then all webgate lock files will be created under 
# <WebGateLockFileDir>/<Hash of WebGateInstancedir>. The hash subdir is to 
# ensure uniqueness for each webserver instance and avoid locking conflicts 
# if two different instances have configured the directive with same value. 
# 
# If the dir does not exist before, will try to create it first. If dir 
# creation failed or the directive not configured, webgate falls back to old 
# model, i.e. use same location as original file that lock is based upon. 
# 
# This directive is useful when webgate instance is located on NFS mounted 
# disks and performance greatly impacted. Configure it to local dir will solve 
# the issue. 

#ESSO#Init fn="EssoBasicAuthInit" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/
components/OTD/instances/otd_TST1_host1.domain.local" Mode="PEER" 
# Oracle WebGate Init FNs end #WGINITFN

Leaving it like this will result in this hardcoded instance name being distributed to all instance. Hence only one instance would start.

Now how to fix this.

Open magnus.conf with an editor

Replace the hardcoded instance name with a variable called ${INSTANCE_NAME}

(I picked up the existence of this variable in the server.xml which is also on the OTD Configuration level and get distributed all instances.)

In our example the magnus.conf now looks like this.

#
# Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
# 

Init fn="load-modules" shlib="libwebapp-firewall.so"

# Oracle WebGate Init FNs start #WGINITFN 
Init fn="load-modules"
funcs="OBWebGate_Init,OBWebGate_Authent,OBWebGate_Control,
OBWebGate_Err,OBWebGate_Handle401,OBWebGate_Response" 
shlib="/u01/app/oracle/product/otd1221/webgate/otd/lib/webgate.so" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/${INSTANCE_NAME}"
#ESSO#Init fn="load-modules" 
funcs="EssoBasicAuthInit,EssoBasicAuth,EssoClean" 
shlib="/u01/app/oracle/product/otd1221/webgate/otd/lib/webgate.so" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/${INSTANCE_NAME}" Init fn="OBWebGate_Init" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/${INSTANCE_NAME}" Mode="PEER" 
#WebGateLockFileDir="<some_local_dir>" 

# WebGateLockFileDir: Optional directive specifying the location to create 
# webgate lock files. 
# 
# If configured, then all webgate lock files will be created under 
# <WebGateLockFileDir>/<Hash of WebGateInstancedir>. The hash subdir is to 
# ensure uniqueness for each webserver instance and avoid locking conflicts 
# if two different instances have configured the directive with same value. 
# 
# If the dir does not exist before, will try to create it first. If dir 
# creation failed or the directive not configured, webgate falls back to old 
# model, i.e. use same location as original file that lock is based upon. 
# 
# This directive is useful when webgate instance is located on NFS mounted 
# disks and performance greatly impacted. Configure it to local dir will solve 
# the issue. 

#ESSO#Init fn="EssoBasicAuthInit"

obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/${INSTANCE_NAME}" Mode="PEER"
# Oracle WebGate Init FNs end #WGINITFN

Now to distributed these files

Open Enterprise ManagerFusion Middleware Control 12c and go to the OTD Configuration

Go to Virtual Server section and click Lock and Edit

EM will show the Pull Components Changes bar.

DON'T pull the changes!
This will replace the conf files of the configuration with those currently in use by the instances.

Instead make a minor, insignificant, change in the configuration.
For example add a hostname to the Virtual Server Settings. (We remove it later)
Now activate the changes
Again, don’t Pull the changes

Discard the Instance Changes and Activate Changes.

Again Discard Changes

And finally Discard Changes to distributed the correct conf files to the instances.

Now let's look at the magnus.conf on both instances (We already know that the virtual-server-tst1-obj.conf is the same everywhere)

On Instance 1

#
# Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved.
#

Init fn="load-modules" shlib="libwebapp-firewall.so"

# Oracle WebGate Init FNs start #WGINITFN
Init fn="load-modules"
funcs="OBWebGate_Init,OBWebGate_Authent,OBWebGate_Control,

OBWebGate_Err,OBWebGate_Handle401,OBWebGate_Response" 
shlib="/u01/app/oracle/product/otd1221/webgate/otd/lib/webgate.so" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/
components/OTD/instances/otd_TST1_host1.domain.local" 
#ESSO#Init fn="load-modules" funcs="EssoBasicAuthInit,EssoBasicAuth,EssoClean" 
shlib="/u01/app/oracle/product/otd1221/webgate/otd/lib/webgate.so" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/otd_TST1_host1.domain.local" Init fn="OBWebGate_Init" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/otd_TST1_host1.domain.local" Mode="PEER" 
#WebGateLockFileDir="<some_local_dir>" 

# WebGateLockFileDir: Optional directive specifying the location to create # webgate lock files.
# 
# If configured, then all webgate lock files will be created under 
# <WebGateLockFileDir>/<Hash of WebGateInstancedir>. The hash subdir is to 
# ensure uniqueness for each webserver instance and avoid locking conflicts 
# if two different instances have configured the directive with same value. 
# 
# If the dir does not exist before, will try to create it first. If dir 
# creation failed or the directive not configured, webgate falls back to old 
# model, i.e. use same location as original file that lock is based upon. 
# 
# This directive is useful when webgate instance is located on NFS mounted 
# disks and performance greatly impacted. Configure it to local dir will solve 
# the issue. 

#ESSO#Init fn="EssoBasicAuthInit"

obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/otd_TST1_host1.domain.local" Mode="PEER" 
# Oracle WebGate Init FNs end #WGINITFN

And on Instance 2

#
# Copyright (c) 2011, 2016, Oracle and/or its affiliates. All rights reserved. 
# 

Init fn="load-modules" shlib="libwebapp-firewall.so" 

# Oracle WebGate Init FNs start #WGINITFN 
Init fn="load-modules" funcs="OBWebGate_Init,OBWebGate_Authent,OBWebGate_Control,
OBWebGate_Err,OBWebGate_Handle401,OBWebGate_Response" 
shlib="/u01/app/oracle/product/otd1221/webgate/otd/lib/webgate.so" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/otd_TST1_host2.domain.local"
#ESSO#Init fn="load-modules" 
funcs="EssoBasicAuthInit,EssoBasicAuth,EssoClean" 
shlib="/u01/app/oracle/product/otd1221/webgate/otd/lib/webgate.so" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/otd_TST1_host2.domain.local" 
Init fn="OBWebGate_Init" 
obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/otd_TST1_host2.domain.local" Mode="PEER"
#WebGateLockFileDir="<some_local_dir>" 

# WebGateLockFileDir: Optional directive specifying the location to create 
# webgate lock files. 
# 
# If configured, then all webgate lock files will be created under 
# <WebGateLockFileDir>/<Hash of WebGateInstancedir>. The hash subdir is to 
# ensure uniqueness for each webserver instance and avoid locking conflicts 
# if two different instances have configured the directive with same value. 
# 
# If the dir does not exist before, will try to create it first. If dir 
# creation failed or the directive not configured, webgate falls back to old 
# model, i.e. use same location as original file that lock is based upon. 
# 
# This directive is useful when webgate instance is located on NFS mounted 
# disks and performance greatly impacted. Configure it to local dir will solve 
# the issue.

#ESSO#Init fn="EssoBasicAuthInit"

obinstalldir="/u01/app/oracle/product/otd1221/webgate/otd" 
obinstancedir="/u01/app/oracle/config/domains/otd_domain_tst/config/fmwconfig/components/OTD/instances/otd_TST1_host2.domain.local" Mode="PEER" 
# Oracle WebGate Init FNs end #WGINITFN

The files look good on both instances.

Now Restart Instances

Validate Restart operation on target /Domain_otd_domain_tst/otd_domain_tst/otd_TST1_host2.domain.local Validate Restart operation on target /Domain_otd_domain_tst/otd_domain_tst/otd_TST1_host1.domain.local ------------------------------------------------

Perform Restart operation on target /Domain_otd_domain_tst/otd_domain_tst/TST1

Perform Restart operation on target /Domain_otd_domain_tst/otd_domain_tst/otd_TST1_host2.domain.local

Perform Restart operation on target /Domain_otd_domain_tst/otd_domain_tst/otd_TST1_host1.domain.local

------------------------------------------------

Checking operation status on target /Domain_otd_domain_tst/otd_domain_tst/TST1

 Operation Restart on target /Domain_otd_domain_tst/otd_domain_tst/otd_TST1_host2.domain.local succeeded

 Operation Restart on target /Domain_otd_domain_tst/otd_domain_tst/otd_TST1_host1.domain.local succeeded

Now you're good to go with WebGate correctly configured on OTD 12c.

I put the solution in the service request and got thanks from the guys at Oracle Support. They told me, they where going to change the documentation to match my solution. Always nice to get this kind of appreciation from them