A Using the Portal Dependency Settings File

OracleAS Portal is dependent on the components: Oracle Application Server Web Cache and Oracle Internet Directory. It is important that you understand these dependencies, as it may be necessary to fine tune or configure these components after Oracle Application Server is installed.

To simplify configuration changes, OracleAS Portal introduces the Portal Dependency Settings File (iasconfig.xml). This file stores configuration data from all the dependent components in a central place and the content of the file is updated when there are configuration changes.

You can use the Portal Dependency Settings file to:

Check settings used by an OracleAS Portal instance
Update settings in the Oracle Application Server Metadata Repository.

This appendix discusses the Portal Dependency Settings, and the Portal Dependency Settings tool in the following two sections:

A.1 Portal Dependency Settings File Details

The following sections describe the Portal Dependency Settings file in more detail:

A.1.1 Name and Location

The name of the Portal Dependency Settings file is iasconfig.xml, and is located by default in ORACLE_HOME/portal/conf, where ORACLE_HOME is the OracleAS Portal and Oracle Application Server Wireless middle-tier home.

When using any of the tools that access the Portal Dependency Settings file, you can override the default location of the file by setting the environment variable IASCONFIG_LOC to the directory in which your file is stored, for example:

set IASCONFIG_LOC=/usr/local/ias904

A.1.2 Updating the Portal Dependency Settings File

If the Portal Dependency Settings file is accessible over a network file system, you can share the file across multiple hosts, avoiding the need to manually replicate it every time the file is modified. If the installation is running on an operating system which supports symbolic links, it is recommended that you use this mechanism to reference a shared file, instead of setting the IASCONFIG_LOC environment variable.

If, however, the Portal Dependency Settings file is not accessible over the network, you must ensure that the file is kept up-to-date with changes to your site topology. The Portal Dependency Settings file is used to configure the Portal Repository with details of OracleAS Web Cache, Oracle Internet Directory and Oracle Enterprise Manager that it is using. It is not required that it is copied into each individual middle-tier in your site, but you must ensure that any changes to the components modeled in the file that affect OracleAS Portal configuration are updated in the file.

To demonstrate how the Portal Dependency Settings file is kept up-to-date, let's use the configuration defined in Section 5.3, "Configuring Multiple Middle-Tiers with a Load Balancing Router".

The Portal Dependency Settings file gets first created in Section 5.3.1, "Step 1: Install a Single Portal and Wireless Middle-Tier (M1)", during the installation. It looks like Example 5-1, "iasconfig.xml After the First Middle-Tier Installation".

This file will be located on machine m1.abc.com, typically in ORACLE_HOME/portal/conf of the middle-tier that has just been installed.

In Step 2: Configure OracleAS Portal on M1 to Be Accessed Through the LBR, the Portal Dependency Settings file is manually changed as shown in Example 5-2, "iasconfig.xml File Edited to Include Farm Element".

This file will be on machine m1.abc.com, typically in ORACLE_HOME/portal/conf of the middle-tier installed in Step 1. You use the ptlconfig tool as shown in Section A.2.1, "Portal Dependency Settings Tool", after you make changes to the file.

Any future changes to the OracleAS Web Cache, Oracle Internet Directory, or Oracle Enterprise Manager settings in iasconfig.xml should be made using the Application Server Control, or by hand on m1.abc.com. You must also use the ptlconfig tool again after you make changes.

Note:

Changes to OracleAS Portal's OracleAS Web Cache settings can also be made on the Portal Web Cache Settings page, as described in Section 7.2.3, "Portal Web Cache Settings Page".

Typically, the hostname and port number, by which OracleAS Portal is addressed, uses the OracleAS Web Cache hostname and port number. This is because, in a simple configuration, browser requests go directly to OracleAS Web Cache. However, in a configuration that has a load balancing router (LBR), or reverse proxy server front-ending OracleAS Web Cache, the hostname and port number defined on this page may need to reflect that of the LBR, or reverse proxy server.

