3 Administering Domains

GlassFish Server Instances

A GlassFish Server instance is a single Virtual Machine for the Java platform (Java Virtual Machine or JVM machine) on a single node in which GlassFish Server is running. A node defines the host where the GlassFish Server instance resides. The JVM machine must be compatible with the Java Platform, Enterprise Edition (Java EE).

GlassFish Server instances form the basis of an application deployment.

Whenever a domain is created, GlassFish Server creates a default instance that is named server. If a single instance meets your requirements, you can use this instance for deploying applications without the need to administer GlassFish Server instances explicitly. You administer the default instance when you administer its domain.

If you require multiple instances, you must administer the instances explicitly. For more information, see "Administering GlassFish Server Instances" in Oracle GlassFish Server High Availability Administration Guide.

For an instance, you can also create virtual servers. Virtual servers do not span instances. For many purposes, you can use virtual servers instead of multiple instances in operational deployments. Virtual servers enable you to offer, within a single instance, separate domain names, IP addresses, and some administration capabilities to organizations or individuals. To these users, a virtual server behaves like a dedicated web server, but without the hardware and basic web server maintenance.

For more information about virtual servers, see Administering Virtual Servers.

Domains for Administering GlassFish Server

A domain is an administrative boundary that contains a group of GlassFish Server instances that are administered together. Each instance can belong to only one domain. A domain provides a preconfigured runtime for user applications. Each domain has its own configuration data, log files, and application deployment areas that are independent of other domains. If the configuration is changed for one domain, the configurations of other domains are not affected.

Domains enable different organizations and administrators to share securely a single GlassFish Server installation. Each organization or administrator can administer the instances in a single domain without affecting the instances in other domains.

At installation time, GlassFish Server creates a default domain that is named domain1. After installation, you can create additional domains as necessary.

When a domain is created, you are prompted for the administration user name and password. If you accept the default, the user admin is created without password. To reset the administration password, see "To Change an Administration Password" in Oracle GlassFish Server Security Guide.

Domain Administration Server (DAS)

The domain administration server (DAS) is a specially designated GlassFish Server instance that hosts administrative applications. The DAS is similar to any other GlassFish Server instance, except that the DAS has additional administration capabilities. The DAS authenticates the administrator, accepts requests from administration tools, and communicates with other instances in the domain to carry out the requests from administration tools.

Each domain has its own DAS with a unique administration port number. The default administration port is 4848, but a different port can be specified when a domain is created.

The DAS has the master copy of the configuration data for all instances in a domain. If an instance is destroyed, for example, because a host failed, the instance can be re-created from the data in the DAS.

The DAS is the default GlassFish Server instance in a domain and is named server. If a single instance meets your requirements, you can use the DAS for deploying applications and for administering the domain.

The graphical Administration Console communicates with a specific DAS to administer the domain that is associated with the DAS. Each Administration Console session enables you to configure and manage only one domain. If you create multiple domains, you must start a separate Administration Console session to manage each domain.

To Create a Domain

After installing GlassFish 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.

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 subcommand

2. Create a domain by using the create-domain 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.

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=Oracle Corp.,L=Redwood Shores,ST
California,C=US]
Domain domain1 created.
Command create-domain executed successfully.

http://hostname:5000

See Also

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

To Create a Domain From a Custom Template

A custom template enables you to customize the configuration of any domain that you create from the template.

1. Create a domain to use as the basis for the template.

   For more information, see To Create a Domain.

2. Use the asadmin utility or the Administration Console to configure the domain.

   Your configuration changes will be included in the template that you create from the domain.

3. Copy the domain's domain.xml file under a new name to the as-install/lib/templates directory.

   A domain's domain.xml file is located in the domain-dir/config directory.

