Oracle9iAS Portal Configuration Guide Release 2 (9.0.2) Part Number A90852-02 |
|
After installing Oracle9iAS Portal with the Oracle9i Application Server installation, several scripts are available for post-installation configuration. For example, you may want to configure a new Oracle9iAS Portal instance, or update an existing Oracle9iAS Portal instance.
For purposes of configuring Oracle9iAS Portal, the following scripts are useful, and are described in this appendix. In Oracle9iAS Portal most Portal configuration is done by using the Oracle9iAS Portal Configuration Assistant (OPCA).
See also:
Section 3.1, "The Oracle9iAS Portal Configuration Assistant (OPCA)" about the Oracle9iAS Portal Configuration Assistant modes and parameters. |
The specific scripts covered in this appendix include:
Oracle9iAS Portal is a partner application to the Oracle9iAS Single Sign-On Server. As such, it needs to be associated with an Oracle9iAS Single Sign-On Server for authentication services. When Oracle9iAS Portall is installed it is automatically associated with the Oracle9iAS Single Sign-On Server in the associated infrastructure installation.
What was formerly called the ssodatan script, in previous versions of Oracle9iAS Portal, has been obsoleted and replaced by running the Oracle9iAS Portal Configuration Assistant (OPCA) in the SSOPARTNERCONFIG mode. When you install Oracle9iAS Portal, the step previously done by ssodatan, is done automatically. However, after installation, there may be various reasons for associating the Oracle9iAS Portal with a different Oracle9iAS Single Sign-On Server, or needing to re-run the association because of a change in the hostname, port or protocol of the Oracle9iAS Single Sign-On Server.
The function performed by the script previously called ssodatax, is now performed by the following mode of OPCA:
ptlasst.csh -i typical -mode SSOPARTNERCONFIG -s portal -sp portal -c myhost.domain.com:1521:mySID -sdad portal -o orasso -odad orasso -host myApache.domain.com -port 7777 -silent -verbose -sso_c myhost.domain.com:1521:mySID -sso_h myApache.domain.com -sso_p 7777 -pa orasso_ pa -pap orasso_pa -ps orasso_ps -pp orasso_ps -pd portal_dblink -p_tns orasso_ps -s_tns portal -iasname myiASInstance.host
where
Whereas the old ssodatax
required you to setup the partner application entry in the SSO server and then invoke the script with the site_id, site_token and encryption_key obtained from partner application registration, the SSOPARTNERCONFIG mode of ptlasst.csh
(OPCA) no longer requires partner application registration to be a two-step process.
The Oracle9iAS Single Sign-On Server now provides a schema ORASSO_PA (default) for accessing the partner application registration procedure. You will need to get the password to this schema and an appropriate connect string to the Oracle9iAS Single Sign-On Server instance to register the Oracle9iAS Portal entry.
Note that if the Oracle9iAS Single Sign-On Server hostname changes, you will also need to run ssocfg.sh
on the Oracle9iAS Single Sign-On Server.
See also:
Oracle9iAS Single Sign-On Administrator's Guide for more details on running the |
This section shows how instead of running OPCA in the MIDTIER mode to adjust Oracle9iAS Web Cache specific settings, such as the Oracle9iAS Web Cache host, or Oracle9iAS Web Cache invalidation port, you can choose to run Oracle9iAS Web Cache configuration scripts to configure Oracle9iAS Portal to work with Oracle9iAS Web Cache. Furthermore, it describes how you can disable Oracle9iAS Web Cache and how you can manage the invalidation message processing job by using the script cachjsub.sql
:
Managing the Invalidation Message Processing Job Using cachjsub.sql
With the cachseed.sql
script you can modify all the Oracle9iAS Web Cache specific configuration parameters. cachseed.sql
is located in the ORACLE_HOME/portal/admin/plsql/wwc
directory. The script takes 6 arguments that are listed in the table below:
Example of running cachseed.sql
@cachseed.sql webdbsvr1.us.oracle.com 3002 3001 invalidator off moc
The script cachset.sql
is used to turn the use of Oracle9iAS Web Cache to on or off. The script can be found in the ORACLE_HOME/portal/admin/plsql/wwc
directory.
To use cachset.sql
connect to SQL*Plus as the schema owner and run cachset.sql as follows:
SQL>@cachset.sql
At the prompt enter on to enable the use of Oracle9iAS Web Cache and off to disable it.
Oracle9iAS Portal uses caching to improve its performance. One type of caching used is the invalidation based caching. In this type of caching Oracle9iAS Portal Caches various objects (pages, portlets, etc) for a set amount of time. When these objects are requested they are retrieved from the Cache, if available, otherwise they are regenerated from the Oracle9iAS Portal repository. The Cache for these objects will expire when the maxcache time has been reached, or when the objects are explicitly invalidated (expired) via invalidation messages.
Oracle9iAS Portal uses invalidation messages when it needs to expire objects in the Cache. invalidation messages are categorized as hard and soft invalidations. Hard invalidations take effect immediately, i.e. the objects which they intend to invalidate expire from Cache immediately. Soft invalidations take effect when they are processed by the invalidation processing job. The frequency by which the invalidation job executes is configurable. This is done via the cachjsub.sql
script. Follow the following steps to change the execution frequency of the invalidation processing job:
ORACLE_HOME/portal/admin/plsql/wwc
sqlplus portal/portal
SQL> @cachjsub.sql <start_time> <start_time_fmt> <interval_mins>
cachjsub.sql
takes three parameters:
Note: If 'START' is provided for 1st parameter, the 2nd parameter is ignored and it will default the start time to the current time.
Example1:
SQL> @cachjsub.sql START null 120
Example2:
SQL> @cachjsub.sql '02-22-2003 7:30' 'MM-DD-YYYY HH:MI' 1440
Oracle9iAS Portal needs to subscribe to OID, in order to be aware of any changes in OID data.
One of the steps in setting this up is running a tool named oidprovtool
. It will be located in:
ORACLE_HOME/bin
See also:
For the complete overview of what needs to be done to set up a subscription profile, refer to Section 2.7.1, "Setting up a Subscription Profile using oidprovtool". |
The following table contains the valid parameter values for running the oidprovtool for creating the subscription profiles as required by Oracle9iAS Portal.
Please note that the parameter values, or parts thereof, that are in italics, must be replaced by their value. All other parts, including quotation marks, must be entered as is in the call to oidprovtool. Thus using the above examples of values the complete call is as follows (please treat this as a single continuous line):
oidprovtool operation=create ldap_host=portaloid ldap_port=389 ldap_user_ dn=cn=orcladmin ldap_user_password=welcome1 application_ dn=orclApplicationCommonName=PORTAL,cn=Portal,cn=Products,cn=OracleContext organization_dn="dc=mycompany,dc=com" interface_name=PORTAL.WWSEC_OID_SYNC interface_type=PLSQL interface_connect_ info=portaldbhost:1521:s901dev8:PORTAL:portalpassword schedule=60 event_ subscription="USER:dc=mycompany,dc=com:DELETE" event_ subscription="GROUP:dc=mycompany,dc=com:DELETE" event_ subscription="USER:dc=mycompany,dc=com:MODIFY(orclDefaultProfileGroup,userpasswo rd)" event_subscription="GROUP:dc=mycompany,dc=com:MODIFY(uniqueMember)"
See also:
For a complete list of all the possible options for oidprovtool, refer to the Oracle Internet Directory Administrator's guide in the Oracle9i Application Server documentation library. |
As part of the process of validating the session cookie of a user's request (even if that user is PUBLIC) Portal performs a comparison between the IP address stored in the cookie with the IP address of the current client. Only if the two value are the same will Oracle9iAS Portal consider the request legitimate.
When a proxy exists between the user's client and the portal the IP address stored in the session cookie is that of the proxy, and not that of the client.
Some proxy systems make use of multiple servers each with different IP addresses. In these circumstances it is conceivable that the original request from a user's client (the request that causes the session cookie to be created) is routed through one proxy server and that a subsequent request is routed through another, separate, proxy server. In these cases, the IP addresses compared by Oracle9iAS Portal will differ and the request will raise a security violation during the IP checking step and access to the page will be denied.
Depending on the network configuration into which the Oracle9i Application Server is installed, it may be necessary to disable IP checking in cookie validation.
To change the state of IP checking in cookie validation, you need to use SQL*Plus to update data in both the portal schema and the SSO schema as detailed in the table below.
By default, Oracle9iAS Portal connects to OID using LDAP without SSL. If the OID server is configured for an SSL port, though, Oracle9iAS Portal can be configured to use LDAP over SSL, also known as LDAPS.
See Also:
Oracle Internet Directory Administrator's Guide for a detailed description on how to configure OID for an LDAPS port. |
To configure Oracle9iAS Portal to use SSL to connect to OID, you must run the secupoid.sql
script. This script allows you to change the following Oracle9iAS Portal configuration parameters related to OID:
When you install Oracle9iAS Portal, it is automatically the associated with an OID server. However, you may want to change some settings, such as whether to use SSL, after installation. To change to an SSL connection for OID, simply run the secupoid.sql script in the PORTAL schema to specify the LDAPS port instead of the LDAP port, and indicate that you want to use SSL.
The section that follows illustrates a sample execution of secupoid.sql
from SQL*Plus.
In the example, OID was initially configured to run LDAP on port 389. Later, an LDAPS port was activated on 636. Since the server name does not change, we retain the old value, update the port, and indicate that we want to use SSL by setting the Use SSL? value to Y. When you run the script, it displays the current configuration and lets you replace any of the configurable settings. The script also allows you to update Oracle9iAS Portal's OID Cache after running it. Since activating SSL does not change any of the OID information cached by Oracle9iAS Portal, it is not usually necessary to refresh the Cache in this case.
SQL> @secupoid Current Configuration -------------------- OID Host: oid.domain.com OID Port: 389 Application DN: orclApplicationCommonName=PORTAL,cn=Portal,cn=Products,cn=OracleContext Application Password: 3E8C2D1B87CB61011757239C5AA9B390 Use SSL? N PL/SQL procedure successfully completed. Updating OID Configuration Entries Press [Enter] to retain the current value for each parameter For SSL Connection to LDAP, specify "Y"es or "N"o ------------------------------------------------ Enter value for oid_host: Enter value for oid_port: 636 Enter value for app_password: Enter value for use_ssl_to_connect_to_ldap: Y Enter value for refresh_with_new_settings: N PL/SQL procedure successfully completed. No errors.
After executing the script, Oracle9iAS Portal is configured for LDAPS access of OID.
See also:
|
If you have your OID and Oracle9iAS Portal servers residing in different domains, you must explicitly set the JavaScript domain for Oracle9iAS Portal such that it can resolve user and group lists of values.
For example, suppose that your installation has Oracle9iAS Portal configured to use a different Oracle HTTP Server than DAS. In this situation, you need to have a common domain so that the values can be transferred from the list of values displayed by DAS to the page displayed by Oracle9iAS Portal.
To create a single domain in this case, do the following:
Performing this procedure enables you to run OID lists of values from Oracle9iAS Portal in either Netscape or MicroSoft Internet Explorer. When using lists of values, a transit window is displayed in addition to the list of values itself. The transit window is required to pass values to Oracle9iAS Portal without forcing pages to reset their domain.
See also:
Oracle9i Application Server Security Guide in the Oracle9i Application Server documentation library. |
In cases where you want access to the same portal from two middle-tiers at the same time, or if you want to open the portal cookie domain as required by the PL/SQL Adapter functionality you need to define the scope of the Oracle9iAS Portal session cookie to be sent to all the middle-tier servers involved in the architecture. By default, the session cookie is scoped to the host from which it was generated which is typically the root path.
For example, if the cookie was generated from www.oracle.com
, then the cookie domain is www.oracle.com
. However, let's say that another server, portal.oracle.com
is also a middle-tier server that needs to get access to that session cookie, then the cookie domain would need to be widened so that the portal.oracle.com
server can also see the cookie.
Follow these steps to modify the scope of the portal session cookie:
ORACLE_HOME/portal/admin/plsql/wwc
sqlplus nodea/nodea
SQL> @ctxckupd Oracle Portal Current Settings for Portal Session Cookie: Cookie Domain : Only send cookie back to originating host:port Enter the domain for the session cookie: .oracle.com Settings changed to Cookie Domain : .oracle.com SQL>
This allows you to set the cookie domain for the session cookie. In the example above, the cookie domain is set to .oracle.com
.
Oracle9iAS Portal and Oracle9iAS Single Sign-On Server perform session management similar to other web-based applications. Sessions are tracked using cookies. Session information is stored in a table in the Portal and Oracle9iAS Single Sign-On Server schema. When a user logs out, the session information is marked inactive. A DBMS job subsequently cleans up the inactive rows.
The session table accumulates a number of rows that are flagged as active. When a user shuts down the browser instead of logging out, the row is "active", even though it is not actually in use. The cleanup job cleans up the active rows that are older than a specified duration.
When Oracle9iAS Portal is installed, a DBMS job is installed to perform session cleanup of the session table, WWCTX_SSO_SESSION$
. The cleanup job is set to run every 24 hours. The first scheduled cleanup occurs 24 hours after the installation of the job.
When the job runs, it deletes all inactive sessions, and all sessions marked active (WWCTX_SSO_SESSION$.ACTIVE = 1
), that are older than 7 days (WWCTX_SSO_SESSION$.SESSION_START_TIME < sysdate - 7
).
These default settings can be modified by running some job management scripts in the Portal schema to manage Portal sessions, or in the Oracle9iAS Single Sign-On Server schema to manage Oracle9iAS Single Sign-On Server sessions. They utilize the same session management infrastructure.
Follow these steps to obtain the current cleanup job information:
ORACLE_HOME/portal/admin/plsql/wwc
sqlplus portal/portal
SQL> @ctxjget The session cleanup job is job ID 7381 dbms_job.isubmit(job=>7381,what=>'begin execute immediate''begin wwctx_sso.cleanup_sessions(p_hours_old => 168); end;''; exception when others then null; end;',next_date=>to_date('2001-04-17:14:07:20', 'YYYY-MM-DD:HH24:MI:SS'),interval=>'SYSDATE + 24/24',no_parse=>TRUE); PL/SQL procedure successfully completed.
The command results in the display of the currently installed job information, as returned by the DBMS_JOB package. It indicates which procedure is executed, what parameters are passed to it, and when the next invocation is to occur. This particular example indicates that the job is to cleanup active sessions which are a week old (168 hours). It also indicates that the next scheduled job execution is on 4/17/2001 at 5:14 pm, and the job should run every 24 hours thereafter.
If the job execution needs to be modified, either to adjust the age of sessions that should be deleted, or to increase or decrease the frequency of cleanup, you can run the ctxjsub.sql
script to submit modified execution parameters.
Follow these steps to submit modified job execution parameters:
ORACLE_HOME/portal/admin/plsql/wwc
sqlplus portal/portal
@ctxjsub <hours_old> <start_time> <time_format> <interval_hours>
Table B-5 lists the ctxjsub
parameters.
For example:
SQL> @ctxjsub 200 '04/17/2001 10:00' 'MM/DD/YYYY HH24:MI' 12 Created path for job id. DBMS_JOB id = 7381 Cleanup job updated. Job ID = 7381 PL/SQL procedure successfully completed.
The cleanup job submission script can be run any number of times to modify the execution parameters. Each invocation updates the job information associated with the job ID for the cleanup job. This job ID is maintained in the preference store so that the job information is updated instead of submitting multiple jobs.
You can also specify a start_time
of 'START', in which case, the time_format
parameter is ignored, but you still need to pass it a value (such as 'NOW'). The result is to run the job <interval_hours>
hours from now:
SQL> @ctxjsub 168 START NOW 24
This submits the job as it does in the installation.
If you want the cleanup job to execute immediately, then obtain the job ID by calling ctxjget.sql
. Once you know the job ID, you can execute the job by issuing the following command in the product schema:
SQL> exec dbms_job.run(7381);
In the preceding example, 7381 is the job ID returned by the call to ctxjget.sql
. When you execute a job in this manner, the next automated invocation of the job occurs at interval_hours
after this manual invocation. To run the job on the original schedule, you need to resubmit the start_time
desired using ctxjsub.sql
.
All Oracle9iAS Portal pages can be run in a special mode in which timing and caching information is displayed. If you want to see this debug information on every page you can set the Parallel Page Engine Parameter showPageDebug to true in the web.xml file.
See also:
Section 6.2.1.1, "Setting PPE Configuration Parameters" for information on how to configure the PPE settings. |
If you just want to see the debug information for a few select pages and portlets, you can run a page with this debugging information enabled by adding "&_debug=0
", or "&_debug=1
" to the end of the Oracle9iAS Portal page url. For example if you want to see the timing statistics for the page http://abc.com/servlet/page?_pageid=21
, you would append an ampersand (&) and "_debug=0"
, or "_debug=1"
to the page url like this:
http://abc.com/servlet/page?_pageid=21&_debug=0
or:
http://abc.com/servlet/page?_pageid=21&_debug=1
The difference between "&_debug=0" and "&_debug=1" is that with the first option, the debug=0 parameter is not passed to either the portlets or the page meta data. The Cache statistics are therefore reflected in the most accurate way. In the second option, "&_debug=1", the parameter debug=1 is passed through to the portlet itself, which can affect the caching information. Since the parameter is passed to the portlets, it can be used by the portlet developers to display portlet-specific debugging information. For instance if you had a portlet, and you wanted to know how long a particular query takes, or if you wanted to debug a specific issue, you could write some debugging code to print data to the browser when the debug=1 parameter is passed in.
The following statistics are available when the portal page is run in debug mode:
The following image shows a page that is running in the "_debug=0" mode:
In the above example you can see a number of Portlet related statistics listed under each portlet. Each Portlet has a unique internal reference identification number. This number is used in the "Information for Portlet" summary. For the portlet in the top left corner of the above image you can see that this number is 6256.
For each portlet the following statistics are listed:
Indicates how many milli-seconds to retrieve the portlet, and how long the request was queued, also in milli-seconds.
This is deprecated and no longer in use.
Displays the number of milli-seconds needed to retrieve the XSL stylesheet, in case the portlet is an XML portlet.
This is the Cache status from both Oracle9iAS Web Cache and the modplsql file Cache.
Valid values for Oracle9iAS Web Cache are:
Valid values for File System Cache are:
If a portlet uses the File System Cache, then the above information will be listed. Otherwise it will be null.
If there is a hit on Oracle9iAS Web Cache, no details about File System Cache will be displayed as the content is served directly out of Oracle9iAS Web Cache. Additionally, if a portlet does not use Oracle9iAS Web Cache, then no Web Cache information will be printed.
Information from both Oracle9iAS Web Cache and File System Cache will be printed here based on the type of caching that the portlet uses.
See also:
Oracle9iAS Web Cache Administration and Deployment Guide in the Oracle9i Application Server documentation library. |
"Cache Expires" lists the number of seconds after which the portlet content in Oracle9iAS Web Cache will expire.
"Age in Cache" lists the number of seconds that the portlet content has been Cached in Oracle9iAS Web Cache.
"File System Cache" displays the information obtained from the File System Cache about Cache key, Cache expiry and about the Cache level in case of a Cache hit, with the Cache Status of either HIT_PING, or HIT_EXPIRES.
In case of a Cache hit, the Cache key and Cache level (for Validation based portlets) and Cache Expires and Cache Level (for expiry based portlets) are displayed, with the Cache Status value of either HIT_PING or HIT_EXPIRES.
For Validation and Expires based portlets, "None" is printed, when there is a Cache miss due to the portlet content being new. (Cache Status: MISS_NEW) The portlet is contacted to get the new Cache key, Cache expiry and Cache level.
For Validation based portlets, if the content in the Cache has become stale resulting in a Cache miss, the current values in the Cache for Cache key and Cache level are displayed. In this case the portlet is contacted to get the updated Cache key and the level (Cache Status: MISS_STALE).
For Expires based portlets, when the content in the Cache has become stale resulting in a Cache miss, a value of "INVALID" in the expires field and Cache level are displayed. In this case the portlet is contacted to get the updated Cache Expiry and Cache level (Cache Status: MISS_STALE).
This is the information obtained from the portlet about File System Cache Key Cache Expiry and Cache Level when there is a Cache miss and when portlet is contacted for the updated, or new values (Cache Status: MISS_NEW, or MISS_STALE). Note that there is no Oracle9iAS Web Cache related information displayed in this section.
For Validation based portlets, when there is a Cache hit and if the ping is successful, meaning the content in the Cache is still valid, then the portlet does not return a new Cache key and level, instead it will indicate that the Cache is still valid. In this case, "Ping Success" is displayed (Cache Status: HIT_PING).
For Expires based portlets, when there is a Cache hit and if the content has not expired, then the portlet is not contacted for the content. In this case, "Not contacted" is displayed (Cache Status: HIT_EXPIRES).
Following are a few examples that show different Caching scenarios and the resulting output. Note that the other Page and Portlet related output is not shown here.
Example Caching Information Debug Output 1
Caching information for portlet: Portlet Cache status: File System Cache:- MISS,STALE From Cache: File System Cache:- Cache Key: 42, Cache Level: USER From Portlet: Cache Key: 44, Cache Level: USER
Example Caching Information Debug Output 2
Caching information for portlet: Portlet Cache status:File System Cache:- MISS,NEW From Cache: File System Cache:-None From Portlet: Cache Expires: 1, Cache Level: USER
Example Caching Information Debug Output 3
Caching information for portlet: Portlet Cache status: Web Cache:- MISS,NEW [M], File System Cache:- MISS,NEW From Cache: Web Cache:- Cache Expires: 86400 secs, Age in Cache: 0 secs , File System Cache:- None From Portlet: Cache Key: 9.0.2.2.1502:04:18:09:19:56, Cache Level: SYSTEM
Example Caching Information Debug Output 4
Every page has a unique internal reference identification number, similar to the portlets on the page, shown in the image above.
For the page the following statistics are listed:
This is the total amount of time required to generate the page calculated in the Parallel Page Engine (PPE). The actual generation time in the browser can be higher, due to network overhead.
Elapsed time is made up of Page meta WAIT time and Stream time. Page meta WAIT time is the time taken to wait on content via an HTTP connection. Stream time is the time taken streaming and assembling the content pieces. Stream time is in turn composed of the following elements:
Effectively, elapsed time is the total amount of time (in milli-seconds), that it takes to put the page together, from the time the request was received to the last byte being written to the browser.
Displays the time that it takes to retrieve the page meta data. The wait time (msecs) represents how long the request was queued.
Represents the Cache status from both Oracle9iAS Web Cache and modplsql file Cache. Valid values for Oracle9iAS Web Cache are MISS, or NEW and HIT. Valid values for file Cache are HIT, or PING, and MISS, or STALE. The Web Cache Expires value and the Age in Cache are both measured in milli-seconds.
Displays the time (in milli-seconds) that it takes to retrieve the login meta data. The wait time represents the total amount of time (in milli-seconds) that the request spend in the request queue.
Similar to Page meta Cache status above, represents the Cache status for the login meta data from both Web Cache and modplsql file Cache.
Represents (in milli-seconds) how long it takes for the page to stream to the browser.
Processing time (in milli-seconds) for streaming.
The write lines can repeat several times. The lines represent each physical buffer write to the stream itself. This are one set for each buffer write.
The flush logs indicate that the writing stream was flushed. this is logged to keep track of the number of network round trips.
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|