<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1999, v.4002-->
<!ENTITY metainfo SYSTEM "metainfo.sgm">
<!ENTITY options-common SYSTEM "options-common.sgm">
<!ENTITY synopsis-common SYSTEM "synopsis-common.sgm">
<!ENTITY % commonents SYSTEM "smancommon.ent">
%commonents;
<!ENTITY % booktitles SYSTEM "booktitles.ent">
%booktitles;
<!ENTITY Dash "&ndash;">
]>
<?Pub UDT _bookmark _target>
<?Pub EntList brvbar bull cross dash diam diams frac12 frac13 frac14 hellip
 laquo lArr loz mdash nabla ndash para pound rArr raquo sect yen ne>
<?Pub Inc>
<refentry id="create-instance-1">
<refmeta><refentrytitle>create-instance</refentrytitle><manvolnum>1</manvolnum>&metainfo;
</refmeta>
<refnamediv><indexterm><primary sortas="create-instance">create-instance &mdash;
creates an instance</primary></indexterm><indexterm><primary sortas="creates an instance">
creates an instance &mdash; create-instance</primary></indexterm><refname>
create-instance</refname><refpurpose>creates an instance</refpurpose></refnamediv>
<refsynopsisdiv><title>&synp-tt;</title>
<cmdsynopsis><command>create-instance</command><arg choice="plain"><option
role="nodash">&Dash;&Dash;nodeagent</option> <replaceable>nodeagent_name</replaceable></arg>&synopsis-common;
<arg><option role="nodash">&Dash;&Dash;config</option> <replaceable>config_name | 
</replaceable><option role="nodash">&Dash;&Dash;cluster</option> <replaceable>
cluster_name</replaceable></arg><arg><option role="nodash">&Dash;&Dash;systemproperties (<replaceable>
name</replaceable>=<replaceable>value</replaceable>)[:<replaceable>name</replaceable>=<replaceable>
value</replaceable>]* </option></arg><arg choice="plain"><replaceable>instance_name
</replaceable></arg>
</cmdsynopsis></refsynopsisdiv>
<refsect1><title>&desc-tt;</title>
<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>
<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>The node agent does not need to be created or 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>
<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>
<para>When creating server instances, Application Server 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="nodash">&Dash;&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><title>&opts-tt;</title>
<variablelist termlength="medium">
<varlistentry><term><option role="nodash">&Dash;&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 or even
created. If the node agent does not exist, a placeholder will automatically
be created in domain.xml.</para>
</listitem></varlistentry><?Pub Caret>&options-common;
<varlistentry><term><option role="nodash">&Dash;&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="nodash">&Dash;&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="nodash">&Dash;&Dash;lbweight</option></term>
<listitem><para>Helps assign weight for the server instance</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;&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>
<para><informaltable frame="all" orient="port">
<tgroup cols="2">
<?PubTbl tgroup dispwid="9.17in">
<colspec colname="col1" colwidth="0.68*"><colspec colname="col2" colwidth="1.32*">
<thead>
<row><entry align="center" valign="top"><para> Property</para></entry><entry
align="center" valign="top"><para>Definition</para></entry></row>
</thead>
<tbody>
<row><entry colname="col1" align="center"><para>http-listener-1&ndash;port
</para></entry><entry colname="col2" align="center"><para>This port is used
to listen for HTTP requests. This property specifies the port number for http-listener-1.
Valid values are 1&ndash;65535. On UNIX, creating sockets that listen on ports
1&ndash;1024 requires superuser privileges.</para></entry></row>
<row><entry colname="col1" align="center"><para>http-listener-2&ndash;port
</para></entry><entry colname="col2" align="center"><para>This port is used
to listen for HTTPS requests. This property specifies the port number for
http-listener-2. Valid values are 1&ndash;65535. On UNIX, creating sockets
that listen on ports 1&ndash;1024 requires superuser privileges.</para></entry>
</row>
<row><entry colname="col1"><para>orb-listener-1&ndash;port</para></entry>
<entry colname="col2"><para>This property specifies which ORB listener port
for IIOP connections orb-listener-1 listens on. </para></entry></row>
<row><entry colname="col1"><para>IIOP_SSL_LISTENER_PORT</para></entry><entry
colname="col2"><para>This port is used for secure IIOP connections.</para></entry>
</row>
<row><entry colname="col1"><para>IIOP_SSL_MUTUALAUTH_PORT</para></entry><entry
colname="col2"><para>This property specifies which ORB listener port for IIOP
connections the IIOP listener called SSL_MUTUALAUTH listens on.</para></entry>
</row>
<row><entry colname="col1"><para>JMS_SYSTEM_CONNECTOR_PORT</para></entry>
<entry colname="col2"><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></entry>
</row>
</tbody>
</tgroup>
</informaltable></para>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1><title>&oper-tt;</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><title>&exam-tt;</title>
<example>
<title>Using the create-instance command</title>
<screen>asadmin> <userinput>create-instance --user admin --passwordfile password.txt 
--host myhost --port 4849 --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 4849 --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><title>&exit-tt;</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><title>&erro-tt;</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><title>&also-tt;</title>
<para><link linkend="delete-instance-1"><citerefentry><refentrytitle>delete-instance
</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,<link linkend="list-instances-1"><citerefentry>
<refentrytitle>list-instances</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>, <link
linkend="start-instance-1"><citerefentry><refentrytitle>start-instance</refentrytitle>
<manvolnum>1</manvolnum></citerefentry></link>, <link linkend="stop-instance-1"><citerefentry>
<refentrytitle>stop-instance</refentrytitle><manvolnum>1</manvolnum></citerefentry></link></para>
</refsect1>
</refentry>
<?Pub *0000011584>