In this configuration, you want OracleAS Web Cache invalidation messages to be sent directly to the OracleAS Web Cache host, as opposed to the LBR, or reverse proxy server. In the scenario where your published hostname is different from the hostname used for OracleAS Web Cache invalidation, you cannot use the Portal Web Cache Settings page in the Oracle Enterprise Manager Application Server Control, or the Portal Dependency Settings file iasconfig.xml, to establish these settings. Instead, you must use the OracleAS Portal Configuration Assistant (OPCA) in the MIDTIER mode with -type OHS., using the host parameter to specify the hostname of the LBR, or reverse proxy server, and the -chost parameter to define the OracleAS Web Cache hostname.

In Step 5: Configure the New Middle-Tier (M2) to Run Your Existing Portal, the Portal Dependency Settings file on m2.abc.com needs to be updated manually with the settings defined in the iasconfig.xml file on m2.abc.com.

A.1.3 Configuration Elements

The Portal Dependency Settings file is an XML file, that is made up of a number of elements that describe the settings of specific Oracle Application Server components and the dependencies Portal instances have on them. Figure A-1 shows all the elements that can be modeled in the Portal Dependency Settings file. The Portal Dependency Settings file definition is modeled in the schema file iasconfig.xsd, which is located in ORACLE_HOME/portal/conf.

Figure A-1 Elements in the Portal Dependency Settings file

Text description of cg_monit_elements.gif follows.

Text description of the illustration cg_monit_elements.gif

The individual elements are:

IASFarm

The IASFarm element represents a logical farm of Oracle Application Server instances.

Table A-1 Element IASFarm

Attribute Name	Type	Description
Name	String	Unique farm name
Host	String	Logical host machine

IASInstance

The IASInstance element represents a specific Oracle Application Server instance, which usually maps to an Oracle home.

Table A-2 Element IASInstance

Attribute Name	Type	Description
Name	String	Oracle Application Server instance name (for example, `ias904.host.domain`)
Host	String	Host machine
Version	String	Version of Oracle Application Server.

PortalInstance

These are the OracleAS Portal instance settings.

Table A-3 Element PortalInstance

Attribute Name	Type	Description
DADLocation	String	The name and location of the OracleAS Portal DAD (for example, `/pls/portal`).
ConnectString	String	OracleAS Metadata Repository connect string
SchemaUsername	Integer	OracleAS Portal schema username
SchemaPassword	String	OracleAS Portal schema password

WebCacheComponent

These are the OracleAS Web Cache settings.

Table A-4 Element WebCacheComponent

Attribute Name	Type	Description
ListenPort	Integer	Listening port
AdminPort	Integer	Administration port
InvalidationPort	Integer	Invalidation port
InvalidationUsername	String	Invalidation username
InvalidationPassword	String	Invalidation password
SSLEnabled	String	Flag to indicate whether the listening port is SSL enabled. The value can either be `TRUE` or `FALSE`.

OIDComponent

These are the Oracle Internet Directory settings.

Table A-5 Element OIDComponent

Attribute Name	Type	Description
AdminPassword	String	Oracle Internet Directory administration password
PortSSLEnabled	String	Flag to indicate whether the HTTP port is SSL enabled. The value can either be `TRUE` or `FALSE`.
LDAPPort	Integer	LDAP port that Oracle Internet Directory is running on.
AdminDN	String	Oracle Internet Directory administration distinguishing name

EMComponent

These are the Oracle Enterprise Manager Application Server Control settings.

Table A-6 Element EMComponent

Attribute Name	Type	Description
ConsoleHTTPPort	Integer	Listening port
SSLEnabled	String	Flag to indicate whether the listening port is SSL enabled. The value can either be `TRUE` or `FALSE`.

WebCacheDependency

This is the OracleAS Portal instance reference to the OracleAS Web Cache it is using.

Table A-7 Element WebCacheDependency

Attribute Name	Type	Description
ContainerType	String	The type of the container the OracleAS Web Cache component is running under. This can be either IASInstance or IASFarm.
Name	String	IASInstance name or the unique IASFarm name, depending on ContainerType.

OIDDependency

This is the OracleAS Portal instance reference to the Oracle Internet Directory it is using.

Table A-8 Element OIDDependency