4. In a plain text editor, edit the file that you copied to replace with tokens values that are to be substituted when a domain is created.

   Each token is identified as %%%token-name%%%, where token-name is one of the following names:

   ADMIN_PORT

   Represents the port number of the HTTP port or the HTTPS port for administration. This token is replaced with one of the following values in the command to create a domain from the template:

   • The value of the --adminport option

   • The value of the domain.adminPort property

   CONFIG_MODEL_NAME

   Represents the name of the configuration that is created for the domain that is being created. This token is replaced with the string server-config.

   DOMAIN_NAME

   Represents the name of the domain that is being created. This token is replaced with the operand of create-domain subcommand.

   HOST_NAME

   Represents the name of the host on which the domain is being created. This token is replaced with the fully qualified host name of the host where the domain is being created.

   HTTP_PORT

   Represents the port number of the port that is used to listen for HTTP requests. This token is replaced with one of the following values in the command to create a domain from the template:

   • The value of the --instanceport option

   • A value that the create-domain subcommand calculates from the value of the --portbase option

   • The value of the domain.instancePort property

   HTTP_SSL_PORT

   Represents the port number of the port that is used to listen for secure HTTP requests. This token is replaced with one of the following values in the command to create a domain from the template:

   • A value that the create-domain subcommand calculates from the value of the --portbase option

   • The value of the http.ssl.port property

   JAVA_DEBUGGER_PORT

   Represents the port number of the port that is used for connections to the Java Platform Debugger Architecture (JPDA) debugger. This token is replaced with one of the following values in the command to create a domain from the template:

   • A value that the create-domain subcommand calculates from the value of the --portbase option

   • The value of the java.debugger.port property

   JMS_PROVIDER_PORT

   Represents the port number for the Java Message Service provider. This token is replaced with one of the following values in the command to create a domain from the template:

   • A value that the create-domain subcommand calculates from the value of the --portbase option

   • The value of the jms.port property

   JMX_SYSTEM_CONNECTOR_PORT

   Represents the port number on which the JMX connector listens. This token is replaced with one of the following values in the command to create a domain from the template:

   • A value that the create-domain subcommand calculates from the value of the --portbase option

   • The value of the domain.jmxPort property

   ORB_LISTENER_PORT

   Represents the port number of the port that is used for IIOP connections. This token is replaced with one of the following values in the command to create a domain from the template:

   • A value that the create-domain subcommand calculates from the value of the --portbase option

   • The value of the orb.listener.port property

   ORB_MUTUALAUTH_PORT

   Represents the port number of the port that is used for secure IIOP connections with client authentication. This token is replaced with one of the following values in the command to create a domain from the template:

   • A value that the create-domain subcommand calculates from the value of the --portbase option

   • The value of the orb.mutualauth.port property

   ORB_SSL_PORT

   Represents the port number of the port that is used for secure IIOP connections. This token is replaced with one of the following values in the command to create a domain from the template:

   • A value that the create-domain subcommand calculates from the value of the --portbase option

   • The value of the orb.ssl.port property

   OSGI_SHELL_TELNET_PORT

   Represents the port number of the port that is used for connections to the Apache Felix Remote Shell. This shell uses the Felix shell service to interact with the OSGi module management subsystem. This token is replaced with one of the following values in the command to create a domain from the template:

   • A value that the create-domain subcommand calculates from the value of the --portbase option

   • The value of the osgi.shell.telnet.port property

   SERVER_ID

   Represents the name of the DAS for the domain that is being created. This token is replaced with the string server.

   Tip:

   For information about how these tokens are used in the default template, examine the as-install/lib/templates/domain.xml file.

5. Create the domain that you want to be based on a custom template.

   In the command to create the domain, pass the name of file that you edited in the previous step as the --template option of the create-domain subcommand.

6. Before starting the domain, verify that the domain's domain.xml file is valid.

   Use the verify-domain-xml subcommand for this purpose.

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

See Also

• To Create a Domain

• create-domain(1)

• verify-domain-xml(1)

You can also view the full syntax and options of the subcommands by typing the following commands at the command line.

• asadmin help create-domain

• asadmin help verify-domain-xml

To 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 domain-root-dir, the default for which is as-install/domains, 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.

List domains by using the list-domains subcommand.

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.

To 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:

• The server (domain) uses file realm for authentication of administrative users.

  If this condition is not true, you will need to specify the user name and password.

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

  If this condition is not true, you will also need to specify the user name.

• That one user has no password.

  If this condition is not true, you will need to specify the 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 administrative user is admin with no 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 logincommand.

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.

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" in Oracle GlassFish Server Security Guide.

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

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.

To 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 domain root directory is started. If there are two or more domains, the domain_name operand must be specified. Each domain must be started separately.

This subcommand is supported in local mode only.

Start a domain by using the start-domain subcommand.

asadmin> start-domain domain2

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.

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

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

2. Stop the domain by using the stop-domain subcommand.

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.

