WebLogic Server Command Reference

weblogic.Admin Command-Line Reference

The weblogic.Admin utility is a command-line interface that you can use to administer, configure, and monitor WebLogic Server.

Like the Administration Console, for most commands this utility assumes the role of client that invokes administrative operations on the Administration Server, which is the central management point for all servers in a domain. (All Managed Servers retrieve configuration data from the Administration Server, and the Administration Server can access runtime data from all Managed Servers.) While the Administration Console interacts only with the Administration Server, the weblogic.Admin utility can access the Administration Server as well as all active server instances directly. If the Administration Server is down, you can still use the weblogic.Admin utility to retrieve runtime information from Managed Servers and invoke some administrative commands. However, you can save configuration changes to the domain's config.xml file only when you access the Administration Server.

To automate administrative tasks, you can invoke the weblogic.Admin utility from shell scripts. If you plan to invoke this utility multiple times from a shell script, consider using the BATCHUPDATE command, which is described in Running Commands in Batch Mode.

The following sections describe using the weblogic.Admin utility:

For more information, see:

"Deployment Tools Reference" in Deploying WebLogic Server Applications. Describes how to deploy J2EE modules on a WebLogic Server instance using the weblogic.Deployer command-line utility.
Using Command-Line Utilities to Configure a WebLogic Server Domain. Provides extended examples of using weblogic.Admin commands to configure a WebLogic Server domain.

Required Environment for the weblogic.Admin Utility

To set up your environment for the weblogic.Admin utility:

Install and configure the WebLogic Server software, as described in the WebLogic Server Installation Guide

Add WebLogic Server classes to the CLASSPATH environment variable and WL_HOME\server\bin to the PATH environment variable.

You can use a WL_HOME\server\bin\setWLSenv script to set both variables. See Modifying the Classpath.

If you want the weblogic.Admin utility to use a listen port that is reserved for administration traffic, you must configure a domain-wide administration port as described in "Enabling the Domain-Wide Administration Port" in the Administration Console Online Help.

The domain-wide administration port is secured by SSL. For information about using secured ports with the weblogic.Admin utility, refer to SSL Arguments.

Note: If a server instance is deadlocked, it can respond to weblogic.Admin commands only if you have enabled the domain-wide administration port. If you have not already enabled the domain-wide administration port, your only option is to shut down the server instance by killing the Java process that is running the server. You will lose all session data. For information on enabling the domain-wide administration port, refer to "Enabling the Domain-Wide Administration Port" in the Administration Console Online Help.

Syntax for Invoking the weblogic.Admin Utility

java [ SSL Arguments ]
     weblogic.Admin 
     [ Connection Arguments ] 
     [ User Credentials Arguments ]
     COMMAND-NAME command-arguments

The command names and arguments are not case sensitive.

The following sections provide detailed syntax information:

Note: Both the weblogic.Deployer tool and the BEA WebLogic Scripting Tool (WLST) also use the SSL arguments, Connection arguments, and User Credentials arguments.

SSL Arguments

java [ -Dweblogic.security.TrustKeyStore=DemoTrust ]
     [ -Dweblogic.security.JavaStandardTrustKeystorePassPhrase=password ]
     [ -Dweblogic.security.CustomTrustKeyStoreFileName=filename 
       -Dweblogic.security.TrustKeystoreType=CustomTrust
       [-Dweblogic.security.CustomTrustKeystorePassPhrase=password ]
     ]
     [ -Dweblogic.security.SSL.hostnameVerifier=classname ]
     [ -Dweblogic.security.SSL.ignoreHostnameVerification=true ]
     weblogic.Admin 
     [ User Credentials Arguments ] 
     COMMAND-NAME command-arguments

If you have enabled the domain-wide administration port, or if you want to secure your administrative request by using some other listen port that is secured by SSL, you must include SSL arguments when you invoke weblogic.Admin. Table 1-1 describes all SSL arguments for the weblogic.Admin utility.

Table 1-1 SSL Arguments

