Download this book in PDF (1147 KB)

asadmin(1M)

Name | Synopsis | Description | Examples | Attributes | See Also

Name

asadmin– utility for performing administrative tasks for Sun GlassFish Enterprise Server

Synopsis

asadmin  subcommand [-short-option[ short-option-argument]]*
 [--long-option[ long-option-argument]]* [operand]*

Description

Use the asadmin utility to perform administrative tasks for Sun GlassFish Enterprise Server. You can use this utility instead of the Administration Console interface.

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.

Options for the asadmin Utility

Options control how the asadmin utility performs a subcommand. Options are also case-sensitive.

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 the asadmin Utility

Operands appear after the argument values, and are set off by a space, a tab, or double dashes (--). The asadmin utility treats anything that comes after the options and their values as an operand.

Required Options for Remote asadmin Subcommands

All remote subcommands require the following options:

-t --terse

Indicates that any output data must be very concise, typically avoiding human-friendly sentences and favoring well-formatted data for consumption by a script. Default is false.

-e --echo

If set to true, the command-line statement is echoed on the standard output. Default is false.

-I --interactive

If set to true (default), only the required password options are prompted.

-H --host

The machine name where the domain administration server is running. The default value is localhost.

-p --port

The HTTP port or HTTPS port for administration. This port is the port in the URL that you specify in your web browser to manage the domain, for example, http://localhost:4848.

The default port number for administration is 4848.

-s --secure

If set to true, uses SSL/TLS to communicate with the domain administration server.

The default is false.

-u --user

The user name of the authorized administrative user of the domain administration server.

If you have authenticated to a domain by using the asadmin login command, you need not specify the --user option for subsequent operations on the domain.

--passwordfile

Specifies the name, including the full path, of a file that contains the password entries in a specific format.

The entry for a password must have the AS_ADMIN_ prefix followed by the password name in uppercase letters. For example, to specify the password for the domain administration server, use an entry with the following format:

AS_ADMIN_PASSWORD=password

In this example, password is the actual administrator password.

The following other passwords can also be specified:

• AS_ADMIN_MAPPEDPASSWORD

• AS_ADMIN_USERPASSWORD

• AS_ADMIN_ALIASPASSWORD

All remote commands must specify the administration password to authenticate to the domain administration server. The password can be specified by one of the following means:

• Through the --passwordfile option

• Through the asadmin login command

• Interactively at the command prompt

The asadmin login command can be used only to specify the administration password. For other passwords that remote commands require, use the --passwordfile option or specify them at the command prompt.

After authenticating to a domain by using the asadmin login command, you need not specify the administration password through the --passwordfile option for subsequent operations on the domain. However, only the AS_ADMIN_PASSWORD option is not required. You still must provide the other passwords, for example, AS_ADMIN_USERPASSWORD, when required by individual commands, such as update-file-user.

For security reasons, a password that is specified as an environment variable is not read by the asadmin command.

The default value for AS_ADMIN_MASTERPASSWORD is changeit.

--help

Displays the help text for the command.

Escape Characters in Options for the asadmin Utility

Escape characters are required in options of the asadmin utility for the following types of characters:

• Meta characters in the UNIX® operating system. These characters have special meaning in a shell. Meta characters in the UNIX operating system include: \/,.!$%^&*|{}[]”'`~;.

  To disable these characters, use the escape character backslash (\).

  The following examples illustrate the effect of the escape character on the * character. In these examples, the current working directory is the domain directory.

  • The following command, without the escape character, echoes all files in the current directory:

    prompt% echo * applications config docroot generated logs master-password session-store

  • The following command, in which the escape character precedes the * character, echoes the * character:

    prompt% echo \* *

• The escape character for Java technology special characters. The escape character backslash (\) identifies Java technology special characters such as:

  • \n for new line

  • \b for backspace

  • \t for tab

  • \" for double quote

  An extra escape character is required to represent the literal \ character.

• Option delimiters. The asadmin utility uses the colon character (:) as a delimiter for options. The escape character backslash (\) is required if the colon is part of any of the following items:

  • A property

  • An option of the Virtual Machine for the Java platform (Java Virtual Machine or JVM machine) [The terms "Java Virtual Machine" and "JVM" mean a Virtual Machine for the Java platform.]

  For example, the operand of the command create-jvm-options(1) specifies JVM machine options in the following format:

  (jvm-option-name[=jvm-option-value]) [:jvm-option-name[=jvm-option-value]]*

  Multiple JVM machine options in the operand of the create-jvm-options command are separated by the colon (:) delimiter. If jvm-option-name or jvm-option-value contains a colon, the escape character backslash (\) is required before the colon.

The escape character disables the delimiter in the command-line interface, and is a special character in the UNIX operating system and in Java technology. Therefore, in the UNIX operating system, you must apply an escape character to every escape character in the command line. This requirement does not apply to the Windows operating system.

---

Tip –