Attribute Name	Type	Description
ContainerType	String	The type of the container the Oracle Internet Directory component is running under. This can be either IASInstance or IASFarm.
Name	String	IASInstance name or the unique IASFarm name, depending on ContainerType.

EMDependency

This is the Oracle Enterprise Manager Application Server Control managing this OracleAS Portal instance.

Table A-9 Element EMDependency

Attribute Name	Type	Description
ContainerType	String	The type of the container the Oracle Enterprise Manager Application Server Control is being managed by. This should be set to IASInstance.
Name	String	IASInstance name

A.1.4 Sample Portal Dependency Settings File

The following XML represents the contents of a sample Portal Dependency Settings file:

<IASConfig XSDVersion="1.0">

   <IASInstance Name="iAS-1" Host="abc.company.com" Version="9.0.4">
      <WebCacheComponent AdminPort="3001" ListenPort="3002" 
InvalidationPort="3003" InvalidationUsername="orcladm" 
InvalidationPassword="orcladm=" SSLEnabled="false"/>
   </IASInstance>

   <IASInstance Name="iAS-2" Host="xyz.company.com" Version="9.0.4">
      <OIDComponent AdminPassword="orcladm" PortSSLEnabled="false" 
LDAPPort="3002" AdminDN="cn=orcladmin"/>
      <EMComponent ConsoleHTTPPort="1814" SSLEnabled="false"/>
   </IASInstance>

   <PortalInstance DADLocation="/pls/portal" SchemaUsername="portal" 
SchemaPassword="welcome1" ConnectString="xyz.company.com:1521:s901dev3">
      <WebCacheDependency ContainerType="IASInstance" Name="iAS-1"/>
      <OIDDependency ContainerType="IASInstance" Name="iAS-2"/>
      <EMDependency ContainerType="IASInstance" Name="iAS-2"/>
   </PortalInstance>

</IASConfig>

In this example, the OracleAS Portal instance is:

Accessed from the Database Access Descriptor (DAD) /pls/portal.
Dependent on:
- OracleAS Web Cache component running in Oracle Application Server instance iAS-1
- Oracle Internet Directory component running in Oracle Application Server instance iAS-2
- Oracle Enterprise Manager Application Server Control component running in Oracle Application Server instance iAS-2

A.1.5 Post-Installation Mapping in the Portal Dependency Setting File

When OracleAS Portal is installed, the OracleAS Portal Configuration Assistant (OPCA) creates appropriate entries in the Portal Dependency Settings file, based on what is installed.

In an Application Server installation, the dependencies of OracleAS Portal on Oracle Application Server Web Cache and Oracle Internet Directory are added to the Portal Dependency Settings file. Existing information is not updated if duplicate entries are encountered during the installation. Instead, a warning is output to the installation log file that the entries already exist.

See Also:

Chapter 3, "Installing OracleAS Portal" for more information about the different installation types.

Note:

By default, the Portal Dependency Settings file is accessed from ORACLE_HOME/portal/conf, where ORACLE_HOME is the OracleAS Portal and Oracle Application Server Wireless middle-tier home. However, if the IASCONFIG_LOC environment variable is set, the location defined by this variable is used.

In a single machine OracleAS Portal and OracleAS Wireless installation, where OracleAS Web Cache and Oracle Internet Directory instances already reside on the same machine, entries to the Portal Dependency Settings file are created as follows:

<IASConfig XSDVersion="1.0">

   <IASInstance Name="iAS-1" Host="abc.company.com" Version="9.0.4">
      <OIDComponent AdminPassword="orcladm" PortSSLEnabled="false" 
LDAPPort="3002" AdminDN="cn=orcladmin"/>
   </IASInstance>

   <IASInstance Name="iAS-2" Host="abc.company.com" Version="9.0.4">
      <WebCacheComponent AdminPort="3001" ListenPort="3002" 
InvalidationPort="3003" InvalidationUsername="orcadm" 
InvalidationPassword="orcladm=" SSLEnabled="false"/>
   </IASInstance>

   <PortalInstance DADLocation="/pls/portal" SchemaUsername="portal" 
SchemaPassword="welcome1" ConnectString="xyz.company.com:1521:s901dev3">
      <WebCacheDependency ContainerType="IASInstance" Name="iAS-2"/>
      <OIDDependency ContainerType="IASInstance" Name="iAS-1"/>
   </PortalInstance>

