<!--Arbortext, Inc., 1988-2008, 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 EntList bull rArr sect>
<refentry id="create-domain-1">
<!-- @(#)create-domain.1 1.13 07/07/25 SMI; -->
<refmeta><refentrytitle>create-domain</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="date">4 Aug 2008</refmiscinfo>
<refmiscinfo class="sectdesc">&man1;</refmiscinfo>
<refmiscinfo class="software">&software;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright">Copyright (c) 2008, Sun Microsystems, Inc.
All Rights Reserved</refmiscinfo>
</refmeta>
<refnamediv><indexterm><primary>create-domain</primary></indexterm><indexterm>
<primary>creates a domain with the given name</primary></indexterm>
<refname>create-domain</refname><refpurpose>creates a domain. </refpurpose>
</refnamediv>
<refsynopsisdiv><title></title>
<synopsis><command>create-domain</command>  [<option role="double-dash">user</option> <replaceable>
user</replaceable>] [<option role="double-dash">passwordfile</option> <replaceable>
passwordfile</replaceable>]
 [(<option role="double-dash">adminport</option> <replaceable>port_number</replaceable> | <option
role="double-dash">portbase</option> <replaceable>portbase</replaceable>)]
 [(<option role="double-dash">profile</option> <literal>developer | cluster </literal> ] <option
role="double-dash">template</option> <replaceable>domain_template</replaceable>)]
 [<option role="double-dash">domaindir</option> <replaceable>domain_directory</replaceable>/domains]
 [<option role="double-dash">instanceport</option> <replaceable>port_number</replaceable>] [<option
role="double-dash">savemasterpassword</option>=<replaceable>false</replaceable>]
 [<option role="double-dash">domainproperties</option> (<replaceable>name</replaceable>=<replaceable>
value</replaceable>)[:<replaceable>name</replaceable>=<replaceable>value</replaceable>]*
]
 [<option role="double-dash">savelogin</option>=<replaceable>false</replaceable>] [<option
role="double-dash">terse</option>=<replaceable>false</replaceable>]
 [<option role="double-dash">echo</option>=<replaceable>false</replaceable>] [<option
role="double-dash">interactive</option>=<replaceable>true</replaceable>]
 <replaceable>domain_name</replaceable></synopsis>
</refsynopsisdiv>
<refsect1 role="description"><title></title>
<para>Use the <command>create-domain</command> command to create an administrative
domain. <?Pub Caret></para>
<para>This  command creates the configuration of a domain. A domain is an
administrative namespace. Every domain has a configuration, which is stored
in a set of files. Any number of domains each of which has a distinct administrative
identity can be created in a given installation . A domain can exist  independent
of other domains. Any user who has access to the <command>asadmin</command> script
on a  given system can create a domain and store its configuration in a folder
of choice. By default, the domain configuration is created in the default
directory for domains. You can override this location to store the configuration
elsewhere.</para>
<para>A domain, in addition to being an administrative boundary, is also a
 fully compliant Java EE Server. This means that you can deploy your Java
