
Administration Commands                        create-instance(1)

NAME
     create-instance - creates an instance

SYNOPSIS
     create-instance  --nodeagent nodeagent_name
     [--terse={true|false}][ --echo={true|false} ]
     [ --interactive={true|false} ] [ --host  host]
     [--port port] [--secure| -s ] [ --user  admin_user]
     [--passwordfile filename] [--help]
     [ --config  config_name | --cluster cluster_name]
     [--systemproperties (name=value)[:name=value]* ]
     instance_name

DESCRIPTION
     Note -

       This command is available only in domains that are config-
       ured to support clusters, such as domains that are created
       with the cluster profile or the  enterprise  profile.  For
       information about profiles, see Usage Profiles in Sun Java
       System Application Server 9.1 Administration Guide.

     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:

         o    A reference to a  node  agent,  which  defines  the
              machine where the server instance resides.

         o    A reference to a configuration, which  defines  the
              configuration  of  the  instance. A server instance
              that is joining a cluster receives  its  configura-
              tion from its parent cluster.

     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.

     There are three  types  of  server  instances  that  can  be
     created. Each server instance can only be of one type:

         1.   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

Java EE 5            Last change: 9 Jul 2007                    1

Administration Commands                        create-instance(1)

              also created based on the default-config configura-
              tion. If no configuration or cluster is identified,
              a  standalone  server  instance   is   created   by
              default.The  name  of  this  configuration  will be
              server-name-config where server-name represents the
              name of an unclustered server instance. Formally, a
              standalone  server  instance  has  a  configuration
              named  server-name-config  and is the only instance
              referencing this configuration.

         2.   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.

         3.   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 clus-
              ter. 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.

     When  creating  server  instances,   Communications   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 --
     systemproperties 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.

OPTIONS
     --nodeagent

         The name of the node agent defining  the  machine  where
         the server will be created. The node agent does not need
         to be running.

     -t --terse
         Indicates that any output data  must  be  very  concise,
         typically avoiding human-friendly sentences and favoring
         well-formatted data for consumption by a script. Default
         is false.

Java EE 5            Last change: 9 Jul 2007                    2

Administration Commands                        create-instance(1)

     -e --echo

         Setting to true will echo the command line statement  on
         the standard output. Default is false.

     -I --interactive
         If set to true (default),  only  the  required  password
         options are prompted.

     -H --host

         The machine name where the domain administration  server
         is running. The default value is localhost.

     -p --port
         The HTTP/S port for administration. This is the port  to
         which  you  should point your browser in order to manage
         the domain. For example, http://localhost:4848.

         The default port number is 4848.

     -s --secure

         If set to true, uses SSL/TLS  to  communicate  with  the
         domain administration server.

     -u --user
         The authorized domain administration server  administra-
         tive username.

         If you have authenticated to a domain using the  asadmin
         login  command,  then  you  need  not specify the --user
         option  on  subsequent  operations  to  this  particular
         domain.

     --passwordfile

         The --passwordfile option specifies the name,  including
         the full path, of a file containing the password entries
         in a specific format. The entry for  the  password  must
         have  the AS_ADMIN_ prefix followed by the password name
         in uppercase letters.

         For example, to specify the domain administration server
         password,  use  an  entry  with  the  following  format:
         AS_ADMIN_PASSWORD=password, where password is the actual
         administrator  password.  Other  passwords  that  can be

Java EE 5            Last change: 9 Jul 2007                    3

Administration Commands                        create-instance(1)

         specified        include        AS_ADMIN_MAPPEDPASSWORD,
         AS_ADMIN_USERPASSWORD, and AS_ADMIN_ALIASPASSWORD.

         All remote commands must specify the admin  password  to
         authenticate to the domain administration server, either
         through --passwordfile or  asadmin  login,  or  interac-
         tively  on the command prompt. The asadmin login command
         can be used only to  specify  the  admin  password.  For
         other  passwords, that must be specified for remote com-
         mands, use the --passwordfile or enter them at the  com-
         mand prompt.

         If you have authenticated to a domain using the  asadmin
         login command, then you need not specify the admin pass-
         word through the  --passwordfile  option  on  subsequent
         operations  to  this particular domain. However, this is
         applicable only to AS_ADMIN_PASSWORD  option.  You  will
         still  need to provide the other passwords, for example,
         AS_ADMIN_USERPASSWORD, as and when required  by  indivi-
         dual commands, such as update-file-user.

         For security reasons, passwords specified as an environ-
         ment variable will not be read by asadmin.

         The  default  value   for   AS_ADMIN_MASTERPASSWORD   is
         changeit.

     --help

         Displays the help text for the command.

     --config
         Creates a shared server instance. The configuration name
         must  exist  and  must  not  be  named default-config or
         server-config. If the configuration name provided  is  a
         standalone configuration, an error is displayed.

         The  --config  and  --cluster   options   are   mutually
         exclusive.  If  both  are  omitted,  a standalone server
         instance is created.

     --cluster

         Creates a clustered server instance  that  inherits  its
         configuration from the named cluster.

     --systemproperties
         Defines system properties for the server instance. These

Java EE 5            Last change: 9 Jul 2007                    4

Administration Commands                        create-instance(1)

         properties  override  property definitions in the server
         instance's configuration.  Currently,  these  properties
         allow  a way for a server instance to override port set-
         tings 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:

         HTTP_LISTENER_PORT

             This property specifies the port number of the  port
             that  is  used  to  listen  for HTTP requests. Valid
             values are 1-65535. On UNIX, creating  sockets  that
             listen    on   ports   1-1024   requires   superuser
             privileges.

         HTTP_SSL_LISTENER_PORT
             This property specifies the port number of the  port
             that  is  used  to listen for HTTPS requests.  Valid
             values are 1-65535. On UNIX, creating  sockets  that
             listen    on   ports   1-1024   requires   superuser
             privileges.

         IIOP_LISTENER_PORT

             This property specifies the port number of the  port
             that is used for IIOP connections.

         IIOP_SSL_LISTENER_PORT
             This property specifies the port number of the  port
             that is used for secure IIOP connections.

         IIOP_SSL_MUTUALAUTH_PORT

             This property specifies the port number of the  port
             that is used for secure IIOP connections with client
             authentication.

         JMX_SYSTEM_CONNECTOR_PORT
             This property specifies the port number on which the
             JMX  connector listens. Valid values are 1-65535. On
             UNIX, creating sockets that listen on  ports  1-1024
             requires superuser privileges.

Java EE 5            Last change: 9 Jul 2007                    5

Administration Commands                        create-instance(1)

OPERANDS
     instance_name               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.

EXAMPLES
     Example 1 Using the create-instance command

       asadmin> create-instance --user admin --passwordfile password.txt
       --host myhost --port 4848 --nodeagent agent1 instance1
       Command create-instance executed successfully

     Where: instance1 is created on a machine where  node  agent,
     agent1 resides.

     Example 2 Using the create-instance command with  systempro-
     perties

       asadmin> 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
       Command create-instance executed successfully

     Where: instance2 is created on a remote machine apple  where
     node agent, apple_agent resides.

EXIT STATUS
     0                           command executed successfully

     1                           error in executing the command

ERRORS
     0                           error message

Java EE 5            Last change: 9 Jul 2007                    6

Administration Commands                        create-instance(1)

     1                           error message

SEE ALSO
     delete-instance(1),list-instances(1),     start-instance(1),
     stop-instance(1)

Java EE 5            Last change: 9 Jul 2007                    7

