<!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 ERROR-CODES "ERROR CODES">
<!ENTITY Date "22 Dec 2004">
<!ENTITY SectDesc "User Commands">
<!ENTITY Software "J2EE SDK 1.4">
<!ENTITY arch "generic">
<!ENTITY copyright "Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved">
<!ENTITY exam-tt "EXAMPLES">
<!ENTITY options-common SYSTEM "options-common.sgm">
<!ENTITY synopsis-common SYSTEM "synopsis-common.sgm">
<!ENTITY sjsas "Sun Java System Application Server">
<!ENTITY attr-tt "ATTRIBUTES">
<!ENTITY opts-tt "OPTIONS">
<!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-domain-1">
<refmeta><refentrytitle>create-domain</refentrytitle><manvolnum>1</manvolnum>&metainfo;
</refmeta>
<refnamediv><indexterm><primary sortas="create-domain">create-domain &mdash;
creates a domain with the given name</primary></indexterm><indexterm><primary
sortas="creates a domain with the given name">creates a domain with the given
name &mdash; create-domain</primary></indexterm><refname>create-domain</refname>
<refpurpose>creates a domain with the given name</refpurpose></refnamediv>
<refsynopsisdiv><title>&synp-tt;</title>
<cmdsynopsis><command>create-domain</command><arg choice="opt">&Dash;&Dash;user <replaceable>
user</replaceable></arg><arg>&Dash;&Dash;passwordfile <replaceable>passwordfile
</replaceable></arg><arg choice="opt">(&Dash;&Dash;adminport <replaceable>
port_number</replaceable> | &Dash;&Dash;portbase <replaceable>portbase</replaceable>)
</arg><arg choice="opt">(&Dash;&Dash;profile <replaceable>profile_name</replaceable> | &Dash;&Dash;template <replaceable>
domain_template</replaceable>)</arg><arg>&Dash;&Dash;domaindir <replaceable>
domain_directory</replaceable>/domains</arg><arg>&Dash;&Dash;instanceport <replaceable>
port_number</replaceable></arg><arg>&Dash;&Dash;savemasterpassword=<replaceable>
false</replaceable></arg><arg choice="opt"><option role="nodash">&Dash;&Dash;domainproperties (<replaceable>
name</replaceable>=<replaceable>value</replaceable>)[:<replaceable>name</replaceable>=<replaceable>
value</replaceable>]*</option></arg><arg choice="opt">&Dash;&Dash;savelogin=<replaceable>
false</replaceable></arg><arg choice="opt">&Dash;&Dash;terse=<replaceable>
false</replaceable></arg><arg>&Dash;&Dash;echo=<replaceable>false</replaceable></arg>
<arg>&Dash;&Dash;interactive=<replaceable>true</replaceable></arg><arg choice="plain"><replaceable>
domain_name</replaceable></arg>
</cmdsynopsis></refsynopsisdiv>
<refsect1><title>&desc-tt;</title>
<para>Use the <command>create-domain</command> command to create an administrative
domain. </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 of application server. 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 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 youwant to run on your new domain. You can choose the developer, cluster,
or enterprise profile for the domain you create. </para>
<para>This command is supported in local mode only.</para>
</refsect1>
<refsect1><title>&opts-tt;</title>
<variablelist termlength="medium">
<varlistentry><term><option role="nodash">&Dash;&Dash;user</option></term>
<listitem><para>The username of the adminstrator of the domain.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;t</option> <option role="nodash">&Dash;&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="nodash">&Dash;e</option> <option role="nodash">&Dash;&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 role="nodash">&Dash;I</option> <option role="nodash">&Dash;&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="nodash">&Dash;&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="nodash">&Dash;&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>
<note><para>We will modify this after Beta. </para>
</note>
<para>Valid values for this option are: </para>
<itemizedlist>
<listitem><para>developer: Use this profile if you are running your domain
in a development environment and if your applications do not need enterprise
features, such as clustering, high availability, NSS keystore, or session
replication.</para>
</listitem>
<listitem><para>cluster: Use this profile if you need to create clusters but
do not require high availability features or NSS keystore. </para>
</listitem>
<listitem><para>enterprise: Use this profile if you need all enterprise features.
The default value of this option for <?Pub Caret>a given installation is determined
by the AS_ADMIN_PROFILE variable in the <filename>asadminenv.conf</filename>
file.</para>
</listitem>
</itemizedlist>
<note><para>Profile names are case-sensitive. Use all profile names in lower
case only. </para>
</note>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;&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="nodash">&Dash;&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="nodash">&Dash;&Dash;portbase</option> option.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;&Dash;passwordfile</option></term>
<listitem><para>The file containing the domain application server 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 application
server security policy, <command>asadmin</command> does not accept clear text
passwords on the command line. </para>
<para>If AS_ADMIN_PASSWORD and AS_ADMIN_MASTERPASSWORD are not in the passwordfile, <command>
create-domain</command> command prompts for admin password and master password.
If AS_ADMIN_PASSWORD is present in the file that is passed into <option>&Dash;&Dash;passwordfile
</option> option, the <command>create-domain</command> command does not prompt
for the master password. In this case, AS_ADMIN_MASTERPASSWORD defaults to
the value, <literal>changeit</literal>.</para>
<para>Additionally, you may omit the <option role="nodash">&Dash;&Dash;passwordfile
</option> from the command line and allow the system to prompt you for these
options.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">&Dash;t</option> <option role="nodash">&Dash;&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="nodash">&Dash;&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="nodash">&Dash;&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="nodash">&Dash;&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>jms.port: Specifies the port number for JMS. Valid value is
7676.</para>
</listitem>
<listitem><para>jms.port: Specifies the port number for JMS. Valid value is
7676.</para>
</listitem>
<listitem><para>jdomain.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="nodash">&Dash;&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="nodash">&Dash;&Dash;portbase
</option> option is specified.</para>
<note><para>The <option role="nodash">&Dash;&Dash;portbase</option> option
cannot be used with the <option role="nodash">&Dash;&Dash;adminport</option>
or the <option role="nodash">&Dash;&Dash;instanceport</option> option.</para>
</note>
</listitem></varlistentry>
<varlistentry><term> <option role="nodash">&Dash;&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="nodash">&Dash;&Dash;user
</option>, <option role="nodash">&Dash;&Dash;passwordfile</option>, <option
role="nodash">&Dash;&Dash;host</option>, or <option role="nodash">&Dash;&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><title>&oper-tt;</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><title>&exam-tt;</title>
<example>
<title>Using the create-domain command (developer profile)</title>
<para>The following command creates <filename>domain4</filename> domain with
developer profile.</para>
<screen>asadmin><userinput>create-domain --adminport 4848 --profile developer domain4
</userinput>
Please enter the admin user name>admin
Please enter the admin password>
Please enter the admin password again>
Please enter the master password>
Please enter the master password again>
Using port 4848 for Admin.
Using default port 8080 for HTTP Instance.
Using default port 7676 for JMS.
Using default port 3700 for IIOP.
Using default port 8181 for HTTP_SSL.
Using default port 3820 for IIOP_SSL.
Using default port 3920 for IIOP_MUTUALAUTH.
Using default port 8686 for JMX_ADMIN.
Domain being created with profile:developer, as specified on command line or environment.
Security Store used should be JKS
Domain domain4 created.

