Sun GlassFish Enterprise Server v3 Administration Guide

Chapter 3 Administering Domains

This chapter provides procedures for administering domains in the Sun GlassFishTM Enterprise Server v3 environment by using the asadmin command-line utility.

The following topics are addressed here:

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.

About Administering Domains (or Servers)

A domain is a group of instances that are administered together. The domain provides a preconfigured runtime for user applications. In addition to providing an administration boundary, a domain provides the basic security structure whereby separate administrators can administer specific groups of server instances. By grouping the server instances into separate domains, different organizations and administrators can share a single installation of Enterprise Server. 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 Enterprise Server installer creates a default administrative domain named domain1, as well as an associated domain administration server (DAS) named server. The DAS is a specially-designated instance that 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.

The default administration port is 4848, but a different port can be specified during installation. When a domain is created, you are prompted for the administration user name and password, but you can accept the default in which case user name is admin and there is no password. To reset the administration password, see To Change the Administration Password.

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.

Creating, Logging In To, and Deleting a Domain

The following topics are addressed here:

ProcedureTo Create a Domain

After installing Enterprise Server and creating the default domain (domain1), you can create additional domains by using the local create-domain subcommand. This subcommand 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.

You are required to specify an administrative user when you create a domain, or you can accept the default login identity which is username admin with no password.

Before You Begin

Determine which profile will apply to the domain.

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

    You can verify that a name is not already in use by using the list-domains(1) subcommand

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

    Information about the options for this subcommand is included in this help page.

  3. Type an admin user name and password for the domain.

    To avoid setting up an admin login, you can accept the default admin, with no password. Pressing Return also selects the default.


Example 3–1 Creating a Domain

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


asadmin> create-domain --adminport 4848 domain1
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 8081 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

You can also view the full syntax and options of the subcommand by typing asadmin help create-domain at the command line.

ProcedureTo List Domains

Use the list-domains subcommand to display 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) subcommand.


Example 3–2 Listing Domains

This example lists the domains in the default as-install/domains directory:


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

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-domain at the command line.

ProcedureTo Log In to a Domain

All remote subcommands require that credentials be specified in terms of an administration user name and its password. By default, the domain is created with an identity that allows an asadmin user to perform administrative operations when no identity is explicitly or implicitly specified. The default identity is in the form of a user whose name is admin and has no password. If you specify no user name on the command line or on prompt, and specify no password in the --passwordfile option or on prompt, and you have never logged in to a domain using either the login subcommand or the create-domain subcommand with the ----savelogin option, then the asadmin utility will attempt to perform a given administrative operation without specifying any identity. A server (domain) allows administrative operations to be run using this default identity if the following conditions are true:

1. The server (domain) uses file realm for authentication of admin users.

2. The file realm has one and only one user (what the user name is does not matter).

3. That one user has no password.

By default, all of these conditions are true, unless you have created the domain with a specific user name and password. Thus, by default, the only administration user is admin with no password. If #3 is not true, you will need to specify the password. If #2 is not true, you will also need to specify the user name. If #1 is not true, you will need to specify the user name and password.

Use the login subcommand in local mode to authenticate yourself (log in to) a specific domain. After such login, you do not need to specify the administration user or password for subsequent operations on the domain. The login subcommand can only be used to specify the administration password. For other passwords that remote subcommands require, use the --passwordfile option, or specify the password at the command prompt. You are always prompted for the administration user name and password.

There is no logout subcommand. If you want to log in 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 3–3 Logging In To a Domain on a Remote Machine

This example logs into a domain located on another machine. Options are specified before the login subcommand.


asadmin> --host foo --port 8282 login
Please enter the admin user name>admin Please enter the admin password> 
Trying to authenticate for administration of server at host [foo] and port [8282] ... 
Login information relevant to admin user name [admin] 
for host [foo] and admin port [8282] stored at [/.asadminpass] successfully. 
Make sure that this file remains protected. Information stored in this
file will be used by asadmin commands to manage associated domain.


Example 3–4 Logging In to a Domain on the Default Port of Localhost

This example logs into a domain on myhost on the default port. Options are specified before the login subcommand.


