5 Setting Up a Domain

This chapter describes how to set up an Oracle Communications Service Broker domain.

About Domain Setup

Whether a domain is a signaling domain, a processing domain, or a unified domain, setting up a domain includes:

Considering the domain configuration directory. See "Domain Configuration Considerations" for more information.
Installing the domain servers and a single instance of the Administration Console.
Creating the domain
Starting the domain Web server
Starting the Administration Console
Adding servers to the domain
Deploying a distributed cluster
Configuring data storage
Starting the domain servers

Domain Configuration Considerations

A domain has an associated domain configuration, which is stored in a domain configuration directory. All configuration data and OSGi software bundles are located in the domain configuration directory. See "Understanding the Domain-Based Administration Model" for more information about the domain configuration directory.

The domain configuration directory is referred to as domain_home in this document. The domain configuration directory needs to be accessible to the Administration Console and all servers in the domain.

The Administration Console requires read and write access to the domain configurations. The servers require only read access to the domain configurations.

The Administration Console and the domain servers can access the domain configuration directory on a shared file system or, for a hosted domain, using a Web server that serves the files:

If you use the shared file-system, set up all servers so that they can access the domain configuration directory.
If you use a Web server to serve the domain files, set up the Web server with read access to the domain configuration directory and map the directory to a URL.

The domain configuration directory is created only when you run the domain creation script and create the domain. You specify the manner of access when creating the domain (as described in "Creating the Domain").

For general information about sharing or hosting files, refer to your operating system or Web server documentation.

Installing the Administration Console and Domain Servers

The Service Broker installation process installs the software of a domain server and the Administration Console. See "About the Service Broker Installer" for more information.

The Administration Console can be installed and run from any host that has access to the other domain servers and to the domain configuration directory.

Because the domain configuration directory is independent of the Administration Console instance used to access it, you can have as many Administration Consoles installed as you wish. Run the installer on each host where you want to run the standalone Administration Console or the Web Administration Console server. Note however that only one Administration Console can manage a specific domain at any given time. Running multiple instances of the Administration Console that access the same domain simultaneously will result in an error.

You run the installation process to install the Administration Console and a single server instance. To install more server instances, run the installer again for each server that you want to add.

If you install multiple server instances on the same physical host, do not run the installer multiple times, because this will install multiple instances of the Administration Console on the same host as well. While having multiple Administration Console instances installed in a domain does not interfere with the system, they are unneeded. Instead, run the installer once and then copy the contents of the managed_server directory to a new directory for each server you want to add.

To create multiple servers on a single physical host:

Run the installer on the physical host. See "Installing the Software" for instructions.

The default installed Administration Console directory is:

Oracle_home/ocsb60/admin_console

The default installed server directory is:

Oracle_home/ocsb60/managed_server
Create a new server directory for each additional server.

To simplify your directory structure, you may choose to create the directories alongside the existing server directory in an existing Oracle home. For example:

Oracle_home/ocsb60/new_server_directory
Copy the contents of the installed server directory to each new server directory that you added.

To create additional servers on another host repeat this procedure on a different host.

At a later stage, after creating the domain and starting the Administration Console, you will have to define each server in the domain configuration by specifying its name and listening ports. See "Adding a Server to the Domain" for more information.

Table 5-1 and other tables in the following sections illustrate a sample domain with four servers. Table 5-1 outlines the directory structure for the components of the example domain.

Table 5-1 Example Directory Structure for Multiple Servers on a Single Physical Host

Physical Host	Directory Path	Description
sb_01	oracle_home`/ocsb60/admin_console`	Administration Console
sb_01	oracle_home`/ocsb60/managed_server`	Default server installation directory Use as the source when creating the directories for the new servers on the sb_01 host.
sb_01	oracle_home`/ocsb60/managed_1`	First server instance directory
sb_01	oracle_home`/ocsb60/managed_2`	Second server instance directory
sb_02	oracle_home`/ocsb60/admin_console`	Administration Console
sb_02	oracle_home`/ocsb60/managed_server`	Default server installation directory Use as the source when creating the directories for the new servers on the sb_01 host.
sb_02	oracle_home`/ocsb60/managed_3`	Third server instance directory
sb_02	oracle_home`/ocsb60/managed_4`	Fourth server instance directory

After installing the domain servers and Administration Console you can move on to the next step which is creating a domain.

