Configuring Service Registry

This section describes the following tasks:

• To Configure Service Registry as Root Using Custom Properties After a Configure Later Installation

• To Configure Service Registry as a Non-Root User Using Custom Properties After a Configure Later Installation

• To Edit Database Properties for the Oracle Database

• To Add Root Certificates to the Trusted Certificates in the Registry Domain

• Configuring an Oracle Database for Use with Service Registry

• Configuring Service Registry with a Non-Default Application Server Location

• Configuring Service Registry with Application Server 9.1

The Sun Java Enterprise System 5 Update 1 Installation Guide for UNIX describes how to perform post-install configuration of Service Registry using default property settings for the Registry. To use custom property settings, make a copy of the file ServiceRegistry-base/install/install.properties or ServiceRegistry-base/install/install.properties.template and edit it before you perform the configuration.

See Default Paths and File Names for the location of ServiceRegistry-base on your platform.

To configure the Registry, you can be logged in as root or become superuser, or you can be logged in as an non-root user.

For security reasons, it is recommended that you configure the Registry as a non-root user. For instructions, see To Configure Service Registry as a Non-Root User Using Custom Properties After a Configure Later Installation.

Before you configure Service Registry, you must first install and configure Sun Java System Application Server (“Application Server”). The configuration process for Service Registry installs the Registry into an Application Server domain.

It is recommended that you install Application Server in its default location. If you installed Application Server in a non-default location, follow the instructions in Configuring Service Registry with a Non-Default Application Server Location before you configure Service Registry.

The version of Application Server that is part of Java Enterprise System 5 Update 1 is Application Server 8.2. You can also install Service Registry on Application Server 9.1. See Configuring Service Registry with Application Server 9.1 for details.

The install.properties file contains a set of modifiable property settings. The properties that are listed in Table 1–1 and Table 1–2 are used by the configuration process. Each property name in Table 1–1 has the prefix registry.install. (terminating in a period). Some of these properties set non-default ports for the Application Server domain created for the Registry. Others set configuration properties described elsewhere in this manual.

You can configure multiple instances of Service Registry either as root or as a non-root user. If you do so, you must change the registry.install.dataHome property to be unique for each Registry instance. If you want to be able to run more than one instance at a time on the server, you must also change the eight port properties to be unique for each instance. For multiple non-root instances, you may want to change the value of registry.install.CACertDir to be unique for each instance.

Table 1–2 describes properties used to configure the database used by the Registry. By default, the Registry uses the Java DB database. You can, however, configure the Registry to use an Oracle database instead of the Java DB database. Some of the database property names do not begin with registry.install, so this table provides the full name of each property.

If you plan to use an Oracle database, you must perform some configuration tasks for the Oracle database before you configure Service Registry to use it. For details, see Configuring an Oracle Database for Use with Service Registry. In addition, you must edit the install.properties file as described in To Edit Database Properties for the Oracle Database.

To Configure Service Registry as Root Using Custom Properties After a Configure Later Installation

Before You Begin

These instructions assume that you are logged in as root or have become superuser.

1. Change to the ServiceRegistry-base/install directory.

2. Copy the file install.properties to a secure location.

   Use a command like the following:

   cp install.properties $HOME/hidden_dir/sr.properties

3. Change the permissions on the properties file to make it writable.

   Use a command like the following:

   chmod 600 $HOME/hidden_dir/sr.properties

4. Edit the modifiable properties in the file.

   For example, it is recommended that you change all the passwords from the default values.

   If you will be using Oracle as the database instead of Java DB, follow the instructions in To Edit Database Properties for the Oracle Database to edit the database properties. (Make sure you have already followed the instructions in Configuring an Oracle Database for Use with Service Registry.)

5. Change the permissions back to the original read-only value.

   Use a command like the following:

   chmod 400 $HOME/hidden_dir/sr.properties

