B
Oracle Portal Installation and Configuration Scripts

After installing Oracle Portal with the Oracle9i Application Server installation, several scripts are made available for post-installation configuration. For example, you may want to customize the configuration and install additional components, such as a standalone Login Server, additional Oracle Portal nodes, or load additional language translations into Oracle Portal.

Specific topics covered include:

• Overview

• Manually Installing Oracle Portal with the winstall Script

• Manually Installing a Login Server with the linstall Script

• Configuring a New Oracle Portal Instance and Login Server with the ssodatan Script

• Updating an Existing Portal Instance with the ssodatax Script

• Modifying the Scope of the Portal Session Cookie

See: For information about the Oracle Portal import and export scripts, see the "Exporting and importing in Oracle Portal" topic in the Oracle Portal Online Help Content Area. For information about Oracle Portal upgrade scripts, visit: http://technet.oracle.com/support/products/iportal/listing.htm

B.1 Overview

For purposes of configuring Oracle Portal, the following scripts are useful, and are described in this appendix:

Table B-1 Oracle Portal installation scripts

Script	Description
winstall	This script allows you to perform a manual installation of Oracle Portal. If you already have a Login Server installed, install a single portal node without having to install another Login Server. See "Manually Installing Oracle Portal with the winstall Script".
linstall	This script allows you to perform a manual installation of a standalone Login Server, without a corresponding Oracle Portal installation. See "Manually Installing a Login Server with the linstall Script".
ssodatan	This script is responsible for setting up the configuration information associated with a newly-installed Oracle Portal node with a Login Server. Run this script on a newly-installed host in which the Login Server and Oracle Portal are on the same database instance and are being setup for the first time. See "Configuring a New Oracle Portal Instance and Login Server with the ssodatan Script".
ssodatax	This script is responsible for setting up the configuration information associated with an Oracle Portal node with a Login Server. This script is also used to add configuration entries to support server aliases or virtual host names. A different partner configuration entry is required for each alias to be used. This script must also be used in any instance when the Oracle Portal node is on a separate database instance from the Login Server. "Updating an Existing Portal Instance with the ssodatax Script".

Note: These scripts are located in the following directory upon installation: <ORACLE_HOME>/portal30/admin/plsql/

B.2 Manually Installing Oracle Portal with the winstall Script

You can perform a manual installation of Oracle Portal by running the winstall script or create a Login Server for the Oracle Portal by invoking this script.

Note: A manual installation of Oracle Portal completes in 1 1/2 - 3 hours.

Follow these steps to manually install Oracle Portal:

1. Make sure that your Oracle8i database is up and running.

2. Verify that the Net8 listener is running by issuing the following command:

   lsnrctl start listener
   
   

3. Ensure that all your ORCL database environment variables are set accordingly. Refer to Chapter 1, "System Requirements".

   Ensure that your ORCL <ORACLE_HOME>/bin is set in the PATH variable before any other ORACLE_HOME. Otherwise, you may encounter LoadJava or JDBC type errors.

4. Ensure you have a working TNS Alias that points to your ORCL database. Test your connection with SQL*Plus.

5. Ensure that your ORCL <ORACLE_HOME>/bin/loadjava works correctly. Type loadjava -help to test it and display the help usage messages.

6. (optional) If you successfully installed a previous Oracle Portal schema into this database either using the OUI or manually, skip this step.

   Otherwise, change the directory to the following to run the following onetime script:

   <ORACLE_HOME>/portal30/admin/plsql 
   
   

   In a command box, run the onetime script file to install the necessary Oracle Portal packages as follows:

   onetime [-p sys_password] [-l logfile] [-c connect_string]
   
   

Example

onetime -p change_on_install -l onetime.log -c orcl

Note: Run this command once for each database where you want to install Oracle Portal. Ignore any ORA messages about dropping objects that do not exist.

In a command box, run the Oracle Portal installation script, winstall, from the following location to install the Oracle Portal product.

<ORACLE_HOME>/portal30/admin/plsql 

Run the Oracle Portal installation script parameters as follows:

Syntax - Usage 1

winstall <-s portal_schema> <-p sys_password> <-u default_tablespace> 
<-t temporary_tablespace> <-d document_tablespace> <-l logging_tablespace> 
<-w workflow_schema> <-o sso_schema> <-i pstore_password> <-r random_seed> 
<-c connect_string> 

Syntax - Usage 2

winstall list_tablespaces [sys_password] [connect_string] 

Syntax - Usage 3

winstall uninstall sys_password portal_schema [sso_schema][connect_string] 