asadmin>  --host myhost login 
Please enter the admin user name>admin Please enter the admin password> 
Trying to authenticate for administration of server at host [myhost] and port [4848] ... 
An entry for login exists for host [myhost] and port [4848], probably from 
an earlier login operation. 
Do you want to overwrite this entry (y/n)?y 
Login information relevant to admin user name [admin] for host [myhost] 
and admin port [4848] stored at [/home/joe/.asadminpass] successfully. 
Make sure that this file remains protected. Information stored in this file will be used by 
asadmin commands to manage associated domain.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help login at the command line. For additional information about passwords, see Administering Passwords.

ProcedureTo Delete a Domain

Use the delete-domain subcommand to delete an existing domain from a server. Only the root user or the operating system user who is authorized to administer the domain can run this subcommand.

Before You Begin

A domain must be stopped before it can be deleted.

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

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

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

    If needed, see To Stop a Domain.

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


Example 3–5 Deleting a Domain

This example deletes a domain named domain1 from the location specified.


asadmin> delete-domain --domaindir ..\domains domain1
Domain domain1 deleted.
Command delete-domain executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-domain at the command line.

Starting and Stopping a Domain

The following topics are addressed here:

ProcedureTo Start a Domain

When you start a domain or server, 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.

If you want the domain you are starting to be able to use the restart-domain subcommand, the --watchdog option must be set to true (true is the default). If you have set the --watchdog option to false, the domain will not be able to use the restart-domain subcommand.


Note –

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 subcommand is supported in local mode only.

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


Example 3–6 Starting a Domain

This example starts domain2 in the default domain directory.


asadmin> start-domain domain2

If there is only one domain, you can omit the domain name. If you do not include the password, you might be prompted to supply it.


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

You can also view the full syntax and options of the subcommand by typing asadmin help start-domain at the command line.

ProcedureTo Stop a Domain

Stopping a domain or server 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 subcommands cannot be used. This subcommand is particularly useful in stopping a runaway server. For more controlled situations, you can use the restart-domain(1) subcommand.


Note –

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) subcommand.


Example 3–7 Stopping a Domain (or Server)

This example stops domain1 in the default directory, where domain1 is the only domain present in the directory.


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

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help stop-domain at the command line.

ProcedureTo Restart a Domain

Use the restart-domain subcommand in remote mode to restart the Domain Administration Server (DAS) of the specified host. When restarting a domain, the DAS stops accepting new connections and then waits for all outstanding connections to complete. This shutdown process takes a few seconds. Until the domain has restarted, the Administration Console and most of the asadmin subcommands cannot be used.

This subcommand is particularly useful for environments where the server machine is secured and difficult to get to. With the right credentials, you can restart the server from a remote location as well as from the same machine.

If the server will not restart, use the stop-domain(1) subcommand followed by the start-domain(1) subcommand.

Before You Begin

For the restart-domain subcommand to work, the --watchdog option of the start-domain subcommand must have been set to true (the default) when the domain was started. If this option was set to false and you attempt to restart the domain, the domain is stopped and a warning message is logged. If the --watchdog option is set to false, you can only restart the domain by using the stop-domain and start-domain subcommands.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Restart the domain by using the restart-domain(1) subcommand.


Example 3–8 Restarting a Domain (or Server)

This example restarts mydoimain4 in the default directory.


asadmin> restart-domain mydomain4
Waiting for the domain to restart ...........
Command restart-domain executed successfully.


Example 3–9 Restarting a Domain in a Browser

This example invokes the restart-domain subcommand in a browser.


http://yourhost:4848/__asadmin/restart-domain

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help restart-domain at the command line.

Automatically Restarting a Domain

This section provides instructions for configuring your system to automatically restart the domain on Solaris.

The following topics are addressed here:

ProcedureTo Automatically Restart a Domain on Solaris 10

The create-service subcommand is supported on the Solaris and Windows platforms, however, only Solaris instructions are provided here.

On Solaris 10, you can use the asadmin create-service subcommand to create a Solaris Service Management Facility (SMF) service that restarts a Domain Administration Server (DAS). The service grants to the process the privileges of the user that runs the process. When you create an SMF service, the default user is the superuser. If you require a different user to run the process, specify the user in method_credential.