6. In the ServiceRegistry-base/install directory, run a command like the following (all on one line), specifying the location of the modified install.properties file.

   Ant-base/ant -f build-install.xml -Dinstall.properties=$HOME/hidden_dir/sr.properties configure

   The ant command requires the JAVA_HOME environment variable to be set. Ordinarily, you set this variable to the following value:

   /usr/jdk/entsys-j2se

   The Registry configuration process creates an Application Server domain at RegistryDomain-base/domains/${registry.install.DomainName}. The default domain name is registry. The configuration process then starts the domain, deploys the Registry, and leaves the domain running.

   The Registry configuration process installs the Registry database and server keystore in the directory RegistryDomain-base/3.0. This directory is not removed when the Registry is uninstalled, so that the database can be preserved for use in a future release. The administrator has control over when and whether to remove this directory.

   The RegistryDomain-base location is /var/opt/SUNWsrvc-registry on Solaris OS, /var/opt/sun/srvc-registry on Linux systems, and C:\Program Files\Sun\JavaES5\srvc-registry\data on Microsoft Windows systems.

   The Registry configuration process creates a directory named ServiceRegistry-base/install/cacerts for you to place added certificates that the Application Server domain should trust.

7. Review the output of the ant configure command for any errors.

   If there are no errors, you can now begin using the Web Console or the Admin Tool.

To Configure Service Registry as a Non-Root User Using Custom Properties After a Configure Later Installation

Before You Begin

These instructions assume that you are logged in as an ordinary user, not as root, and that someone logged in as root has installed Service Registry.

1. Change to the ServiceRegistry-base/install directory.

2. Copy the file install.properties.template to a location in your home directory and rename it.

   Use a command like the following:

   cp install.properties.template $HOME/sr.properties

3. Open your copy of the file in a text editor and modify properties as needed.

   You must supply password values for the following properties, which are left empty in the template file:

   registry.install.AdministratorPassword=
   registry.install.ApplicationServerKeystorePassword=
   registry.install.RegistryServerKeystorePassword=

   If you will be using Oracle as the database instead of Java DB, follow the instructions in To Edit Database Properties for the Oracle Database to edit the database properties. (Make sure you have already followed the instructions in Configuring an Oracle Database for Use with Service Registry.)

4. Change the permissions on the file so that only you can read it.

   Use a command like the following:

   chmod 400 $HOME/sr.properties

5. In the ServiceRegistry-base/install directory, run a command like the following (all on one line), specifying the location of the modified file.

   Ant-base/ant -f build-install.xml -Dinstall.properties=$HOME/sr.properties configure

   Use a similar command to run any other configuration targets that you need.

   The Registry configuration process creates an Application Server domain at $HOME/srvc-registry/domains/${registry.install.DomainName}. The default domain name is registry.

   The Registry configuration process installs the Registry database and server keystore in the directory $HOME/srvc-registry/3.0.

   The Registry configuration process creates a directory named $HOME/srvc-registry/cacerts for you to place added certificates that the Application Server domain should trust.

6. Review the output of the ant configure command for any errors.

   If there are no errors, you can now begin using the Web Console or the Admin Tool.

To Edit Database Properties for the Oracle Database

Follow these steps if you will be using the Oracle database instead of Java DB. These steps assume that you have opened a copy of the install.properties or install.properties.template file in a text editor.

1. Change the values of the registry.install.RequireDatabaseAuthentication, registry.install.DatabaseUserID, and registry.install.DatabasePassword properties to match the values you provided for the Oracle user name and password in To Create a Database User:

   registry.install.RequireDatabaseAuthentication=true
   registry.install.DatabaseUserID=user-name
   registry.install.DatabasePassword=password
   