Argument	Definition
`-Dweblogic.security. TrustKeyStore= DemoTrust`	Causes `weblogic.Admin` to trust the CA certificates in the demonstration trust keystore (`WL_HOME\server\lib\DemoTrust.jks`). This argument is required if the server instance to which you want to connect is using the demonstration identity and certificates. By default, `weblogic.Admin` trusts only the CA certificates in the Java Standard Trust keystore (`SDK_HOME\jre\lib\security\cacerts`).
`-Dweblogic.security. JavaStandardTrustKeysto rePassPhrase=password`	Specifies the password that was used to secure the Java Standard Trust keystore. If the Java Standard Trust keystore is protected by a password, and if you want to trust its CA certificates, you must use this argument. By default, the Java Standard Trust keystore is not protected by a password.
`-Dweblogic.security. CustomTrustKeyStoreFileNa me=filename` `-Dweblogic.security.Trust KeystoreType=CustomTrust`	Causes `weblogic.Admin` to trust the CA certificates in a custom keystore that is located at `filename`. You must use both arguments to trust custom keystores.
`-Dweblogic.security.Custo mTrustKeystorePassPhrase=password`	Specifies the password that was used to secure the custom keystore. You must use this argument only if the custom keystore is protected by a password.
`-Dweblogic.security.SSL. hostnameVerifier=classname`	Specifies the name of a custom Host Name Verifier class. The class must implement the `weblogic.security.SSL.HostnameVerifier` interface.
`-Dweblogic.security.SSL. ignoreHostnameVerificat ion=true`	Disables host name verification.

Using SSL to Secure Administration Requests: Main Steps

To secure administration requests with SSL:

Ensure that two-way SSL is disabled on the server instance to which you want to connect.

See "Using the SSL Protocol to Connect to WebLogic Server from weblogic.Admin" in Managing WebLogic Security.
By default, when you enable SSL, a server instance supports one-way SSL. Because two-way SSL provides additional security, you might have enabled two-way SSL. However, weblogic.Admin does not support two-way SSL.

Ensure that the trusted CA certificates are stored in a keystore that the weblogic.Admin utility can access through the file system.

When you invoke the weblogic.Admin utility, include arguments that specify the following:

A secure protocol and port.

See Protocol Support.

(Optional) The trusted CA certificates and certificate authorities.

See Specifying Trust for weblogic.Admin.

(Optional) A host name verifier.

See Specifying Host Name Verification for weblogic.Admin.

Specifying Trust for weblogic.Admin

When the weblogic.Admin utility connects to a server's SSL port, it must specify a set of certificates that describe the certificate authorities (CAs) that the utility trusts. See "Private Keys, Digital Certificates and Trusted Certificate Authorities" in Managing WebLogic Security.

To specify trust for weblogic.Admin:

To trust only the CA certificates in the Java Standard Trust keystore, you do not need to specify command-line arguments, unless the keystore is protected by a password.

If the Java Standard Trust keystore is protected by a password, use the following command-line argument:
-Dweblogic.security.JavaStandardTrustKeystorePassPhrase=password

To trust both the CA certificates in the Java Standard Trust keystore and in the demonstration trust keystore, include the following argument:

-Dweblogic.security.TrustKeyStore=DemoTrust
This argument is required if the server instance to which you want to connect is using the demonstration identity and certificates.
If the Java Standard Trust keystore is protected by a password, include the following command-line argument:
-Dweblogic.security.JavaStandardTrustKeystorePassPhrase=password

To trust only the CA certificates in a keystore that you create, specify the following command-line arguments:

-Dweblogic.security.CustomTrustKeyStoreFileName=filename

where filename specifies the fully qualified path to the trust keystore.

-Dweblogic.security.TrustKeystoreType=CustomTrust

This optional command-line argument specifies the type of the keystore. Generally, this value for type is jks.

If the custom keystore is protected by a password, include
-Dweblogic.security.CustomTrustKeystorePassPhrase=password

Specifying Host Name Verification for weblogic.Admin

A host name verifier ensures the host name URL to which the client connects matches the host name in the digital certificate that the server sends back as part of the SSL connection. A host name verifier is useful when an SSL client, or a SSL server acting as a client, connects to an application server on a remote host. It helps to prevent man-in-the-middle attacks. See "Using Host Name Verification" in Managing WebLogic Security.

To specify host name verification for weblogic.Admin:

To use the host name verifier that the WebLogic Security Service provides, you do not need to specify host-name verification arguments.

Note: If you specify an IP address or the localhost string in the weblogic.Admin -url or -adminurl argument, the host name verifier that the WebLogic Security Service provides will allow the connection if the CN field of the digital certificate matches the DNS name of the local host.

