Using the asadmin Utility

Use the asadmin utility to perform administrative tasks for Sun GlassFish Enterprise Server from the command line or from a script. You can use this utility instead of the Administration Console interface.

The following topics are addressed here:

• Path to the asadmin Utility

• asadmin Utility Syntax

• To Run an asadmin Utility Subcommand in Single Mode

• To Display Help Information for the asadmin Utility or a Subcommand

• To Start a Multimode Session

• To End a Multimode Session

• To Run a Set of asadmin Subcommands From a File

Path to the asadmin Utility

The asadmin utility is located in the as-install/bin directory. To run the asadmin utility without specifying the path, ensure that this directory is in your path.

asadmin Utility Syntax

The syntax for running the asadmin utility is as follows:

asadmin [asadmin-util-options] [subcommand [subcommand-options] [operands]]

The replaceable items in this syntax are described in the subsections that follow. For full details of this syntax, see the asadmin(1M) help page.

Subcommands of the asadmin Utility

The subcommand identifies the operation or task that you are performing. Subcommands are case-sensitive. Each subcommand is either a local subcommand or a remote subcommand.

• A local subcommand can be run without a running domain administration server (DAS). However, to run the subcommand and have access to the installation directory and the domain directory, the user must be logged in to the machine that hosts the domain.

• A remote subcommand is always run by connecting to a DAS and running the subcommand there. A running DAS is required.

For a list of the subcommands for this release of Enterprise Server, see Section 1 of Sun GlassFish Enterprise Server v3 Reference Manual.

asadmin Utility Options and Subcommand Options

Options control the behavior of the asadmin utility and its subcommands. Options are case-sensitive.

The asadmin utility has the following types of options:

• asadmin utility options. These options control the behavior of the asadmin utility, not the subcommand. The asadmin utility options may precede or follow the subcommand, but asadmin utility options after the subcommand are deprecated. All asadmin utility options must either precede or follow the subcommand. If asadmin utility options are specified both before and after the subcommand, an error occurs. For a description of the asadmin utility options, see the asadmin(1M) help page.

• Subcommand Options. These options control the behavior of the subcommand, not the asadmin utility. Subcommand options must follow the subcommand. For a description of a subcommand’s options, see the entry for the subcommand in Sun GlassFish Enterprise Server v3 Reference Manual.

  ---

  Note - Not all subcommand options are supported for this release of Enterprise Server. If you specify an unsupported option, a syntax error does not occur. Instead, the command runs successfully and the unsupported option is silently ignored.

  ---

A subcommand option may have the same name as an asadmin utility option, but the effects of the two options are different.

Options have a long form and a short form.

• The short form of an option has a single dash (-) followed by a single character.

• The long form of an option has two dashes (--) followed by an option word.

For example, the short form and the long form of the option for specifying terse output are as follows:

• Short form: -t

• Long form: --terse

Most options require argument values, except Boolean options, which toggle to enable or disable a feature.

Operands of asadmin Utility Subcommands

Operands specify the items on which the subcommand is to act. Operands must follow the argument values of subcommand options, and are set off by a space, a tab, or double dashes (--). The asadmin utility treats anything that follows the subcommand options and their values as an operand.

To Run an asadmin Utility Subcommand in Single Mode

In single mode, you must type a separate asadmin command for each subcommand that you want to use. After the subcommand has run, you are returned to the operating system's command shell. Any asadmin utility options must be specified in each separate asadmin command that you run. If you require the same asadmin utility options for multiple subcommands, use the asadmin utility in multimode. For more information, see To Start a Multimode Session.

• In the operating system's command shell, run the asadmin utility, specifying the subcommand.

  If necessary, also specify any required asadmin utility options, subcommand options, and operands.

Running an asadmin Utility Subcommand in Single Mode

This example runs the list-applications(1) subcommand in single mode. In this example, the default values for all options are used.

The example shows that the application hello is deployed on the local host.

asadmin list-applications
hello <web>
Command list-applications executed successfully.

Specifying an asadmin Utility Option With a Subcommand in Single Mode

This example specifies the --host asadmin utility option with the list-applications subcommand in single mode. In this example, the DAS is running on the host srvr1.example.com.

The example shows that the applications basic-ezcomp, scrumtoys, ejb31-war, and automatic-timer-ejb are deployed on the host srvr1.example.com.

asadmin --host srvr1.example.com list-applications
basic-ezcomp <web>
scrumtoys <web>
ejb31-war <ejb, web>
automatic-timer-ejb <ejb>
Command list-applications executed successfully.

Specifying an asadmin Utility Option and a Subcommand Option in Single Mode