Creating the Domain

By now, you have installed the domain servers and Administration Console, but you did not define them as a related group of servers.

Creating the domain generates the domain configuration directory that contains the server configuration settings and artifacts that the domain servers run. When you start a server, you pass it the domain archive file. This file controls all aspects of the server's operating behavior.

The contents of the domain reflect a specific Service Broker product type, such as Service Controller, Policy Controller, or VPN. When you create a domain, you are prompted for the product type of the domain. Only those products types that have been specifically installed in a given Oracle home are available. See "Installing the Software" for more information.

Domain types reflect the role that servers will perform in the domain. See "Understanding the Domain-Based Administration Model" for information about domain types.

Servers can access the contents of a domain configuration directory in the following ways:

Through the local or shared file system
Through a Web server that hosts the domain configuration files

You choose the access mode when creating the domain. For most deployments, file system access to the domain configuration is sufficient. However, you may choose to use hosted access if your local network topology requires it.

The following instructions assume the use of file system access mode. For more information on hosted domain access, see Oracle Communications Service Broker System Administrator's Guide.

Securing the Domain

The domain creation script creates domains based on the settings in property files in the Administration Console directory. By default, the setting that controls security in the domain is enabled. This setting applies to the connections between components in the domain; that is, between the Administration Console and servers.

Before you run the script, you must either disable the setting or, if you want to retain security for the domain, set up the client and server certificate keystores on the host system.

For a non-production system intended for test, instructional, or evaluation purposes only, you may choose to disable security between the components, as follows:

Open the following document for editing:

Oracle_home/ocsb60/admin_console/properties/common.properties
Set the axia.ssl property to false:

axia.ssl=false

For more information on the properties in the file, see Oracle Communications Service Broker System Administrator's Guide.
Save and close the file.

For information on setting up a secure domain, see the discussion on configuring security between Service Broker components in Oracle Communications Service Broker System Administrator's Guide.

Creating the Domain in Interactive Mode

The following instructions describe how to create a domain using the domain creation script.

If you kept SSL security enabled, you must create the client and server security keystores on the target system before attempting to run the domain creation script. Otherwise, the domain creation script will not complete successfully. See "Securing the Domain" for information about disabling SSL security.

The domain creation script can operate interactively or in silent mode. The following instructions describe how to use the script interactively. See "Creating the Domain in Silent Mode" for information about running the script in silent mode.

To create a domain using the domain creation script in interactive mode:

In a command shell, navigate to the following directory:

Oracle_home/oracle/ocsb60/admin_console
Run the create domain script, as follows:

./create_domain.sh
If you retained the default value (true) for the SSL security setting, enter Y at the following prompt:
```
The SSL security flag for the Administration Console is enabled. 
Note that the client and server keystores must be created for the domain creation to succeed.
Continue? 
[Y]es, [N]o:
```
The prompt does not appear if you disabled SSL security for the domain. See "Securing the Domain" for information about disabling SSL security.

If you still need to create the security keystores, enter N to cancel the domain creation script.
When prompted for the index of the product for which to create the domain, enter the number corresponding to the product domain type you want to create.

Options are:
- Online-Mediation-Controller
- Policy-Controller
- Service-Controller
- Virtual-Private-Network
- Social-Voice-Communicator
- Co-Deployed-Policy-Controller-and-Online-Mediation-Controller
- Co-Deployed-Service-Controller-and-Online-Mediation-Controller
- Co-Deployed-Virtual-Private-Network-and-Social-Voice-Communicator
Only the product types installed in the Oracle home directory are shown.
Enter the number corresponding to the domain type you want to create. The options are: 1 for a unified domain, 2 for a processing domain, or 3 for a signaling domain.
If you selected the unified (1) for the domain type, you will be prompted for Service Mode. At the prompt, enter 1 for service availability (if you create a domain for a single-domain production deployment), or 2 for service availability and continuity (if you create a domain for a single-domain test and evaluation deployment). See "Service Mode" for more information.
When prompted for the domain path, enter the full path to the directory where the domain configuration will be created. For example:

/home/oracle/domains/mydomain