To use a custom host name verifier, specify:
-Dweblogic.security.SSL.hostnameVerifier=classname

where classname specifies the implementation of the weblogic.security.SSL.HostnameVerifier interface.

To disable host name verification, specify:
-Dweblogic.security.SSL.ignoreHostnameVerification=true

Connection Arguments

java [ SSL Arguments ]
     weblogic.Admin 
     [ {-url URL} | {-adminurl URL} ]
     [ User Credentials Arguments ]
     COMMAND-NAME command-arguments

When you invoke most weblogic.Admin commands, you specify the arguments in Table 1-2 to connect to a WebLogic Server instance. Some commands have special requirements for the connection arguments. Any special requirements are described in the command documentation.

Table 1-2 Connection Arguments

Argument	Definition
`-url` [`protocol://`]`listen-address:listen-port`	The listen address and listen port of the server instance that runs the command. In most cases, you should specify the Administration Server's address and port, which is the central management point for all servers in a domain. Some commands, such as START and CREATE, must run on the Administration Server. The documentation for each command indicates whether this is so. If you specify a Managed Server's listen address and port, the command can access data only for that server instance; you cannot run a command on one Managed Server to view or change data for another server instance. When you use MBean-related commands, you must specify the Administration Server's listen address and port to access Administration MBeans. To access Local Configuration MBeans or Runtime MBeans, you can specify the server instance on which the MBeans reside. (However, the `-adminurl` argument can also retrieve Local Configuration MBeans or Runtime MBeans from any server.) For more information on where MBeans reside, refer to "WebLogic Server Managed Resources and MBeans" in the Programming WebLogic Management Services with JMX guide. To use a listen port that is not secured by SSL, the format is `-url` `[protocol://]listen-address:port` To use a port that is secured by SSL, the format is `-url` `secure-protocol://listen-address:port` If you have set up a domain-wide administration port, you must specify the administration port number: `-url` `secure-protocol://listen-address:domain-wide-admin-port` For information about valid values for `protocol` and `secure-protocol`, refer to Protocol Support. For more information about the listen address and listen ports, refer to -Dweblogic.ListenAddress=host and -Dweblogic.ListenPort= portnumber. For more information about the domain-wide administration port, refer to "Enabling the Domain-Wide Administration Port" in the Administration Console Online Help. The default value for this argument is `t3://localhost:7001`.
`-adminurl` [`protocol://`]`Admin-Server-listen-address:listen-port`	Enables the Administration Server to retrieve Local Configuration MBeans or Runtime MBeans for any server instance in the domain. For information about types of MBeans, refer to "WebLogic Server Managed Resources and MBeans" in the Programming WebLogic Management Services with JMX guide. For all commands other than the MBean commands, `-adminurl` `admin-address` and `-url` `admin-address` are synonymous. The `-adminurl` value must specify the listen address and listen port of the Administration Server. To use a port that is not secured by SSL, the format is `-adminurl` `[protocol]Admin-Server-listen-address:port`. To use a port that is secured by SSL, the format is `-adminurl` `secure-protocol://Admin-Server-listen-address:port` If you have set up a domain-wide administration port, you must specify the administration port number: `-adminurl` `secure-protocol://Admin-Server-listen-address:domain-wide-admin-port` For information about valid values for `protocol` and `secure-protocol`, refer to Protocol Support. There is no default value for this argument.

Argument

Definition