To 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 subcommand followed by the start-domain subcommand.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Restart the domain by using the restart-domain subcommand.

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

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.

To Configure a DAS or an Instance for Automatic Restart on Windows

On Windows systems, the create-service subcommand creates a Windows service to represent the DAS or instance. The service is created in the disabled state. After this subcommand creates the service, you must use the Windows Services Manager or the Windows Services Wrapper to start, stop, uninstall, or install the service. To administer the service from the Windows command line, use the sc.exe tool.

This subcommand must be run as the OS-level administrator user.

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

2. After the service is created, start the service by using the Windows Services Manager or the Windows Services Wrapper.

   For example, to start the service for the default domain by using the sc.exe tool, type:

   C:\> sc start domain1
   

   If you are using the sc.exe tool to administer the service, use the tool as follows:

   • To obtain information about the service, use the sc query command.

   • To stop the service, use the sc stop command.

   • To uninstall the service, use the sc delete command.

asadmin> create-service
Found the Windows Service and successfully uninstalled it.
The Windows Service was created successfully.  It is ready to be started.  Here are 
the details:
ID of the service: domain1
Display Name of the service:domain1 GlassFish Server
Domain Directory: C:\glassfishv3\glassfish\domains\domain1
Configuration file for Windows Services Wrapper: C:\glassfishv3\glassfish\domains\
domain1\bin\domain1Service.xml
The service can be controlled using the Windows Services Manager or you can use the
Windows Services Wrapper instead:
Start Command:  C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe  start
Stop Command:   C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe  stop
Uninstall Command:  C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe
uninstall
Install Command:  C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe
install

This message is also available in a file named PlatformServices.log in the domain's 
root directory
Command create-service executed successfully.

C:\> sc query domain1

SERVICE_NAME: domain1
        TYPE               : 10  WIN32_OWN_PROCESS
        STATE              : 1  STOPPED
        WIN32_EXIT_CODE    : 1077  (0x435)
        SERVICE_EXIT_CODE  : 0  (0x0)
        CHECKPOINT         : 0x0
        WAIT_HINT          : 0x0

To Configure a DAS or an Instance for Automatic Restart on Linux

On Linux systems, the create-service subcommand creates a System-V-style initialization script /etc/init.d/GlassFish_domain-or-instance-name and installs a link to this script in any /etc/rcN.d directory that is present, where N is 0, 1, 2, 3, 4, 5, 6, and S. After this subcommand creates the script, you must use this script to start, stop, or restart the domain or instance.

The script automatically restarts the domain or instance only during a reboot. If the domain or instance is stopped, but the host remains running, the domain or instance is not restarted automatically. To restart the domain or instance, you must run the script manually.

You might no longer require the domain or instance to be automatically restarted during a reboot. In this situation, use the operating system to delete the initialization script and the link to the script that the create-service subcommand creates.

The create-service subcommand must be run as the OS-level root user.

Create the service by using the create-service subcommand.

asadmin> create-service
Found the Linux Service and successfully uninstalled it.
The Service was created successfully. Here are the details:
Name of the service:domain1
Type of the service:Domain
Configuration location of the service:/etc/init.d/GlassFish_domain1
User account that will run the service: root
You have created the service but you need to start it yourself.
Here are the most typical Linux commands of interest:

* /etc/init.d/GlassFish_domain1 start
* /etc/init.d/GlassFish_domain1 stop
* /etc/init.d/GlassFish_domain1 restart

For your convenience this message has also been saved to this file: 
/export/glassfish3/glassfish/domains/domain1/PlatformServices.log
Command create-service executed successfully.

To Configure a DAS or an Instance for Automatic Restart on Oracle Solaris

On Oracle Solaris systems, the create-service subcommand creates an Oracle Solaris Service Management Facility (SMF) service that restarts a DAS or an instance. 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 Oracle Solaris, the process requires the net_privaddr privilege. The privileged ports of the Oracle 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 or instance is stopped, SMF restarts it.

Before You Begin

To run the create-service subcommand, you must have solaris.smf.* authorization. For information about how to set the authorizations, see the useradd(1M) man page and the usermod(1M) man page. You must also have write permission in the directory tree: /var/svc/manifest/application/SUNWappserver. Usually, the superuser has both of these permissions. Additionally, Oracle Solaris administration commands such as svccfg, svcs, and auths must be available in the PATH.

