id·io·syn·cra·sies with createinstance

Talking with someone today about using the $ORACLE_HOME/bin/createinstance command, I thought it might be worth a short post to explain its use a little.

What createinstance does is to create a new OC4J instance within the $ORACLE_HOME in which it is exected.

It's usage pattern is something like:

$ORACLE_HOME/bin/createinstance -instanceName FOO

Which will create a new OC4J instance named FOO in $ORACLE_HOME.

In effect this does several things:

1. It creates the directory structure to host the new OC4J instance and its respective configuration files and deployed applications.

$ORACLE_HOME
/j2ee
/foo
  /config
  /applications
  /application-deployments
 /connectors
 /...
/home

2. It updates the $ORACLE_HOME/opmn/conf/opmn.xml file, adds a new process-type entry to represent the new OC4J process to be managed and then calls OPMN to reload itself so it is aware of the new instance.

<process-type id="FOO" status="enabled">
<module-data>
<category id="start-parameters">
 <data id="java-options" value="-server ...">
</data>
<category id="stop-parameters">
 <data id="java-options" value="...">
</data>
</category>
<start timeout="600" retry="2">
<stop timeout="120">
<restart timeout="720" retry="2">
<port id="default-web-site" range="12501-12600"
protocol="ajp"></port>
<port id="rmi" range="12401-12500">
<port id="jms" range="12601-12700">
<process-set id="default_group" numprocs="1">
</process-set>                                                     

Now the thing of importance to note here is that there is an implicit assumption made. The new instance will be created as a CLONE of the "home" instance which is defined in the opmn.xml file. You have no explicit control over the shape of the new instance.

So what ... you may well say.

Well where this has an effect is in how the default-web-site port is configured -- if the home instance is configured to run in AJP mode then the new FOO instance would similarly be configured to run in AJP mode and will be preset with the default AJP port range of 12501-12600.

But if the home instance is configured to run in HTTP mode, then the new FOO instance will be configured to run in HTTP mode too -- in which case you must supply the port to use for the HTTP listener. The reason is that its common that a HTTP listener is configured to run at a known dedicated port instead of a range since its consumer is a user with a browser. So the port gets set to one known value.

If the default-web-site is running in HTTP mode then you MUST specify the port to use with the -port tag.

Here's the output when createinstance is run with the default-web-site set to run in HTTP mode:

[buttso@stadp57 bin]$ createinstance -instanceName FOO

Creating OC4J instance "FOO"...
Error creating new OC4J instance: Invalid protocol or port range.
This is a J2EE Server and Process Management install type.
Please specify the -port option on the command to create
the new instance.

So if the port is specified using the -port option

[buttso@stadp57 bin]$ createinstance -instanceName FOO -port 5001
Creating OC4J instance "FOO"...
Set OC4J administrator's password for "FOO" (password text
will not be displayed as it is entered)
Enter password:   
Confirm password:   
The password for OC4J administrator "oc4jadmin" has been set.
New OC4J instance "FOO" has been created.

Then the resulting entry in OPMN is:

<process-type id="<span style=">FOO" module-id="OC4J" status="enabled">
<module-data>
<category id="start-parameters">
 <data id="java-options" value="-server -Djava.security.policy=...">
</data>
<category id="stop-parameters">
 <data id="java-options" value="-Djava.security.policy=...">
 </data>
</category>
<start timeout="600" retry="2">
<stop timeout="120">
<restart timeout="720" retry="2">
<port id="default-web-site" range="5001" protocol="http"></port>
<port id="rmi" range="12401-12500">
<port id="jms" range="12601-12700">
<process-set id="default_group" numprocs="1">
</process-set>

And to come to the end of a promised short but delivered long story, the default-web-site will be reachable directly using HTTP from a browser on port 5001.

Now if you want to change any of these settings of course you are free to do so by directly editing the $ORACLE_HOME/opmn/conf/opmn.xml to adjust the attributes to the desired values and then reload OPMN so they take effect.

Or you can use the opmnctl command to make a similar change. I usually do it by hand since I can remember the commands to operate vi ... ;-)