-url [protocol://]listen-address:listen-port

The listen address and listen port of the server instance that runs the command.

In most cases, you should specify the Administration Server's address and port, which is the central management point for all servers in a domain. Some commands, such as START and CREATE, must run on the Administration Server. The documentation for each command indicates whether this is so.

If you specify a Managed Server's listen address and port, the command can access data only for that server instance; you cannot run a command on one Managed Server to view or change data for another server instance.

When you use MBean-related commands, you must specify the Administration Server's listen address and port to access Administration MBeans. To access Local Configuration MBeans or Runtime MBeans, you can specify the server instance on which the MBeans reside. (However, the -adminurl argument can also retrieve Local Configuration MBeans or Runtime MBeans from any server.) For more information on where MBeans reside, refer to "WebLogic Server Managed Resources and MBeans" in the Programming WebLogic Management Services with JMX guide.

To use a listen port that is not secured by SSL, the format is -url [protocol://]listen-address:port

To use a port that is secured by SSL, the format is -url secure-protocol://listen-address:port

If you have set up a domain-wide administration port, you must specify the administration port number: -url secure-protocol://listen-address:domain-wide-admin-port

For information about valid values for protocol and secure-protocol, refer to Protocol Support.

For more information about the listen address and listen ports, refer to -Dweblogic.ListenAddress=host and -Dweblogic.ListenPort= portnumber.

For more information about the domain-wide administration port, refer to "Enabling the Domain-Wide Administration Port" in the Administration Console Online Help.

The default value for this argument is t3://localhost:7001.

-adminurl [protocol://]Admin-Server-listen-address:listen-port

Enables the Administration Server to retrieve Local Configuration MBeans or Runtime MBeans for any server instance in the domain.

For information about types of MBeans, refer to "WebLogic Server Managed Resources and MBeans" in the Programming WebLogic Management Services with JMX guide.

For all commands other than the MBean commands, -adminurl admin-address and -url admin-address are synonymous.

The -adminurl value must specify the listen address and listen port of the Administration Server.

To use a port that is not secured by SSL, the format is -adminurl [protocol]Admin-Server-listen-address:port.

To use a port that is secured by SSL, the format is -adminurl secure-protocol://Admin-Server-listen-address:port

If you have set up a domain-wide administration port, you must specify the administration port number: -adminurl secure-protocol://Admin-Server-listen-address:domain-wide-admin-port

For information about valid values for protocol and secure-protocol, refer to Protocol Support.

There is no default value for this argument.

User Credentials Arguments

java [ SSL Arguments ]
     weblogic.Admin 
     [ Connection Arguments ] 
     [ { -username username [-password password] } |
       [ -userconfigfile config-file [-userkeyfile admin-key] ] 
     ]
     COMMAND-NAME command-arguments

When you invoke most weblogic.Admin commands, you specify the arguments in Table 1-3 to provide the user credentials of a WebLogic Server user who has permission to invoke the command.

Table 1-3 User Credentials Arguments

Argument	Definition
`-username` `username`	The name of the user who is issuing the command. This user must have appropriate permission to view or modify the target of the command. For information about permissions for system administration tasks, refer to "Security Roles" in the Securing WebLogic Resources guide.
`-password` `password`	The password that is associated with the username. If you do not specify the `-password` argument, `weblogic.Admin` prompts you for a password. If `WL_HOME\server\bin` is specified in the `PATH` environment variable, `weblogic.Admin` uses a set of WebLogic Server libraries that prevent the password from being echoed to standard out. For information on setting environment variables, see Required Environment for the weblogic.Admin Utility.
`-userconfigfile` config-file	Specifies the name and location of a user-configuration file, which contains an encrypted username and password. The encrypted username must have permission to invoke the command you specify. If you do not specify `-userconfigfile` config-file, and if you do not specify `-username` `username`, `weblogic.Admin` searches for a user-configuration file at the default path name. (See STOREUSERCONFIG.)
`-userkeyfile` admin-key	Specifies the name and location of the key file that is associated with the user-configuration file you specify. When you create a user-configuration file, the `STOREUSERCONFIG` command uses a key file to encrypt the username and password. Only the key file that encrypts a user-configuration file can decrypt the username and password. If you do not specify `-userkeyfile` admin-key, `weblogic.Admin` searches for a key file at the default path name. (See STOREUSERCONFIG.)

Note: The exit code for all commands is 1 if the Administration client cannot connect to the server or if the WebLogic Server instance rejects the username and password.

Specifying User Credentials

The simplest way to specify user credentials is to create a user configuration file and key file in the default location. Thereafter, you do not need to include user credentials in weblogic.Admin invocations. A user-configuration file contains encrypted user credentials that can be decrypted only by a single key file. See STOREUSERCONFIG.

For example, the following command creates a user configuration file and key file in the default location:

java weblogic.Admin -username weblogic -password weblogic STOREUSERCONFIG

After you enter this STOREUSERCONFIG command, you can invoke weblogic.Admin without specifying credentials on the command line or in scripts. For example:

java weblogic.Admin GET -pretty -type -Domain

If you create a user configuration file or key file in a location other than the default, you can include the -userconfigfile config-file and -userkeyfile admin-key arguments on the command line or in scripts.

If you do not create a user configuration file and key file, you must use the -username and -password arguments when invoking the weblogic.Admin utility directly on the command line or in scripts. With these arguments, the username and password are not encrypted. If you store the values in a script, the user credentials can be used by anyone who has read access to the script.

The following list summarizes the order of precedence for the weblogic.Admin user-credentials arguments:

If you specify -username username -password password, the utility passes the unencrypted values to the server instance you specify in the -url argument.

These arguments take precedence over the { -userconfigfile config-file -userkeyfile admin-key } arguments.

If you specify -username username, the utility prompts for a password. Then it passes the unencrypted values to the server instance you specify in the -url argument.

This argument also takes precedence over the { -userconfigfile config-file -userkeyfile admin-key } arguments.

If you specify { -userconfigfile config-file -userkeyfile admin-key } and do not specify { -username username [-password password]}, the utility passes the values that are encrypted in config-file to the server instance you specify in the -url argument.
If you specify neither { -username username [-password password] } nor { -userconfigfile config-file -userkeyfile admin-key }, the utility searches for a user-configuration file and key file at the default path names. The default path names vary depending on the JVM and the operating system. See Configuring the Default Path Name.

Examples of Providing User Credentials

The following command specifies the username weblogic and password weblogic directly on the command line:
java weblogic.Admin -username weblogic -password weblogic COMMAND

The following command uses a user-configuration file and key file that are located at the default pathname:
java weblogic.Admin COMMAND

See Configuring the Default Path Name.

The following command uses a user-configuration file named c:\wlUser1-WebLogicConfig.properties and a key file named e:\secure\myKey:
java -userconfigfile c:\wlUser1-WebLogicConfig.properties -userkeyfile e:\secure\myKeyCOMMAND

Protocol Support

The -url and -adminurl arguments of the weblogic.Admin utility support the t3, t3s, http, https, and iiop protocols.

If you want to use http or https to connect to a server instance, you must enable HTTP Tunneling for that instance. For more information, refer to "Configuring the HTTP Protocol" in the Administration Console Online Help.

If you want to use iiop to connect to a server instance, you must enable the iiop protocol for that instance. For more information, refer to "Enabling and Configuring the IIOP Protocol" in the Administration Console Online Help.

If you use the -url argument to specify a non-secured port, the weblogic.Admin utility uses t3 by default. For example, java weblogic.Admin -url localhost:7001 resolves to java weblogic.Admin -url t3://localhost:7001.

If you use either the -url or -adminurl argument to specify a port that is secured by SSL, you must specify either t3s or https. See Using SSL to Secure Administration Requests: Main Steps.

Example Environment

In many of the examples throughout the sections that follow, it is assumed that a certain environment has been set up:

The WebLogic Server administration domain is named MedRec.
The Administration Server is named MedRecServer and listens on port 7001.
The Administration Server uses the name of its host machine, AdminHost, as its listen address. For more information about the listen address and listen ports, refer to -Dweblogic.ListenAddress=host and -Dweblogic.ListenPort= portnumber.
The weblogic username has system-administrator privileges and uses weblogic for a password.
The user credentials have not been encrypted in a user configuration file.
A Managed Server named MedRecManagedServer uses the name of its host machine, ManagedHost, as its listen address and 8001 as its listen port.

Exit Codes Returned by weblogic.Admin

All weblogic.Admin commands return an exit code of 0 if the command succeeds and an exit code of 1 if the command fails.

To view the exit code from a Windows command prompt, enter echo %ERRORLEVEL% after you run a weblogic.Admin command. To view the exit code in a bash shell, enter echo $?.

For example:

D:\>java weblogic.Admin -username weblogic -password weblogic GET -pretty 
-mbean "MedRec:Name=MyServer,Type=Server" -property ListenPort

---------------------------
MBeanName: "MedRec:Name=MyServer,Type=Server"
        ListenPort: 7010

D:\>echo %ERRORLEVEL%
0

weblogic.Admin calls System.exit(1) if an exception is raised while processing a command, causing Ant and other Java client JVMs to exit. You can override this default behavior by specifying -noExit for Ant tasks (wlconfig) and -continueOnError for weblogic.Admin batch operations (BATCHUPDATE).

Command for Storing User Credentials

For any weblogic.Admin command that connects to a WebLogic Server instance, you must provide user credentials. You can use the STOREUSERCONFIG command to encrypt the user credentials instead of passing credentials directly on the command line or storing unencrypted credentials in scripts. See Specifying User Credentials.