Example

winstall -s portal30 -p change_on_install -u users -t temp -d users -l users 
-o portal30_sso -i portal30_sso_ps -r 12345 -c orcl > winstall.log

The parameter descriptions are provided in the winstall file which opens with any text editor. All arguments are validated before the installation starts.

By default, five schemas are created: portal30, portal30_sso, portal30_sso_public, portal30_public, portal30_demo. The default base schema name and password is portal30 which you can change at installation time. For more information, see "Default Schemas Created".

Install an Oracle Portal node without an associated Login Server by invoking winstall with the following usage:

winstall -s newportalnode -nosso

In the above example, executing this command installs an Oracle Portal node in a schema named newportalnode without loading an associated Login Server schema. Usage of this command is useful for installing nodes for a distributed Oracle Portal installation as discussed in Chapter 4.

Check the installation session log that describes the actions performed and the components created upon installation. GREP the log file for "ORA-" , "PLS-" , and "ERROR:" that may have occurred during installation. The log file is located in:

<ORACLE_HOME>/assistants/opca/install.log

Note: If you need to abort or re-run the winstall script in case of failure, fist drop all Oracle Portal schemas that were created using SQL*Plus. For example, enter: SQLPLUS > drop user <schema> cascade; You might need to stop and restart the database to release any defunct or runaway database processes that are locking your Oracle Portal schema before re-running winstall.

Proceed with the next step only if you successfully ran the winstall script and Oracle Portal was installed properly.

If you install an Oracle Portal node with the winstall script, you need to run the ssodatan script afterwards to establish the linkage between the Portal node and the Login Server.

However, if the installation of the Oracle Portal node does not include the Login Server, or you are linking to an existing Login Server, then run the ssodatax script to perform the linkage. See "Updating an Existing Portal Instance with the ssodatax Script".

In a command box, run the ssodatan script from this location:

<ORACLE_HOME>/portal30/admin/plsql  

This script configures your Single Sign-On (SSO) login via the Login Server, which is installed as part of Oracle Portal.

For example, if your settings are as follows:

DAD              = simpledad  
;(from <ORACLE_HOME>/Apache/modplsql/cfg/wdbsvr.app ) 
SSO DAD           = ssodad     
;(from <ORACLE_HOME>/Apache/modplsql/cfg/wdbsvr.app ) 
Portal schema     = portal30 
Host name         = myhost 
IAS/Apache port   = 7777 
TNS Alias         = ORCL 

You would run the ssodatan script as follows in one continuous line. If you use port 80, then omit the colon ':' and the port number altogether:

Also, the hostname must match the ServerName parameter in your <ORACLE_HOME>/Apache/Apache/conf/httpd.conf file.

./ssodatan -w http://hostname:7777/pls/simpledad/ -l 
http://hostname:7777/pls/ssodad/ -s portal30 -o portal30_sso -c orcl > 
ssodatan.log 

This script completes in a few seconds. Verify that there were no "ORA-" or "PLS-" type errors in your ssodatan.log file. If there were such errors, make sure you correct these before re-running the ssodatan script.

See also: Appendix A, "Oracle HTTP Server Configuration File (httpd.conf)". Section B.4, "Configuring a New Oracle Portal Instance and Login Server with the ssodatan Script".

10. Go to the <ORACLE_HOME>/Apache/modplsql/cfg directory.

11. Create a backup copy of the PL/SQL Gateway configuration file, wdbsvr.app.

12. Edit the wdbsvr.app file by removing all existing entries, and then adding these initial settings (using the example values):

    ; 
    [WVGATEWAY] 
    defaultDAD      = simpledad 
    administrators  = all 
    adminPath       = /admin_/ 
    ;upload_as_long_raw = 
    ;upload_as_blob = 
    ;debugModules   = 
    ; 
    [DAD_simpledad] 
    connect_string  =  orcl 
    password    =  portal30 
    username    =  portal30 
    default_page    =  portal30.home 
    document_table  =  portal30.wwdoc_document 
    document_path   =  docs 
    document_proc   =  portal30.wwdoc_process.process_download 
    upload_as_long_raw   = 
    upload_as_blob       = * 
    reuse       =  Yes 
    connmax     = 10 
    enablesso   = Yes 
    pathalias   = url 
    pathaliasproc   = portal30.wwpth_api_alias.process_download 
    ;name_prefix   = 
    ;always_describe   = 
    ;after_proc   = 
    ;before_proc   = 
    ; 
    [DAD_ssodad] 
    connect_string   =  orcl 
    password   =  portal30_sso 
    username   =  portal30_sso 
    default_page   =  portal30_sso.wwsso_home.home 
    document_table =  portal30_sso.wwdoc_document 
    document_path  =  docs 
    document_proc  =  portal30_sso.wwdoc_process.process_download 
    upload_as_long_raw  = 
    upload_as_blob      = * 
    reuse     =  Yes 
    connmax   = 10 
    enablesso = Yes 
    pathalias = url 
    pathaliasproc  = portal30_sso.wwpth_api_alias.process_download 
    ;name_prefix   = 
    ;always_describe = 
    ;after_proc   = 
    ;before_proc   = 
    ; 
      
    