This example specifies the --host asadmin utility option and the --type subcommand option with the list-applications subcommand in single mode. In this example, the DAS is running on the host srvr1.example.com and applications of type web are to be listed.

asadmin --host srvr1.example.com list-applications --type web
basic-ezcomp <web>
scrumtoys <web>
ejb31-war <ejb, web>
Command list-applications executed successfully.

To Display Help Information for the asadmin Utility or a Subcommand

Enterprise Server provides help information about the syntax, purpose, and options of the asadmin utility and its subcommands. This help information is written in the style of UNIX platform man pages. This help information is also available in Sun GlassFish Enterprise Server v3 Reference Manual.

1. If you are displaying help information for a remote subcommand, ensure that the server is running.

   Remote subcommands require a running server.

2. Specify the subcommand of interest as the operand of the help subcommand.

   If you run the help subcommand without an operand, help information for the asadmin utility is displayed.

Displaying Help Information for the asadmin Utility

This example displays the help information for the asadmin utility.

asadmin help

Displaying Help Information for an asadmin Utility Subcommand

This example displays the help information for the create-jdbc-resource subcommand.

asadmin help create-jdbc-resource

See Also

To display the available subcommands, use the list-commands(1) subcommand. Local subcommands are displayed before remote subcommands. If the server is not running, only local subcommands are displayed.

To Start a Multimode Session

The asadmin utility can be used in multiple command mode, or multimode. In multimode, you run the asadmin utility once to start a multimode session. During the session, the asadmin utility continues to accept subcommands until you end the session and return to the operating system's command shell. Any asadmin utility options that you set for your multimode session are used for all subsequent subcommands in the session.

• Do one of the following:

  • Run the asadmin utility without a subcommand.

  • Use the multimode(1) subcommand.

  If necessary, also specify any asadmin utility options that will apply throughout the multimode session.

  In a multimode session, the asadmin> prompt is displayed on the command line. You can now type asadmin subcommands at this prompt to administer Enterprise Server.

Starting a Multimode Session With asadmin Utility Options

This example starts a multimode session in which the asadmin utility options --user and --passwordfile are set for the session.

asadmin --user admin1 --passwordfile pwd.txt multimode

Starting a Multimode Session by Using the multimode Subcommand

This example uses the multimode subcommand to start a multimode session in which the default asadmin utility options are used.

asadmin multimode

The asadmin> prompt is displayed on the command line.

Running a Subcommand in a Multimode Session

This example starts a multimode session and runs the list-domains subcommand in the session.

asadmin
Enter commands one per "line", ^D to quit
asadmin> list-domains
Name: domain1 Status: Running
Command list-domains executed successfully.
asadmin>

Starting a Multimode Session From Within an Existing Multimode Session

You can start a multimode session from within an existing session by running the multimode subcommand from within the existing session. After you end the second multimode session, you return to your original multimode session.

See Also

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

To End a Multimode Session

• At the asadmin> prompt, type one of the following commands or key combinations:

  • exit

  • quit

  • UNIX and Linux systems: Ctrl-D

  • Windows systems: Ctrl-Z

  You are returned to the operating system's command shell and the asadmin> prompt is no longer displayed. If the asadmin> prompt is still displayed, you might have opened a multimode session within a multimode session. In this situation, repeat this procedure to end the remaining multimode session.

To Run a Set of asadmin Subcommands From a File

Running a set of asadmin subcommands from a file enables you to automate repetitive tasks.

1. Create a plain text file that contains the sequence of subcommands that you want to run.

2. Run the multimode(1) subcommand, specifying the file that you created.

   If necessary, also specify any asadmin utility options that are required to enable subcommands in the file to run.

Running a Set of asadmin Subcommands From a File

This example contains the following:

• A listing of a file that is named commands_file.txt, which contains a sequence of asadmin subcommands

• The command to run the subcommands in the file commands_file.txt

The commands_file.txt file contains the asadmin utility subcommands to perform the following sequence of operations:

1. Creating the domain customdomain

2. Starting the domain customdomain

3. Listing all available subcommands

4. Stopping the domain customdomain

5. Deleting the domain customdomain

The content of the commands_file.txt file is as follows:

create-domain --portbase 9000 customdomain
start-domain customdomain
list-commands
stop-domain customdomain
delete-domain customdomain

This example runs the sequence of subcommands in the commands_file.txt file. Because the --portbase option is specified for the create-domain subcommand in the file, the --port asadmin utility option must also be set.

asadmin --port 9048 multimode --file commands_file.txt

See Also

For more information about the subcommands in the preceding example, see the following help pages:

• create-domain(1)

• delete-domain(1)

• list-commands(1)

• multimode(1)

• start-domain(1)

• stop-domain(1)