Administering Domains

A domain provides a preconfigured runtime for user applications. This runtime includes a basic security structure where specific groupings of server instances (domains) can be administered by different administrators. Enterprise Server installer creates a default administrative domain named domain1, as well as an associated domain administration server (DAS) named server. The default administration port is 4848, but a different port can be specified during installation. The administration user name and password are also established if anonymous login was not chosen during installation.

A domain has its own configuration, log files, and application deployment areas that are independent of other domains. If the configuration is changed for a domain, the configurations for other domains are not affected.

The domain administration server (DAS) is a specially-designated instance that hosts the administrative applications. The DAS authenticates the administrator, accepts requests from administration tools, and communicates with server instances in the domain to carry out requests. The DAS is sometimes referred to as the default server because it is the only server instance created during Enterprise Server installation that can be used for deployment.

Each domain has its own DAS with a unique port number. The graphical Administration Console communicates with a specific DAS to administer the domain associated with the DAS. Each Administration Console session enables you to configure and manage the specific domain. If you create multiple domains, you must start a separate Administration Console session to manage each domain.

The following instructions are used to administer domains:

• To Create a Domain

• To List Domains

• To Delete a Domain

• To Start a Domain (or Server)

• To Stop a Domain (or Server)

• To Log In to a Domain (or Server)

• To Display Domain Uptime

• To Switch a Domain to Another Supported Java Version

To Create a Domain

After installing Enterprise Server and creating the default domain (domain1), you can create additional domains by using the local create-domain command. This command creates the configuration of a domain.

Any user who has access to the asadmin utility on a given system can create a domain and store the domain 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.

1. Select a name for the domain that you are creating.

   You can verify that a name is not already in use by listing the existing domains:

   asadmin list-domains

2. Create a domain by using the create-domain(1) command.

Example 2–1 Creating a Domain

The following example command creates a domain named domain1 . When you type the command, you might be prompted for login information.

asadmin create-domain --adminport 4848 domain1

Information similar to the following is displayed:

Enter admin user name[Enter to accept default]>
Using port 4848 for Admin.
Default port 8080 for HTTP Instance is in use. Using 1161
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.
Default port 8686 for JMX_ADMIN is in use. Using 1162
Distinguished Name of the self-signed X.509 Server Certificate is:
[CN=moonbeam.gateway.2wire.net,OU=GlassFish,O=Sun Microsystems,L=Santa Clara,ST
California,C=US]
Domain domain1 created.
Command create-domain executed successfully.

To start the Administration Console in a browser, enter the URL in the following format:

http://hostname:5000

For this example, the domain’s log files, configuration files, and deployed applications now reside in the following directory:

domain-root-dir/mydomain

See Also

To see the full syntax and options of the command, type asadmin create-domain --help at the command line.

To List Domains

The list-domains command provides a list of domains and their statuses. If the domain directory is not specified, the contents of the default as-install/domains directory is listed. If there is more than one domain, the domain name must be specified.

To list domains that were created in other directories, specify the --domaindir option.

1. List domains by using the list-domains(1) command.

Example 2–2 Listing Domains

The following example command lists the domains in the default as-install/domains directory:

asadmin list-domains

Information similar to the following is displayed:

Name: domain1 Status: Running
Name: domain4 Status: Not Running
Name: domain6 Status: Not Running
Command list-domains executed successfully.

See Also

To see the full syntax and options of the command, type asadmin list-domain --help at the command line.

To Delete a Domain

Only the root user or the operating system user who is authorized to administer the domain can run this command.

Before You Begin

A domain must be stopped before it can be deleted.

1. Obtain the exact name of the domain that you are deleting.

   To list the existing domains:

   asadmin list-domains

2. If necessary, notify domain users that the domain is being deleted.

3. Ensure that the domain you want to delete is stopped.

   For instructions, see To Stop a Domain (or Server).

4. Delete the domain by using the delete-domain(1) command.

Example 2–3 Deleting a Domain

The following example command deletes a domain named domain1 from the location specified:

asadmin delete-domain --domaindir ..\domains domain1

Information similar to the following is displayed:

Domain domain1 deleted.
Command delete-domain executed successfully.

See Also

To see the full syntax and options of the command, type asadmin delete-domain --help at the command line.

To Start a Domain (or Server)

When you start a domain, the domain administration server (DAS) is started. After startup, the DAS runs constantly, listening for and accepting requests.

If the domain directory is not specified, the domain in the default as-install/domains directory is started. If there are two or more domains, the domain_name operand must be specified. Each domain must be started separately.

For Microsoft Windows, you can use an alternate method to start a domain. From the Windows Start menu, select Programs -> Sun Microsystems ->Enterprise Server -> Start Admin Server.

This command is supported in local mode only.

1. Start a domain by using the start-domain(1) command.

Example 2–4 Starting a Domain

The following example command starts domain1:

asadmin start-domain domain1