This directory is referred to as domain_home in this document.
At the Enable domain SSL prompt, enter true to enable SSL or false to disable SSL for the domain connections. This setting controls whether Service Broker requires a secure connection between deployed domain components.
Enter the IP multicast address, which is the address on which servers and the Administration Console exchange certain types of internal communication within the domain. The address must be within the range 224.0.0.0 to 239.255.255.255. If you plan to set up additional domains that are part of the same cluster, keep a record of the value entered, and enter the same value when you create the other domains.
Enter the port number on which the servers and the Administration Console listen for multicast messages. The port number must be 1024 or greater. If you plan to set up additional domains that are part of the same cluster, keep a record of the value entered, and enter the same value when you create the other domains.
Enter the time-to-live for multicast messages. The value must be 1 or greater.
Indicate whether this domain should be a hosted domain:
- true if you want servers to access the domain configuration over a web connection.
- false if you want servers to access the domain files from either the local file system or a shared remote file system.
If you specified true for the hosted domain, enter the host name and port for the Web server that will provide access to the domain configuration. For example:

http://localhost:9001/

The port is defined in the org.eclipse.equinox.http.jetty.http.port property in the hosting.properties file.

Note that if security is enabled then the URL should start with https:// and the port is defined in the org.eclipse.equinox.http.jetty.https.port property in the hosting.properties file.

Note:
Hosted domains are intended for test and evaluation environments only. Oracle recommends that you do not use a hosted domain in a production deployment.
For VPN or SVC domains, enter the password of the built-in admin user. The admin user is the administrator for the RESTful Provisioning APIs.

The following is an example of the domain creation script command and its prompts, with user input in bold:

./create_domain.sh 
-----------------------------------------------------------------------
Welcome, please follow the steps below to create a domain.
 
-----------------------------------------------------------------------
Available Domains:
-----------------------------------------------------------------------
[1] Online-Mediation-Controller
[2] Policy-Controller
[3] Service-Controller
Please enter the index of the domain to create: 1
 
-----------------------------------------------------------------------
Available Online-Mediation Controller Domain Types:
-----------------------------------------------------------------------
[1] Unified
[2] PN
[3] SSU
Please enter the index of the domain type to create: 1

-----------------------------------------------------------------------
Available Service Modes: 
-----------------------------------------------------------------------
[1] Service Availability
[2] Service Availability and Continuity
Please select the service mode: 1
Please enter the domain path: /home/oracle/orahome/mc/domain 
Enable domain SSL? 
Please enter one of the following: true false > false 
Please enter the multicast address: 239.255.255.255 
Please enter the multicast port: 1036 
Please enter the multicast time-to-live (ttl): 3 
Should this domain be a hosted domain? 
Please enter one of the following: true false > false

The script creates the domain according to your selections. When the script finishes, END SCRIPT appears. You can now start the Administration Console and add servers to the domain.

Creating the Domain in Silent Mode

In silent mode, you run the domain creation script with the -silent flag, passing domain parameters as command line input to the script. Run the installer by using the following syntax:

./create_domain.sh -silent product_domain_type domain_type domain_path domain_ssl multicast_address multicast_port multicast_ttl hosted service_mode hosted_url

Where:

product_domain_type is the solution type of the domain, from these options:
- Online-Mediation-Controller
- Policy-Controller
- Service-Controller
- Virtual-Private-Network
- Social-Voice-Communicator
- Co-Deployed-Policy-Controller-and-Online-Mediation-Controller
- Co-Deployed-Service-Controller-and-Online-Mediation-Controller
- Co-Deployed-Virtual-Private-Network-and-Social-Voice-Communicator
domain_type is the type of the domain. The options are: Unified, PN, SSU, which correspond to a unified domain, processing domain, and signaling domain.
domain_path is the path to the new domain. This would be the domain configuration directory, for example: /home/oracle/domains/mydomain
domain_ssl specifies whether to enable SSL in the new domain: true or false.
multicast_address is the multicast address on which the servers and Administration Console exchange certain types of internal messages within the domain. The address must be within the range 224.0.0.0 to 239.255.255.255.
multicast_port is the multicast port for the domain.
multicast_ttl is the time-to-live (TTL) heading value for multicast messages on the domain.
hosted indicates whether the domain files will be hosted on a Web server: true or false.
service_mode specifies whether the domain should support service continuity in addition to service availability: true or false.
hosted_url is the URL of the hosted domain, if you entered true for the hosted value. If you entered false for the hosted value, this parameter is not required.

For example:

./create_domain.sh -silent Policy-Controller Unified /home/oracle/orahome/domain false 239.255.255.255 1034 2 false true

For VPN or SVC domains, enter the password of the built-in admin user when prompted. The admin user is the administrator for the RESTful Provisioning APIs.

When the script finishes, END SCRIPT appears. You can now start the Administration Console and add servers to the domain.

Starting the Domain Web Server

If you created a hosted domain, that is the domain servers access the domain configuration over a web connection, then you need to start the domain web server.

The domain web server provides servers with HTTP access to the domain configuration and the OSGi bundles for the domain. The web server's sole functionality is to allow HTTP access to the domain configuration.

The Domain web server must be started by a user who has read privileges to the Domain Configuration directory. See the discussion about configuring security between Service Broker components for more information about setting up user privileges.

To start the domain web server:

Open a command line shell.

Note:
You must be logged in as a user who has read privileges on the file system where the domain configuration resides.
Change the directory to:

Oracle_home/ocsb60/admin_console

Oracle_home is the Oracle Home directory you defined when you installed the product.
Enter:

./host.sh directory

Replace directory with the path to the domain configuration directory.
If HTTPS is enabled, enter the keystore password.
If Basic Authentication is enabled, enter the user name and password combination to use for HTTP Basic Authentication.

When the domain web server is started, servers can access the domain configuration over HTTP or HTTPS.

The port is defined in the property org.eclipse.equinox.http.jetty.http.port. The default value is 9000. See the system administrator's reference appendix in Oracle Communications System Administrator's Guide.

Starting the Administration Console

The Administration Console provides the graphical interface for the domain configuration. After creating the domain, you can start configuring it from the Administration Console interface.

You can run the Administration Console in Web access mode or standalone mode, as described in the following sections.

Starting the Administration Console in Web Access Mode

Starting the Administration Console in Web access mode enables its browser-based user interface. It allows administrators to configure the Service Broker domain from any computer with a browser and network access to the Web Administration Console server.

The Administration Console may serve the user interface over HTTP or Secure HTTP (HTTPS). The following file contains the properties that control web access, including security for the connection and the Administration Console Web interface port:

Oracle_home/ocsb60/admin_console/properties/web.properties

If you retain the default value (true) for the HTTP Basic Authentication requirement setting (axia.basic.auth), you will need to specify the username and password for accessing the user interface when starting the Web Administration Console server. Set the value to false to disable authentication requirements for the Administration Console interface.

By default, the Administration Console is served on the HTTPS port, as specified by the following setting:

org.eclipse.equinox.http.jetty.https.enabled=true

To use this port, you need to configure the SSL keystore for the Administration Console server.

Set this value to false to disable the HTTPS. You will also need to enable the HTTP port, as in the following sample portion of the file:

axia.basic.auth=false
 
org.eclipse.equinox.http.jetty.http.enabled=true
org.eclipse.equinox.http.jetty.http.port=9000
 
org.eclipse.equinox.http.jetty.https.enabled=false
org.eclipse.equinox.http.jetty.https.port=9000

For more information on web.properties and security, see Oracle Communications Service Broker System Administrator's Guide.

To start the Administration Console for Web access:

Open a command line shell.
Change to the Oracle_home/ocsb60/admin_console directory.
Enter the following command to start the Web Administration Console server:

./web.sh domain_home

where domain_home is the path to the domain configuration directory.
If HTTP Basic Auth is enabled in the web.properties file (axia.basic.auth=true), enter the username and password that clients must use to access the Web Administration Console interface from a browser.

The Administration Console enforces the password complexity requirements specified in common.properties. By default, the password must be at least six characters in length and must contain at least one upper-case letter, lower-case letter, and digit. You can modify the requirements by editing the values of the axia.console.password.validation settings in the file.
If starting the Web Administration Console for a Policy Controller domain with HTTP Basic Auth enabled, enter a second user name and password combination when prompted. The second set of credentials are used to control access to the Policy Designer GUI.

After starting the Web Administration Console server, you access the user interface from a browser by opening the following URL:

https://ipadress:9000/console

See Oracle Communications Service Broker System Administrator's Guide for more information about starting and using the Administration Console. See Oracle Communications Service Broker Policy Controller Implementation Guide for more information about the Policy Designer GUI.

Starting the Administration Console in Standalone Mode