13. Stop and restart the Oracle HTTP Server powered by Apache with the following commands:

• <ORACLE_HOME>/Apache/Apache/bin/apachectl stop

• <ORACLE_HOME>/Apache/Apache/bin/apachectl start

with Secure Sockets Layer, the start command is:

• <ORACLE_HOME>/Apache/Apache/bin/apachectl startssl

Note: Access the Gateway Configuration Menu page by pointing your browser to the following location: http://hostname:7777/pls/simpledad/admin_/gateway.htm See also: "Starting and Stopping the Oracle HTTP Server powered by Apache"

B.2.1 Manually Installing Online Help

The Oracle Portal Online Help Content Area contains conceptual, getting started, step-by-step, and troubleshooting Help topics. If you've manually installed Oracle Portal, choose to install the Oracle Portal online help.

In the <ORACLE_HOME>/portal30/admin/plsql/wwu directory, run the following script (in one continuous line):

Syntax

./contimp.csh -s portal30 -p portal30 -o portal_help -m reuse -u 
database_user  -d ../../../doc/site/hlp30ca.dmp -c orcl 

Notes: Enter the "-o", "-m", "-u" , "-d" static values. Change the "-s" , "-p", "-c" options as appropriate to your environment.

This process takes about three minutes to complete. Ignore the following messages after the script is run:

security.dmp: No such file or directory
pobpage.dmp: No such file or directory
Unable to set user acl for:

See also: For additional information, see the appropriate manual installation document at: http://technet.oracle.com/docs/products/iportal/ listing.htm

B.3 Manually Installing a Login Server with the linstall Script

To install an instance of the Login Server which resides in a database instance without an associated Oracle Portal, execute the linstall script.

This script installs the Login Server schema and also automatically sets the configuration information that registers the Login Server application as a Partner Application to the Login Server itself.

Syntax

linstall <-o sso_schema> <-i pstore_password> <-s login_server_url> <-r random_
seed> <-p sys_password> <-u default_tablespace> <-t temporary_tablespace> <-d 
document_tablespace> <-l logging_tablespace> <-c connect_string> 

Example

linstall -o portal30_sso -i portal30_sso_ps -s
http://server.oracle.com:3000/pls/portal30_sso/ -r 12345 -p change_on_install 
-u users -t temp -d users -l users -c orcl

where

Table B-2 linstall script parameters

Parameter	Description
-o sso_schema	Oracle database schema containing the Login Server installation (database objects). Default = portal30_sso
- i pstore_password	The password for the password store. The password store schema name is <sso_schema>_PS.
-s login_server_url	URL that points to the Login Server host and DAD. Include the full domain name with the host, http:// prefix in your URL, and end the URL with a forward slash (/). Note: If you are not using the default port number (for example, 443), specify it in the Login Server URL.
-r random_seed	Optional specification of a random string to be used to seed the random number generator for initializing encryption keys.
-p sys_password	Oracle database password for the SYS schema. Default = change_on_install
-u default_tablespace	Default = USERS
-t temporary_tablespace	Default = TEMP
-d document_tablespace	Default = <default_tablespace>
-l logging_tablespace	Default = <default_tablespace>
-c connect_string	Optional connect string to a remote database.
-casesensitive	Enforce case-sensitivity on passwords.

B.4 Configuring a New Oracle Portal Instance and Login Server with the ssodatan Script

The ssodatan script sets up a fresh Oracle Portal and a new Login Server. Running this script completely removes any pre-existing configuration information in the Login Server configuration and replaces it with the information specified in the most recent invocation of this script.

Alternatively, if you are associating a Portal node with an existing Login Server that contains configuration information you want to retain, do not use this script. Instead, invoke the ssodatax script which is described in the next section, "Updating an Existing Portal Instance with the ssodatax Script".