</IASConfig>

A.1.6 Common Configuration Mapping in the Portal Dependency Settings File

This section shows what the Portal Dependency Settings file looks like in the recommended topologies.

OracleAS Portal and OracleAS Wireless Developer Configuration: Medium Sized Machines

The topology for this common configuration is seen in Figure A-2.

Figure A-2 OracleAS Portal and OracleAS Wireless Developer Configuration

Text description of cg_monit_develop.gif follows.

Text description of the illustration cg_monit_develop.gif

This configuration assumes that both the application server and the infrastructure are installed on the same machine, called Host 1.

When you install the Infrastructure on Host 1 in Oracle home OH_2, no changes are made to the Portal Dependency Settings file.

When you install OracleAS Portal and OracleAS Wireless on Host 1 in Oracle home OH_1, referencing the Oracle Internet Directory instance in OH_2, the Portal Dependency Settings file looks like this:

<IASConfig XSDVersion="1.0">

   <IASInstance Name="host1.OH_1" Host="host1.us.oracle.com" Version="9.0.4">
      <WebCacheComponent AdminPort="3001" ListenPort="7778" 
InvalidationPort="3003" InvalidationUsername="orcadm" 
InvalidationPassword="orcladm=" SSLEnabled="false"/>
   </IASInstance>

   <IASInstance Name="host1.OH_2" Host="host1.us.oracle.com" Version="9.0.4">
      <OIDComponent AdminPassword="orcladm" PortSSLEnabled="false" 
LDAPPort="3002" AdminDN="cn=orcladmin"/>
   </IASInstance>

   <PortalInstance DADLocation="/pls/portal" SchemaUsername="portal" 
SchemaPassword="welcome1" ConnectString="host1.us.oracle.com:1521:iasdb">
      <WebCacheDependency ContainerType="IASInstance" Name="host1.OH_1"/>
      <OIDDependency ContainerType="IASInstance" Name="host1.OH_2"/>
   </PortalInstance>

</IASConfig>

Enterprise Data Center Configuration: Multiple Departments Sharing the Same Data Center

The topology for this common configuration is seen in Figure A-3.

Figure A-3 Enterprise Data Center Configuration

Text description of cg_monit_enterprise.gif follows.

Text description of the illustration cg_monit_enterprise.gif

This configuration assumes that the application server and the infrastructure are installed on different machines.

When you install the entire infrastructure, no changes are made to the Portal Dependency Settings file.

As shown in Figure A-3, the OracleAS Web Cache cluster front-ending OracleAS Portal is not yet known. When you install the application server (Portal and Wireless installation) on host Host 1 in Oracle home OH_1, referencing the Oracle Internet Directory on host Host 2, the configuration will look like this:

<IASConfig XSDVersion="1.0">

   <IASInstance Name="host2.OH_2" Host="host2.us.oracle.com" Version="9.0.4">
      <OIDComponent AdminPassword="orcladm" PortSSLEnabled="false" 
LDAPPort="3002" AdminDN="cn=orcladmin"/>
   </IASInstance>

   <IASInstance Name="host1.OH_1" Host="host3.us.oracle.com" Version="9.0.4">
      <WebCacheComponent AdminPort="3001" ListenPort="7778" 
InvalidationPort="3003" InvalidationUsername="orcladm" 
InvalidationPassword="orcladm=" SSLEnabled="false"/>
   </IASInstance>

   <PortalInstance DADLocation="/pls/portal" SchemaUsername="portal" 
SchemaPassword="welcome1" ConnectString="host1.us.oracle.com:1521:iasdb">
      <WebCacheDependency ContainerType="IASInstance" Name="host1.OH_1"/>
      <OIDDependency ContainerType="IASInstance" Name="host2.OH_2"/>
   </PortalInstance>

</IASConfig>

If you want the application server on Host 1 to be front-ended by OracleAS Web Cache (item 5 in the image), you need to manually edit the Portal Dependency Settings file. First, remove the existing OracleAS Web Cache entry and then create an OracleAS Web Cache entry that belongs to a farm. The modified Portal Dependency Settings file will now look like this:

<IASConfig xmlns="http://www.oracle.com/iAS/iASConfigFile" XSDVersion="1.0">

   <IASInstance Name="host2.OH_2" Host="host2.us.oracle.com" Version="9.0.4">
      <OIDComponent AdminPassword="orcladm" PortSSLEnabled="false" 
LDAPPPort="3002" AdminDN="cn=orcladmin"/>
   </IASInstance>

   <IASFarm name="Farm_1" host="frontend.us.oracle.com">
      <WebCacheComponent AdminPort="3001" ListenPort="7778" 
InvalidationPort="3003" InvalidationUsername="orcladm" 
InvalidationPassword="orcladm=" SSLEnabled="false"/>
   </IASFarm>

   <PortalInstance DADLocation="/pls/portal" SchemaUsername="portal" 
SchemaPassword="welcome1" ConnectString="host1.us.oracle.com:1521:iasdb">
      <WebCacheDependency ContainerType="IASFarm" Name="Farm_1"/>
      <OIDDependency ContainerType="IASInstance" Name="host2.OH_2"/>
   </PortalInstance>

</IASConfig>

The OracleAS Portal instance now references the virtual OracleAS Web Cache front-ending it.

Finally, you must run ptlconfig to change the settings stored in the OracleAS Metadata Repository:

ptlconfig -encrypt
ptlconfig -all

A.2 Configuration Tools

The following sections describe the available configuration tools, and the state of the portal dependency settings file in various topologies, in more detail:

A.2.1 Portal Dependency Settings Tool

To update the OracleAS Metadata Repository with configuration settings in iasconfig.xml, you must use the script ptlconfig. This script can:

Update the OracleAS Metadata Repository for a specific Portal instance defined in the Portal Dependency Settings file.
Update the OracleAS Metadata Repository for all Portal instances defined in the Portal Dependency Settings file.
Encrypt all plain text passwords in the Portal Dependency Settings file.
Update OracleAS Web Cache, Oracle Internet Directory, Oracle Enterprise Manager, and OracleAS Portal site data, as defined in the Portal Dependency Settings file.

The configuration script file is named ptlconfig (on UNIX) and ptlconfig.bat (on Windows). It is located in ORACLE_HOME/portal/conf, where ORACLE_HOME is the OracleAS Portal and OracleAS Wireless middle-tier home.

You can use this script as follows:

ptlconfig (-all | -dad <dad>) [-wc] [-oid] [-site] [-em] | -encrypt

Table A-10 ptlconfig Parameters

Parameter	Description	Example
-all	Updates all OracleAS Portal instances from the Portal Dependency Settings file.	`ptlconfig -all`
-dad	Portal DAD name. Used to update a specific OracleAS Portal instance from the Portal Dependency Settings file.	`ptlconfig -dad portal`
-encrypt	Encrypt any plain text passwords in the Portal Dependency Settings file.	`ptlconfig -encrypt`
-wc	Updates OracleAS Web Cache data as defined in the Portal Dependency Settings file.	`ptlconfig -dad portal -wc`
-oid	Updates Oracle Internet Directory data as defined in the Portal Dependency Settings file.	`ptlconfig -all -oid`
-site	Configures OracleAS Portal as a partner application for OracleAS Single Sign-On as defined in the Portal Dependency Settings file.	`ptlconfig -dad portal -site`
-em	Updates Oracle Enterprise Manager data as defined in the Portal Dependency Settings file.	`ptlconfig -dad portal -em`

When you run this script, the log file ptlconfig.log is created in the directory ORACLE_HOME/portal/logs, which records operations performed on the OracleAS Metadata Repository.

A.2.2 Oracle Enterprise Manager Application Server Control

Oracle Enterprise Manager Application Server Control also enables you to configure how an OracleAS Portal instance integrates with its dependent components. When you use Application Server Control to configure Portal Web Cache settings, the log file ptlemcfg.log is created in the directory ORACLE_HOME/portal/logs. This log file contains information about the operations performed on the OracleAS Metadata Repository. See Chapter 7, "Monitoring and Administering OracleAS Portal" for more information.