In standalone mode, the Administration Console runs as a Java client application. You can run the standalone console only on the physical computer on which the Administration Console is installed. Web-access mode, on the other hand, allows console users to access the Web Administration Console interface from a browser on a remote client computer.

To start the standalone Administration Console:

Open a command line shell.
Change to the Oracle_home/ocsb60/admin_console directory.
Enter the following command to start the Administration Console:

./start.sh domain_home

where domain_home is the path to the domain configuration directory.

The standalone Administration Console interface appears.

Adding a Server to the Domain

After creating the domain, you add the servers you installed to the domain. You can add servers to a domain by using either JMX MBean operations or the Administration Console. After you add a server to the domain, you will be able to start the server, passing it the domain configuration. See "Starting the Server" for more information.

The following steps provide an overview of adding a server to the domain. For details on servers and on using the Administration Console interface, see Oracle Communications Service Broker System Administrator's Guide.

To add a server to the domain:

Open the Administration Console interface.

See "Starting the Administration Console" for more information on starting the Administration Console.
Click the Switch to OFFLINE mode icon at the top of the page.

Offline mode enables you to make changes to the configuration before adding servers to the domain or when the servers are not running. In online mode, changes are pushed to the managed servers when you commit the changes.
In the navigation tree, expand the OCSB node.
Expand the Domain Management node.
Click Servers.
Click the Add Server icon.

Set the following fields in the Add Server dialog:

Table 5-2 Server Configuration Fields

Field	Description
Name	The name of the server. This name will be passed in the start command for the server. It must be unique across all domains. In a multi-domain deployment (that is, when using separate processing and signaling domains), server names should follow this format: pn_number for processing domain servers, where number is an integer. For example, pn_1, pn_2, and so on. ssu_number for signaling domain servers, where number is an integer. For example, ssu_1, ssu_2, and so on. It is possible to use custom server names, but then you must configure a mapping between the custom names to the expected names. See the discussion about mapping custom server names in Oracle Communications Service Broker System Administrator's Guide for more information. Format: Alpha-numeric characters. Case-sensitive. No white spaces.
Address	The host name or IP-address of the physical computer where the server runs. Format: alpha-numeric. IP-address format or DNS name format.
Port	The port number is deprecated and no longer used. Set this parameter to -1.
Admin Port	The IP port used by the server to communicate with the Administration Console. Format: numeric
JMX JRMP port	The port to use for Java Remote Method Protocol (JRMP) invocations to the server. Format: numeric
JMX Registry port	The port to use for the MBean Server on the server. Format: numeric

Click OK.

The new server definition appears in the server list.

Repeat this procedure for each server you installed.

Table 5-3 outlines the corresponding server configurations for the example domain servers whose installation is demonstrated in Table 5-1.

Table 5-3 Example Server Configuration Settings

Server Name	Host	Port	Admin port	JMX Port	JMX Registry
pn_1	sb_01.telco.com	-1	8901	10003	10103
pn_2	sb_01.telco.com	-1	8901	10003	10104
pn_3	sb_02.telco.com	-1	8902	10004	10105
pn_4	sb_02.telco.com	-1	8902	10004	10106

You can now start the server, passing it the identity you configured in the domain, as described in "Starting the Server".

If you want to make configuration changes while the server is running, you can switch the Administration Console to online editing mode by clicking the Switch to ONLINE mode icon. If you intend to continue configuring the domain before starting the server (for example, to configure data store connectivity), you can keep the Administration Console interface in offline editing mode.

Deploying a Distributed Cluster

Servers within a domain and servers in different domains work together closely. Servers distribute events among each other inside the domain, and also across the domain boundaries. Therefore, all servers are grouped in a cluster.

Service Broker deploys Oracle Coherence for a distributed cluster. By default, servers in the cluster use IP multicasting for intra-server communication. IP multicasting configuration is set during domain creation, when you run the domain creation script. See "Creating the Domain" for more information.

For cluster deployments, if not using IP multicasting for intra-server communication, group the domains into clusters using well-known addresses. See the discussion on managing clusters in Oracle Communications Service Broker System Administrator's Guide.

Configuring Data Storage

Certain Service Broker features generate data that can be stored in persistent storage. These features include the Degraded Mode service and Subscriber Profile store.

Service Broker works with the following types of storage:

Oracle Database 11g
Oracle Berkeley DB (BDB) file-based storage