If your process is to bind to a privileged port of Solaris 10, the process requires the net_privaddr privilege. The privileged ports of the Solaris operating system have port numbers less than 1024.

To determine if a user has the net_privaddr privilege, log in as that user and type the command ppriv -l | grep net_privaddr.

After you create and enable the SMF service, if the domain goes down, SMF restarts it.

Before You Begin

To run the asadmin create-service subcommand, you must have solaris.smf.* authorization. See the useradd and usermod man pages to find out how to set the authorizations. You must also have write permission in the directory tree: /var/svc/manifest/application/SUNWappserver. Usually, the superuser has both of these permissions. Additionally, the Solaris 10 administration commands such as svccfg, svcs, and auths must be available in the PATH.

If a particular Enterprise Server domain should not have default user privileges, modify the manifest of the service and reimport the service.

  1. Create the service by using the create-service(1) subcommand.

    Information about properties for the subcommand is included in this help page.

  2. After the service is created, enable the service by using the svacdm enable subcommand.

    For example:


    svacdm enable /appserver/domains/domain1
    

Example 3–10 Creating a Service to Restart a Domain Automatically on Solaris 10

This example creates a service .


asadmin> create-service
The Service was created successfully. Here are the details:
Name of the service:application/GlassFish/domain1
Type of the service:Domain
Configuration location of the service:/home/gfuser/glassfish-installations
/glassfishv3/glassfish/domains
Manifest file location on the system:/var/svc/manifest/application
/GlassFish/domain1_home_gfuser_glassfish-installations_glassfishv3
_glassfish_domains/Domain-service-smf.xml.
You have created the service but you need to start it yourself.
Here are the most typical Solaris commands of interest:
* /usr/bin/svcs -a | grep domain1 // status
* /usr/sbin/svcadm enable domain1 // start
* /usr/sbin/svcadm disable domain1 // stop
* /usr/sbin/svccfg delete domain1 // uninstall
Command create-service executed successfully

See Also

As you administer your service, the following Solaris commands are useful: auths, smf_security, svcadm, svccfg, rbac, useradd, and usermod.

ProcedureTo Restart Automatically on Linux

To set up automatic restart on Linux, you edit the /etc/inittab file. If you use /etc/rc.local, or your system’s equivalent, place a line in /etc/rc.local that calls the desired asadmin subcommand.

  1. Add a line of text to the /etc/inittab file.

    For example:


    das:3:respawn:/opt/SUNWappserver/bin/asadmin start-domain --user admin 
    --passwordfile /opt/SUNWappserver/password.txt domain1

    The text must be on a single line. The first three letters are a unique designator for the process and can be altered.

ProcedureTo Prevent Service Shutdown When User Logs Out on Windows

By default, the Java Virtual Machine (JVM) receives signals from Windows that indicate that Windows is shutting down, or that a user is logging out of Windows, which causes the system to shut itself down cleanly. This behavior causes the Enterprise Server service to shut down. To prevent the service from shutting down when a user logs out, you must set the -Xrs Java VM option.

  1. Add the following line to the section of the as-install\domains\domain-name\config\domain.xml file that defines Java VM options:

    <jvm-options>-Xrs</jvm-options>
  2. If the Enterprise Server service is running, restart the service for your changes to take affect.

Additional Domain Tasks

The following topics are addressed here:

ProcedureTo Display Domain Uptime

Use the uptime subcommand in remote mode to display 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 subcommands require a running server.

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


Example 3–11 Displaying the DAS Uptime

This example displays the length of time that the DAS has been running.


asadmin> uptime
Uptime: 1 Weeks, 4 days, 0 hours, 17 minutes, 14 seconds, Total milliseconds: 951434595
Command uptime executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help uptime at the command line.

ProcedureTo Switch a Domain to Another Supported Java Version

Enterprise Server v3 requires Version 6 Java SE platform as the underlying virtual machine for the JavaTM platform (Java Virtual Machine or JVMTM machine).


Note –

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.

    Use the following format:


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

    For a valid JVM installation, locations are checked in the following order:

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

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

    If a legal JDK is not found, a fatal error occurs and the problem is reported back to you.

  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"