Information similar to the following is displayed:

Name of the domain started: [domain1] and its location: 
[C:\prelude\v3_prelude_release\distributions\web\target\glassfish
domains\domain1].
Admin port for the domain: [4848].

See Also

To see the full syntax and options of the command, type asadmin start-domain --help at the command line.

To Stop a Domain (or Server)

Stopping a domain shuts down its domain administration server (DAS). When stopping a domain, the DAS stops accepting new connections and then waits for all outstanding connections to complete. This shutdown process takes a few seconds. While the domain is stopped, the Administration Console and most of the asadmin commands cannot be used.

For Microsoft Windows, you can use an alternate method to stop a domain. From the Start menu, select Programs -> Sun Microsystems -> Enterprise Server -> Stop Admin Server.

1. If necessary, notify users that you are going to stop the domain.

2. Stop the domain by using the stop-domain(1) command.

Example 2–5 Stopping a Domain (or Server)

The following example command stops domain1:

asadmin stop-domain domain1

Information similar to the following is displayed:

Waiting for the domain to stop ...........
Command stop-domain executed successfully.

See Also

To see the full syntax and options of the command, type asadmin stop-domain --help at the command line.

To Log In to a Domain (or Server)

The login command enables you to authenticate yourself (log in to) a specific domain, after which you need not specify the administration password through the --user option or the ---passwordfile option for subsequent operations on the domain.

The login command can only be used to specify the administration password. For other passwords that remote commands require, use the --passwordfile option, or specify the passwords at the command prompt. You are always prompted for the admin user name and password.

There is no logout command. If you want to login to another domain, invoke asadmin login with new values for --host and --port.

1. Determine the name of the domain that you are logging in to.

   To list the existing domains:

   asadmin list-domains

2. Log in to the domain by using the login(1)command.

Example 2–6 Logging In To a Domain Located on Another Machine

The following example command logs you in to the running domain on port 4848 of host moonbeam:

asadmin login --host moonbeam --port 4848

Information similar to the following is displayed:

Enter admin user name[Enter to accept default]>admin
Enter admin password>adminadmin
GlassFish v3 Prelude (build Jennifer-private)
Login information relevant to admin user name [admin] for host [localhost] and
dmin port [4848] stored at [C:\Documents and Settings\Jennifer\.asadminpass] su
cessfully.
Make sure that this file remains protected. Information stored in this file will
be used by asadmin commands to manage associated domain.
Command login executed successfully.

Example 2–7 Logging In to a Domain on the Default Port of Localhost

The following example command logs you in to the default domain of localhost:

asadmin login

Information similar to the following is displayed:

Enter admin user name[Enter to accept default]>
GlassFish v3 Prelude (build Jennifer-private)
Admin login information for host [localhost] and port [4848] is being 
overwrittn with credentials provided. This is because the --savelogin option 
was used during create-domain command.
Login information relevant to admin user name [anonymous] for host [localhost]
nd admin port [4848] stored at [C:\Documents and Settings\Jennifer\.asadminpass
successfully.
Make sure that this file remains protected. Information stored in this file will
be used by asadmin commands to manage associated domain.
Command login executed successfully.

See Also

To see the full syntax and options of the command, type asadmin login --help at the command line. For additional information on passwords, see Administering Passwords.

To Display Domain Uptime

The uptime command displays the length of time that the domain administration server (DAS) has been running since it was last started.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Display uptime by using the uptime(1) command.

Example 2–8 Displaying the DAS Uptime

The following example command displays the length of time that the DAS has been running:

asadmin uptime

Information similar to the following is displayed:

Uptime: 31 minutes, 54 secons
Command uptime executed successfully.

See Also

To see the full syntax and options of the command, type asadmin uptime --help at the command line.

To Switch a Domain to Another Supported Java Version

Enterprise Server v3 Prelude requires Version 5 Java SE platform as the underlying virtual machine for the Java^TM platform (Java Virtual Machine or JVM^TM machine).

Do not downgrade to an earlier Java version after a domain has been created with a newer JVM machine. If you must downgrade your JVM machine, downgrade it only for individual domains.

1. If you have not already done so, download the desired Java SDK (not the JRE) and install it on your system.

   The Java SDK can be downloaded from http://java.sun.com/j2se.

2. Start the domain for which you are changing the JDK.

   as-install/bin/asadmin start-domain domain-name

   For a valid JVM installation, the order in which locations are checked is as follows:

   1. domain.xml (java-home inside java-config)

   2. asenv.conf (setting AS_JAVA="path to java home")

   3. JAVA_HOME environmental variable

   4. system.getProperty ("java.home") + "../"

   5. system.getProperty ("java.home")

3. If necessary, change the JVM machine attributes for the domain.

   In particular, you might need to change the JAVA_HOME environment variable. For example, to change the JAVA_HOME variable, type:

   as-install/bin/asadmin set "server.java-config.java-home=path-to-java-home"