<!--Arbortext, Inc., 1988-2007, v.4002-->
<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD SolBook 3.5//EN" [
<!ENTITY options-common SYSTEM "options-common.sgm">
<!ENTITY synopsis-common SYSTEM "synopsis-common.sgm">
<!ENTITY % commonents SYSTEM "common.ent">
%commonents;
]>
<?Pub UDT _bookmark _target>
<?Pub CX solbook(>
<refentry id="create-instance-1"><?Pub Tag atict:info tracking="off" ref="2"><?Pub Tag
atict:user user="hl34125" fullname=""><?Pub Tag atict:user user="pmdavies"
fullname=""><?Pub Tag atict:user user="ah95648" fullname="">
<!-- @(#)create-instance.1 1.12 07/07/24 SMI; -->
<refmeta><refentrytitle>create-instance</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="date">9 Jul 2007</refmiscinfo>
<refmiscinfo class="sectdesc">&man1;</refmiscinfo>
<refmiscinfo class="software">&software;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright">Copyright (c) 2007, Sun Microsystems, Inc.
All Rights Reserved</refmiscinfo>
</refmeta>
<refnamediv><indexterm><primary>create-instance</primary></indexterm><indexterm>
<primary>creates an instance</primary></indexterm>
<refname>create-instance</refname><refpurpose>creates an instance</refpurpose>
</refnamediv>
<refsynopsisdiv><title></title>
<synopsis><command>create-instance</command>  <option role="double-dash">nodeagent
</option> <replaceable>nodeagent_name</replaceable>&synopsis-common; [<option
role="double-dash">config</option> <replaceable>config_name | </replaceable><option
role="double-dash">cluster</option> <replaceable>cluster_name</replaceable>]
 [<option role="double-dash">systemproperties</option> (<replaceable>name</replaceable>=<replaceable>
value</replaceable>)[:<replaceable>name</replaceable>=<replaceable>value</replaceable>]* ]
 <replaceable>instance_name</replaceable></synopsis>
</refsynopsisdiv>
<refsect1 role="description"><title></title>&cmd-clust-domain-only;
<para>Use the create-instance command to create a new server instance residing
on a local or remote machine. For a server instance to be functional it must
have:</para>
<itemizedlist>
<listitem><para>A reference to a node agent, which defines the machine where
the server instance resides.</para></listitem>
<listitem><para>A reference to a configuration, which defines the configuration
of the instance. A server instance that is joining a cluster receives its
configuration from its parent cluster.</para></listitem>
</itemizedlist>
<para>The node agent does not need to be started to create the instance; however,
if the node agent is running, a remote server instance is created in a stopped
state. If the node agent is not running, domain.xml is updated with the instance
information and a new server instance is created the next time the node agent
is started.</para>
<para>There are three types of server instances that can be created. Each
server instance can only be of one type:</para>
<orderedlist>
<listitem><para>Standalone server instance: the configuration for this instance
is not shared by any other server instances or clusters. When a standalone
server instance is created, a standalone configuration is also created based
on the <filename>default-config</filename> configuration. If no configuration
or cluster is identified, a standalone server instance is created by default.The
name of this configuration will be <filename>server&mdash;name-config</filename> where
server&mdash;name represents the name of an unclustered server instance. Formally,
a standalone server instance has a configuration named <filename>server&mdash;name-config
</filename> and is the only instance referencing this configuration.</para>
</listitem>
<listitem><para>Shared server instance: the configuration for this instance
is shared with other server instances or clusters. A server instance is considered
shared if its configuration is shared by any other server instances.</para>
</listitem>
<listitem><para>Clustered server instance: the configuration for this instance
is shared with other instances in the cluster. A server instance that is a
member of the cluster inherits its configuration from that cluster. Any server
instance that is not part of a cluster is considered an unclustered server
instance. Standalone server instances and shared server instances can be considered
unclustered server instances.</para></listitem>
</orderedlist>
<para>When creating server instances, Communications Server<?Pub Caret> attempts
to resolve possible port conflicts. It also assigns random ports, currently
not in use and not already assigned to other instances on the same node agent.
Use the <option role="double-dash">systemproperties</option> option to create
additional instances on the same node agent and specify system properties
to resolve the port conflicts. System properties can be manipulated after
instance creation using the system property commands.</para>
</refsect1>
<refsect1 role="options"><title></title>
<variablelist termlength="wholeline">
<varlistentry><term><option role="double-dash">nodeagent</option></term>
<listitem><para>The name of the node agent defining the machine where the
server will be created. The node agent does not need to be running. </para>
</listitem>
</varlistentry>&options-common;
<varlistentry><term><option role="double-dash">config</option></term>
<listitem><para>Creates a shared server instance. The configuration name must
exist and must not be named <filename>default-config</filename> or <filename>server-config
</filename>. If the configuration name provided is a standalone configuration,
an error is displayed. </para>
<para>The --config and --cluster options are mutually exclusive. If both are
omitted, a standalone server instance is created. </para>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">cluster</option></term>
<listitem><para>Creates a clustered server instance that inherits its configuration
from the named cluster.</para>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">systemproperties</option></term>
<listitem><para>Defines system properties for the server instance. These properties
override property definitions in the server instance's configuration. Currently,
these properties allow a way for a server instance to override port settings
defined in its configuration. This is necessary if for example two clustered
instances (sharing the same configuration) reside on the same machine. The
following properties are available:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>HTTP_LISTENER_PORT</literal></term>
<listitem><para>This property specifies the port number of the port that is
used to listen for HTTP requests. Valid values are 1&ndash;65535. On UNIX,
creating sockets that listen on ports 1&ndash;1024 requires superuser privileges.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>HTTP_SSL_LISTENER_PORT</literal></term>
<listitem><para>This property specifies the port number of the port that is
used to listen for HTTPS requests.  Valid values are 1&ndash;65535. On UNIX,
creating sockets that listen on ports 1&ndash;1024 requires superuser privileges.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>IIOP_LISTENER_PORT</literal></term>
<listitem><para>This property specifies the port number of the port that is
used for IIOP connections.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>IIOP_SSL_LISTENER_PORT</literal></term>
<listitem><para>This property specifies the port number of the port that is
used for secure IIOP connections.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>IIOP_SSL_MUTUALAUTH_PORT</literal></term>
<listitem><para>This property specifies the port number of the port that is
used for secure IIOP connections with client authentication.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>JMX_SYSTEM_CONNECTOR_PORT</literal></term>
<listitem><para>This property specifies the port number on which the JMX connector
listens. Valid values are 1&ndash;65535. On UNIX, creating sockets that listen
on ports 1&ndash;1024 requires superuser privileges.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="operands"><title></title>
<variablelist termlength="medium">
<varlistentry><term><replaceable>instance_name</replaceable></term>
<listitem><para>The unique name of the instance being created. Each instance
in the domain must have a unique name across all node agents, server instances,
cluster names, and configuration names.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="examples"><title></title>
<example><title>Using the create-instance command</title>
<screen>asadmin> <userinput>create-instance --user admin --passwordfile password.txt 
--host myhost --port 4848 --nodeagent agent1 instance1</userinput>
Command create-instance executed successfully</screen>
<para>Where: instance1 is created on a machine where node agent, agent1 resides.</para>
</example>
<example><title>Using the create-instance command with systemproperties</title>
<screen>asadmin> <userinput>create-instance --user admin --passwordfile password.txt 
--host myhost --port 4848 --nodeagent apple_agent 
--systemproperties HTTP_LISTENER_PORT=58294:
HTTP_SSL_LISTENER_PORT=58297:IIOP_LISTENER_PORT=58300:
IIOP_SSL_LISTENER_PORT=58303:IIOP_SSL_MUTUALAUTH_PORT=58306:
JMX_SYSTEM_CONNECTOR_PORT=58309 instance2</userinput>
Command create-instance executed successfully</screen>
<para>Where: instance2 is created on a remote machine apple where node agent,
apple_agent resides.</para>
</example>
</refsect1>
<refsect1 role="exit-status"><title></title>
<variablelist termlength="medium">
<varlistentry><term>0</term>
<listitem><para>command executed successfully</para>
</listitem>
</varlistentry>
<varlistentry><term>1</term>
<listitem><para>error in executing the command</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="errors"><title></title>
<variablelist termlength="medium">
<varlistentry><term>0</term>
<listitem><para>error message</para>
</listitem>
</varlistentry>
<varlistentry><term>1</term>
<listitem><para>error message</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="see-also"><title></title>
<para><olink targetdoc="asrefman" targetptr="delete-instance-1">delete-instance(1)
</olink>,<olink targetdoc="asrefman" targetptr="list-instances-1">list-instances(1)
</olink>, <olink targetdoc="asrefman" targetptr="start-instance-1">start-instance(1)
</olink>, <olink targetdoc="asrefman" targetptr="stop-instance-1">stop-instance(1)
</olink></para>
</refsect1>
</refentry>
<?Pub *0000010463 0>
