This chapter describes how to set up an Oracle Communications Service Controller domain. Before you perform the procedures described in this chapter, you must install Service Controller.
Whether a domain is a signaling domain, a processing domain, or a unified domain, setting up a domain requires the following steps:
Configuration data and software bundles are located in the domain configuration directory. The domain configuration directory is referred to as the domain_home.
The domain configuration directory is created when you run the domain creation script to create the domain. You define the method that servers use to access the directory when you create the domain.
The Administration Server and all managed servers in the domain require access to the domain configuration directory.
The Administration Server requires read and write access to the domain configurations. The managed servers require read-only access to the domain configuration.
The Administration Server and managed servers can access the domain configuration directory by using either a hosted or a nonhosted domain. You select either method when you run the domain creation script:
Hosted domain: Uses a Web server to provide managed servers with HTTP or HTTPS access to the domain configuration directory. See "Starting the Domain Web Server" for more information.
If you use a Web server to provide the domain configuration files, set up the Web server with read access to the domain configuration directory and map the directory to a URL.
Note:
The Administration Server requires local file system access to the domain directory because it needs write access to configuration, bundles, credential store and domain lock files.In a production environment be sure to enable HTTPS, provide redundancy for the Web server, and make backups of the domain configuration directory.
A Web server does not provide any redundancy support by default. A Web server that fails will not impact managed servers that are running, but new managed servers cannot be started until the Web server is back online.
See the discussion on considerations for using Credential Store with hosted domains in the Service Controller Security Guide for additional information about working with hosted domains securely.
Nonhosted domain: Connects to the domain configuration directory and the software bundles using a shared file system, not using a Web server.
If you use a shared file system, set up all servers so that they can access the domain configuration directory.
Whether you use a hosted or a nonhosted domain, be certain that all of your restore procedures are rapid to ensure minimal service down time. A recommended solution for high availability is to provide a backup Service Controller installation with a mirrored copy of the domains.
See "Understanding the Domain-Based Administration Model" for more information about domains.
See Service Controller Security Guide for information on securing a domain.
You can use the Service Controller installer to install the Administration Server and managed servers on a single computer or on multiple computers. Oracle recommends that you install the Administration Server on its own physical server from where it manages the domain remotely.
Note:
Only one Administration Console can be used to manage a domain at a time.In a unified domain deployment, if you want to install multiple managed server instances on the same physical host, you can do either of the following:
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. See "Creating Multiple Managed Servers by Copying Them" for more information.
Run the installer multiple times, and other than for the first installation, clear the check box for installing the Administration Server when you select which products and components to install.
Note:
Copying the managed_server directory is faster than running the installer multiple times.Installing managed servers on a host and adding them to a domain are separate procedures. After you install the managed server instances, you must use the Administration Console to add the managed servers to a domain. See "Adding a Managed Server to The Domain" for more information.
This section describes how to create multiple servers on a single physical host by copying the managed server directory:
Run the installer on the physical host. See "Installing the Software" for instructions.
The default installed Administration Server directory is:
Oracle_home/ocsb62/admin_server
The default installed managed server directory is:
Oracle_home/ocsb62/managed_server
Create a new managed server directory for each additional managed 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/ocsb62/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 Server, you must define each managed server in the domain configuration by specifying its name and listening ports.
Table 5-1 illustrates a sample domain with one Administration Server and four managed servers on two physical hosts. The table outlines the directory structure for the example domain.
Tip:
To increase availability, you can install the Administration Server on a separate physical host.Table 5-1 Example Directory Structure
| Physical Host | Directory Path | Description |
|---|---|---|
|
sb_01 |
oracle_home |
Administration Server |
|
sb_01 |
oracle_home |
Default managed server installation directory Used as the source when creating the directories for the new servers on the sb_01 host. |
|
sb_01 |
oracle_home |
First managed server instance directory |
|
sb_01 |
oracle_home |
Second managed server instance directory |
|
sb_02 |
oracle_home |
Default managed server installation directory Use as the source when creating the directories for the new servers on the sb_02 host. |
|
sb_02 |
oracle_home |
Third managed server instance directory |
|
sb_02 |
oracle_home |
Fourth managed server instance directory |
By default, the setting that controls security in the domain is enabled. This setting applies to the connections between the Administration Server and the managed servers in a domain.
Before you run the domain creation 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/ocsb62/admin_server/properties/common.properties
Set the axia.ssl property to false:
axia.ssl=false
For more information on the properties in the file, see Service Controller 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 Controller components in Service Controller Security Guide. For information on the property file entries, see the Service Controller System Administrator's Guide.
The domain creation script can operate interactively or in silent mode. The following instructions describe how to use the script interactively. See "Creating a Domain in Silent Mode" for information about running the script in silent mode.
Important: If you choose to create separate signaling and processing domains, that is a multi-domain topology, you must run the script separately for each domain.
When you run the script, be sure to make the same selections for both the signaling and processing domains. Select the same combination of 1) Available Domains (Service Controller), and the same 2) Service Mode (Continuity, Availability).
To create a domain using the domain creation script in interactive mode:
In a command shell, navigate to the admin_server directory:
Oracle_home/ocsb62/admin_server
Run the create domain script, as follows:
./script.sh scripts/create_domain_interactive.xml
Enter the number corresponding to the domain type you want to create.
The options are:
[0] Unified
[1] Processing
[2] Signaling
When prompted for the index of the available product domain types, enter the number corresponding to the product domain you want to create.
The options are (example):
[0] Service Controller Domain
Product domains are displayed only for products you previously installed. You can select one, or any combination, of the product domains.
Enter a domain path which can be any valid path to where the domain configuration will be located. Example: /home/oracle/domains/ocsb-all-products
This path is referred to as domain_home in this document.
Do one of the following:
To create a hosted domain, enter the URL of the Web server that will provide access to the domain configuration: http://<address>:<port>
To create a nonhosted domain, do not enter any value and press Enter.
If you select a hosted domain the managed servers will access the domain configuration by connecting to a Web server. If you select a nonhosted domain they will instead need to use a shared file system.
Note that if security is enabled 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.
If security is disabled, the port is defined in the org.eclipse.equinox.http.jetty.http.port property in the hosting.properties file.
Enter the IP multicast address for initial Coherence cluster configuration, which is the address on which managed servers and the Administration Server 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 for initial Coherence cluster configuration on which the servers and the Administration Server 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.
At the prompt Enable SSL for this domain? (Yes/No) enter Y or N. In a production environment you should always use SSL. This setting controls whether Service Controller requires a secure connection between deployed domain components.
At the prompt for Service Mode enter [1] Continuity, or [2] Availability. Continuity provides availability and persistent data but can reduce performance. See "About Setting the Service Availability Mode" for more information.
The following is an example of the domain creation script command and its prompts, with user input in bold:
./script.sh scripts/create_domain_interactive.xml
--------------------------------------------------------------------------------
Welcome, please follow the steps below to create a domain.
--------------------------------------------------------------------------------
Available Domain Types:
----------------------------------------------------------------------
[0] Unified
[1] Processing
[2] Signaling
Please enter the index of a domain type to create : 0
--------------------------------------------------------------------------------
General Domain Properties:
--------------------------------------------------------------------------------
Please enter the Domain Path : /home/oracle/domains/ocsb-all-products
Please enter the Hosted URL http://<address>:<port> (For non-hosted, press Enter to skip) :
Please enter the Multicast Address : 239.255.255.255
Please enter the Multicast Port : 1034
Please enter the Multicast Time-To-Live : 2
Enable SSL for this domain? (Yes/No) : y
--------------------------------------------------------------------------------
Additional Domain Properties:
--------------------------------------------------------------------------------
Please select the Service Mode
--------------------------------------------------------------------------------
[0] Continuity
[1] Availability
Please enter the index of the selection : 0
--------------------------------------------------------------------------------
Domain Summary:
Domain Types/Names : Service Controller Unified Domain
Domain Path : /home/oracle/domains/ocsb-all-products
Hosted URL (null if not hosted) : null
Multicast Address : 239.255.255.255
Multicast Port : 1034
Multicast Time-To-Live : 2
Domain SSL Enabled : True
Online Charging Server type : BRM Online Charging Server
Service Mode : Continuity
--------------------------------------------------------------------------------
Proceed with the domain creation? (Yes/No) : y
The script creates the domain according to your selections. When the script finishes, the message Domain created successfully appears. You can now start the Administration Server and add managed servers to the domain.
You can create a domain in silent mode two different ways:
Specifying parameters in an XML file
Entering command-line arguments
To create a domain in silent mode, before you run the domain creation script, you must replace all placeholders in the create_domain_silent.xml file with valid domain creation values. The XML file is located here: admin_server/scripts/create_domain_silent.xml.
When you run the silent install script, the XML file passes domain parameters to the script. If you do not replace any of the placeholders in the XML file with values, when you run the script you will be prompted for the value at the console.To learn about the parameters, see the descriptions in the section "Domain Creation Parameters in the create_domain_silent.xml File".
Note:
The scripting engine validates format and platform compatibility where applicable. However, it will not perform any spell checking so be sure to enter values into the XML file carefully.If you omit any required value in the properties file, the installer will prompt you to enter the value at the command prompt.To create a domain in silent mode using an XML file:
In a command shell, navigate to the admin_server directory:
Oracle_home/ocsb62/admin_server
Open the create_domain_silent.xml file for editing and enter the values you want to use to create the domain. Table 5-2 lists the parameters with descriptions.
Save and close the file.
Run the create domain script, as follows:
./script.sh scripts/create_domain_silent.xml
When the script finishes, Domain created successfully appears. You can now start the Administration Server and add managed servers to the domain.
Table 5-2 lists the installation parameters in silentInstall.properties file that the silent installer applies.
Table 5-2 Parameters in the create_domain_silent.xml File
| Parameter | Description |
|---|---|
|
domainTypes |
Comma-separated list of domain types to include in the domain. Example: policycontroller-processing,onlinemediationcontroller-processing |
|
domainPath |
Absolute file path to the new domain. Example: /home/user/ocsb_home/ocsb62/pc_omc_processing_domain |
|
multicastAddress |
Multicast address for initial Coherence cluster configuration. Example: 224.0.1.123 |
|
multicastPort |
Multicast port for initial Coherence cluster configuration. Example: 9876 |
|
multicastTtl |
Multicast TTL for initial Coherence cluster configuration. Example: 2 |
|
properties |
Comma-separated list of properties to allow the specification of default choices and template specific properties. If a property value is not supplied, the default value will be used. If domain.ssl or domain.hosted.url are not included, then the default values will apply (SSL will be enabled and the domain not hosted). Example: domain.hosted.url=http://localhost:9000/,domain.ssl=false,service.mode=availability |
Tip:
There are two additional properties that can assist you in preparing a silent configuration:"domain.help": If set to true, this property will cause all available options to be printed to the console. It is important that you select the domain types when using this property. The domain will not be created if this property is set to true.
"domain.summary": If set to true, this property displays a summary of the domain parameters and values before creating the domain. This feature is similar to how the interactive mode summary precedes domain creation.
The next section describes how to create a domain in silent mode by entering arguments at the command-line.
To create a domain in silent mode, you must create an AXIA environment variable, assign it parameter-value pairs described in Table 5-2, and then run the silent installation script.
To create a domain in silent mode by entering arguments at a command-line:
In a command shell, use the export command to create an AXIA environment variable and set the parameter-value pairs as described in Table 5-2.
Example:
export AXIA_OPTS="-Ddomain.types=servicecontroller-processing -Ddomain.path=/home/user/domains/ocsc-processing -Ddomain.maddress=225.226.228.229 -Ddomain.mport=1122 -Ddomain.ttl=1 -Ddomain.properties=domain-ocsb,service.mode=availability,domain.ssl=true"
Run the silent domain script, which picks up the parameter values from the AXIA_OPTS environment variable:
./script.sh scripts/create_domain_silent.xml
When the script finishes, Domain created successfully appears. You can now start the Administration Server and add managed servers to the domain.
If you created a hosted domain, you need to start the domain Web server. If you created a non-hosted domain skip this section.
The domain Web server provides servers with secure HTTPS access to the domain configuration and to the OSGi bundles for the domain. The domain Web server's only functionality is to allow access to the domain configuration.
You specified the domain Web server port when you ran the domain creation script and indicated you wanted to use a hosted domain. The port number is located in the hosting.properties file org.eclipse.equinox.http.jetty.https.port property.
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 Controller 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/ocsb62/admin_server
Oracle_home is the Oracle Home directory you defined when you installed the product.
Enter:
./host.sh domain_home
Replace domain_home with the path to the domain configuration directory.
Enter the keystore password.
When the domain Web server is running, the managed servers can access the domain configuration.
Starting the Administration Server enables you to start the Administration Console. You can configure the a Service Controller domain from any computer with a browser and network access to the Administration Server.
Note:
The instructions below describe setting up default security for the Administration Server to Administration Console connection. The Administration Console supports a single user. By default the security for this user includes 1) Digest Authentication and an 2) SSL connection between the Administration Console and the Administration Server.Administration Console password is set by a startup prompt. The first time the Administration Server is started, the user needs to supply a user name and password. These login credentials must be supplied in each Administration Console session.An alternative security method is described in the Chapter Administering Credential Stores in the Service Controller Security Guide.For more information about Administration Server client authentication, see the Administrator's Reference appendix in the Service Controller System Administrator's Guide.
The Administration Console can connect to the Administration Server over (default) Secure HTTP (HTTPS) or HTTP. The following file contains the properties that control Web access, including security for the connection and the Administration Server port:
Oracle_home/ocsb62/admin_server/properties/admin.properties
The default authentication method for the Administration Console is called Digest Authentication (axia.digest.auth=true). This setting enables digest authentication which is described in this IEEE RFC, http://www.ietf.org/rfc/rfc2617.txt. See the Service Controller Security Guide for more information.
By default, the Administration Server is connected 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 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
If you are using separate Processing and Signaling domains, you will need to use a separate Administration Server for each domain. Each Administration Server must be assigned a unique port number.
Open this file for editing: Oracle_home/ocsb62/admin_server/properties/admin.properties
Change the port number assigned to the following property:
org.eclipse.equinox.http.jetty.http.port=9000
Save the file.
For more information on admin.properties and security, see Service Controller System Administrator's Guide.
To start the Administration Console:
Open a command-line shell.
Change directory to Oracle_home/ocsb62/admin_server.
Enter the following command to start the Administration Server:
./start.sh domain_home
where domain_home is the path to the domain configuration directory.
The first time you start the Administration Server if Digest Authentication (the default setting) is enabled in the admin.properties file (axia.digest.auth=true) you are prompted to enter a user name and password for subsequent uses of the Administration Console.
The Administration Server enforces 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.
When the script finishes it displays this message: "Administration Server started".
After starting the Administration Server, you can access the Administration Console in a browser by entering the following URL:
https://ipadress:9000/console
See Service Controller System Administrator's Guide for more information.
All Managed servers and the Administration Server in a single domain are nodes in a cluster. This is true whether the domain, for example a processing or a signaling domain, exists on a single or on multiple hosts. See "About Clusters" for more information.After creating the domain, you need to add to the domain all of the managed servers you installed. You add servers to a domain by using the Administration Console. After you add a managed server to the domain, you will be able to start the managed server, passing it the domain configuration. See "Starting the Managed Server" for more information.
The following steps provide an overview of adding a managed server to the domain. For more information, see Service Controller System Administrator's Guide.
To add a managed server to the domain:
Start 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 as described in Table 5-3.
Table 5-3 Server Configuration Fields
| Field | Description |
|---|---|
|
Name |
The name of the managed 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:
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 Service Controller System Administrator's Guide for more information. Format: Alpha-numeric characters. Case-sensitive. No white spaces. |
|
Host |
The host name or IP-address of the physical computer where the managed server runs. Format: alpha-numeric. IP-address format or DNS name format. |
|
Admin Port |
The IP port used by a managed server to communicate with the Administration Server. The value is assigned automatically and incremented for each managed server. Format: numeric All ports for servers need to be unique for each physical machine. |
|
JMX JRMP port |
The port to use for Java Remote Method Protocol (JRMP) invocations to the managed server. Format: numeric All ports for servers need to be unique for each physical machine. |
|
JMX Registry port |
The port to use for the MBean Server on the server. Format: numeric All ports for servers need to be unique for each physical machine. |
Click OK.
The new server definition appears in the server list.
Repeat this procedure for each server you installed.
Table 5-4 outlines the corresponding server configurations for the example managed servers whose installation is demonstrated in Table 5-1.
Table 5-4 Example Server Configuration Settings
| Server Name | Host | Admin port | JMX Port | JMX Registry |
|---|---|---|---|---|
|
pn_1 |
sb_01.telco.com |
8901 |
10003 |
10104 |
|
pn_2 |
sb_01.telco.com |
8902 |
10005 |
10106 |
|
pn_3 |
sb_02.telco.com |
8903 |
10007 |
10108 |
|
pn_4 |
sb_02.telco.com |
8904 |
10009 |
10110 |
You can now start the server, passing it the identity you configured in the domain, as described in "Starting the Managed Server".
If you want to make configuration changes while the server is running, you can switch the Administration Server 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 Server in offline editing mode.
After you add a managed server to the domain, you can start the managed server. If a domain contains several managed servers, you need to start each managed server individually.
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 Service Controller 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/ocsb62/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 path to the domain configuration directory where the initial.zip file is located. 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-5 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-4, corresponds to the name given as a parameter when starting the server.
Table 5-5 Example Server Start Commands
| Server Directory | Server Start Command for a Non-hosted Domain | Server Start Command for a Hosted Domain |
|---|---|---|
|
managed_1 |
|
|
|
managed_2 |
|
|
|
managed_3 |
|
|
|
managed_4 |
|
|
When you start multiple servers on a single physical host, Oracle recommends that you use a separate command shell for each server.
See Service Controller System Administrator's Guide for more information about starting servers.