Note:

The Social Voice Communicator and VPN web applications only support Oracle Database storage for persistence.

Configuring data storage requires these steps:

Configure the database connection or local file storage location for each server.

See "Using Oracle Berkeley DB File-Based Storage" or "Using Oracle Database 11g Storage" for more information.
Specify the persistence mechanism each feature should use by installing the appropriate persistence package.

See "Specifying the Persistence Mechanism by Feature" for more information.

The following sections contain more information on these steps.

Using Oracle Berkeley DB File-Based Storage

Oracle Berkeley DB is a file-based storage mechanism. When configured to use Berkeley DB, each processing server has its own data directory in which it stores and accesses application data. Stored data is automatically synchronized across the servers in the cluster.

Note:

Multiple processing servers should not be configured to share a single data directory, even if the servers reside on the same physical host computer.

Additional deployment design considerations exist for using Berkeley DB in a cluster of domain servers. When the servers in a domain cluster start, they nominate a single server to act as the master node. The data on the master node serves as the primary copy of the data, from which the other servers in the domain cluster are synchronized. The nomination and synchronization processes among the nodes occur automatically.

However, if a server that is acting as the master node subsequently becomes unavailable, the remaining nodes must nominate a new node to serve as the master. To nominate a new master node, a majority of the servers in the domain cluster must be available. If less than a majority remain, a new master cannot be nominated and data storage and synchronization will fail. Note that this scenario will always occur in a cluster of only two servers.

You can avoid this issue by increasing the number of servers in your domain cluster. This reduces the likelihood that most servers in a cluster would be unavailable at a given time. For example, the cluster should use 3 servers instead of 2, 5 servers instead of 4, and so on.

To use Berkeley DB file-based storage, follow these steps:

Create or identify the directory on the server host in which you want Berkeley DB to store data. Oracle recommends that you use a local disk for better performance.
In the Administration Console, click the Switch to OFFLINE mode icon at the top of the page to switch the configuration mode to offline mode, if necessary.
Click the Lock & Edit icon.
In the navigation tree, expand the OCSB node and then Domain Management.
Expand the Data Store node.
Click the Persistent Stores node.
Click the Berkeley DB Store tab.
Click the New button.

Set the following fields in the dialog box:

Table 5-4 Berkeley DB Store Configuration Fields

Name	Description
Managed Server Name	The name of the domain server as specified in the domain configuration, such as pn_1 or pn_2.
BDB Enabled	Set to true to direct the server to use Berkeley DB file-based storage for data persistence, or false to disable file-based storage.
BDB Environment Directory	The location of the data directory where the server should store persistent data. Use the full path to the directory, such as: /home/oracle/OHOME1/bdbfiles
Address (Host:Port)	The local IP address or host name and port of the server on which Berkeley DB service exchanges data synchronization messages with other servers in the domain cluster. By default, the port is 5001. For example: 192.168.1.10:5001

Click OK to close the dialog box.
Repeat steps 8 through 10 for each managed server in your domain.
Click the Commit icon.

You may choose to continue working in offline edit mode, or switch to online mode if starting the managed servers. If the managed servers are running when you perform the configuration, you need to restart the servers to have the persistence changes take effect.

Using Oracle Database 11g Storage

To use Oracle Database 11g for Service Broker persistent storage, you must first prepare the database. You then configure Service Broker connections to the Oracle Database, as described in the following sections.

Preparing the Database

To prepare the database for Service Broker application storage:

In the database management system, create a user that Service Broker will use to access the database. The user should have permissions to create tables and add and modify data.

You will enter this username and password when configuring the JDBC connection information (see "Configuring the Database Connection").
Run the SQL script needed for the Service Broker applications you are using.

The SQL scripts create the database tables as required by the application. The scripts applicable to the Online Mediation Controller and Policy Controller are in the following directory:

Oracle_home/ocsb60/admin_console/scripts/database

The scripts are:
- degraded_mode_cdr_store.sql: Configures the database for storing CDRs that are generated by Service Broker when it is operating in degraded mode. Use this script to configure the database for the Online Mediation Controller.
- subscriber_store.sql: Configures the database for the subscriber profile storage. Use this script to configure the database for the Online Mediation Controller or Policy Controller.