The ssodatan script can only be used on an Oracle Portal and Login Server which reside on the same database instance. If you are setting up a configuration with separate database instances for the Portal and the Login Server, then use a combination of the linstall and ssodatax script to set this up.

In the case of the single instance, where you want to associate a fresh association of Oracle Portal with Login Server, invoke the ssodatan script as follows:

Syntax (full usage)

ssodatan <-w portal_url> <-l login_server_url> <-s portal_schema> <-p portal_
password> <-o sso_schema> <-d sso_password> <-e pstore_schema> <-c portal_
connect_string> 

Syntax (Login Server only)

ssodatan -loginserver <-l login_server_url> <-o sso_schema> <-d sso_password> 
<-c portal_connect_string>

Example (full usage)

ssodatan -w http://webdbsvr.us.oracle.com:3000/pls/portal/ -l 
http://webdbsvr.us.oracle.com:3000/pls/portal_sso/ -s portal30 -p portal30 -o 
portal30_sso -d portal30_sso -e portal30_sso_ps -c orcl 

Example (skip optional parameters)

ssodatan -w http://webdbsvr.us.oracle.com:3000/pls/portal/ -l 
http://webdbsvr.us.oracle.com:3000/pls/portal_sso/ -s portal30 

Example (standalone Login Server)

ssodatan -loginserver -l http://webdbsvr.us.oracle.com:3000/pls/portal_sso/ -o 
portal30_sso -d portal30_sso -c orcl 

Note: This shell script installs the appropriate seed data to set up a connection between Oracle Portal and a newly installed Login Server in SQL*Plus.

where

Table B-3 ssodatan script parameters

Parameter	Description
-w portal_url	URL that points to the Oracle Portal node DAD. Include the full domain name with the host, http:// prefix in your URL, and end the URL with a forward slash (/). Note: If you are not using the default port number (for example, 80), specify it in the Oracle Portal URL.
-l login_server_url	URL that points to the Login Server host and DAD. Include the full domain name with the host, http:// prefix in your URL, and end the URL with a forward slash (/). Note: If you are not using the default port number (for example, 443), specify it in the Login Server URL.
-s portal_schema	Oracle database schema containing the Oracle Portal installation (database objects). Default = portal30
-p portal_password	Oracle database password for the Oracle Portal schema. Default = <portal_schema>
-o sso_schema	Oracle database schema for Login Server objects. Default = <portal_schema>_SSO
-d sso_password	Oracle database password for Login Server schema. Default = <sso_schema>
-e pstore_schema	Oracle database password for access to password store objects.
<-c portal_connect_string>	Connect string for the database in which the Oracle Portal schema is installed. You need to provide the connect string only if the Oracle Portal schema is located on a remote database. Default = null
-loginserver	Sets up the enabler configuration entry for the standalone Login Server. Do not use the -w, -s, -p, and -e options with this parameter.

Warning: If you are using port 80, which is the default HTTP port number, do not include the port number in the Portal URL prefix or the Login Server URL prefix. Also, do not specify the port in the URL that is used to access the Web site since some browsers exclude the port in the URL if it is the default port, resulting in a problem selecting the appropriate enabler configuration entry.

B.5 Updating an Existing Portal Instance with the ssodatax Script

The ssodatax script updates the Partner Application's enabler configuration table, WWSSO_PAPP_CONFIGURATION_INFO$. However, before running this script, first update the Login Server's Partner Application configuration table to create the entries on the Login Server side in the following way:

1. Click
   Text description of the illustration home.gif to navigate to the Oracle Portal Home Page.

2. Click the Administer tab.

3. In the Services portlet, click Login Server Administration.

4. Click Administer Partner Applications.

5. Click Add Partner Application.

6. In the Partner Application Login section, enter the Partner Application's name, the URL to the application's home page, and a success URL.

7. In the Valid Login Timeframe section, enter the dates when users can log on to the application through the Login Server. If you leave the End Date field blank, users can log on to the application indefinitely. In the Application Administrator section, enter an e-mail address and other information for the application's contact person or administrator.

8. Click OK.

The new Partner Application appears in the Edit/Delete Partner Application list on the Partner Application page. After adding a Partner Application entry on the Login Server, the Login Server generates a site id, site token, and encryption key for the new Partner Application. These are used as input when invoking the ssodatax script.

In the case where you want to add or update entries in the enabler configuration table, invoke the ssodatax script as follows:

Syntax (full usage)