</screen>
</example>
<example>
<title>Using the create-domain command (enterprise profile)</title>
<para>The following command creates <filename>sampleDomain</filename> domain
with enterprise profile in the <filename>/export/domains</filename> directory. 
</para>
<screen>asadmin> <userinput> create-domain --domaindir /export/domains --adminport 7070 --adminuser admin --instanceport 7071 sampleDomain
</userinput>
Please enter the admin password>
Please enter the admin password again>
Please enter the master password>
Please enter the master password again>
Using port 7070 for Admin.
Using default port 8080 for HTTP Instance.
Using default port 7676 for JMS.
Using default port 3700 for IIOP.
Using default port 8181 for HTTP_SSL.
Using default port 3820 for IIOP_SSL.
Using default port 3920 for IIOP_MUTUALAUTH.
Using default port 8686 for JMX_ADMIN.
Domain being created with profile:enterprise, as specified by variable AS_ADMIN_PROFILE in configuration file.
Security Store used should be NSS
Domain sampleDomain created.</screen>
</example>
<note><para>In this example, the domain, <literal>sampleDomain</literal>,
takes the enterprise profile though the <option>&Dash;&Dash;profile</option>
option is not specified, because AS_ADMIN_PROFILE in the configuration file
is set to enterprise profile. </para>
</note>
<example>
<title>Using the create-domain command (savelogin)</title>
<para>The following command creates the <filename>myDomain</filename> domain
with the enterprise profile and saves the admin username and password.</para>
<screen>asadmin> <userinput> create-domain --adminport 8282 --adminuser admin --savelogin=true myDomain
</userinput>
Please enter the admin user name>admin
Please enter the admin password>
Please enter the admin password again>
Please enter the master password>
Please enter the master password again>
Using port 8282 for Admin.
Using default port 8080 for HTTP Instance.
Using default port 7676 for JMS.
Using default port 3700 for IIOP.
Using default port 8181 for HTTP_SSL.
Using default port 3820 for IIOP_SSL.
Using default port 3920 for IIOP_MUTUALAUTH.
Using default port 8686 for JMX_ADMIN.
Domain being created with profile:enterprise, as specified by variable AS_ADMIN_PROFILE in configuration file.
adSecurity Store used should be NSS
Domain myDomain created.
Login information relevant to admin user name [admin] for this domain [myDomain] stored at [/.asadminpass] successfully.
Make sure that this file remains protected. Information stored in this file will be used by asadmin commands to manage this domain.

</screen>
</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>&also-tt;</title>
<para><link linkend="login-1"><citerefentry><refentrytitle>login</refentrytitle>
<manvolnum>1</manvolnum></citerefentry></link>, <link linkend="delete-domain-1"><citerefentry>
<refentrytitle>delete-domain</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>, <link
linkend="start-domain-1"><citerefentry><refentrytitle>start-domain</refentrytitle>
<manvolnum>1</manvolnum></citerefentry></link>, <link linkend="stop-domain-1"><citerefentry>
<refentrytitle>stop-domain</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>, <link
linkend="list-domains-1"><citerefentry><refentrytitle>list-domains</refentrytitle>
<manvolnum>1</manvolnum></citerefentry></link></para>
</refsect1>
</refentry>
<?Pub *0000020417>
