This chapter describes how to configure Service Registry after you install it and how to perform other administrative tasks.
This chapter contains the following sections:
The Sun Java Enterprise System 2005Q4 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, edit the file ServiceRegistry-base/install/install.properties before you perform the configuration.
The ServiceRegistry-base location is /opt/SUNWsoar in the Solaris operating environment and /opt/sun/SUNWsoar on Linux systems.
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 for a Non-Default Application Server Installation before you configure Service Registry.
The install.properties file contains a set of modifiable property settings. The properties that are listed in Table 1–1 are used by the installation process. Each property name has the prefix registry.install. (terminating in a period). Most of these properties set non-default ports for the Application Server domain created for the Registry.
Table 1–1 Service Registry Installation Properties
Property Name |
Description |
Default Property Value |
---|---|---|
DomainName |
Application Server domain name |
registry |
ServerInstancePort |
Application Server HTTP port. |
6060 |
ServerInstanceSecurePort |
Application Server HTTPS port. |
6443 |
ServerJMSPort |
Application Server Message Queue port |
6484 |
ServerIIOPPort |
Application Server IIOP port |
6485 |
ServerIIOPSecurePort |
Application Server IIOP secure port |
6486 |
ServerIIOPMutualAuthPort |
Application Server IIOP mutual authentication port |
6487 |
AdministrationJMXPort |
Application Server JMX port |
6488 |
AdministrationPort |
Application Server Administrative Server port |
6489 |
AdministratorUserID |
User name used to access Application Server Administrative Server |
admin |
AdministratorPassword |
Password used to access Application Server Administrative Server |
12345678 |
ApplicationServerKeystorePassword |
Password used to access Application Server keystore |
12345678 |
RegistryServerKeystorePassword |
Password used to access Service Registry keystore |
12345678 |
To configure the Registry, you must be logged in as root or become superuser.
Change to the ServiceRegistry-base/install directory.
Edit the modifiable properties in the file install.properties.
For security reasons, it is recommended that you not edit this file to change the password values. Instead, specify these values on the command line.
After editing the file, run the following command (all on one line):
On Solaris: /usr/sfw/bin/ant -f build-install.xml install
On Linux: /opt/sun/bin/ant --noconfig -f build-install.xml install
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
To specify changed passwords on the command line, specify the following options to the command (all on one line):
/usr/sfw/bin/ant -f build-install.xml -Dregistry.install.RegistryServerKeystorePassword=passwd1 -Dregistry.install.AdministratorPassword=passwd2 -Dregistry.install.ApplicationServerKeystorePassword=passwd3 install |
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/SUNWsoar in the Solaris operating environment and /var/opt/sun/SUNWsoar on Linux systems.
Review the output of the ant install command for any errors.
If there are no errors, you can now begin using the Web Console or the Admin Tool.
To perform Admin Tool tasks that are restricted to users with the role of administrator, you need to work around a bug by adding a JAR file to the Admin Tool manifest classpath.
Make sure you are still in the ServiceRegistry-base/install directory.
Copy the file soapprocessor.jar from the deployed Registry to the Registry lib directory. Execute the following command (all on one line):
cp RegistryDomain-base/domains/registry/applications/j2ee-modules/soar/WEB-INF/lib/soapprocessor.jar ../lib |
Run the admin.jar.manifest.fix installation target as follows:
On Solaris: /usr/sfw/bin/ant -f build-install.xml admin.jar.manifest.fix
On Linux: /opt/sun/bin/ant --noconfig -f build-install.xml admin.jar.manifest.fix
The configuration process for Service Registry by default creates an Application Server domain named registry, to which the Service Registry web application is deployed. This domain is in the RegistryDomain-base/domains/registry directory.
This location is different from the default location for Application Server domains, /var/opt/SUNWappserver/domains (Solaris) or /var/opt/sun/appserver/domains (Linux).
To administer the registry domain, you can use the Application Server Administration Console (“Admin Console”). You can use the Admin Console to start and stop the domain, view the server log, and perform other administrative tasks. See To Use the Application Server Admin Console for details.
You can also examine the server log directly. The log is in the file RegistryDomain-base/domains/registry/logs/server.log.
You can also use the asadmin command to administer the registry domain. Because the domain is not in the default location, you must specify the --domaindir option when you use asadmin commands that provide that option.
The password file for the registry domain is ServiceRegistry-base/pw.txt. Specify this password file as the argument to the --passwordfile option of asadmin commands when you administer the registry domain.
The registry domain uses a set of non-default ports so as not to cause conflicts with the default Application Server domain, domain1. Table 1–2 lists and describes these ports. For more information, see Ports in the Application Server in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.
Table 1–2 Service Registry Domain Default Ports
Port Value |
Description |
---|---|
6060 |
HTTP port |
6443 |
HTTPS over SSL |
6484 |
Message Queue port |
6485 |
IIOP port |
6486 |
IIOP SSL port |
6487 |
IIOP Mutual Authentication port |
6488 |
JMX port |
6489 |
Application Server domain administration port |
In a web browser, go to the URL https://hostname:6489/.
hostname is the system on which Application Server and Service Registry are running.
Accept the certificate that is offered.
A login page appears
On the login page, type admin in the User Name field.
Type the Application Server administrator password in the Password field. Use the value that you specified for the AdministratorPassword property when you configured the Registry. The default is 12345678.
Click Log In.
For details on using the Admin Console, refer to the online help for the Admin Console or to the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.
To change the logging level for Service Registry, follow the instructions in To configure log levels in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide. The property to specify in the Additional Properties area is org.apache.commons.logging.simplelog.log.org.freebxml.omar.
The configuration process for the Registry starts the Application Server domain in which the registry is deployed. After you perform certain administrative tasks, you need to stop and restart the domain. Examples of such tasks are Allowing Access to External Web Sites and Creating an Administrator.
The Admin Console informs you if you need to restart the domain. You can use the Admin Console to perform this task. If you are using the asadmin command, you can use Ant tasks to stop and start the domain.
Change to the Service Registry install directory.
cd ServiceRegistry-base/install
Run the following command (all on one line):
Solaris: /usr/sfw/bin/ant -f build-install.xml appserver.domain.bounce
Linux: /opt/sun/bin/ant --noconfig -f build-install.xml appserver.domain.bounce
This target stops the domain and then restarts it.
The build-install.xml file also contains separate Ant targets for stopping and starting the Registry domain. To stop the domain, use the Ant target appserver.domain.stop. To start the domain, use the Ant target appserver.domain.start.
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.
Download any root certificates that you want to support. Sites that provide root certificates include the following:
If necessary, use the unzip command to extract .cer files from the downloaded archive.
Some files have the suffix .der.
Copy the .cer files to the directory ServiceRegistry-base/install/cacerts.
Change to the directory ServiceRegistry-base/install.
Run the following command (all on one line):
Solaris: /usr/sfw/bin/ant -f build-install.xml install.cacerts
Linux: /opt/sun/bin/ant --noconfig -f build-install.xml install.cacerts
This command installs any certificates found in the directory ServiceRegistry-base/install/cacerts into the Application Server domain truststore.
You can use the list.cacerts target to make sure that the certificates have been installed correctly.
Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.
The default location for installing Application Server is /opt/SUNWappserver/appserver in the Solaris operating environment and /opt/sun/appserver on Linux systems. If you installed Application Server in a different location, you must edit the file install.properties before you configure Service Registry.
In the ServiceRegistry-base/install directory, open the file install.properties in a text editor.
Find the commented-out definition of the property appserver.root.dir.
Remove the comment character (#) and replace the property definition with the actual location of Application Server.
Save and close the install.properties file.
Continue with the instructions in Configuring Service Registry.
The default location for installing Service Registry is /opt/SUNWsoar in the Solaris operating environment and /opt/sun/SUNWsoar on Linux systems. If you installed Service Registry in a different location, you must edit the file install.properties before you configure Service Registry.
In the ServiceRegistry-base/install directory, open the file install.properties in a text editor.
Find the commented-out definition of the properties soar.sdk.home and soar.server.home.
For each property, remove the comment character (#) and replace the property definition with the actual location of Service Registry.
Save and close the install.properties file.
Continue with the instructions in Configuring Service Registry.
Any registry object can have an ExternalLink object, which specifies a URL associated with that registry object. In order for users to create ExternalLink objects, Service Registry must be able to validate the URL, and this task requires access to external web sites. If the Registry is deployed behind a firewall, you need to set a proxy configuration that allows this access.
Proxy configuration requires you to specify a web proxy host and port as Java Virtual Machine (JVM) options of the Application Server instance where Service Registry is deployed.
Log in to the Application Server Admin Console as described in To Use the Application Server Admin Console.
Expand the Configurations node.
Expand the server node, server-config (Admin Config).
Click JVM Settings.
Click the JVM Options tab.
Click Add JVM Option.
In the text field, type the following (all on one line):
-Dhttp.proxyHost=hostname.domainname -Dhttp.proxyPort=8080 |
The port value is usually 8080. If the port is different in your location, specify the correct value.
Click Save.
Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.
The Service Registry administration tool has some tasks that only a user who is registered as an administrator can perform. In addition, an administrator might be called upon to implement life cycle changes (for example, approvals) to objects other users submit.
An administrator can also change the default access control policy (ACP). However, writing an ACP is currently a manual process that requires knowledge of OASIS eXtensible Access Control Markup Language (XACML). For details, refer to Chapter 9, “Access Control Information Model,” of ebXML RIM 3.0, especially the examples in Sections 9.7.6 through 9.7.8. See Before You Read This Book for information on how to find the ebXML RIM 3.0 specification.
To register yourself as an administrator, follow these steps.
Perform user registration as described in Creating a User Account in Service Registry 3 2005Q4 User’s Guide
Remember the path name of the certificate you downloaded. The default name of the certificate file is generated-key.p12.
Obtain the unique identifier of your User object as follows:
Copy the certificate to the following location in your home directory, creating directories as needed:
$HOME/soar/3.0/jaxr-ebxml/security
Change to the directory RegistryDomain-base/domains/registry/applications/j2ee-modules/soar/WEB-INF/classes.
Open the file omar.properties in a text editor.
Find the definition of the property omar.security.authorization.registryAdministrators.
Edit the property definition by adding a vertical bar (|), followed by the logical identifier string that you made a note of in Step 2.
The property definition must all be on one line and must not contain spaces. After you finish, it will look something like this (all on one line):
omar.security.authorization.registryAdministrators= urn:freebxml:registry:predefinedusers:registryoperator| urn:uuid:77f5c196-79de-4286-8483-8d80def3583b
Save and close the omar.properties file.
Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.
To create additional administrators, you do not have to edit the omar.properties file. If you are an administrator, you can use either the Admin Tool or the Web Console to add users, and you can use the Web Console to classify the users as administrators.
As an administrator, you can customize some aspects of the Web Console display by editing configuration files. This section describes the following tasks:
For information about using the Web Console, see the Service Registry 3 2005Q4 User’s Guide.
Service Registry includes several predefined queries, which appear in the Web Console Search form in the Select Predefined Query drop-down list. As an administrator, you can add new queries to the drop-down list that are specific to your installation of the Registry.
Use the Web Console to publish an AdhocQuery object to the Registry.
The name and description you specify for the query will appear in the drop-down list of predefined queries. In the SQL statement for the query, specify placeholders for user-supplied data by enclosing them in pairs of single quotes, as follows:
select * from registryobject where id = ''$lid''
Make a note of the unique identifier of the AdhocQuery object and of any placeholders in the SQL statement.
Change to the directory RegistryDomain-base/3.0/jaxr-ebxml.
Open the file registry-browser-config.xml in a text editor.
Add an entry to the registry-browser-config.xml file, using the following format. Specify a Parameter element for each placeholder in the SQL statement.
<Query> <AdhocQueryRef id="unique_identifier"/> <Parameter parameterName="$placeholder_name" datatype="string"> <rim:Name> <rim:LocalizedString xml:lang="en" charset="UTF-8" value="parameter_name_in_en_locale"/> <rim:LocalizedString xml:lang="fr" charset="UTF-8" value="parameter_name_in_fr_locale"/> </rim:Name> <rim:Description> <rim:LocalizedString xml:lang="en" charset="UTF-8" value="parameter_description_in_en_locale"/> <rim:LocalizedString xml:lang="fr" charset="UTF-8" value="parameter_description_in_fr_locale"/> </rim:Description> </Parameter> ... </Query>
The unique_identifier is the unique identifier of the AdhocQuery object.
The parameterName attribute value for each parameter must come from a placeholder in the SQL statement for the query.
The datatype attribute can have any of the following values:
string: The parameter appears as a text field in the Search form.
taxonomyElement: The parameter appears as a drop-down list in the Search form. If you specify a taxonomyElement data type, the Name and Description elements must be followed by a SlotList element that looks like this:
<rim:SlotList> <rim:Slot name="domain"> <rim:ValueList> <rim:Value> classification_scheme_or_concept_id </rim:Value> </rim:ValueList> </rim:Slot> </rim:SlotList>
The classification_scheme_or_concept_id is the unique identifier of the classification scheme or concept whose concepts (or subconcepts) must appear in the drop-down list. You must publish the classification scheme if it does not already exist in the registry.
The slot name must be "domain".
boolean: The parameter appears as a checkbox in the Search form.
If the datatype is string or boolean, you can also add a defaultValue attribute to the Parameter element to specify a default value to appear in the Search form.
Specify localized string values for each parameter name and description for any locales you support. The parameter_name in the current locale appears as the label of the parameter in the Search form.
Use the existing entries in the registry-browser-config.xml file as a reference.
Save and close the registry-browser-config.xml file.
Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.
The query that appears as the default in the Select Predefined Query drop-down list is Basic Query, which allows users to search for registry objects by name, description, and classification.
As an administrator, you can change this default to a query that is appropriate to your installation. For example, you might want the default query to be a new predefined query that you added to the Registry, as described in Adding Predefined Queries. To make this change, edit a property in a configuration file.
Change to the directory RegistryDomain-base/domains/registry/applications/j2ee-modules/soar/WEB-INF/classes.
Open the file jaxr-ebxml.properties in a text editor.
Find the definition of the property jaxr-ebxml.thin.defaultQueryPanel. By default, this property is commented out:
#jaxr-ebxml.thin.defaultQueryPanel=
Remove the comment character (#).
Set the value of the property by specifying the logical identifier of the query that will be the default, as in the following example:
jaxr-ebxml.thin.defaultQueryPanel=urn:oasis:names:tc:ebxml-regrep:query:MyQuery
Save and close the jaxr-ebxml.properties file.
Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.
A tree structure of classification schemes appears in the following areas of the Web Console:
The Search form area, when Basic Query is selected
The Explore menu area
The ClassificationScheme/Concept Selector window that appears when you need to choose a concept for some kinds of registry objects
As an administrator, you can hide classification schemes from view if you do not want the classification schemes to be available to users of Service Registry. To hide classification schemes, define a property in a configuration file.
Change to the directory RegistryDomain-base/domains/registry/applications/j2ee-modules/soar/WEB-INF/classes.
Open the file jaxr-ebxml.properties in a text editor.
Set the property jaxr-ebxml.registryBrowser.ConceptsTreeModel.hiddenSchemesList by using the following syntax. All of the property definition must be on one line and must not contain spaces.
jaxr-ebxml.registryBrowser.ConceptsTreeModel.hiddenSchemesList= class_scheme_id1|class_scheme_id2|...
Specify the logical identifier of each classification scheme that is to be hidden. If you specify more than one identifier, separate the identifiers with a vertical bar (|), as in the following example:
jaxr-ebxml.registryBrowser.ConceptsTreeModel.hiddenSchemesList= urn:oasis:names:tc:ebxml-regrep:classificationScheme:StatusType| urn:oasis:names:tc:ebxml-regrep:profile:ws:classificationScheme:BindingType
Save and close the jaxr-ebxml.properties file.
Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.
By default, the Web Console displays 10 search results at a time for each query. If the search returns more than 10 results, users can display additional pages of results. As an administrator, you can modify the number of search results that appears on each page.
By default, the Web Console displays certain columns in the search results area. For each object, it displays the object type, name, description, version, and version comment. For some object types, a non-default display is configured. For example, for a ServiceBinding object, the display includes the endpoint instead of the version information. As an administrator, you can add configuration information to display non-default data for object types of your choice.
To perform each of these tasks, you edit a configuration file.
Change to the directory RegistryDomain-base/domains/registry/applications/j2ee-modules/soar/WEB-INF/classes.
Open the file jaxr-ebxml.properties in a text editor.
Find the definition of the property omar.client.thinbrowser.numSearchResults:
omar.client.thinbrowser.numSearchResults=10
Change the value 10 to the value you prefer.
Save and close the jaxr-ebxml.properties file.
Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.
Change to the directory RegistryDomain-base/3.0/jaxr-ebxml.
Open the file registry-browser-config.xml in a text editor.
Add an entry to the registry-browser-config.xml file, using the following format.
This example configures a non-default display for Service objects.
<ObjectTypeConfig className="org.freebxml.omar.client.xml.registry.infomodel.ServiceImpl" id="urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:Service"> <SearchResultsConfig> <SearchResultsColumn columnClass="java.lang.Object" columnHeader="Object Type" columnWidth="25" editable="false" method="getObjectType"/> <SearchResultsColumn columnClass="java.lang.Object" columnHeader="Name" columnWidth="25" editable="true" method="getName"/> <SearchResultsColumn columnClass="java.lang.Object" columnHeader="Description" columnWidth="30" editable="true" method="getDescription"/> <SearchResultsColumn columnClass="java.lang.Object" columnHeader="Status" columnWidth="15" method="getStatusAsString"/> <SearchResultsColumn columnClass="java.lang.Object" columnHeader="Version" columnWidth="5" method="getVersionName"/> </SearchResultsConfig> </ObjectTypeConfig>
The registry-browser-config.xml provides syntax for the ObjectTypeConfig element. Use the elements that are already in the file as examples. These elements configure the default display for registry objects as well as non-default displays for ExternalLink, ExtrinsicObject, and ServiceBinding objects.
For the most part, you can deduce the method names from the class attributes in the ebXML Registry Information Model Version 3.0 specification (see Before You Read This Book for details). The getStatusAsString method can be found in the RegistryObjectImpl implementation class. (This release of Service Registry does not include API documentation, however.)
Save and close the registry-browser-config.xml file.
Follow the instructions in To Stop and Restart the Application Server Domain for the Registry.
To verify the reconfiguration, use the Search or Explore menu of the Web Console to display the objects whose columns you changed.
If you need to uninstall and reinstall Service Registry, perform the following tasks before you reinstall:
If the Registry database contains data that you want to preserve, back up the database as described in Backing Up and Restoring the Database.
Stop the Application Server domain for the Registry, then delete the domain. If you do not delete the domain, post-install configuration of the reinstalled Registry will fail.
If you need to reinstall the Service Registry database (for example, if the database becomes corrupted), follow the instructions in To Reinstall the Service Registry Database. You do not need to uninstall the database before you reinstall it.
Change to the ServiceRegistry-base/install directory.
Run the following command (all on one line):
Solaris: /usr/sfw/bin/ant -f build-install.xml appserver.domain.stop
Linux: /opt/sun/bin/ant --noconfig -f build-install.xml appserver.domain.stop
Run the following command (all on one line):
Solaris: /usr/sfw/bin/ant -f build-install.xml appserver.domain.delete
Linux: /opt/sun/bin/ant --noconfig -f build-install.xml appserver.domain.delete
Change to the ServiceRegistry-base/install directory.
Run the following command (all on one line):
Solaris: /usr/sfw/bin/ant -f build-install.xml install.db
Linux: /opt/sun/bin/ant --noconfig -f build-install.xml install.db
The Registry uses the Apache Derby database. By default, the database is located in the directory RegistryDomain-base/3.0/data/registry/soar/.
To learn how to back up and restore the database, consult the Apache Derby documentation.
In a web browser, go to the Apache Derby web site.
Click the Manuals tab.
Click 10.0 Manuals.
Locate the Server & Admin Guide.
Locate the sections on backing up and restoring databases.