ssodatax <-i portal_site_id> <-t portal_site_token> <-k encryption_key> <-w 
portal_url> <-l login_server_url> <-s portal_schema> <-p portal_password> <-v 
cookie_version> <-o sso_schema> <-e pstore_schema> <-r pstore_password> <-b 
pstore_dblink> <-c connect_string> <-n ps_connect_string> 

Syntax (remove enabler configuration entry)

ssodatax <-s portal_schema> <-p portal_password> <-remove portal_host> <-b 
pstore_dblink> <-c connect_string> 

Example (full usage)

ssodatax -i 1234 -t A1B2C3 -k X9Y8Z7 -w 
http://webdbsvr.us.oracle.com:3000/pls/portal30/ -l 
http://webdbsvr.us.oracle.com:3000/pls/portal30_sso/ -s portal30 -p portal30 -v 
v1.1 -o portal30_sso -e portal30_sso_ps -r portal30_sso_ps -b portal30_dblink -c 
orcl -n orcl01 

Example (skip optional parameters)

ssodatax -i 1234 -t A1B2C3 -k X9Y8Z7 -w 
http://webdbsvr.us.oracle.com:3000/pls/portal30/ -l 
http://webdbsvr.us.oracle.com:3000/pls/portal30_sso/ -s portal30 

Example (deletion)

ssodatax -s portal30 -remove webdbsvr.us.oracle.com:3000 -b portal30_dblink 

where

Table B-4 ssodatax script parameters

Parameter	Description
-i portal_site_id	The ID is automatically set when a Partner Application (in this case, Oracle Portal installation) is added. It is used by the Login Server to identify the Partner Application to this node.
-t portal_site_token	The token is automatically set when a Partner Application (in this case, Oracle Portal installation) is added. It is used by the Login Server to identify the Partner Application. The Partner Application must use the application token to identify itself to the Login Server to this node when requesting authentication.
-k encryption_key	When a user tries to log on to this Oracle Portal node using Single Sign-On, the Login Server generates a cookie that indicates a user's identity and whether the user has been authenticated. This key encrypts the login cookie.
-w portal_url	URL prefix to this Oracle Portal node and the DAD being accessed. Include the full domain name with the host, http:// prefix in your URL, and end the URL with a forward slash (/).
-l login_server_url	URL prefix to the Login Server host and DAD. Include the full domain name with the host, http:// prefix in your URL, and end the URL with a forward slash (/).
-s portal_schema	Oracle database schema containing the Oracle Portal installation (database objects). Default = portal30
-p portal_password	Oracle database password for the Oracle Portal schema. Default = <portal_schema>
-v cookie_version	Cookie version being used by the Login Server." Default = v1.0
-o sso_schema	Oracle database schema for Login Server objects. Default = <portal_schema>_SSO
-e pstore_schema	Oracle database schema for access to Password Store objects. Default = <sso_schema>_PS
-r pstore_password	Oracle database password for Password Store access schema. Default = <pstore_schema>
-b pstore_dblink	Name of the database link for connecting from the Oracle Portal schema to the Password Store access schema across database instances. Default = <portal_schema>_DBLINK
-c connect_string	Connect string for the database in which the Oracle Portal schema is installed. Provide the connect string only if the Oracle Portal schema is located on a remote database. Default = null
-n ps_connect_string	Connect string to connect to the Password Store access schema on a remote database. Default = null
-remove portal_host	Removes the enabler configuration entry associated with the specified portal host.

The ssodatax script removes entries from the enabler table with the -remove option. When you use this option, the following parameters are applicable:

• -s portal schema

• -p portal_password

• - remove portal_host

  The portal_host is the value of the lsnr_token to remove from the enabler table.

• -c connect_string

See also: If you have any problems starting Oracle Portal, see Chapter 9, "Troubleshooting" or run the diagnostics tool.

B.6 Modifying the Scope of the Portal Session Cookie

In cases where you want to install a distributed Oracle Portal environment, and you need to have more than one distinctly named middle-tier server, you need to define the scope of the Oracle 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:

1. Locate the following directory:

   <ORACLE_HOME>/portal30/admin/plsql/wwc 
   
   

2. On the database where your Login Server schema is installed, log on to SQL*Plus with the appropriate username and password. For example:

   sqlplus nodea/nodea
   
   

3. Enter the following command as follows:

   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.

   Tip: If you want to use different listeners or keep the session cookie throughout different domains, specify a Cookie Domain to be the host name only. For example, if you access Oracle Portal from two machines: machine1.us.oracle.com:3000 machine2.us.oracle.com:4000 When running ctxckupd.sql, set the cookie domain to .us.oracle.com.

See: "Step 2: Create Same Cookie Domain"