If a particular GlassFish Server domain or instance 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 subcommand.

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

   For example, to enable the SMF service for the default domain, type:

   svacdm enable /appserver/domains/domain1
   

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

For information about administering the service, see the following Oracle Solaris documentation:

• "Managing Services (Overview)" in System Administration Guide: Basic Administration

• "Managing Services (Tasks)" in System Administration Guide: Basic Administration

• auths(1)

• svcs(1)

• svcadm(1M)

• svccfg(1M)

• useradd(1M)

• usermod(1M)

• rbac(5)

• smf_security(5)

To Prevent Service Shutdown When a User Logs Out on Windows

By default, the Java Virtual Machine (VM) 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 GlassFish 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 (http://download.oracle.com/docs/cd/E17409_01/javase/6/docs/technotes/tools/solaris/java.html).

1. Ensure that the DAS is running.

2. Set the -Xrs Java VM option for the DAS.

   Use the create-jvm-options subcommand for this purpose.

   asadmin> create-jvm-options -Xrs
   

3. Set the -Xrs Java VM option for the Java VM within which the asadmin utility runs.

   To set this option, edit the asadmin.bat file to add the -Xrs option to the line that runs the admin-cli.jar file.

   1. In the as-install\bin\asadmin.bat file, edit the line to read as follows:

      %JAVA% -Xrs -jar "%~dp0..\modules\admin-cli.jar" %*
      

   2. In the as-install-parent\bin\asadmin.bat file, edit the line to read as follows:

      %JAVA% -Xrs -jar "%~dp0..\glassfish\modules\admin-cli.jar" %*
      

4. If the GlassFish Server service is running, restart the service for your changes to take effect.

To Suspend a Domain

Use the suspend-domain subcommand in remote mode to suspend a specified domain.

Suspending a domain causes the domain administration server (DAS) to enter a state where it will not accept any asadmin, Administration Console, or REST API command that might alter the configuration or content of the domain. However, because the DAS is still running, commands that do not change the configuration or content of the domain are accepted and performed. For example, asadmin list and get commands are available, and the Administration Console is available with view-only access.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Suspend the domain by using the suspend-domain subcommand:

   asadmin> suspend-domain --timeout seconds --message display-message
   

   --timeout

   Specifies a time in seconds to wait for certain running operations to complete before suspending the domain. If any such running operation does not complete in this time, the suspend-domain subcommand fails. The default time is 30 seconds.

   --message

   An optional message that is displayed to administrators who try to perform operations that would be blocked because the domain is suspended. If this option is not used, administrators are only informed that the domain has been suspended and when it was suspended.

asadmin> suspend-domain --message "Manual backup in progress"
The domain was successfully suspended on Sun, 15 Jan 2011 08:30:22 PST.
Command suspend-domain executed successfully.

See Also

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

To Resume a Domain

Use the resume-domain subcommand in remote mode to resume a specified domain.

Resuming a domain that is suspended causes the domain administration server (DAS) to return to a fully operational state where it will accept and perform all asadmin, Administration Console, and REST API commands.

Resume the domain by using the resume-domain subcommand.

asadmin> resume-domain
The domain is resumed. (Sun, 15 Jan 2011 08:32:17 PST)
Command resume-domain executed successfully.

See Also

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

To Create a Backup Configuration

Use the create-backup-config subcommand in remote mode to create a backup configuration.

By default, a backup configuration is enabled when it is created.

Before You Begin

When creating a backup configuration, you specify the name of the schedule that determines when automatic backups are to be performed. Use the list-schedules --full subcommand to find out whether an existing schedule meets your needs. If necessary, use the create-schedule subcommand to create a schedule.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Create the backup configuration by using the create-backup-config subcommand:

   asadmin> create-backup-config --schedule schedule-name
   --backupdir backup-directory --configonly=true-or-false
   --activebackupenabled=true-or-false --autobackupenabled=true-or-false
   --recyclelimit recycle-limit backup-config-name
   

   --schedule

   Specifies the name of the schedule that determines when automatic backups are to be performed.

   --backupdir

   Optionally specifies a directory other than the default domain-dir/backups where automatic backups are to be stored.

   --configonly

   Optionally specifies whether automatic backups are to contain only the config subdirectory of the domain or all subdirectories of the domain. The default value is false.

   --activebackupenabled

   Optionally specifies whether the automatic backups are to be performed without suspending the domain during the backup operation. The default value is false.

   --autobackupenabled

   Optionally specifies whether automatic backups are enabled. The default value is true.

   --recyclelimit

   Optionally specifies how many backup files to keep. After this limit is reached, the oldest existing backup is deleted when a new backup needs to be created. The default value is 25.

asadmin> create-backup-config --schedule monthly
--backupdir /net/backups.example.com/glassfish monthly-full
Command create-backup-config executed successfully.

See Also

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

To List Backup Configurations

Use the list-backup-configs subcommand in remote mode to list backup configurations defined in the domain.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List backup configurations by using the list-backup-configs subcommand.

asadmin> list-backup-configs
weekly-config
quarterly-full
Command list-backup-configs executed successfully.

asadmin> list-backup-configs --long quarterly-full
Name of Backup Config   :quarterly-full
Auto Backup Enabled     :true
Schedule                :quarterly
Recycle Limit           :25
Config Only backup      :false
Active Backup Enabled   :false
Backup Directory        :/net/backups.example.com/glassfish
Last Backup Attempt     :Sat Jan 01 00:00:01 PST 2011
Last Successful Backup  :Sat Jan 01 00:00:01 PST 2011

Schedule Details:
NAME       SECOND  MINUTE  HOUR  DAY OF WEEK  DAY OF MONTH  MONTH     YEAR
quarterly  0       0       0     *            1             1,4,7,10  *
Command list-backup-configs executed successfully.

See Also

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

To Enable a Backup Configuration

Use the enable-backup-config subcommand in remote mode to enable automatic backups triggered by a specified backup configuration.

Using the enable-backup-config subcommand is equivalent to using the set subcommand to set the auto-backup-enabled attribute of a backup configuration to true.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Enable the backup configuration by using the enable-backup-config subcommand:

   asadmin> enable-backup-config backup-config-name
   

asadmin> enable-backup-config quarterly-full
Command enable-backup-config executed successfully.

See Also

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

To Disable a Backup Configuration

Use the disable-backup-config subcommand in remote mode to disable automatic backups triggered by a specified backup configuration.

Using the disable-backup-config subcommand is equivalent to using the set subcommand to set the auto-backup-enabled attribute of a backup configuration to false.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Disable the backup configuration by using the disable-backup-config subcommand:

   asadmin> disable-backup-config backup-config-name
   

asadmin> disable-backup-config quarterly-full
Command disable-backup-config executed successfully.

See Also

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

To Delete a Backup Configuration

Use the delete-backup-config subcommand in remote mode to delete a specified backup configuration.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Delete the backup configuration by using the delete-backup-config subcommand:

   asadmin> delete-backup-config backup-config-name
   

asadmin> delete-backup-config quarterly-full
Command delete-backup-config executed successfully.

See Also

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

To Create a Schedule

Use the create-schedule subcommand in remote mode to create a schedule.

A schedule defines a single event at a specified date and time, such as "on January 1, 2012 at 8:00:00", or a series of events occurring with a specified frequency, such as "on the first and sixteenth of every month as midnight".

The create-schedule subcommand uses an event-specification model similar to EJB timers to define a single event or a recurring event. It provides event control for year, month, hour, minute and second units directly, and for day units in terms of both days of the week and days of the month. See create-schedule(1) for complete information about recurrence options for each unit.

GlassFish Server provides three predefined schedules:

• daily, which specifies every day at midnight

• weekly, which specifies every week on Sunday at midnight

• monthly, which specifies every month on the first at midnight

You can use these schedules just as they are defined, or you can edit them to suit your needs.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Create the schedule by using the create-schedule subcommand.

asadmin> create-schedule --dayofmonth 1 --month 1,4,7,10 quarterly
Command create-schedule executed successfully.

See Also

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

To List Schedules

Use the list-schedules subcommand in remote mode to list schedules defined in the domain.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. List schedules by using the list-schedules subcommand.

asadmin> list-schedules --long
NAME         SECOND  MINUTE  HOUR   DAY OF WEEK  DAY OF MONTH  MONTH     YEAR
daily        0       0       0      *            *             *         *
weekly       0       0       0      Sun          *             *         *
monthly      0       0       0      *            1             *         *
quarterly    0       0       0      *            1             1,4,7,10  *
Command list-schedules executed successfully.

See Also

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

To Delete a Schedule

Use the delete-schedule subcommand in remote mode to delete a specified schedule.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Delete the schedule by using the delete-schedule subcommand:

   asadmin> delete-schedule schedule-name
   

asadmin> delete-schedule quarterly
Command delete-schedule executed successfully.

See Also

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

To Back Up a Domain

Use the backup-domain subcommand in local mode to make a backup of a specified domain.

When you use the backup-domain subcommand, GlassFish Server creates a ZIP file backup of all the files and subdirectories in the domain's directory, domain-root-dir/domain-dir, except for the backups subdirectory.

The backup-domain subcommand provides several options to meet particular needs, including:

• --backupdir to specify a directory in which to store the backup instead of the default domain-root-dir/domain-dir/backups.

• --description to provide a description of the backup to be stored in the backup itself.

1. Ensure that the domain is stopped or suspended.

   The backup-domain subcommand operates only when the domain is stopped or suspended.

2. Back up the domain by using the backup-domain subcommand.

3. Restore the domain to its previous state, if necessary.

   Start or resume the domain.

asadmin> backup-domain --backupdir /net/backups.example.com/glassfish domain1
Backed up domain1 at Mon Jan 17 08:16:22 PST 2011.
Command backup-domain executed successfully

See Also

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

To Restore a Domain

Use the restore-domain subcommand in local mode to use a backup file to restore the files and subdirectories in a specified domain's directory.

The restore-domain subcommand can use backup files created by the backup-domain subcommand and by automatic backup configurations, both full backups and configuration-only backups. Automatic backup configurations are available only in Oracle GlassFish Server.

1. If necessary, notify domain users that the domain is being restored from backup.

2. Ensure that the domain is stopped.

   The restore-domain subcommand operates only when the domain is stopped.

   To determine whether the domain is running, use the list-domains subcommand, as described in To List Domains.

   To stop the domain, use the stop-domain subcommand as described in To Stop a Domain.

3. Restore backup files for a domain by using the restore-domain subcommand.

4. Verify that the restore has succeeded.

5. If necessary, notify users that the domain has been restored and is available.

asadmin> restore-domain --backupdir /net/backups.example.com/glassfish domain1
Restored the domain (domain1) to /home/user1/glassfish3/glassfish/domains/domain1
Command restore-domain executed successfully.

See Also

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

To List Domain Backups

Use the list-backups subcommand in local mode to display information about backups of a specified domain stored in a specified backup directory.

The list-backups subcommand provides several options to meet particular needs, including --backupdir to specify a directory where backups are stored instead of the default domain-dir/backups.

List backups by using the list-backups subcommand.

asadmin> list-backups --backupdir /net/backups.example.com/glassfish domain1
CONFIG        USER   BACKUP DATE                   FILENAME
              user1  Mon Jan 17 08:16:22 PST 2011  domain1_2011_01_17_v00001.zip
monthly-full  user1  Wed Dec 01 00:00:00 PST 2010  domain1_2010_12_01_v00001.zip
monthly-full  user1  Sat Jan 01 00:00:03 PST 2011  domain1_2011_01_01_v00001.zip
monthly-full  user1  Tue Feb 01 00:00:01 PST 2011  domain1_2011_02_01_v00001.zip
Command list-backups executed successfully.

See Also

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

To Migrate the DAS

The following steps are required to migrate the DAS from the first host (olddashost) to the third host (newdashost).

1. Install GlassFish Server on newdashost just as it was installed on olddashost.

   This is required so that the DAS can be properly restored on newdashost without causing path conflicts.

2. Use the restore-domain subcommand to restore the latest backup file onto newdashost.

   For example:

   asadmin> restore-domain --backupdir /net/backups.example.com/glassfish
   

   This example assumes that backups are stored in a network-accessible location. If this is not the case, manually copy the latest backup file from offline storage to a directory on newdashost.

   If you have both configuration-only and full backups, restore the latest full backup first. Then, restore the latest configuration-only backup if it is newer than the latest full backup. Use the --backupconfig option of the restore-domain subcommand to specify the appropriate full and configuration-only backups.

   You can backup any domain. However, while re-creating the domain, the domain name should be same as the original.

3. Stop the domain on olddashost, if it is running.

4. Start the domain on newdashost by using the start-domain subcommand.

   For example:

   asadmin> start-domain domain1
   

5. If the domain on olddashost was centrally administered, set up centralized administration on newdashost.

   See "Enabling Centralized Administration of GlassFish Server Instances" in Oracle GlassFish Server High Availability Administration Guide for instructions.

6. Verify that instances on other hosts are visible to the new DAS on newdashost:

   asadmin> list-instances --long
   

7. Update instances on apphost to communicate with the new DAS.

   If the domain uses centralized administration, use the update-admin-server-coordinates subcommand on newdashost:

   asadmin> update-admin-server-coordinates
   

   If the domain does not use centralized administration, use the update-admin-server-local-coordinates subcommand on apphost:

   asadmin> update-admin-server-local-coordinates
   --adminhost host3 --adminport port-number node-name
   

8. Use the new DAS to restart clusters and standalone instances on apphost:

   Restarting the clustered and standalone instances on apphost triggers their recognition of the new DAS on newdashost.

   1. Use the list-clusters subcommand to list the clusters in the domain.

   2. Use the stop-cluster subcommand to stop each cluster.

   3. Use the list-instances subcommand to list the instances in the domain.

   4. Use the restart-instance subcommand to restart each standalone instance.

   5. Use the start-cluster subcommand to start each cluster.

      If the domain does not use centralized administration, use the start-local-instance subcommand to start the cluster instances on apphost.

9. Verify that instances on apphost are running:

   asadmin> list-instances --long
   

10. Decommission and discontinue use of the DAS on olddashost.

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

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.

To Switch a Domain to Another Supported Java Version

GlassFish Server 3.1.2 requires Version 6 Java SE platform as the underlying virtual machine for the Java platform (Java Virtual Machine or JVM machine).

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 the Java SE Downloads page.

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"
   

To Change the Administration Port of a Domain

Use the set subcommand in remote mode to change the administration port of a domain.

The HTTP port or the HTTPS port for administration of a domain is defined by the --adminport option of the create-domain subcommand when the domain is created. If this port must be reallocated for another purpose, change the port on which the DAS listens for administration requests.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Set the port number to its new value.

   Use the set subcommand for this purpose.

   $ asadmin set 
   server-config.network-config.network-listeners.network-listener.admin-listener.port=new-port-number
   

   The new-port-number is the new value that you are setting for the port number.

   Note:

   After you set the port number to its new value, running the list-domains subcommand incorrectly reports that the DAS is not running. The list-domains subcommand reports the correct state again only after you stop and restart the domain as explained in the steps that follow.

3. Stop the domain, specifying the host on which the DAS is running and the old administration port number of the domain.

   You must specify the old port number because the DAS is still listening for administration requests on this port. If you omit the port number, the command fails because the stop-domain subcommand attempts to contact the DAS through the new port number.

   Note:

   Only the options that are required to complete this task are provided in this step. For information about all the options for controlling the behavior of the domain, see the stop-domain(1) help page.

   $ asadmin --host host-name --port old-port-number stop-domain
   

   host-name

   The name of the host on which the DAS is running. If you run the stop-domain subcommand on the host where the DAS is running, you must specify the actual host name and not localhost. If you specify localhost, the stop-domain subcommand fails.

   old-port-number

   The value of administration port number of the domain before you changed it in the preceding step.

4. Start the domain.

   Note:

   Only the options that are required to complete this task are provided in this step. For information about all the options for controlling the behavior of the domain, see the start-domain(1) help page.

   $ start-domain [domain-name]
   

   The domain-name is the name of the domain to start. If only one domain subdirectory is contained in the domains directory, you may omit this option.

$ asadmin set 
server-config.network-config.network-listeners.network-listener.admin-listener.port=4849
server-config.network-config.network-listeners.network-listener.admin-listener.port=4849
Command set executed successfully.
$ asadmin --host xk01.example.com --port 4848 stop-domain
Waiting for the domain to stop ....
Command stop-domain executed successfully.
$ asadmin start-domain
Waiting for domain1 to start ........................
Successfully started the domain : domain1
domain  Location: /export/glassfish3/glassfish/domains/domain1
Log File: /export/glassfish3/glassfish/domains/domain1/logs/server.log
Admin Port: 4849
Command start-domain executed successfully.

See Also

• create-domain(1)

• set(1)

• start-domain(1)

• stop-domain(1)

You can also view the full syntax and options of the subcommands by typing the following commands at the command line:

• asadmin help create-domain

• asadmin help set

• asadmin help start-domain

• asadmin help stop-domain