2. Put comment characters (#) in front of the lines that define properties for Java DB, so that they look like the following:

   #registry.install.clientDatabase=false
   #registry.install.databaseHost=localhost
   #registry.install.databasePort=1527
   #registry.db.dialect=org.freebxml.omar.server.repository.hibernate.DerbyDialect
   #registry.install.jdbcClassName=org.apache.derby.jdbc.EmbeddedDriver
   #registry.install.dbURL=jdbc:derby:$omar.home/data/registry/soar;create=true
   #registry.install.dbTransactionIsolation=TRANSACTION_READ_UNCOMMITTED
   #registry.database.supportsOrderBy=true

3. Remove the comment characters from the lines that define properties for the Oracle database, so that they look like the following.

   ---

   Note –

   Each property definition must appear on one line. The registry.install.dbURL and registry.install.dbURLFixed appear on two lines below so that they fit on the page.

   ---

   registry.install.clientDatabase=true
   registry.install.databaseHost=localhost
   registry.install.databasePort=1521
   registry.install.nonJavaDB=true
   registry.install.jdbcClassName=oracle.jdbc.driver.OracleDriver
   registry.install.jdbcDataSourceName=oracle.jdbc.pool.OracleDataSource
   registry.install.dbURL=jdbc:oracle:thin:@${registry.install.databaseHost}:
   ${registry.install.databasePort}:soar
   registry.install.dbURLFixed=jdbc\\:oracle\\:thin\\:@${registry.install.databaseHost}\\:
   ${registry.install.databasePort}\\:soar
   registry.db.installScript=database.sql
   registry.db.cleanupScript=cleanup.sql
   libs.db.jar=../lib/ojdbc14.jar
   registry.db.dialect=net.sf.hibernate.dialect.Oracle9Dialect
   registry.install.dbTransactionIsolation=TRANSACTION_READ_COMMITTED

   ---

   Note –

   The values of the registry.install.dbURL and registry.install.dbURLFixed properties assume that you gave the Oracle database the name soar when you followed the instructions in Configuring an Oracle Database for Use with Service Registry.

   ---

4. Add the following property definition to the file:

   registry.database.supportsOrderBy=false

   You must set this property in order for Service Registry to work correctly with an Oracle database. If you do not set this property, some queries will fail.

5. If the Oracle database is not installed on the same machine as Service Registry, change the value of the registry.install.databaseHost property from localhost to the IP address or hostname of the system where the Oracle database is installed (for example, 111.222.33.44 or mysys.mydomain.mycompany.com).

To Add Root Certificates to the Trusted Certificates in the Registry Domain

This task extends the list of trusted certificates in the Application Server registry domain.

Perform this task only if you use a third-party certificate and the root Certificate Authority (CA) certificate for the third party is not already in the Application Server truststore. Do not perform this task if you use only registry-issued certificates.

To determine whether the CA certificate you need is already available, you can use the list.cacerts target of the build-install.xml file:

Ant-base/ant -f build-install.xml -Dinstall.properties=props-file list.cacerts

where props-file is the path name of the copy of install.properties file that you edited in To Configure Service Registry as Root Using Custom Properties After a Configure Later Installation or To Configure Service Registry as a Non-Root User Using Custom Properties After a Configure Later Installation.

1. Download any root certificates that you want to support.

   Sites that provide root certificates include the following:

   • http://www.entrust.net/developer/

   • http://www.geotrust.com/resources/root_certificates/

   • http://www.thawte.com/roots/

   • http://www.verisign.com/support/roots.html

2. If necessary, use the unzip command to extract .cer files from the downloaded archive.

   ---

   Note –

   Some files have the suffix .der.

   ---

3. Copy the .cer files to the directory specified by the registry.install.CACertDir property in your copy of the install.properties file.

   This value is normally ServiceRegistry-base/install/cacerts if you configured as root, or $HOME/srvc-registry/cacerts if you configured as a non-root user.

4. Change to the directory ServiceRegistry-base/install.

5. Run the following command (all on one line):

   Ant-base/ant -f build-install.xml -Dinstall.properties=props-file install.cacerts

6. This command installs any certificates found in the directory specified by the registry.install.CACertDir property into the Application Server domain truststore.

   You can use the list.cacerts target again to make sure that the certificates have been installed correctly.

7. Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.

Configuring an Oracle Database for Use with Service Registry

In order to use Service Registry with an Oracle database instead of the default Java DB database, you must install and configure the Oracle database for use with Service Registry. This manual does not describe how to install an Oracle database; consult the Oracle documentation for this information.

Once Oracle is installed, the required configuration tasks are as follows:

• Download and install the Oracle JDBC JAR file

• Create a database, defining a non-default number of cursors

• Create a user for the database

• Edit the tnsnames.ora file to allow multiple clients to connect over the network

These tasks are described in the following sections:

• To Obtain the Oracle JDBC JAR File

• To Create a Database

• To Create a Database User

• To Edit the tnsnames.ora File

After these tasks are completed, configure Service Registry as described in To Configure Service Registry as Root Using Custom Properties After a Configure Later Installation or To Configure Service Registry as a Non-Root User Using Custom Properties After a Configure Later Installation. This configuration must include the task described in To Edit Database Properties for the Oracle Database.

To Obtain the Oracle JDBC JAR File

1. Download the ojdbc14.jar file from the Oracle OTN network.

2. Copy this file into the ServiceRegistry-base/lib directory.

   For example, on Solaris OS, the command would look something like this:

   cp ojdbc14.jar /opt/SUNWsrvc-registry/lib

3. Change to the ServiceRegistry-base/install directory.

4. Run the following command:

   Ant-base/ant -f build-install.xml -Dinstall.properties=props-file configure.extern

To Create a Database

To create an Oracle database, use the Oracle Database Configuration Assistant utility.

1. Start the utility using the dbca command:

   dbca

2. On the Welcome screen, click Next.

3. On the Step 1 screen (Operations), select the Create a Database radio button and click Next.

4. On the Step 2 screen (Database Templates), select the General Purpose radio button and click Next.

5. On the Step 3 screen (Database Identification), specify a Global Database Name and a System Identifier (SID) for the database and click Next.

   For the Global Database name, specify soar followed by a domain name, as in soar.mydomain.mycompany.com.

   For the SID, specify soar.

6. On the Step 4 screen (Management Options), accept the default settings and click Next.

   The Configure the Database with Enterprise Manager checkbox is selected, and the Use Database Control for Database Management radio button is selected.

7. On the Step 5 screen (Database Credentials), select the Use the Same Password for All Accounts radio button, type a password of your choice in the text fields, and click Next.

8. On the Step 6 screen (Storage Options), accept the default settings and click Next.

   The File System radio button is selected.

9. On the Step 7 screen (Database File Locations), accept the default settings and click Next.

   The Use Database File Locations from Template radio button is selected.

10. On the Step 8 screen (Recovery Configuration), accept the default settings and click Next.

    The Specify Flash Recovery Area checkbox is selected, and default values are filled in for the two fields.

11. On the Step 9 screen (Database Content), accept the default settings and click Next.

    The Sample Schemas checkbox is not selected.

12. On the Step 10 screen (Initialization Parameters), select the Character Sets tab.

13. Select the radio button labeled “Choose from the list of character sets”, then select UTF8 from the menu.

14. At the bottom of the Step 10 screen, select the All Initialization Parameters radio button.

15. In the All Initialization parameters dialog, scroll to the open_cursors parameter.

16. Change the value to 3000 and click Close.

17. Click Next.

18. On the Step 11 screen (Database Storage), click Next.

19. On the Step 12 screen (Creation Options), accept the default selection of Create Database and click Finish.

To Create a Database User

To create a database user, use the sqlplus utility.

1. Become superuser by issuing the following command:

   su - oracle

2. Start the sqlplus utility:

   sqlplus /nolog

3. At the prompt, connect to the database:

   sqlplus>connect / as sysdba

4. Create a user and specify the password for the user:

   sqlplus>create user user-name identified by password;

   The password value must be at least six characters.

   For example, to specify a user named APP and a password of app123, you would use the following command:

   sqlplus>create user APP identified by app123;

5. Grant privileges to the user you created:

   sqlplus>grant connect, resource, dba to APP;

6. Exit the utility:

   exit

To Edit the tnsnames.ora File

To allow multiple clients to connect to the database over a network, edit the file tnsnames.ora.

1. Go to the directory Oracle-base/product/10.1.0/db_1/network/admin/.

2. Open the file tnsnames.ora in a text editor.

3. At the end of the file, append the following:

   SOAR =
     (DESCRIPTION =
       (ADDRESS = (PROTOCOL = TCP)(HOST = host.domain)(PORT = 1521))
       (CONNECT_DATA =
         (SERVER = SHARED)
         (SERVICE_NAME = soar)
       )
     )

   For host.domain, substitute the full domain name of the system where the database is installed.

Configuring Service Registry with a Non-Default Application Server Location

The default location for installing Application Server is Appserver-base, as described in Default Paths and File Names. If you installed Application Server in a different location, you must edit a copy of the file install.properties before you configure Service Registry.

To Edit a Copy of the install.properties File

1. Change to the ServiceRegistry-base/install directory.

2. Copy the file install.properties.template to a secure location and rename it.

   Use a command like the following:

   cp install.properties.template $HOME/hidden_dir/sr.properties

3. Change the permissions on the properties file to make it writable.

   Use a command like the following:

   chmod 600 $HOME/hidden_dir/sr.properties

4. Open the file in a text editor.

5. Find the commented-out definition of the property appserver.root.dir.

6. Remove the comment character (#) and replace the property definition with the actual location of Application Server.

7. Edit the file to specify the required passwords.

8. Save and close the file.

Next Steps

Continue with the instructions in Configuring Service Registry.

Configuring Service Registry with Application Server 9.1

The version of Application Server in Java ES 5 Update 1 is 8.2. It is possible, however, to install Service Registry on Application Server 9.1.

To Configure Service Registry with Application Server 9.1

1. If an Application Server 8.2 domain for the Registry is running, stop the domain:

   1. Change to the Service Registry install directory.

      cd ServiceRegistry-base/install

   2. Run the following command:

      Ant-base/ant -f build-install.xml -Dinstall.properties=props-file appserver.domain.stop

2. Install Application Server 9.1 in a location of your choice.

3. Deploy Service Registry on Application Server 9.1:

   Ant-base/ant -f build-install.xml -Dinstall.properties=props-file appserver.deploy.as9

4. Run the Application Server upgrade utility. Use the following command (Appserver-base is the location where you installed Application Server 9.1):

   Appserver-base/bin/asupgrade

   For the Source Domain Directory, specify RegistryDomain-base/domains/registry. For example, on a Linux system you would specify /var/opt/sun/srvc-registry/domains/registry.

   For the Target Domains Root Directory, specify RegistryDomain-base without registry. For example, on Linux you would specify /var/opt/sun/srvc-registry/domains/. The upgraded domain will also be named registry.

   ---

   Note –

   This step instructs you to create an Application Server 9.1 domain for the Registry in the same location as the previous domain (the term for this is an in-place upgrade). If you specify a different location for the Target Domains Root Directory (the term for this is a side-by-side upgrade), you must perform the task To Create a New Certificate Realm after you complete the current task.

   ---

5. Start the Application Server domain for the Registry.

   Ant-base/ant -f build-install.xml -Dinstall.properties=props-file appserver.domain.start

Next Steps

If you performed a side-by-side upgrade instead of an in-place upgrade, as described in Step 4, you must now perform the task To Create a New Certificate Realm.

For the Application Server 9.1 documentation, go to http://docs.sun.com/coll/1343.4.

To Create a New Certificate Realm

1. Change to the Appserver-base/bin directory.

2. Run the following command to remove any existing certificate realm (there should not be one):

   ./asadmin delete-auth-realm --host localhost --port 6489 certificate

3. Run the following command (all on one line) to create a new certificate realm:

   ./asadmin create-auth-realm --terse=false --echo=true --interactive=true --user admin --host localhost --port 6489 --classname com.sun.enterprise.security.auth.realm.certificate.CertificateRealm --property assign-groups=have.client.cert certificate

4. Stop and restart the Application Server domain, as described in To Stop and Restart the Application Server Domain for the Registry.