Instead of using the backslash (\) escape character, you can use the double quote character ("). However, because the double quote is a special character in Java technology, you must add an escape character in single mode.

---

Password File Options

The --passwordfile option takes the file containing the passwords. The valid contents for the file are:

AS_ADMIN_PASSWORD=value
AS_ADMIN_ADMINPASSWORD=value
AS_ADMIN_USERPASSWORD=value
AS_ADMIN_MASTERPASSWORD=value

If the AS_ADMIN_PASSWORD environment variable has been exported to the global environment, specifying the --passwordfile option produces a warning about using the --password option. To avoid this warning, unset the AS_ADMIN_PASSWORD environment variable.

The master password is not propagated on the command line or an environment variable, but can be specified in the file that the --passwordfile option specifies.

Requirements for Using the --secure Option

To use the --secure option, you must use the set(1) command to set the security-enabled attribute of the http-listener in Sun GlassFish Enterprise Server v3 Prelude Administration Reference element to true. This element is stored in the domain.xml configuration file.

Server Restart After Creation or Deletion

When you use the asadmin subcommands to create or delete an item, you must restart the DAS for the change to take effect. To restart the DAS, use the start-domain(1) command.

Usage Information for asadmin Utility Subcommands

To obtain usage information for an asadmin utility subcommand, specify the --help option. If you specify a subcommand, the usage information for that subcommand is displayed. If you specify the --help option without a subcommand, this usage information for the asadmin utility is displayed.

To obtain a listing of available asadmin subcommands, use the list-commands(1) command.

Examples

---

Example 1 Specifying a UNIX Operating System Meta Character in an Option




The commands in this example show how to specify the UNIX operating system meta character backslash (\) in the option argument Test\Escape\Character.

For the UNIX operating system, the backslash (\) is required to escape the meta character backslash (\):

asadmin create-jdbc-connection-pool -u admin --passwordfile mypasswordfile --datasourceclassname --description Test\\Escape\\Character sampleJDBCConnectionPool

For the Windows operating system, no escape character is required:

asadmin create-jdbc-connection-pool -u --passwordfile mypasswordfile --datasourceclassname sampleClassName --description Test\Escape\Character sampleJDBCConnectionPool

---

---

Example 2 Specifying a Meta Character and an Option Delimiter Character in a Property




The commands in this example show how to specify the UNIX operating system meta character backslash (\) and the option delimiter character colon (:) in the --property option of the create-jdbc-connection-pool(1) command.

The name and value pairs for the --property option are as follows:

user=dbuser passwordfile=dbpasswordfile DatabaseName=jdbc:derby server=http://localhost:9092

For the UNIX operating system, a backslash (\) is required to escape the colon (:) and the backslash (\):

asadmin create-jdbc-connection-pool --user --passwordfile mypasswordfile --port 4848 --host localhost --datasourceclassname com.derby.jdbc.jdbcDataSource --property user=dbuser:passwordfile=dbpasswordfile: DatabaseName=jdbc\\:derby:server=http\\://localhost\\:9092 sqe-jdbc-pool

For the Windows operating system, a backslash (\) is required to escape only the colon (:), but not the backslash (\):

asadmin create-jdbc-connection-pool --user admin --passwordfile mypasswordfile --port 4848 --host localhost --datasourceclassname com.derby.jdbc.jdbcDataSource --property user-dbuser:passwordfile-dbpasswordfile: DatabaseName=jdbc\:derby:server=http\://localhost\:9092 sqe-jdbc-pool

For all operating systems, the need to escape the colon (:) in a value can be obviated by enclosing the value in double quotes:

asadmin create-jdbc-connection-pool --user --passwordfile mypasswordfile --port 4848 --host localhost --datasourceclassname com.derby.jdbc.jdbcDataSource --property user=dbuser:passwordfile=dbpasswordfile: DatabaseName=\"jdbc:derby\":server=\"http://localhost:9092\" sqe-jdbc-pool

---

---

Example 3 Specifying an Option Delimiter and a Java Technology Escape Character in a JVM Machine Option




The commands in this example show how to specify the following characters in the JVM machine option -Dlocation=c:\sun\appserver:

• The option delimiter colon (:)

• The Java technology escape character backslash (\)

For the UNIX operating system, two backslashes (\\) are required to escape the colon (:) and three backslashes (\\\) are required to escape the backslash (\). As a result, a total of four backslashes are required:

1. The first backslash escapes the UNIX operating system meta character.

2. The second backslash escapes the Java escape character.

3. The third backslash escapes the UNIX operating system meta character.

4. The fourth backslash is the literal value.

The resulting command is as follows:

asadmin create-jvm-options --target test-server -e -Dlocation=c\\:\\\\sun\\\\appserver

For the Windows operating system, a backslash (\) is required to escape the colon (:) and the backslash (\):

asadmin create-jvm-options --target test-server -e -Dlocation=c\:\\sun\\appserver

---

---

Example 4 Specifying an Option That Contains an Escape Character




The commands in this example show how to specify the backslash character in the option argument "admin\admin".

For the UNIX operating system, a backslash (\) is required to escape the double quote (") and the backslash (\):

asadmin list-jdbc-resources --user \"admin\\admin\" --passwordfile mypasswordfile --host localhost --port 4848

For the Windows operating system, a backslash (\) is required to escape only the double quote ("), but not the backslash (\):

asadmin list-jdbc-resources --user \"admin\admin\" --passwordfile mypasswordfile --host localhost --port 4848

---

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Unstable

See Also

create-jdbc-connection-pool(1), create-jvm-options(1), list-commands(1), set(1), start-domain(1)

attributes(5)

http-listener in Sun GlassFish Enterprise Server v3 Prelude Administration Reference

Name | Synopsis | Description | Examples | Attributes | See Also