blob: 50216964f2c212ad224a67c068eb85b9d758347a [file] [log] [blame]
type=page
status=published
title=create-domain
next=create-file-user.html
prev=create-custom-resource.html
~~~~~~
= create-domain
[[create-domain-1]][[GSRFM00023]][[create-domain]]
== create-domain
Creates a domain
[[sthref208]]
=== Synopsis
[source]
----
asadmin [asadmin-options] create-domain [--help]
[--adminport adminport]
[--instanceport instanceport]
[--portbase portbase]
[--profile profile-name]
[--template template-name]
[--domaindir domaindir]
[--savemasterpassword={false|true}]
[--usemasterpassword={false|true}]
[--domainproperties (name=value)[:name=value]*]
[--keytooloptions (name=value)[:name=value]*]
[--savelogin={false|true}]
[--checkports={true|false}]
[--nopassword={false|true}]
domain-name
----
[[sthref209]]
=== Description
The `create-domain` subcommand creates a {productName} domain. A
domain in {productName} is an administrative namespace that complies
with the Java Platform, Enterprise Edition (Jakarta EE) standard. 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 {productName}. A domain
can exist independently of other domains.
Any user who has access to the `asadmin` utility on a given system can
create a domain and store its configuration in a folder of the user's
choosing. By default, the domain configuration is created in the default
directory for domains. You can override this location to store the
configuration elsewhere.
If domain customizers are found in JAR files in the as-install``/modules``
directory when the `create-domain` subcommand is run, the customizers
are processed. A domain customizer is a class that implements the
`DomainInitializer` interface.
The `create-domain` subcommand creates a domain with a single
administrative user specified by the `asadmin` utility option `--user`.
If the `--user` option is not specified, and the `--nopassword` option
is set to true, the default administrative user, `admin`, is used. If
the `--nopassword` option is set to false (the default), a username is
required. In this case, if you have not specified the user name by using
the `--user` option, you are prompted to do so.
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, cluster, or enterprise profile for the domain you create.
This subcommand is supported in local mode only.
[[sthref210]]
=== Options
asadmin-options::
Options for the `asadmin` utility. For information about these
options, see the link:asadmin.html#asadmin-1m[`asadmin`(1M)] help page.
`--help`::
`-?`::
Displays the help text for the subcommand.
`--adminport`::
The HTTP port or the HTTPS port for administration. This port is the
port in the URL that you specify in your web browser to manage the
domain, for example, `http://localhost:4949`. The `--adminport` option
cannot be used with the `--portbase` option. The default value is 4848. +
The `--adminport` option overrides the `domain.adminPort` property of
the `--domainproperties` option.
`--instanceport`::
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 domain creation.
The `--instanceport` option cannot be used with the `--portbase`
option. The default value is 8080. +
The `--instanceport` option overrides the `domain.instancePort`
property of the `--domainproperties` option.
`--portbase`::
Determines the number with which port assignments should start. A
domain uses a certain number of ports that are statically assigned.
The portbase value determines where the assignment should start. The
values for the ports are calculated as follows:
* Administration port: portbase + 48
* HTTP listener port: portbase + 80
* HTTPS listener port: portbase + 81
* JMS port: portbase + 76
* IIOP listener port: portbase + 37
* Secure IIOP listener port: portbase + 38
* Secure IIOP with mutual authentication port: portbase + 39
* JMX port: portbase + 86
* JPDA debugger port: portbase + 9
* Felix shell service port for OSGi module management: portbase + 66
+
When the `--portbase` option is specified, the output of this
subcommand includes a complete list of used ports. +
The `--portbase` option cannot be used with the `--adminport`,
`--instanceport`, or the `--domainproperties` option.
`--profile`::
Do not specify this option. This option is retained for compatibility
with earlier releases. If you specify this option, a syntax error does
not occur. Instead, the subcommand runs successfully and displays a
warning message that the option is ignored.
`--template`::
The file name, including a relative or absolute path, of a domain
configuration template to use for creating the domain. If a relative
path is specified, the subcommand appends the path to the
as-install``/lib/templates`` directory to locate the file. If it is an
absolute pathname, the subcommand locates the file in the specified
path. +
This option enables domains of different types to be created and
custom domain templates to be defined.
`--domaindir`::
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,
as-install``/domains``.
`--savemasterpassword`::
Setting this option to `true` allows the master password to be written
to the file system. If this option is `true`, the
`--usemasterpassword` option is also true, regardless of the value
that is specified on the command line. The default value is `false`. +
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 the 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 the store (a file) that contains this certificate.
This file is called `keystore.jks` and is created in the configuration
directory of the domain created. If however, this option is chosen,
the master password is saved on the disk in the domain's configuration
location. The master password is stored in a file called
`master-password`, which is a Java JCEKS type keystore. The reason for
using the `--savemasterpassword` option is for unattended system
boots. In this case, the master password is not prompted for when the
domain starts because the password will be extracted from this file. +
It is best to create a master password when creating a domain, because
the master password is used by the `start-domain` subcommand. For
security purposes, the default setting should be false, because saving
the master password on the disk is an insecure practice, unless file
system permissions are properly set. If the master password is saved,
then `start-domain` does not prompt for it. The master password gives
an extra level of security to the environment.
`--usemasterpassword`::
Specifies whether the key store is encrypted with a master password
that is built into the system or a user-defined master password. +
If `false` (default), the keystore is encrypted with a well-known
password that is built into the system. Encrypting the keystore with a
password that is built into the system provides no additional
security. +
If `true`, the subcommand obtains the master password from the
`AS_ADMIN_MASTERPASSWORD` entry in the password file or prompts for
the master password. The password file is specified in the
`--passwordfile` option of the
link:asadmin.html#asadmin-1m[`asadmin`(1M)]utility. +
If the `--savemasterpassword` option is `true`, this option is also
true, regardless of the value that is specified on the command line.
`--domainproperties`::
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 colon (:) character. The `--portbase` options cannot be used
with the `--domainproperties` option. The following properties are
available:
`domain.adminPort`;;
This property specifies the port number of the HTTP port or the
HTTPS port for administration. This port is the port in the URL that
you specify in your web browser to manage the instance, for example,
`http://localhost:4949`. Valid values are 1-65535. On UNIX, creating
sockets that listen on ports 1-1024 requires superuser privileges. +
The `domain.adminPort` property is overridden by the `--adminport`
option.
`domain.instancePort`;;
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. +
The `domain.instancePort` property is overridden by `--instanceport`
option.
`domain.jmxPort`;;
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.
`http.ssl.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.
`java.debugger.port`;;
This property specifies the port number of the port that is used for
connections to the
http://java.sun.com/javase/technologies/core/toolsapis/jpda/[Java
Platform Debugger Architecture (JPDA)]
(http://www.oracle.com/technetwork/java/javase/tech/jpda-141715.html)
debugger. Valid values are 1-65535. On UNIX, creating sockets that
listen on ports 1-1024 requires superuser privileges.
`jms.port`;;
This property specifies the port number for the Java Message Service
provider. Valid values are 1-65535. On UNIX, creating sockets that
listen on ports 1-1024 requires superuser privileges.
`orb.listener.port`;;
This property specifies the port number of the port that is used for
IIOP connections. Valid values are 1-65535. On UNIX, creating
sockets that listen on ports 1-1024 requires superuser privileges.
`orb.mutualauth.port`;;
This property specifies the port number of the port that is used for
secure IIOP connections with client authentication. Valid values are
1-65535. On UNIX, creating sockets that listen on ports 1-1024
requires superuser privileges.
`orb.ssl.port`;;
This property specifies the port number of the port that is used for
secure IIOP connections. Valid values are 1-65535. On UNIX, creating
sockets that listen on ports 1-1024 requires superuser privileges.
`osgi.shell.telnet.port`;;
This property specifies the port number of the port that is used for
connections to the
http://felix.apache.org/site/apache-felix-remote-shell.html[Apache
Felix Remote Shell]
(http://felix.apache.org/site/apache-felix-remote-shell.html). This
shell uses the Felix shell service to interact with the OSGi module
management subsystem. Valid values are 1-65535. On UNIX, creating
sockets that listen on ports 1-1024 requires superuser privileges.
`--keytooloptions`::
Specifies an optional list of name-value pairs of keytool options for
a self-signed server certificate. The certificate is generated during
the creation of the domain. Each pair in the list must be separated by
the colon (:) character. +
Allowed options are as follows:
`CN`;;
Specifies the common name of the host that is to be used for the
self-signed certificate. This option name is case insensitive. +
By default, the name is the fully-qualified name of the host where
the `create-domain` subcommand is run.
`--savelogin`::
If set to true, this option saves the administration user name and
password. Default value is false. The username and password are stored
in the `.asadminpass` file in user's home directory. A domain can only
be created locally. Therefore, when using the `--savelogin` option,
the host name saved in `.asadminpass` is always `localhost`. If the
user has specified default administration port while creating the
domain, there is no need to specify `--user`, `--passwordfile`,
`--host`, or `--port` on any of the subsequent `asadmin` remote
commands. These values will be obtained automatically.
+
[NOTE]
====
When the same user creates multiple domains that have the same
administration port number on the same or different host (where the
home directory is NFS mounted), the subcommand does not ask if the
password should be overwritten. The password will always be
overwritten.
====
`--checkports`::
Specifies whether to check for the availability of the administration,
HTTP, JMS, JMX, and IIOP ports. The default value is true.
`--nopassword`::
Specifies whether the administrative user will have a password. If
false (the default), the password is specified by the
`AS_ADMIN_PASSWORD` entry in the `asadmin` password file (set by using
the `--passwordfile` option). If false and the `AS_ADMIN_PASSWORD` is
not set, you are prompted for the password. +
If true, the administrative user is created without a password. If a
user name for the domain is not specified by using the `--user`
option, and the `--nopassword` option is set to true, the default user
name, `admin`, is used.
[[sthref211]]
=== Operands
domain-name::
The name of the domain to be created. The name may contain only ASCII
characters and must be a valid directory name for the operating system
on the host where the domain is created.
[[sthref212]]
=== Examples
[[GSRFM471]][[sthref213]]
==== Example 1   Creating a Domain
This example creates a domain named `domain4`.
[source]
----
asadmin>create-domain --adminport 4848 domain4
Enter admin user name [Enter to accept default "admin" / no password]>
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.
Using default port 6666 for OSGI_SHELL.
Distinguished Name of the self-signed X.509 Server Certificate is:
[CN=sr1-usca-22,OU=GlassFish,O=Oracle Corp.,L=Redwood Shores,ST=California,C=US]
No domain initializers found, bypassing customization step
Domain domain4 created.
Domain domain4 admin port is 4848.
Domain domain4 allows admin login as user "admin" with no password.
Command create-domain executed successfully.
----
[[GSRFM472]][[sthref214]]
==== Example 2   Creating a Domain in an Alternate Directory
This example creates a domain named `sampleDomain` in the
`/home/someuser/domains` directory.
[source]
----
asadmin> create-domain --domaindir /home/someuser/domains --adminport 7070
--instanceport 7071 sampleDomain
Enter admin user name [Enter to accept default "admin" / no password]>
Using port 7070 for Admin.
Using port 7071 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.
Using default port 6666 for OSGI_SHELL.
Enterprise ServiceDistinguished Name of the self-signed X.509 Server Certificate is:
[CN=sr1-usca-22,OU=GlassFish,O=Oracle Corp.,L=Redwood Shores,ST=California,C=US]
No domain initializers found, bypassing customization step
Domain sampleDomain created.
Domain sampleDomain admin port is 7070.
Domain sampleDomain allows admin login as user "admin" with no password.
Command create-domain executed successfully.
----
[[GSRFM473]][[sthref215]]
==== Example 3   Creating a Domain and Saving the Administration User Name and Password
This example creates a domain named `myDomain` and saves the
administration username and password.
[source]
----
asadmin> create-domain --adminport 8282 --savelogin=true myDomain
Enter the admin password [Enter to accept default of no password]>
Enter the master password [Enter to accept default password "changeit"]>
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.
Using default port 6666 for OSGI_SHELL.
Enterprise ServiceDistinguished Name of the self-signed X.509 Server Certificate is:
[CN=sr1-usca-22,OU=GlassFish,O=Oracle Corp.,L=Redwood Shores,ST=California,C=US]
No domain initializers found, bypassing customization step
Domain myDomain created.
Domain myDomain admin port is 8282.
Domain myDomain allows admin login as user "admin" with no password.
Login information relevant to admin user name [admin]
for this domain [myDomain] stored at
[/home/someuser/.asadminpass] successfully.
Make sure that this file remains protected.
Information stored in this file will be used by
asadmin commands to manage this domain.
Command create-domain executed successfully.
----
[[GSRFM474]][[sthref216]]
==== Example 4   Creating a Domain and Designating the Certificate Host
This example creates a domain named `domain5`. The common name of the
host that is to be used for the self-signed certificate is `trio`.
[source]
----
asadmin> create-domain --adminport 9898 --keytooloptions CN=trio domain5
Enter the admin password [Enter to accept default of no password]>
Enter the master password [Enter to accept default password "changeit"]>
Using port 9898 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.
Using default port 6666 for OSGI_SHELL.
Distinguished Name of the self-signed X.509 Server Certificate is:
[CN=trio,OU=GlassFish,O=Oracle Corp.,L=Redwood Shores,ST=California,C=US]
No domain initializers found, bypassing customization step
Domain domain5 created.
Domain domain5 admin port is 9898.
Domain domain5 allows admin login as user "admin" with no password.
Command create-domain executed successfully.
----
[[sthref217]]
=== Exit Status
0::
subcommand executed successfully
1::
error in executing the subcommand
[[sthref218]]
=== See Also
link:asadmin.html#asadmin-1m[`asadmin`(1M)]
link:delete-domain.html#delete-domain-1[`delete-domain`(1)],
link:list-domains.html#list-domains-1[`list-domains`(1)],
link:login.html#login-1[`login`(1)],
link:start-domain.html#start-domain-1[`start-domain`(1)],
link:stop-domain.html#stop-domain-1[`stop-domain`(1)]
Apache Felix Remote Shell
(`http://felix.apache.org/site/apache-felix-remote-shell.html`), Java
Platform Debugger Architecture (JPDA)
(`http://www.oracle.com/technetwork/java/javase/tech/jpda-141715.html`)