For information on preparing the databases for the Service Broker VPN and Service Broker SVC products, see Oracle Communications Service Broker VPN Implementation Guide and Oracle Communications Service Broker SVC Implementation Guide.

After preparing the database, you can configure the database connection in the Service Broker domain.

Configuring the Database Connection

Service Broker connects to external databases using the settings defined in the JDBC driver connections in the domain configuration.

The credentials used to connect to the database are stored in the Service Broker credential store. The credential store is a secure credential storage mechanism used by Service Broker applications. For complete information on the Credential Store, see Oracle Communications Service Broker System Administrator's Guide.

Creating the Database Connection

To create the database connection by using the Administration Console:

If the Administration Console is not already in offline mode, click the Switch to OFFLINE mode icon at the top of the page.
Click the Lock & Edit icon.
Expand the OCSB node and then Domain Management.
Expand the Data Store node.
Click the Credential Store node.
In the Credential Store tab, use the fields in the Password group to add the database user credentials to the Credential Store, as follows
1. Enter a name for the credential in the Key field. This value serves as an internal alias for the database user credential in the credential store.
2. In the Password field, enter the password associated with the database user you created for Service Broker.
3. Deselect the One-way check box so that the credential is created as a two-way credential. This allows Service Broker to retrieve the password from the credential store for submission to the external database management system.
4. Click the Set Password button.
Click the Persistent Stores node.
Click the JDBC Store tab.
Click the New button.

Set the following fields in the dialog box:

Table 5-5 Database Connection Configuration Fields

Field	Description
URL	Connection URL to the database. For example: jdbc:oracle:thin:@//dbhost.example.com:1521/orcl
User	The username of the database user you created that Service Broker uses to access the Oracle Database.
Password Credential Key	The identifier for the database credential in the credential store. This value should match the value you entered in the Key field in the Password area of the Credential Store tab when adding the database credential to the Credential Store.
Connection Factory	The Java class used to create connections to the database. In most cases, this should be the default, oracle.jdbc.pool.OracleDataSource. If you have installed a custom or third party connection class, specify its name.
Initial Pool Size	The initial number of connections in the database connection pool.
Min Pool Size	Minimum number of connections in the connection pool.
Max Pool Size	Maximum number of connections in the connection pool.
Validation SQL	A SQL command used to verify that an open connection to the database remains valid over time. A connection can become invalid, or stale, when it is open for long time without activity. Typically, the command simply reads from an empty table. For example: `"select * from dual"`
Connection Pool Name	The name of the JDBC connection. By default, the Subscriber Profile feature attempts to access storage associated with a driver named oracle_driver. If you do not use oracle_driver for this value, you need to configure the Subscriber Profile feature to use the connection identified by your custom driver name. For better control of database access, Oracle recommends that you use different driver names for the Subscriber Profile and Degraded Mode features.

Click OK to save the configuration.

The new connection instance appears in the list of drivers.
Repeat steps 9 through 11 for each Processing Server in your domain.
Click the Commit icon.

You may choose to continue working in offline edit mode, or switch to online mode if you intend to start the managed server. If the managed servers are running when you perform the configuration, you need to restart the servers to have the changes take effect.

Specifying the Persistence Mechanism by Feature

The particular storage mechanism used by a feature is determined by the persistence package that is installed in the domain. By default, the Degraded Mode and Subscriber Store features use Berkeley DB storage. (The VPN and SVC products can only use Oracle DB.)

To modify the storage mechanism for each feature, you need to replace its persistence package in the domain.

Note:

Only a single persistence package for a given feature should be installed in the domain at a time. If you install a new persistence package, be sure to remove the existing package for that feature before you attempt to restart the servers in the domain.

The following instructions describe how to install and remove packages from the domain. If servers are running, they will need to be restarted for the changes to take effect. For details on package management, see the Oracle Communications Service Broker System Administrator's Guide.

Also, these instructions reflect the interface presented by the Web Administration Console. The steps are slightly different in the standalone Administration Console interface.

To apply a storage mechanism by Service Broker feature:

In the Administration Console, switch to offline mode.
Click the Lock & Edit icon
Expand the OCSB node.
Expand Domain Management.
Click Packages.
Click the Install button.
In the Install Bundle dialog box, click the Browse button.
In the Upload File dialog box, click Browse and navigate to the package directory:

oracle_home/ocsb60/admin_console/modules
Use the file chooser dialog box to select one of the following package files, depending on the persistence mechanism you want to use.

For Subscriber Store persistence, select one of the following files:
- oracle.ocsb.app.rcc.service.subscriber_store.providers.store.config_bdb.jar: Select this file to use Oracle Berkeley DB file-based storage. This is the default package for Subscriber Store persistence.
- oracle.ocsb.app.rcc.service.subscriber_store.providers.store.config_db.jar: Select this file to use Oracle Database.
For Degraded Mode persistence, select one of the following files:
- oracle.ocsb.app.rcc.service.degraded_mode.persistence.bdb.jar: Select this file to use Oracle Berkeley DB file-based storage. This is the default package for Degraded Mode persistence.
- oracle.ocsb.app.rcc.service.degraded_mode.persistence.database.jar: Select this file to use Oracle Database.
- oracle.ocsb.app.rcc.service.degraded_mode.persistence.in_memory.jar: Select this file to use Oracle Coherence cache storage.
With the file you selected showing in the Upload File dialog box file field, click Upload.
Click the OK button in the File Uploaded dialog box.
Click OK in the Upload File dialog box.
Click Install in the Install Bundle dialog box.

The package you selected appears in the package list.
Change the start level of the package you loaded to match the level of the following packages, depending on whether it is a Subscriber Profile or a Degraded Mode package:
- oracle.ocsb.app.rcc.service.degraded_mode.core for the Degraded Mode persistence package
- ocsb.app.rcc.service.subscriber_store.core for the Subscriber Profile persistence package
To change the start level:
1. Select the package in the list.
2. Click the Start Level button.
3. In the Enter the start level field, enter the new start level number. Enter 190 for the Subscriber Profile package, or 295 for the Degraded Mode package.
4. Click OK.
Remove the previously installed persistence package (that is, the package that you are replacing) as follows:
1. Select the package in the list.
2. Click the Uninstall button.

Starting the Server

After you add a server to the domain and configured data storage, you can start the server. If a domain contains several servers, you need to start each server individually.

For Service Broker controller types that rely on persistent storage, you should configure data storage before attempting to start the server. See "Configuring Data Storage" for information on setting up data storage.

For hosted domains (that is, if you configured the domain files to be exposed by a Web server), you need to start the Web server process first using the host.sh script. For more information on hosted domains, see the Oracle Communications Service Broker System Administrator's Guide.

To start the server:

In a command line shell, change directories to the server directory. By default, the server is installed to the following directory:

Oracle_home/ocsb60/managed_server
Enter:

./start.sh server_name domain_home/initial.zip

where:

server_name is the name you gave the server when you added the server to the domain.

domain_home is the full path to the domain configuration directory where the initial.zip file is. The path may be in the form of a file location or URL. Specify the protocol as follows:
- For a Web-hosted domain, add the protocol prefix http:// or https:// to the path, depending on your security settings.
- If your domain configuration is accessed on a shared file system, add the protocol prefix file:// to the path.
The following is an example of how to start a server, passing it the pn_1 identity and the configuration bundle located on the local file system:

./start.sh pn_1 file:///home/oracle/sc_basic_domain/initial.zip
If using HTTPS, enter the keystore password when prompted.

Table 5-6 shows the start command and parameters for each server in the example domain introduced in Table 5-1. The start script is located in the server directory.

Note that the name of the server in the domain configuration, as shown in Table 5-3, corresponds to the name given as a parameter when starting the server.

Table 5-6 Example Server Start Commands

Server Directory	Server Start Command for a Non-hosted Domain	Server Start Command for a Hosted Domain
managed_1	`start.sh pn_1 file:../domain/initial.zip`	`start.sh pn_1 http://`ipaddress`:9001/initial.zip`
managed_2	`start.sh pn_2 file:../domain/initial.zip`	`start.sh pn_2 http://`ipaddress`:9001/initial.zip`
managed_3	`start.sh pn_3 file:../domain/initial.zip`	`start.sh pn_3 http://`ipaddress`:9001/initial.zip`
managed_4	start.sh pn_4 file:../domain/initial.zip	`start.sh pn_4 http://`ipaddress`:9001/initial.zip`

When you start multiple servers on a single physical host, Oracle recommends use of a separate command shell for each server.

See Oracle Communications Service Broker System Administrator's Guide for more information about starting servers.