EE  Applications to the domain and run them when the domain is started. A
domain provides all  the necessary environment and services that are essential
to run the applications. </para>
<para>A domain can be managed by tools such as the Administration GUI or <command>
asadmin</command>.</para>
<para>You choose an appropriate profile for the domain, depending on the applications
that you want to run on your new domain. You can choose the developer or cluster
for the domain you create. </para>
<para>This command is supported in local mode only.</para>
</refsect1>
<refsect1 role="options"><title></title>
<variablelist termlength="medium">
<varlistentry><term><option role="double-dash">user</option></term>
<listitem><para>The username of the adminstrator of the domain.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>t</option> <option role="double-dash">terse</option></term>
<listitem><para>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.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>e</option> <option role="double-dash">echo</option></term>
<listitem><para>Setting to true will echo the command line statement on the
standard output. Default is false.</para>
</listitem>
</varlistentry>
<varlistentry><term><option>I</option> <option role="double-dash">interactive</option></term>
<listitem><para>If set to true (default), only the required password options
are prompted.</para>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">domaindir</option></term>
<listitem><para>The directory where the domain is to be created. If specified,
the path must be accessible in the filesystem. If not specified, the domain
is created in the default domain directory.</para>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">profile</option></term>
<listitem><para>The profile of the domain. A usage profile depicts how a particular
domain is going to be used. It determines how the templates for various files
are customized. Currently, only the customization for domain.xml template
is supported. </para>
<para>Valid values for this option are: developer and cluster. The default
value for this option is set to developer if you have installed the product
without clustering capabilities.</para>
<note><para>Profile names are case-sensitive. Use all profile names in lower
case only. </para></note>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">template</option></term>
<listitem><para>The file name of a domain.xml template used to create the
domain. This allows domains of different types to be created. This also allows
you to define your own template. </para>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">adminport</option></term>
<listitem><para>The HTTP/S port for  administration. This is the port to which
you should point your browser  (example, http://localhost:&lt;this-port>)
to manage the domain. This option is mandatory unless you specify a value
for the <option role="double-dash">portbase</option> option.</para>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">passwordfile</option></term>
<listitem><para>The file containing the domain password associated with the
administrative instance. The <command>create-domain</command> command reads
values for AS_ADMIN_PASSWORD and the AS_ADMIN_MASTERPASSWORD from this file.
The password is defined in the following form: AS_ADMIN_PASSWORD=<replaceable>password
</replaceable>, where <replaceable>password</replaceable> is the actual administrator
password for the domain. This file can contain many other passwords required
by the <command>asadmin</command> commands.  In adherence to security policy, <command>
asadmin</command> does not accept clear text passwords on the command line. </para>
<para>If AS_ADMIN_PASSWORD or AS_ADMIN_MASTERPASSWORD are not in the passwordfile, <command>
create-domain</command> command prompts for admin password and master password. </para>
</listitem>
</varlistentry>
<varlistentry><term><option>t</option> <option role="double-dash">terse</option></term>
<listitem><para>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.</para>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">instanceport</option></term>
<listitem><para>As noted above, the  domain provides services so that applications
can run when deployed. This (HTTP) port specifies where the  web application
context roots are available for a Web browser to connect to. This port  is
a positive integer and must be available at the time of creation of the domain. </para>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">savemasterpassword</option></term>
<listitem><para>Setting this option to true allows the <command>masterpassword</command> to
be written to the file system. A master password is really a password for
the secure key store. A domain is designed to keep  its own certificate (created
at the time of domain creation) in a safe place in  the configuration location.
This certificate is called domain's SSL server certificate. When the  domain
is contacted by a Web browser over a secure channel (HTTPS), this certificate
is presented by the domain. The master password is supposed to protect this
 store (a file) that contains this certificate. This file is called <filename>keystore.jks
</filename> and is  created in the config directory of the domain created.
If however, this option is  chosen, the master password is saved on the disk
in domain's configuration location. The  master password is stored in a file
called <filename>master-password</filename>, which is a Java JCEKS type  keystore.
The only advantage of using this option is in case of unattended system  boots,
where at the time of start-domain, the master password is not prompted for,
 because it will be extracted from this file. </para>
<para>It is best to create a masterpassword when creating a domain, because
masterpassword is used by the <command>start-domain</command> command. For
security purposes, the default setting should be false, because saving the
masterpassword on the disk is an insecure practice, unless file system permissions
are properly set. If masterpassword is saved, then <command>start-domain</command> will
not prompt for it. Masterpassword gives an extra level of security to the
environment.</para>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">domainproperties</option></term>
<listitem><para>Setting the optional name/value pairs overrides the default
values for the properties of the domain to be created. The list must be separated
by the &ldquo;:&rdquo; character. The following properties are available:</para>
<itemizedlist>
<listitem><para>jms.port: Specifies the port number for JMS. Valid value is
7676.</para></listitem>
<listitem><para>domain.jmxPort: Specifies the port on which the JMX connector
is  initialized. The valid values are 1-65535.</para></listitem>
<listitem><para>orb.listener.port: Specifies the ORB listener port  for IIOP
connections on which orb-listener-1 listens . </para></listitem>
<listitem><para>http.ssl.port: Specifies the port number for http-listener-2.
Valid values are 1 to 65535. On UNIX, to create sockets that listen on ports
1&ndash;1024, you need superuser privileges.</para></listitem>
<listitem><para>orb.ssl.port: Specifies the ORB listener port for IIOP connections
on which the IIOP listener called SSL listens.</para></listitem>
<listitem><para>orb.mutualauth.port: Specifies the ORB listener port for IIOP
connections on which the IIOP listener called SSL_MUTUALAUTH listens.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry><term><option role="double-dash">portbase</option></term>
<listitem><para>Determines the number with which the port assignment should
start. A domain uses a certain number of ports that are statically assigned.
The portbase value determines where the assignment should start. Choose this
value judiciously. The values for the ports are calculated as follows: Admin
port: portbase + 48, HTTP listener port: portbase + 80, IIOP listener port:
portbase + 37, JMX port: portbase + 86. See the output of this command for
a complete list of occupied ports, when <option role="double-dash">portbase</option> option
is specified.</para>
<note><para>The <option role="double-dash">portbase</option> option cannot
be used with the <option role="double-dash">adminport</option> or the <option
role="double-dash">instanceport</option> option.</para></note>
</listitem>
</varlistentry>
<varlistentry><term> <option role="double-dash">savelogin</option></term>
<listitem><para>Saves the admin user name and password if you set this option
to true. The default value is false. The username and password are stored
in the <filename>.asadminpass</filename> file in user's home directory. A
domain can only be created locally and hence while using the above option,
the host name saved in <filename>.asadminpass</filename> will always be <literal>
localhost</literal>. If the user has specified default admin port while creating
the domain, there is no need to specify <option role="double-dash">user</option>, <option
role="double-dash">passwordfile</option>, <option role="double-dash">host</option>,
or <option role="double-dash">port</option> on any of the subsequent <command>asadmin
</command> remote commands. These values will be automatically obtained.</para>
<note><para>When the same user creates multiple domains having same admin
port number on the same or different machines (where the home directory is
NFS mounted), the command is not going to prompt whether the password should
be overwritten. It will always be overwritten. </para></note>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="operands"><title></title>
<variablelist termlength="medium">
<varlistentry><term><replaceable>domain_name</replaceable></term>
<listitem><para>The name of the domain to be created.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="examples"><title></title>
<example><title>Using the create-domain command (developer profile)</title>
<para>The following command creates <filename>sampleDomain</filename> domain
with developer profile. </para>
<screen>asadmin> <userinput>create-domain --adminport 5006 
--profile developer --adminuser admin domain3</userinput>
Please enter the admin user name>admin
Please enter the admin password>
Please enter the admin password again>
Please enter the master password [Enter to accept the default]:>
Please enter the master password again [Enter to accept the default]:>
Using port 5005 for Admin.
Default port 8080 for HTTP Instance is in use. Using 51871
Default port 7676 for JMS is in use. Using 51872
Default port 3700 for IIOP is in use. Using 51873
Default port 8181 for HTTP_SSL is in use. Using 51874
Default port 3820 for IIOP_SSL is in use. Using 51875
Default port 3920 for IIOP_MUTUALAUTH is in use. Using 51876
Default port 8686 for JMX_ADMIN is in use. Using 51877
Domain being created with profile:developer,as specified on command line 
or environment
----- Using Profile [developer] to create the domain ------
XML processing for profile: 
Base document [/home/SUNWappserver/lib/install/templates/default-domain.xml.template].
Profile name [developer]. Processing property [domain.xml.style-sheets].
Domain sampleDomain created.</screen>
</example>
<example><title>Using the create-domain command (cluster profile)</title>
<para>The following command creates <filename>domain2</filename> domain with
cluster profile.</para>
<screen>asadmin><userinput>create-domain --adminport 4647 --profile cluster domain2
</userinput>
Please enter the admin user name>admin
Please enter the admin password>
Please enter the admin password again>
Please enter the master password [Enter to accept the default]:>
Please enter the master password again [Enter to accept the default]:>
Using port 4647 for Admin.
Using default port 8080 for HTTP Instance.
Default port 7676 for JMS is in use. Using 51256
Default port 3700 for IIOP is in use. Using 51257
Using default port 8181 for HTTP_SSL.
Default port 3820 for IIOP_SSL is in use. Using 51258
Default port 3920 for IIOP_MUTUALAUTH is in use. Using 51259
Using default port 8686 for JMX_ADMIN.
Domain being created with profile:cluster, as specified on command line or environment.
------ Using Profile [cluster] to create the domain ------
XML processing for profile: Base document 
[/home/SUNWappserver/lib/install/templates/default-domain.xml.template]. 
Profile name [cluster]. Processing property [domain.xml.style-sheets].

Security Store uses: JKS
Domain domain2 created.

</screen>
</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="see-also"><title></title>
<para><olink targetdoc="asrefman" targetptr="login-1">login(1)</olink>, <olink
targetdoc="asrefman" targetptr="delete-domain-1">delete-domain(1)</olink>, <olink
targetdoc="asrefman" targetptr="start-domain-1">start-domain(1)</olink>, <olink
targetdoc="asrefman" targetptr="stop-domain-1">stop-domain(1)</olink>, <olink
targetdoc="asrefman" targetptr="list-domains-1">list-domains(1)</olink></para>
</refsect1>
</refentry>
<?Pub *0000017318 0>
