Starting and Stopping WebLogic Servers

The following sections describe procedures for starting and stopping Administration Servers and Managed Servers:

• The Server Lifecycle

• Providing Usernames and Passwords to Start a Server

• Starting an Administration Server

• Starting a Managed Server

• Shutting Down WebLogic Servers

• Configuring Startup and Shutdown Classes

• Setting Up a WebLogic Server Instance as a Windows Service

 

---

The Server Lifecycle

A WebLogic Server can be in one of several states at any given time, and it follows a set of rules that determine how and when it can transition between those states. The series of states through which a server transitions is called the server lifecycle. (See Figure 2-1.)

Figure 2-1 The Server Lifecycle

 

The most common pattern of transitions is as follows:

1. SHUTDOWN. In this state, the server is configured but inactive.

2. STARTING. When you start a server, it takes the following actions:

   1. Retrieves its configuration data.

      An Administration Server retrieves the configuration data (including security configuration data) from the domain's configuration files. A Managed Server contacts the Administration Server for its configuration and security data. If you set up SSL, a Managed Server uses its own set of certificate files, key files, and other SSL-related files and contacts the Administration Server for the remaining configuration and security data.

   2. Starts its kernel-level services, which include logging and timer services.

   3. Initializes subsystem-level services with the configuration data that it retrieved in step 2a. These services include the following:

      Security Service RMI Service Cluster Service IIOP Service Naming Service RMI Naming Service File Service

      JCA Container JDBC Container EJB Container Web Container Deployment Manager JMS Provider Remote Management Transaction Service

   4. If you have configured a server to use a separate administration port, the server enables remote configuration and monitoring. For information about administration ports, refer to Configuring a Domain-Wide Administration Port in the Creating and Configuring WebLogic Server Domains Guide.

   5. Deploys modules in the appropriate container and in the order that you specify in the WebLogic Server Administration Console.

      For any startup classes that are configured to load before application deployments, the classes are loaded and run before the server deploys JDBC connection pools, Web applications, and EJBs.

   6. For any startup classes that are configured to load after application deployments, the classes are loaded and run after the server deploys JDBC connection pools, Web applications, and EJBs.

3. STANDBY. (Available only if you have configured an administration port.) You can issue a command that starts a server and places it in this state. In this state, a server has initialized all of its services and applications and can accept administration commands and participate in cluster communication. It is not accessible for requests that come from external clients.

   A typical use of the STANDBY state is to keep a server available as a "hot" backup, especially in a high-availability or mission-critical environment. When you need to use the backup server, you can quickly resume its ability to process client requests.

4. RUNNING. In this state, a server offers its services to clients and can operate as a full member of a cluster.

5. SHUTDOWN. You can move a server into this state either from the RUNNING state or the STANDBY state. As it transitions to SHUTDOWN, a server goes through the SHUTTING_DOWN state.

   When you issue a graceful shutdown, the server invokes any shutdown classes that you have configured. You can shut down a server gracefully only from the RUNNING or STANDBY states.

   When you issue a forceful shutdown, the server notifies all applications and subsystems to drop all current work and release all resources. A forceful shutdown could result in rolled back transactions and session loss for some clients. You can shut down a server forcefully from any state.

A server can be in two additional states:

• FAILED. If one or more critical services become dysfunctional during the lifetime of server, the server transitions to the FAILED state. Your only option to recover from the FAILED state is to shut down the server. You can set up a server to restart itself if critical services become dysfunctional. For information about automatic restarts, refer to Server Self-Health Monitoring in the Configuring and Managing Domains Guide.

• UNKNOWN. If a server cannot be contacted, it is considered to be in the UNKNOWN state.

Controlling the Server Lifecycle

You can use any of the following interfaces to control a server's lifecycle:

• The Administration Console provides the following ways to control a server's lifecycle:

  • On the Server—>Configuration—>General tab, the Startup Mode field determines whether a server starts in STANDBY or RUNNING by default.

  • On the Server—>Tuning tab, the Timeout for Server Lifecycle Operations field determines the number of seconds a lifecycle operation waits before timing out. For more information, refer to Timeout Period for LifeCycle Operations.

  • On the Server—>Control—>Start/Stop tab, a list of commands start, stop, and resume servers. For more information, refer to server tasks in the Administration Console Online Help.

• The weblogic.Server startup command includes an argument that overrides the default startup state. For information about the -Dweblogic.management.startupMode=STANDBY argument, refer to Frequently Used Optional Arguments.

• The weblogic.Admin utility provides the following commands:

  • START (requires the Node Manager)

  • STARTINSTANDBY (requires the Node Manager)

  • RESUME

  • SHUTDOWN

  • FORCESHUTDOWN

  An additional command, GETSTATE, returns the current state of a server.

  For information about using the weblogic.Admin utility, refer to WebLogic Server Command-Line Interface Reference, or enter the following command at a command line:

  java weblogic.Admin HELP

  For information about the Node Manager, refer to Managing Server Availability with Node Manager in the Creating and Configuring WebLogic Server Domains Guide.

Timeout Period for LifeCycle Operations

When you issue a lifecycle command, the server notifies subsystems and applications of the requests and waits a number of seconds for the subsystems and application to respond. If they do not respond in the specified number of seconds, the server times out the lifecycle operation. The actions that it takes after the timeout depend on the operation.

This timeout period applies only to the SHUTDOWN and FORCESHUTDOWN operations. If the operation does not complete within the configured period, one of the following occurs:

• If the state of the server at that time was SHUTTING_DOWN or if the operation was FORCESHUTDOWN, then the server shuts down automatically.

• Otherwise, a ServerLifecycleException will be thrown with a message describing the timeout condition.

You can change the default timeout period on the Server—>Tuning tab. For more information, refer to Setting the Timeout Period for LifeCycle Operations in the Administration Console Online Help.

 

---

Providing Usernames and Passwords to Start a Server

By default, a WebLogic Server prompts you to enter a username and password in the command shell that runs the server process. The username must belong to a role that is permitted to start servers. For information on roles and permissions, refer to Protecting System Administration Operations.

This section describes the following tasks:

• Specifying an Initial Administrative Username

• Bypassing the Prompt for Username and Password

Specifying an Initial Administrative Username

The Configuration Wizard prompts you to provide a username and password, which becomes the initial administrative username for the myrealm security realm. A security realm is a collection of components (providers) that authenticate usernames, determine the type of resources that the user can access, and provide other security-related services for WebLogic resources. WebLogic Server installs the myrealm security realm and uses it by default.

The first time you start a WebLogic Server, enter this initial administrative username and password. If you did not use the Configuration Wizard, the WebLogic Server prompts you to enter a initial username and password.

You can use the Administration Console to add users to myrealm. If you use an Authentication provider other than the one that WebLogic Server installs, you must use the provider's administration tools to create at least one user with administrative privileges. For information on granting administrative privileges, refer to Protecting System Administration Operations.

Note: The guest user is no longer supplied by default in WebLogic Server version 7.0. To use the guest user, you must run in Compatibility mode or define the guest user as a user in the Authentication provider for your security realm. For information about Compatibility mode, refer to Using Compatibility Security in the Managing WebLogic Security guide.

You can configure a WebLogic Server to use a different security realm. If you set up different security realms, you must designate one of those realms as the default. During its startup cycle, a WebLogic Server uses the default realm to authenticate the username that you supply.

Bypassing the Prompt for Username and Password

If you want to bypass the prompt for username and password, we recommend that you create and use a boot identify file, which contains your username and password in an encrypted format.

This section contains the following subsections:

• Creating a Boot Identity File for an Administration Server

• Creating a Boot Identity File for a Managed Server

• Using a Boot Identity File

• Removing a Boot Identity File After Startup

• Alternate Method: Passing Identity Information on the Command Line

Creating a Boot Identity File for an Administration Server

To create a boot identity file for an Administration Server:

1. Start the Administration Server at least once and provide the user credentials on the command line.

   During the Administration Server's initial startup process, it generates security files that must be in place before a server can use a boot identity file.

2. Place the following two lines in a text file:

   username=username
   password=password

   The username and password values must match an existing user account in the Authentication provider for the default security realm and must belong to a role that has permission to start a server. For information on roles and permissions, refer to Protecting System Administration Operations.

3. Save the file.

   If you save the file as boot.properties and locate it in the server's root directory, the server will automatically use this file during startup. For more information, refer to Using a Boot Identity File.

The first time you use this file to start a sever, the server reads the file and then overwrites it with an encrypted version of the username and password.

Alternative Technique for Creating a Boot Identity File for an Administration Server

If you invoke the weblogic.Server class directly on the command line, instead of following the steps in the previous section, you can create a boot identity file by including the following options in the Java command:

-Dweblogic.management.username=username
-Dweblogic.management.password=password
-Dweblogic.system.StoreBootIdentity=true

These options cause the server instance to boot with the supplied user credentials and then store them in a file named boot.properties.

For example, the following command starts an Administration Server named myAdminServer and creates a boot identity file:

java -Dweblogic.management.username=username
-Dweblogic.management.password=password
-Dweblogic.system.StoreBootIdentity=true
-Dweblogic.Name=myAdminServer weblogic.Server

For more information about invoking the weblogic.Server class directly from a command line, refer to Using the weblogic.Server Command.

Note: If you use a script to start an Administration Server, BEA recommends that you do not use the technique described in this section for the following reasons:

• It requires you to store an unencrypted password in the startup script.

• Each time you run the script, the server boots with the supplied user credentials and then creates a new boot identity file.

Creating a Boot Identity File for a Managed Server

If a Managed Server uses the same root directory as the Administration Server, you do not need to create an additional boot identity file for the Managed Server, unless you want the Managed Server to run under different user credentials. For information about a server's root directory, refer to A Server's Root Directory.

In addition, if you use a Node Manager to start a Managed Server, you do not need to create a boot identity file. Instead, you must specify user credentials on the Managed Server's Remote Start tab in the Administration Console. For more information, refer to "Configure Startup Arguments for Managed Servers."

To create a boot identity file for a Managed Server:

1. Start the domain's Administration Server.

2. Copy the SerializedSystemIni.dat file from the Administration Server's root directory to the Managed Server's root directory.

3. Place the following two lines in a text file:

   username=username
   password=password

   The username and password values must match an existing user account in the Authentication provider for the default security realm and must belong to a role that has permission to start a server. For information on roles and permissions, refer to Protecting System Administration Operations.

4. Save the file.

   If you save the file as boot.properties and locate it in the server's root directory, the server will automatically use this file during startup. For more information, refer to Using a Boot Identity File.

Using a Boot Identity File

A server instance uses a boot identity file as follows:

• If a server's root directory contains a valid boot.properties, it uses this file by default. For information about a server's root directory, refer to A Server's Root Directory.

• If you want to specify a different file (or if you do not want to store boot identity files in a server's root directory), you can include the following argument in the server's weblogic.Server startup command:

  -Dweblogic.system.BootIdentityFile=filename

  where filename is the fully qualified pathname of a valid boot identity file.

  If you use the startWebLogic script, add -Dweblogic.system.BootIdentityFile as a value of the JAVA_OPTIONS variable. For example:
  JAVA_OPTIONS=-Dweblogic.system.BootIdentityFile=C:\BEA\user_domains\mydomain\myidentity.prop

• If you do not want a server instance to use a boot identity file, include the following options in the server's weblogic.Server startup command:

  -Dweblogic.management.username=username
  -Dweblogic.management.password=password

  These options prevent a server instance from using any boot identity file and override other startup options that cause a server to use boot identity files.

  Note: If you use a script to start a server instance, BEA recommends that you do not use this technique because it requires you to store an unencrypted password in the startup script. Use this technique only if you invoke the weblogic.Server class directly from the command line. For more information, see Using the weblogic.Server Command.

• If a server is unable to access its boot identity file, it displays the username and password prompt in its command shell and writes a message to the log file.

For a given server instance, use only the boot identity file that the instance has created. WebLogic Server does not support copying a boot identity file from one server root directory to another.

For example, if you use ServerA to generate a boot identity file, use only that boot identity file with ServerA. Do not copy ServerA's boot identity file into the root directory of ServerB. Instead, create a boot identity file for ServerB as described in the previous sections.

Removing a Boot Identity File After Startup

If you want to remove the boot identity file after a server starts, you can include the following argument in the server's weblogic.Server startup command:

-Dweblogic.system.RemoveBootIdentity=true

This argument removes only the file that the server used to start. For example, if you specify -Dweblogic.system.BootIdentityFile=c:\secure\boot.MyServer, only boot.MyServer is removed, even if the server's root directory contains a file named boot.properties.

Alternate Method: Passing Identity Information on the Command Line

Using a boot identity file is the most secure and convenient way to bypass the interactive prompt. However, instead of using a boot identify file, you can add the following arguments to the weblogic.Server startup command:

-Dweblogic.management.username=username
-Dweblogic.management.password=password

If you supply both of these arguments, you can bypass the interactive prompt.

These options prevent a server instance from using any boot identity file and override other startup options that cause a server to use boot identity files.

Because the command to start a server can be long, typically you place most of the startup command in a script. Unless you are in an environment in which security is not a concern, we recommend that you do not save the -Dweblogic.management.password=password argument in a startup script.

For more information about these arguments, refer to Using the weblogic.Server Command.

 

---

Starting an Administration Server

A WebLogic Server runs as a process within a Java Virtual Machine (JVM). Each JVM can host only one server process. To start a server, you initiate a JVM with a set of arguments.

If a domain consists of only one WebLogic Server, that server is the Administration Server. If a domain consists of multiple WebLogic Servers, you must start the Administration Server before you start the Managed Servers.

The Administration Server and all Managed Servers in a domain must be the same WebLogic Server version. The Administration Server must be either at the same service-pack level or at a later service-pack level than the Managed Servers. For example, if the Managed Servers are at release 7.0, then the Administration Server can be either release 7.0 or 7.0 SP1. However, if the Managed Servers are at SP1, then the Administration Server must be at SP1. Each server within a domain must have a unique name.

This section describes starting an Administration Server by completing any of the following tasks from the local host:

• Starting an Administration Server from the Windows Start Menu

• Starting an Administration Server Using a Script

• Using the weblogic.Server Command

• Using the Default Configuration to Start a Server

For information, see:

• Setting Up a WebLogic Server Instance as a Windows Service

• "Binding to Protected Ports on UNIX" in the Administration Console Online Help

Note: When starting WebLogic Server, JDK 1.3 may throw an OutOfMemory error if you are trying to load a large number of classes. This error occurs even though there appears to be plenty of memory available. If you encounter a java.lang.OutOfMemory error exception when you start WebLogic Server, increase the value of the following JVM option:

java -XX:MaxPermSize=<value>

where <value> is some number in kilobytes.

For JDK1.3.1, the default value for MaxPermSize is 64m, where m stands for megabytes.

Starting an Administration Server from the Windows Start Menu

If you use the Configuration Wizard to create Single Server, an Administration Server with Managed Servers, or an Administration Server with Clustered Managed Servers on a Windows computer, the wizard prompts you to install the domain in the Windows Start Menu. If you choose yes, then you can do the following to start the Single Server or Administration Server:

From the Windows desktop, click Start—>Programs—>BEA WebLogic Platform 7.0—>User Projects—>domain_name—>Start Server.

The Start Server command opens a command window and calls the domain_name\startWebLogic.cmd script, which is described in Starting an Administration Server Using a Script. When the server has successfully completed its startup process, it writes the following message to the command window:

<Notice> <WebLogicServer> <000360> <Server started in RUNNING mode>

Starting an Administration Server Using a Script

Because the arguments needed to start a WebLogic Server from the command line can be lengthy and prone to error, we recommend that you incorporate the command into a script.

This section describes the following tasks:

• Using the Configuration Wizard Scripts to Start an Administration Server

• Creating Your Own Script to Start an Administration Server

• Using a Non-Default JVM with WebLogic Server

Using the Configuration Wizard Scripts to Start an Administration Server

When you use the Configuration Wizard to create a domain, the wizard also creates a script that you can use to start an Administration Server for the domain. To use the script, enter one of the following commands at a command prompt:

• domain_name\startWebLogic.cmd (Windows)

• domain_name\startWebLogic.sh (UNIX and Windows. On Windows, this script supports the MKS and Cygnus BASH UNIX shell emulators.)

  where domain_name is the directory in which you located your domain.

The script sets values for some domain-specific variables and then calls the master startup script, WL_HOME\server\bin\startWLS.cmd (startWLS.sh on UNIX), where WL_HOME is the location in which you installed WebLogic Server. The master startup script sets environment variables, such as the location of the JVM, and then starts the JVM with WebLogic Server arguments.

Creating Your Own Script to Start an Administration Server

If you use some other means to create a domain (such as the Administration Console), you can create your own startup script that does the following:

1. Sets the value of a variable named SERVER_NAME. All servers in a domain must be named. For example,

   set SERVER_NAME=myserver

   In the domain's config.xml file, the name of a server is specified as <Server Name=serverName>. Make sure that the value for set SERVER_NAME refers to the server name as specified in config.xml.

2. Sets values for any of the following optional variables:

   Table 2-1 Optional variables

   Variable	Description
   WLS_USER	Variable for setting a cleartext user for server startup. Instead of using this variable, we recommend that you use a boot identity file. For more information, refer to Bypassing the Prompt for Username and Password.
   WLS_PW	Variable for setting a cleartext password for server startup. Instead of using this variable, we recommend that you use a boot identity file. For more information, refer to Bypassing the Prompt for Username and Password.
   ADMIN_URL	If you specify a URL for this variable, the server will start as a Managed Server and will use the specified URL to contact its Administration Server. For more information, refer to The Administration Server and Managed Servers.
   STARTMODE	Determines whether the server runs in production mode or development mode. Specify true for production mode servers or false for development mode. For more information on using production and development modes refer to Development Mode vs. Production Mode.
   JAVA_OPTIONS	Java command-line options for running the server. The Java command-line options will be passed to the JVM after JAVA_VM and MEM_ARGS are passed. -Dweblogic.ListenAddress is an example of a Java option that you can call from the domain start script. For more information about command-line options, refer to Using the weblogic.Server Command. If you are listing multiple options in a UNIX shell, put quotes around the entire set of options and include spaces between each option. For example: JAVA_OPTIONS="-Dweblogic.attribute=value -Djava.attribute=value"
   JAVA_VM	Java argument that specifies the mode in which the virtual machine runs. Use one of the following options: -server -client -hotspot (Windows only) If you are using a JVM that does not support any of these operational modes, you must edit the master script to prevent these arguments from being passed to the JVM. For more information, refer to Using a Non-Default JVM with WebLogic Server.
   MEM_ARGS	Variable to override the default memory arguments passed to Java. In the master start scripts, the options are set by default to -Xms200m and -Xmx200m.

   
    

3. Calls the master startup script, WL_HOME\server\bin\startWLS.cmd (startWLS.sh on UNIX).

   The master startup script sets environment variables, such as the location of the JVM, and then starts the JVM with WebLogic Server arguments. If you are not using the JVM installed with WebLogic Server, you must edit the master start script. For more information, refer to Using a Non-Default JVM with WebLogic Server.

4. If you plan to locate your startup script outside of the domain's root directory, your script must include the following value for the JAVA_OPTIONS variable:

   -Dweblogic.RootDirectory=path

   where path specifies the location of the domain's root directory.

   For example,

   JAVA_OPTIONS=-Dweblogic.RootDirectory=c:\serverRoot

Using a Non-Default JVM with WebLogic Server

If you are not using the JVM installed with WebLogic Server, you must edit the master start script so that the JAVA_HOME variable specifies the correct location of the JVM on your system.

For detailed information, see "Using a Non-Bundled JVM With WebLogic Platform" at the following URL: http://download.oracle.com/docs/cd/E13196_01/platform/docs70/relnotes/relnotes.html.

Using the weblogic.Server Command

weblogic.Server is the command that starts a WebLogic Server on a local host. The startup scripts described in previous sections are wrappers that send a consistent set of options to this command. While we recommend that you incorporate this command and its options into a startup script, for simple invocations you can enter the weblogic.Server command directly on the command line.

For example, a simple invocation for starting the examples server on Windows is as follows (you must enter this command from the WL_HOME\samples\server\config\examples directory):

c:\bea\jdk131\bin\java 
-hotspot -Xms200m -Xmx200m 
-classpath "c:\bea\jdk131\lib\tools.jar;
   c:\bea\weblogic700\server\lib\weblogic_sp.jar;
   c:\bea\weblogic700\server\lib\weblogic.jar;" 
-Dweblogic.Name=examplesServer 
-Dbea.home="C:\bea" -Djava.security.policy="c:\bea\weblogic700\server\lib\weblogic.policy" 
weblogic.Server

This section describes the following:

• Setting the Classpath

• Command Syntax for weblogic.Server

• Required Arguments

• Frequently Used Optional Arguments

• Other Optional Arguments

• Development Mode vs. Production Mode

• Startup Arguments for the Administration Port and the weblogic.Admin Utility

• A Server's Root Directory

For information about starting a Managed Server on a remote host, refer to Managing Server Availability with Node Manager in the Creating and Configuring WebLogic Server Domains Guide.

Setting the Classpath

The Java Virtual Machine (JVM) uses a setting called classpath to locate essential files and directories.

You can use the following command to set the classpath for a WebLogic Server:

WL_HOME\server\bin\setWLSEnv.cmd (on Windows)
WL_HOME/server/bin/setWLSEnv.sh (on UNIX)

Instead of using setWLSEnv, you can use an environment variable or a -classpath argument in the startup command. Regardless of the method you choose, include the following in the classpath for the JVM that runs your instances of WebLogic Server:

• WL_HOME/server/lib/weblogic_sp.jar

  Depending on which WebLogic Server release, service pack, or patch that you have installed, this file might not exist on your system. Regardless of whether the file currently exists on your system, we recommend that you include WL_HOME/server/lib/weblogic_sp.jar on your classpath to ensure compatibility with any updates. You must add this file to the classpath before you add weblogic.jar.

• WL_HOME/server/lib/weblogic.jar

• If you use the trial version of PointBase, an all-Java database management system, then include the following files:

  SAMPLES_HOME/server/eval/pointbase/server/lib/
  pbserver41ev.jar and pbclient41ev.jar

  where SAMPLES_HOME is WL_HOME/samples.

• If you use WebLogic Enterprise Connectivity, include the following files:

  WL_HOME/server/lib/wlepool.jar
  WL_HOME/server/lib/wleorb.jar

  where WL_HOME is the directory where you installed WebLogic Server.

Command Syntax for weblogic.Server

The syntax for the weblogic.Server command is as follows:

java RequiredArguments [OptionalArguments] weblogic.Server 

Required Arguments

The following table describes the required arguments for starting a WebLogic Server from the java command line.

Table 2-2 Required Arguments for Starting a Server

Argument	Description
-Xms and -Xmx	Specify the minimum and maximum values (in megabytes) for Java heap memory. For example, you may want to start the server with a default allocation of 200 megabytes of Java heap memory to the WebLogic Server. To do so, you can start the server with the java -Xms200m and -Xmx200m options. For best performance it is recommended that the minimum and maximum values be the same so that the JVM does not resize the heap. The values assigned to these parameters can dramatically affect the performance of your WebLogic Server and are provided here only as general defaults. In a production environment you should carefully consider the correct memory heap size to use for your applications and environment.
-classpath	The minimum content for this option is described under Setting the Classpath. Note: This is optional if the classpath is set in the user environment.
-Dweblogic.Name= servername	Assigns a name to the server. Server names must be unique within a domain. For example, if you name a server instance ManagedServer1 in a domain named DomainA, you cannot name another server instance ManagedServer1 in DomainA.
-Dbea.home=bea_home	Specifies the location of the BEA home directory, which contains licensing and other essential information.

 

Frequently Used Optional Arguments

The following table describes optional arguments that are frequently used. The description of each argument indicates whether it can also be set through the Administration Console or some other WebLogic Server command. Any argument that sets an attribute for a Managed Bean (MBean) can also be set through the MBean's API. Other Optional Arguments, describes setting MBean attributes.

Table 2-3 Frequently Used Optional Arguments

Argument	Description
-Dweblogic.RootDirectory=path	Specifies the server's root directory. For more information, refer to A Server's Root Directory.
-Dweblogic.ConfigFile= file_name	Specifies a configuration file for your domain. The file_name value must refer to a valid XML file that conforms to the config.dtd. The XML file must exist in the Administration Server's root directory, which is either the current directory or the directory that you specify with -Dweblogic.RootDirectory. The file_name value cannot contain a pathname component. For example, the following value is invalid: -Dweblogic.ConfigFile=c:\mydir\myfile.xml Instead, use the following arguments: -Dweblogic.RootDirectory=c:\mydir -Dweblogic.ConfigFile=myfile.xml For information about config.dtd, refer to BEA WebLogic Server Configuration Reference. If you do not specify this value, the default is config.xml.
-Dweblogic.management. username=username	Specifies the username. The username must belong to a role that has permission to start a server. For information on roles and permissions, refer to Protecting System Administration Operations. This option prevents a server instance from using any boot identity file and overrides other startup options that cause a server to use boot identity files. For more information, refer to Bypassing the Prompt for Username and Password.
-Dweblogic.management. password=password	Specifies the user password. This option prevents a server instance from using any boot identity file and overrides other startup options that cause a server to use boot identity files. For more information, refer to Bypassing the Prompt for Username and Password.
-Dweblogic.ListenAddress=host	Specifies a listen address for this server. The host value must be either the DNS name or the IP address of the server. This option sets the value of the listenAddress attribute in the ServerMBean, which is also accessible from the Administration Console under Server—>Configuration—>General—>Listen Address. If you do not specify a Listen Address, a server uses either the machine's DNS name or the IP address. We recommend that you specify a known IP address or DNS name and that you use the Administration Console instead of this argument to do so. For more information, refer to Configuring Network Resources.
-Dweblogic.ListenPort= portnumber	Enables and specifies the plain-text (non-SSL) listen port for this server. The argument sets the value of the listenPort attribute in the ServerMBean, which is also accessible from the Administration Console under Server—>Configuration—>General—>Listen Port. If you do not specify a Listen Port, a server uses 7001 as the default. For more information, refer to Configuring Network Resources.
-Dweblogic.ssl.ListenPort= portnumber	Enables and specifies the port at which this WebLogic Server listens for SSL connection requests. The argument sets the value of the listenPort attribute in the SSLMBean, which is also accessible from the Administration Console under Server—>Connections—>SSL Ports—>SSL Listen Port. If you do not specify a Listen Port, a server uses 7002 as the default. For more information, refer to Configuring Network Resources.
-Dweblogic.system. StoreBootIdentity=true	Creates a boot.properties in the server's root directory. The file contains the username and an encrypted version of the password that you used to start the server. For more information, refer to Bypassing the Prompt for Username and Password.
-Dweblogic.system. BootIdentityFile=filename	Specifies a boot identity file that contains a username and password. The filename value must be the fully qualified pathname of a valid boot identity file. For example: -Dweblogic.system.BootIdentityFile=C:\BEA\ wlserver7.0\user_config\mydomain\myidentity.prop If you do not specify a filename, a server uses the boot.properties in the server's root directory. If there is no boot identity file, the server prompts you to enter a username and password.
-Dweblogic.system. RemoveBootIdentity=true	Removes the boot identity file after a server starts.
-Dweblogic.management. pkpassword=pkpassword	Specifies the password for retrieving Secure Socket Layer (SSL) private keys from an encrypted flat file. Use this option if you store private keys in an encrypted flat file.
-Dweblogic.security.SSL. trustedCAKeyStore=path	If you use SSL, you can use this argument to specify the certificate authorities that the server or client trusts. The path value must be a relative or qualified name to the Sun JKS keystore file (contains a repository of keys and certificates). If you do not specify this argument, the WebLogic Server or client trusts all of the certificates that are specified in JAVA_HOME\jre\lib\security\cacerts. We recommend that you do not use the demonstration certificate authorities in any type of production deployment.
-Dweblogic.security.SSL. ignoreHostnameVerification= true	Disables host-name verification. Include this argument if you want to use the demonstration digital certificates that are shipped with WebLogic Server. Note: BEA does not recommend using the demonstration digital certificates or turning off host name verification in a production deployment. If you do not specify this argument, the Host Name Verifier in WebLogic Server compares the SubjectDN of a digital certificate with the host name of the server that initiated the SSL connection. If the SubjectDN and the host name do not match, the SSL connection is dropped.
-Dweblogic.security.SSL. HostnameVerifier= hostnameverifierimplmentation	Specifies the name of a custom Host Name Verifier class. The class must implement the weblogic.security.SSL.HostnameVerifier interface.
-Dweblogic.security.SSL. sessionCache.ttl= sessionCacheTimeToLive	Modify the default server-session time-to-live for SSL session caching. The sessionCacheTimeToLive value specifies (in seconds) the session cache time-to-live. For sessionCache.ttl: The minimum value is 1 The maximum value is Integer.MAX_VALUE The default value is 90
-Djava.security.manager -Djava.security.policy= filename	Enable the Java 2 security manager, which prevents untrusted code from performing actions that are restricted by the policy file. The -Djava.security.policy argument specifies a filename (using a relative or fully-qualified pathname) that contains Java 2 security policies. The WebLogic Server sample policy file, which you can edit and use, is WL_HOME\server\lib\weblogic.policy. For more information, refer to Modifying the weblogic.policy File for General Use in the Managing WebLogic Security guide.
-Dweblogic.security.anonymousUserName=guest	Enables support for the guest user account. If you start a WebLogic Server instance with this argument, you must also add the guest user to the Authentication provider in the default security realm. For more information, refer to Creating Users in the Securing WebLogic Resources guide.
-Dweblogic.management.commo. dumpFormat=<encrypted | cleartext>	As described in Recovering Failed Servers: Backing Up Security Data in the Creating and Configuring WebLogic Server Domains guide, security domain configuration information is stored in the domain_name/userConfig/Security directory. You can back up the data in a security domain or export the data to a new security domain using WebLogicMBeanLoader, which outputs an XML file. By default, the values of password attributes are not printed in clear text in the XML file but instead are masked as "*****". This avoids the security risk of printing passwords in clear text in the file system, but makes these files non-portable to different domains since the ***** mask strings cannot be intrepreted meaningfully. To make the XML file portable, you need to print clear text values to it, or else encrypted values that the new domain can decrypt. The value encrypted prints the attribute values in 3DES encrypted form. This should only be used when using the same Encryption salt in the new domain. The value cleartext prints the attribute values in clear text. Omitting this argument or using any other value obscures the attribute values, printing *****.
-Dweblogic.management. startupMode=STANDBY	Starts a server and places it in the STANDBY state. To use this startup argument, you must configure a server to use a separate administration port. For information about administration ports, refer to Configuring a Domain-Wide Administration Port in the Creating and Configuring WebLogic Server Domains Guide. This value overrides any startupMode value specified in the Administration Console under Server—>Configuration—>General tab for the current session only. If you do not specify this value (either on the command line or in config.xml), the default is to start in the RUNNING state.
-Dweblogic.ProductionModeEnabled= {true | false}	Determines whether all servers in a domain start in production mode. This option is applicable only when starting the Administration Server. All Managed Servers start in the same mode as the Administration Server. A true value prevents a WebLogic Server from automatically deploying and updating applications that are in the domain_name/applications directory. If you do not specify this option, the assumed value is false. For more information, refer to Development Mode vs. Production Mode.
-Dweblogic.management. discover={true | false}	Determines whether an Administration Server recovers control of a domain after the server fails and is restarted. A true value causes an Administration Server to refer to its running-managed-servers.xml file, which contains information about the deployment state of deployable modules and a list of all Managed Servers that are currently running. When the Administration Server starts with this specified as true, it communicates with the Managed Servers and informs them that it is running. A false value prevents an Administration Server from referring to this file and thus prevents it from communicating with any Managed Servers that are currently active in the domain. Caution: Specify false for this option only in the development environment of a single server. Specifying false can cause server instances in the domain to have an inconsistent set of deployed modules. If you do not specify this option, the assumed value is true.
-Dweblogic.Stdout="filename"	Redirects the server and JVM's standard output stream to a file. You can specify a pathname that is fully qualified or relative to the WebLogic Server root directory. For more information, refer to Redirecting System.out and System.err to a File.
-Dweblogic.Stderr="filename"	Redirects the server and JVM's standard error stream to a file. You can specify a pathname that is fully qualified or relative to the WebLogic Server root directory. For more information, refer to Redirecting System.out and System.err to a File.
-Dweblogic. AdministrationMBeanAuditingEnabled= {true | false}	Determines whether the Administration Server emits configuration auditing log messages when a user changes the configuration or invokes management operations on any resource within a domain. By default, the Administration Server does not emit configuration auditing messages. See Configuration Auditing.
-Dweblogic.net.http. URLStreamHandlerFactory= classname	Used to override the default WebLogic Server HTTP stream handler. To use this option, write a class that implements the java.net.URLStreamHandlerFactory interface. In addition to implementing the createURLStreamHandler("http") method specified by the interface, the class must include a main() method that calls java.net.URL.setURLStreamHandlerFactory() with an instance of the class as its argument. Set this system property to the name of this class. For more information, see the javadocs for the java.net.URL.URLStreamHandlerFactory interface.

 

Other Optional Arguments

You can use arguments of the weblogic.Server startup command to set attributes of the following MBeans:

• ServerMBean. Use the following syntax:
  -Dweblogic.attribute-name=value

  For example, to set the value of the listenPort attribute, -Dweblogic.ListenPort=7010

• LogMBean. Use the following syntax:
  -Dweblogic.log.attribute-name=value

  For example, to set the value of the FileName attribute, -Dweblogic.log.FileName="C:\logfiles\myServer.log"

• SSLMBean. Use the following syntax:
  -Dweblogic.ssl.attribute-name=value

  For example, to set the value of the Enable attribute to true, -Dweblogic.ssl.Enable="true"

You can set any attribute that the MBean exposes as a setter method. In the above syntax statements, attribute-name is the name of an MBean's setter method without the set prefix.

For example, the ServerMBean exposes its listen port attribute with the following setter method:

• setListenPort()

To set the listen port value from the weblogic.Server command, use the following syntax: -Dweblogic.ListenPort=portnumber

The command-line arguments override any settings currently in the MBean and they are not persisted to the domain's config.xml file.

Development Mode vs. Production Mode

You can run WebLogic Server in two different modes: development and production. You use development mode to test your applications. Once they are ready for a production environment, you deploy your applications on a server that is started in production mode.

Development mode enables a WebLogic Server to automatically deploy and update applications that are in the domain_name/applications directory (where domain_name is the name of a WebLogic Server domain).

Production mode disables the auto-deployment feature. Instead, you must use the WebLogic Server Administration Console or the weblogic.Deployer tool. For more information on deployment, refer to WebLogic Server Deployment in the Developing WebLogic Server Applications Guide.

By default, a WebLogic Server runs in development mode. To specify the mode for a server, do one of the following:

• If you use the startWebLogic startup script, edit the script and set the STARTMODE variable as follows:

  • STARTMODE = false enables deployment mode

  • STARTMODE = true enables production mode

  For more information about startWebLogic, refer to Starting an Administration Server Using a Script.

• If you start a server entering the weblogic.Server command directly on the command line, use the -Dweblogic.ProductionModeEnabled option as follows:

  • -Dweblogic.ProductionModeEnabled=false enables deployment mode

  • -Dweblogic.ProductionModeEnabled=true enables production mode

Note: Production or development mode is a domain-wide setting, which you specify when starting the Administration Server. All Managed Servers run in the same mode as the Administration Server.

Startup Arguments for the Administration Port and the weblogic.Admin Utility

An administration port is a separate port that you must set up if you want to start server instances in the STANDBY state or if you want to separate administration traffic from application traffic in your domain.

If you want to use an administration port to carry requests from the weblogic.Admin utility, you must do the following:

1. Set up SSL and an administration port for all server instances in the domain as described in "Configuring a Domain-Wide Administration Port" in the Creating and Configuring WebLogic Server Domains guide.

2. Include the following startup arguments in the weblogic.Server command for all server instances:
   -Dweblogic.security.SSL.trustedCAKeystore=path
   -Dweblogic.security.SSL.ignoreHostnameVerification=true

A Server's Root Directory

All instances of WebLogic Server use a root directory to store runtime data and to provide the context for any relative pathnames in the server's configuration.

In addition, an Administration Server uses its root directory as a repository for the domain's configuration data (such as config.xml) and security resources (such as the default, embedded LDAP server), while a Managed Server stores replicated administrative data in is root directory. (See Figure 2-2.)

Figure 2-2 Root Directory for WebLogic Server Instances

 

Multiple instances of WebLogic Server can use the same root directory. However, if your server instances share a root directory, make sure that all relative filenames are unique. For example, if two servers share a directory and they both specify .\MyLogFile, then each server instance will overwrite the other's .\MyLogFile.

To determine the root directory for an Administration Server, WebLogic Server does the following:

• If the server's startup command includes the -Dweblogic.RootDirectory=path option, then the value of path is the root directory.

• If -Dweblogic.RootDirectory=path is not specified, and if the working directory (that is, the directory from which you issue the startup command) contains a config.xml file, then the working directory is the root directory.

• If neither of the previous statements is true, then the server looks for a config.xml file in working-directory/config/domain-name. If it finds config.xml in this directory, then working-directory/config/domain-name is the root directory.

• If WebLogic Server cannot find a config.xml file, then it offers to create one, as described in Using the Default Configuration to Start a Server" on page 31.

To determine the root directory for a Managed Server, WebLogic Server does the following:

• If the server's startup command includes the -Dweblogic.RootDirectory=path option, then the value of path is the root directory.

• If -Dweblogic.RootDirectory=path is not specified, then the working directory is the root directory. For example, if you run the weblogic.Server command from c:\config\MyManagedServer, then c:\config\MyManagedServer is the root directory.

To make it easier to maintain your domain configurations and applications across upgrades of WebLogic Server software, it is recommended that the root directory not be the same as the installation directory for the WebLogic Server software.

Using the Default Configuration to Start a Server

If you run into problems in your environments and want to boot a server with a clean (default) configuration, you can start WebLogic Server in such a way that it generates a new config.xml file.

This new config.xml file contains only the default settings, unless you use command-line arguments to override the defaults. The username and password that you supply when you start the server becomes the default administrative user.

Note that the server starts as an Administration Server in a new domain. There are no other servers in this domain, nor are any of your deployments or third-party solutions included. You can add them as you would add them to any WebLogic domain.

To cause WebLogic Server to generate a new config.xml file, start an Administration Server using a server root directory that does not already contain a config.xml file. For example, you can do the following:

1. Make a new directory for your default configuration.

2. Navigate to that directory, and in a command shell, enter the following command:
   WL_HOME\server\bin\setWLSEnv.cmd (Windows)
   WL_HOME/server/bin/setWLSEnv.sh (UNIX)

3. Enter the following command:

   java weblogic.Server

4. When the server prompts you, enter a username and password. This will become the default administrative user for the domain.

5. When the server prompts you to create a new default configuration, enter y.

The server prompts you to reenter your password. Then it starts a server with the new configuration.

 

---

Starting a Managed Server

Before you can run a WebLogic Server as a Managed Server, you must do the following:

• Start the domain's Administration Server.

• Create an entry for that server in the configuration for the domain as described in Adding a Managed Server to a Domain.

After describing how to add a Managed Server to a domain, this section describes starting a Managed Sever by completing any of the following tasks:

• Starting a Managed Server from the Windows Start Menu

• Starting a Managed Server Using a Script

• Starting a Managed Server from the Command Line

• Configuring a Connection to the Administration Server

• Specifying the Default Startup State

• Starting a Remote Managed Server

• Starting and Killing All WebLogic Servers in a Domain or Cluster

For information on starting Managed Servers when the Administration Server is unavailable, refer to Starting a Managed Server When the Administration Server Is Not Available in the Creating and Configuring WebLogic Server Domains Guide.

Adding a Managed Server to a Domain

To add a Managed Server to a domain, do the following:

1. Start the Administration Server for the domain.

2. Invoke the Administration Console by pointing your browser at http://hostname:port/console, where hostname is the name of the machine where the Administration Server is running and port is the listen port number that you have configured for the Administration Server (default is 7001).

3. If the server runs on a machine that is different from the Administration Server's machine, do the following:

   1. In the left pane of the Administration Console, click the Machines node.

   2. In the right pane, click Configure a new Machine.

   3. Enter a name and click Create.

4. In the left pane, click the Servers node.

5. On the right pane, click Configure a new Server and do the following:

   1. Enter a name for the server.

      Within a given domain, each server name must be unique.

   2. If you created a machine, select it for this Managed Server.

   3. Click Create.

6. If you want to set up an administration channel for this server, refer to Configuring a Domain-Wide Administration Port in the Creating and Configuring WebLogic Server Domains Guide.

Starting a Managed Server from the Windows Start Menu

If you use the Configuration Wizard to create a Managed Server (with owning Administration Server configuration) on a Windows computer, the wizard prompts you to install the domain in the Windows Start Menu. If you choose yes, then you can do the following to start the Managed Server:

From the Windows desktop, click Start—>Programs—>BEA WebLogic Platform 7.0—>User Projects—>domain_name—>Start Server.

The Start Server command opens a command window and calls the domain_name\startManagedWebLogic.cmd script, which is described in Starting a Managed Server Using a Script. When the server has successfully completed its startup process, it writes the following message to the command window:

<Notice> <WebLogicServer> <000360> <Server started in RUNNING mode>

Starting a Managed Server Using a Script

Because the arguments needed to start a WebLogic Server from the command line can be lengthy and prone to error, we recommend that you incorporate the command into a script.

This section describes the following tasks:

• Using the Configuration Wizard Scripts to Start a Managed Server

• Creating Your Own Script to Start a Managed Server

If you are not using the JVM installed with WebLogic Server, refer to Using a Non-Default JVM with WebLogic Server.

Using the Configuration Wizard Scripts to Start a Managed Server

When you use the Configuration Wizard to create a domain, the wizard creates a script that you can use to start a Managed Server:

• domain_name\startManagedWebLogic.cmd (Windows)

• domain_name/startManagedWebLogic.sh (UNIX and Windows. On Windows, this script supports the MKS and Cygnus BASH UNIX shell emulators.)

  where domain_name is the directory in which you located your domain.

Similar to the script for starting an Administration Server, startManagedWebLogic script sets values for some domain-specific variables. However, startManagedWebLogic also specifies the listen address of the domain's Administration Server, which causes the server to run as a Managed Server and retrieve its configuration from the Administration Server.

Before you use startManagedWebLogic, open the script in a text editor and make sure that the SERVER_NAME variable is set to the name of the WebLogic Managed Server that you wish to start. Also verify that the ADMIN_URL specifies the host (host name or IP address) and port number where the Administration Server is listening for requests (default is 7001). For example:

set SERVER_NAME=bigguy
set ADMIN_URL=peach:7001

Instead of opening and modifying startManagedWebLogic, you can enter either of the following commands:

• domain_name\startWebLogic managed_server_name admin_url

  By passing two parameters to the script that starts an Administration Server, you can start a Managed Server.

• domain_name\startManagedWebLogic managed_server_name admin_url

  The above syntax overrides the values of the SERVER_NAME and ADMIN_URL in the startManagedWebLogic script.

For example, the following command uses startWebLogic.cmd to start a managed server named myManagedServer using the Administration Server named peach that listens on port 7001:

c:\user_domains\mydomain\startWebLogic.cmd myManagedServer http://peach:7001 

For a complete description of the variables and Java options that can be specified in startManagedWebLogic, see Table 2-1 under Starting an Administration Server Using a Script.

For more information on configuring a connection to the Administration Server, refer to Configuring a Connection to the Administration Server.

When the server has successfully completed its startup process, it writes the following message to the command window:

<Notice> <WebLogicServer> <000360> <Server started in RUNNING mode>

Creating Your Own Script to Start a Managed Server

If you use some other means to create a domain (such as the Administration Console), you can create your own startup script that starts a Managed Server in your domain. The steps for creating such a script are the same as the steps described in Creating Your Own Script to Start an Administration Server with the following addition:

You must set a value for a variable named ADMIN_URL. For information on configuring a connection to the Administration Server, refer to Configuring a Connection to the Administration Server.

When the server has successfully completed its startup process, it writes the following message to the command window:

<Notice> <WebLogicServer> <000360> <Server started in RUNNING mode>

Starting a Managed Server from the Command Line

To start a WebLogic Managed Server from a command line, you use same command and arguments that you use for an Administration Server plus one of the following arguments, which configures a connection to the Administration Server:

• -Dweblogic.management.server=host:port

• -Dweblogic.management.server=http://host:port

• -Dweblogic.management.server=https://host:port

For information on configuring a connection to the Administration Server, refer to Configuring a Connection to the Administration Server.

For information on the command and arguments for starting an Administration Server, refer to Using the weblogic.Server Command.

When the server has successfully completed its startup process, it writes the following message to the command window:

<Notice> <WebLogicServer> <000360> <Server started in RUNNING mode>

Configuring a Connection to the Administration Server

Regardless of whether you start a Managed Server from the Windows Start menu, a script, or the weblogic.Server command, you must make sure that the Managed Server specifies the correct listen address of the Administration Server. A Managed Server uses this address to retrieve its configuration from the Administration Server.

Note: The first time you start a Managed Server, it must be able to contact the Administration Server. Thereafter you can configure Managed Servers to start even if the Administration Server is unavailable. For more information, refer to Starting a Managed Server When the Administration Server Is Not Available in the Creating and Configuring WebLogic Server Domains Guide.

You can express the listen address in one of the following formats:

• host:port

  where host is the name or IP address of the machine where the Administration Server is running and port is the Administration Server's default, non-SSL listen port. (By default the Administration Server's listen port is 7001.)

  With this format, the Managed Server uses its default protocol (t3) to access the Administration Server. To modify the default protocol, do the following:

  1. Start the Administration Server.

  2. From the Administration Console, in the left pane, expand the Servers node and click the name of the Managed Server.

  3. In the right pane, click Connections—>Protocols.

  4. The Default Protocol field determines the default protocol for a server.

• http://host:port

  where host is the name or IP address of the machine where the Administration Server is running and port is the Administration Server's default, non-SSL listen port. (By default the Administration Server's listen port is 7001.)

  To verify the host IP address, name, and default listen port of the Administration Server, start the Administration Server in a command shell. When the server successfully finishes its startup cycle, it prints to standard out messages that are similar to the following (among other messages):

  <Apr 19, 2002 9:24:19 AM EDT> <Notice> <WebLogicServer> <000355> <Thread "Listen Thread.Default" listening on port 7001, ip address 11.12.13.141>

  ...

  <Apr 19, 2002 9:24:19 AM EDT> <Notice> <WebLogicServer> <000331> <Started WebLogic Admin Server "myserver" for domain "mydomain" running in Development Mode>

  You can change the IP address and listen port values from the Administration Console on a server's Configuration—>General tab.

• https://host:port

  If you have configured Secure Socket Layer (SSL) communication for the Managed Server and Administration Server, you can use this format. In this format, host is the name or IP address of the machine where the Administration Server is running and port is the Administration Server's SSL listen port.

  If you set up the Administration Server to use an Administration Port, port must specify the Administration Port.

  For information on enabling SSL, refer to Configuring the SSL Protocol in the Administration Console Online Help. For more information on Administration Ports, refer to Configuring a Domain-Wide Administration Port in the Creating and Configuring WebLogic Server Domains Guide.

Because the Managed Server receives its configuration from the Administration Server, the Administration Server specified must be in the same domain as the Managed Server.

Specifying the Default Startup State

To set up a server so that the weblogic.Server command (or a script that executes the command) starts it in STANDBY by default, do the following (starting a server in STANDBY requires you to set up an Administration Port for the server):

1. In the Administration Console, expand the Servers node in the left pane. A list of servers appears under the Servers node.

2. Select a specific server in the left pane.

3. On the General tab, in the Startup Mode field, enter STANDBY.

4. Click Apply to save your changes.

Starting a Remote Managed Server

If a Node Manager is running on the host machine of a Managed Server, you can start the Managed Server from a remote host using the Administration Console or the weblogic.Admin utility. Node Manager is a standalone Java program provided with WebLogic Server that enables you to start and stop remote Managed Servers.

For information about starting a remote server from the Administration Console, refer to Starting a Server and Starting a Server in the STANDBY State in the Administration Console Online Help.

For information on using the weblogic.Admin command utility, refer to START and STARTINSTANDBY.

For information about the Node Manager, refer to Managing Server Availability with Node Manager in the Creating and Configuring WebLogic Server Domains Guide.

Starting and Killing All WebLogic Servers in a Domain or Cluster

If the Node Manager is running on the host machines of your Managed Servers, you can use the Administration Console to start all of the Managed Servers in the domain or in a specific cluster. You cannot start the Administration Server from the Administration Console.

You can also use the Administration Console to force a shutdown (kill) of all WebLogic Servers in a domain or in a cluster. The kill command initiates a forced shutdown for Managed Servers and the Administration Server. It does not require the Node Manager.

This section describes the following tasks:

• Starting All Managed Servers in a Domain

• Starting All Managed Servers in a Cluster

• Killing All Servers in a Domain

• Killing All Servers in a Cluster

For information about the Node Manager, refer to Managing Server Availability with Node Manager in the Creating and Configuring WebLogic Server Domains Guide.

Starting All Managed Servers in a Domain

To start all of the Managed Servers in the active domain, do the following:

1. Start the Administration Server for the domain.

2. Start the Node Manager on all machines in the domain. For more information, refer to Starting Node Manager in the Creating and Configuring WebLogic Server Domains Guide.

3. From the Administration Console, right click on the name of the active domain in the left panel.

4. Select Start this domain...

5. When the Administration Console prompts you to confirm the command, click Yes.

   The Administration Console displays a page that lists the name of each WebLogic Server in the domain.

6. To view the result of the start operation for a server, click its name.

Starting All Managed Servers in a Cluster

To start all of the Managed Servers in a cluster, do the following:

1. Start the Administration Server for the domain.

2. Start the Node Manager on all machines in the cluster. For more information, refer to Starting Node Manager in the Creating and Configuring WebLogic Server Domains Guide.

3. From the Administration Console, right click on the name of the cluster in the left panel.

4. Select Start this cluster...

5. When the Administration Console prompts you to confirm the command, click Yes.

   The Administration Console displays the Tasks page, which displays the status of the startup task for each Managed Server in the cluster.

6. To view details about a server's startup status, on the Tasks page, click the startup task's name. Then click the Details tab.

Killing All Servers in a Domain

To initiate a force shutdown (kill) for all servers in a domain, do the following:

1. From the Administration Console, right click on the name of the cluster in the left panel.

2. Kill this domain...

3. When the Administration Console prompts you to confirm the command, click Yes.

   Managed Servers and the Administration Server immediately stop all work items and shut down. If a Managed Server does not respond, and if you used the Node Manager to start the server, the Node Manager kills the server.

4. To confirm that the domain is killed, review the output in the shell process that runs the Administration Server. It displays an ALERT message that indicates the shutdown sequence has been initiated, and then it exits the process.

Killing All Servers in a Cluster

To initiate a force shutdown (kill) for servers in a cluster, do the following:

1. From the Administration Console, right click on the name of the cluster in the left panel.

2. Kill this domain...

3. When the Administration Console prompts you to confirm the command, click Yes.

   All servers in the cluster immediately stop all work items and shut down. If a Managed Server does not respond, and if you used the Node Manager to start the server, the Node Manager kills the server.

4. To confirm that the cluster is killed, do one of the following:

   • If the Administration Server is not part of the cluster, in the left pane, click the Tasks node. On the Tasks page, click the shutdown task's name. Then click the Details tab.

   • If the Administration Server is part of the cluster, review the output in the shell process that runs the Administration Server. It displays an ALERT message that indicates the shutdown sequence has been initiated, and then it exits the process.

 

---

Shutting Down WebLogic Servers

You can do any of the following to shut down a WebLogic Server:

• Using the Administration Console:

  • Shutting Down a Server

  • Forcing Shutdown of a Server

• Using the weblogic.Admin utility:

  • SHUTDOWN

  • FORCESHUTDOWN

When you initiate a graceful shutdown, the server notifies subsystems to complete all in-work requests. After the subsystems complete their work, the server stops.

When you initiate a forced shutdown, the server instructs subsystems to immediately drop in-work requests. If you force a Managed Server to shut down and it fails to respond, and if you started the server with the Node Manager, the Node Manager kills the server process.

The server waits a number of seconds for all subsystems to successfully stop. After the number of seconds expires, the server does one of the following:

• If the timeout occurs when the server is in the RUNNING state, the server returns a message to standard out. To shut down the server after this occurs, you must issue a force shutdown command.

• If the timeout occurs when the server is in the STANDBY or SHUTTING_DOWN state, it kills all processes and shuts down.

For information on changing the default number of seconds, refer to Setting the Timeout Period for LifeCycle Operations in the Administration Console Online Help.

 

---

Configuring Startup and Shutdown Classes

You can use startup and shutdown classes to configure a WebLogic Server to perform tasks when you start or gracefully shut down the server. A startup class is a Java program that is automatically loaded and executed when a WebLogic Server is started or restarted.

By default, startup classes are loaded and executed after all other server subsystems have initialized and after the server deploys modules. For any startup class, you can override the default and specify that the server loads and executes it before the server deploys JDBC connection pools, Web applications, and EJBs.

A shutdown class is a Java program that is automatically loaded and executed when the WebLogic Server is shut down either from the Administration Console or the weblogic.admin shutdown command. For more information about when a server invokes startup and shutdown classes, refer to The Server Lifecycle.

To use startup or shutdown classes, you must configure and assign these classes to one or more servers. To configure a class from the Administration Console, refer to Startup and Shutdown Classes in the Administration Console Online Help. BEA provides the examples.jms.startup API code example which demonstrates how to establish a JMS message consumer from a WebLogic startup class.

Note: WebLogic Server 7.0 optionally installs API code examples in WL_HOME\samples\server\src\examples, where WL_HOME is the top-level directory of your WebLogic Server installation. You can start the examples server, and obtain information about the samples and how to run them.

 

---

Setting Up a WebLogic Server Instance as a Windows Service

If you want a WebLogic Server instance to start automatically when you boot a Windows host computer, you can set up the server as a Windows service.

For each server instance that you set up as a Windows service, WebLogic Server creates a key in the Windows Registry under HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services. The registry entry contains such information as the name of the server and other startup arguments.

When you start the Windows host, the Windows Service Control Manager (SCM), which is part of the Windows operating system, uses the information in the Windows Registry key to invoke the weblogic.Server main class. The Windows SCM cannot be configured to use a Node Manager to start Managed Servers, and therefore the Node Manager's monitoring and automatic restart features cannot be used for servers that run as a Windows service.

The following tasks set up and manage WebLogic Server instances that run as Windows Services:

• Setting Up a Windows Service: Main Steps

• Verifying the Setup

• Using the Control Panel to Stop or Restart a Server Instance

• Removing a Server as a Windows Service

• Changing Startup Credentials for a Server Set Up as a Windows Service

Setting Up a Windows Service: Main Steps

To set up a Windows service:

1. Do one of the following:

   • If the Domain Configuration Wizard prompts you to install a server as a Windows Service, choose Yes.

     Some of the domain templates in the Domain Configuration Wizard prompt you to set up a server as a Windows service. If you choose Yes, the wizard installs the server as a Windows service. If you are using the wizard to create an Administration Server and Managed Servers, the wizard creates a Windows service only for the Administration Server. The wizard also creates a server-specific script for you that you can modify and use to install other servers as Windows services. The script is named domain-name\installService.cmd, where domain-name is the name of the domain that you created.

   • Create a script that sets values for server-specific variables and then calls a WebLogic Server master script. For more information, refer to Create a Server-Specific Script.

2. If you are installing a Managed Server as a Windows service, you must set additional variables in the server-specific script. For more information, refer to Set Additional Values for Managed Servers.

3. If you set up both an Administration Server and a Managed Server to run as Windows services on the same computer, modify the master script so that the Managed Server starts only after the Administration Server finishes its startup cycle. For more information, refer to Require Managed Servers to Start After Administration Servers.

4. If you want a server instance to shut down gracefully when you use the Windows Control Panel to stop the Windows service, create a Java class and modify the master script so that the Windows SCM will invoke the class. For more information, refer to Enable Graceful Shutdowns from the Control Panel.

5. If you want to see the messages that a server instance prints to standard out and standard error (including stack traces and thread dumps), redirect standard out and standard error to a file. For more information, refer to Redirecting Standard Out and Standard Error to a File.

6. If you have created additional Java classes that you want the WebLogic Server instance to invoke, you must add them to the server's classpath. For more information, refer to Adding Classes to the Classpath.

7. Run the server-specific script. For more information, refer to Run the Server-Specific Script.

Create a Server-Specific Script

If the Domain Configuration Wizard did not already create a server-specific script for your domain, you can create one. The script sets values for variables that identify the name of the server instance and other server-specific information. Then the script calls a master script, WL_HOME\server\bin\installSvc.cmd, where WL_HOME is the directory in which you installed WebLogic Server. The master scripts invokes the beasvc utility, which adds a key to the Windows Registry.

Note: For more information about beasvc, enter the following command at a command prompt: WL_HOME\server\bin\beasvc -help, where WL_HOME is the directory in which you installed WebLogic Server.

To see an example of a server-specific script, refer to Listing 2-1.

To create a server-specific script:

1. In the root directory for the domain's Administration Server (the directory that contains the domain's config.xml file), create a text file.

2. Add the following, required batch commands to the text file, each command on a separate line:

   • SETLOCAL

     This is a batch command that begins the localization of environment variables in a batch file.

   • set DOMAIN_NAME=domain-name

     where domain-name is the name of your WebLogic Server domain.

   • set USERDOMAIN_HOME=absolute-pathname

     where absolute-pathname is the absolute pathname of the Administration Server's root directory (the directory that contains the domain's configuration file). For more information about the root directories for servers, refer to A Server's Root Directory.

   • set SERVER_NAME=server-name

     where server-name is the name of an existing server instance that you want set up as a Windows service.

3. Add the following optional batch commands to the text file. Place each command on a separate line:

   • set WLS_USER=username
     set WLS_PW=password

     where username is the name of an existing user with privileges to start a server instance and password is the user's password. The beasvc utility encrypts the login credentials and stores them in the Windows registry.

     This is one of two possible methods for avoiding the username/password prompt when a server instance starts. The disadvantage to this method is that changing the username or password for the server instance requires you to delete the Windows service and set up a new one with the new username and password. Instead of this method, you can use a boot identity file. With a boot identity file, you can change the login credentials without needing to modify the Windows service. For more information, refer to Bypassing the Prompt for Username and Password.

   • set STARTMODE=[true]

     When the STARTMODE variable is set to true, the server instance starts in production mode. When not specified, or when set to false, the server starts in development mode. For more information about development mode and production mode, refer to Development Mode vs. Production Mode.

   • set JAVA_OPTIONS=java-options

     where java-options is one or more Java arguments that you want to pass to the Java Virtual Machine (JVM). Separate multiple arguments with a space. For a list of Java options that are specific to WebLogic Server, refer to Command Syntax for weblogic.Server. The JVM that you use supports additional options and are documented by the JVM vendor.

   • set JAVA_VM=-JVM-mode

     where JVM-mode is a text string that indicates the mode in which you want the JVM to run. The values that you supply depend on the JVM that you are using. If you use the JRockit JVM, the default value is -jrockit. For more information, refer to "Starting and Configuring the JRockit JVM" in the JRockit User Guide.

     To see a list of supported JVMs, refer to the List of Supported Platforms at the following URL: http://download.oracle.com/docs/cd/E13222_01/wls/certifications/certs_700/overview.html.

   • set MEM_ARGS=[-XmsNumberm] [-XmxNumberm]

     where Number is a numerical value in megabytes (MB). The-XmsNumberm argument establishes a minimum heap size for the JVM and the -XmxNumberm sets a maximum heap size. By default, the minimum heap size is 23 MB and the maximum heap size is 200 MB.

4. Add the following required commands to the end of the script:

   • call "WL_HOME\server\bin\installSvc.cmd"

     where WL_HOME is an absolute pathname for the directory in which you installed WebLogic Server. This command calls the WebLogic Server master script.

   • ENDLOCAL

     This is a batch command that ends the localization of environment variables in a batch file.

5. Save the text file with a .cmd extension. By default, the Windows command prompt associates the .cmd extension with batch files.

Set Additional Values for Managed Servers

If you want to install a Managed Server as a Windows service, you must include a variable that specifies the location of the domain's Administration Server. The Managed Server must contact the Administration Server to retrieve its configuration data.

To set additional values for Managed Servers:

1. In a text editor, open the server-specific script.

   If you are modifying a script that the Domain Configuration Wizard created, BEA recommends that you make a copy of domain-name\installService.cmd (where domain-name is the name of the domain that you created) and open the copy.

2. In the text file, between the SETLOCAL command and the call command, create the following command:

   set ADMIN_URL=protocol://listen-address:listen-port

   where

   • protocol is http or https

   • listen-address is a listen address of the Administration Server

   • listen-port is a port of the Administration Server

   For more information, refer to Configuring a Connection to the Administration Server.

   For an example, refer to the bold text in Listing 2-1.

3. Save your modifications to the server-specific script.

Listing 2-1 Example Script for Setting Up a Server as a Windows Service

echo off
SETLOCAL

set DOMAIN_NAME=myWLSdomain 
set USERDOMAIN_HOME=d:\bea\user_projects\myWLSdomain
set SERVER_NAME=myWLSserver 
set STARTMODE=true
set JAVA_OPTIONS=-Dweblogic.Stdout="d:\bea\user_projects\myWLSdomain\stdout.txt" -Dweblogic.Stderr="d:\bea\user_projects\myWLSdomain\stderr.txt" 

set ADMIN_URL=http://adminserver:7501 

set MEM_ARGS=-Xms40m -Xmx250m

call "d:\bea\weblogic700\server\bin\installSvc.cmd"

ENDLOCAL

Require Managed Servers to Start After Administration Servers

If you set up both an Administration Server and a Managed Server to run as Windows services on the same computer, you can specify that the Managed Server starts only after the Administration Server.

To require a Managed Server to start after the Administration Server Windows service, do the following:

1. Create a backup copy of the WL_HOME\server\bin\installSvc.cmd master script.

2. If you have already installed the Administration Server as a Windows Service, remove the service. For more information, refer to Removing a Server as a Windows Service.

3. Before you install (or reinstall) the Administration Server as a Windows Service, do the following:

   1. In a text editor, open the WL_HOME\server\bin\installSvc.cmd master script.

      The last command in this script invokes beasvc, which is the WebLogic Server utility that modifies the Windows Registry.

   2. In installSvc.cmd, add the following argument to the command that invokes the beasvc utility:

      -delay:delay_milliseconds

   This specifies the number of milliseconds to wait before the Windows SCM changes the service status from SERVER_START_PENDING to STARTED.

   For example, if your Administration Server requires 2 minutes to complete its startup cycle and begin listening for requests, then specify -delay=120000. When you boot the Windows host computer, the Windows SCM reports a status of SERVER_START_PENDING for 2 minutes. Then it changes the status to STARTED.

   The modified beasvc invocation for the Administration Server will resemble the following:

   "%WL_HOME%\server\bin\beasvc" -install
   -svcname:"%DOMAIN_NAME%_%SERVER_NAME%"
   -delay:120000
   -javahome:"%JAVA_HOME%" -execdir:"%USERDOMAIN_HOME%"
   -extrapath:"%WL_HOME%\server\bin" -password:"%WLS_PW%"
   -cmdline:%CMDLINE%

   For more information about beasvc, enter the following command at a command prompt: WL_HOME\server\bin\beasvc -help, where WL_HOME is the directory in which you installed WebLogic Server.

4. Install the Administration Server Windows service.

5. Before you install the Managed Server as a Windows service, do the following:

   1. In a text editor, open the WL_HOME\server\bin\installSvc.cmd master script.

   2. In installSvc.cmd, add the following argument to the command that invokes the beasvc utility:

      -depend:Administration-Server-service-name

      where Administration-Server-service-name is the name of the Administration Server Windows service. To verify the service name, look on the Windows Services Control Panel.

   With this option, the Windows SCM will wait for the Administration Server Windows service to report a status of STARTED before it starts the Managed Server Windows service.

   For example, the modified beasvc invocation for the Managed Server will resemble the following:

   "%WL_HOME%\server\bin\beasvc" -install
   -svcname:"%DOMAIN_NAME%_%SERVER_NAME%"
   -depend:"myDomain_myAdminServer"
   -javahome:"%JAVA_HOME%" -execdir:"%USERDOMAIN_HOME%"
   -extrapath:"%WL_HOME%\server\bin" -password:"%WLS_PW%"
   -cmdline:%CMDLINE%

   You can also add the -delay:delay_milliseconds option to a Managed Server Windows service if you want to configure when the Windows SCM reports a status of STARTED for the service.

Enable Graceful Shutdowns from the Control Panel

By default, if you use the Windows Control Panel to stop a server instance, the Windows Service Control Manager (SCM) kills the server's Java Virtual Machine (JVM). If you kill the JVM, the server immediately stops all processing. Any session data is lost. If you kill the JVM for an Administration Server while the server is writing to the config.xml file, you can corrupt the config.xml file.

To enable graceful shutdowns from the Windows Control Panel, do the following:

1. Create a Java class that invokes the weblogic.management.runtime.ServerRuntime.shutdown() method.

   This method gracefully shuts down a server after the server has completed all inflight work. For an example of such a class, refer to Java Class that Shuts Down a Server Instance.

2. Create a backup copy of the WL_HOME\server\bin\installSvc.cmd master script.

3. In a text editor, open the WL_HOME\server\bin\installSvc.cmd master script and do the following:

   1. Add the class that you created to the set CLASSPATH statement.

      For example if you archived your class in a file named c:\myJar, the modified statement will be as follows:
      set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%WL_HOME%\server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\weblogic.jar;c:\myJar;%CLASSPATH%

   2. Add the following argument to the last line of the script, which calls the beasvc utility:
      -stopclass:javaclass
      where javaclass is the full classpath name of the class that you created. This argument loads javaclass and then invokes its public void static stop() method.

      For example, if you packaged the class in Java Class that Shuts Down a Server Instance in com.myClasses, the modified beasvc command will be as follows:
      the modified beasvc invocation will resemble the following:

      "%WL_HOME%\server\bin\beasvc" -install
      -svcname:"%DOMAIN_NAME%_%SERVER_NAME%"
      -stopclass:com.myClasses.ServerStopper
      -javahome:"%JAVA_HOME%" -execdir:"%USERDOMAIN_HOME%"
      -extrapath:"%WL_HOME%\server\bin" -password:"%WLS_PW%"
      -cmdline:%CMDLINE%

      For more information about beasvc, enter the following command at a command prompt: WL_HOME\server\bin\beasvc -help, where WL_HOME is the directory in which you installed WebLogic Server.

4. Consider modifying the default timeout value that the Windows SCM specifies.

   By default, when you use the Windows 2000 Control Panel to stop a Windows service, the Windows SCM waits 30 seconds for the service to stop before it kills the service and prints a timeout message to the System event log.

   If you use -stopclass to gracefully shut down a server, 30 seconds might not be enough time for the server to gracefully end its processing.

   To configure a timeout period on Windows 2000, create a REG_DWORD registry value named ServicesPipeTimeout under the following registry key:
   HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control

   The key value must be in milliseconds.

   This value is read from the registry during the startup of the Windows operating system and it affects all services that are installed.

5. Save your changes to the WebLogic Server master script.

Java Class that Shuts Down a Server Instance

The following Java class uses Java Management Extensions (JMX) to shut down a server instance. Each server uses JMX Managed Beans (MBeans) to expose its management attributes and operations. One such MBean, ServerRuntime, exposes a shutdown() method that gracefully shuts down a server.

The class in Listing 2-2 uses the Administration MBeanHome interface, which can retrieve and call ServerRuntime MBean operations for all server instances in a domain.

For more information about JMX programming, refer to the Programming WebLogic Management Services with JMX guide.

Listing 2-2 Java Class that Shuts Down a Server Instance

import java.util.Set;
import java.util.Iterator;
import java.rmi.RemoteException;
import javax.naming.*;
import weblogic.jndi.Environment;

import weblogic.management.MBeanHome;
import javax.management.ObjectName;
import weblogic.management.WebLogicMBean;
import weblogic.management.configuration.ServerMBean;
import weblogic.management.runtime.ServerRuntimeMBean;
import weblogic.management.WebLogicObjectName;

public class ServerStopper {
  public static void stop() throws Exception {
    MBeanHome home = null;

    //url of the Admin server
    String url = "t3://qa113:7001";
    String username = "system";
    String password = "gumby1234";
    ServerRuntimeMBean serverRuntime = null;
    Set mbeanSet = null;
    Iterator mbeanIterator = null;

    try {
      // Set ContextClassloader to prevent assertions
      URL[] urls = { new File("/").toURL() };
      Thread.currentThread().setContextClassLoader(new
         URLClassLoader(urls));

      Environment env = new Environment();
      env.setProviderUrl(url);
      env.setSecurityPrincipal(username);
      env.setSecurityCredentials(password);
      Context ctx = env.getInitialContext();
      home = (MBeanHome)
           ctx.lookup("weblogic.management.adminhome");
      mbeanSet = home.getMBeansByType("ServerRuntime");
      mbeanIterator = mbeanSet.iterator();

      while(mbeanIterator.hasNext()) {
        serverRuntime = (ServerRuntimeMBean)mbeanIterator.next();
        if(serverRuntime.getState().equals("RUNNING")) {
          serverRuntime.shutdown();
        }
      }

    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Redirecting Standard Out and Standard Error to a File

By default, when you install a WebLogic Server instance as a Windows service, you cannot see the messages that the server or its JVM print to standard out and standard error.

To view these messages, you must redirect standard out and standard error to a file:

1. Create a backup copy of the WL_HOME\server\bin\installSvc.cmd master script.

2. In a text editor, open the WL_HOME\server\bin\installSvc.cmd master script.

3. In installSvc.cmd, the last command in the script invokes the beasvc utility. At the end of the beasvc command, append the following command option:

   -log:"pathname "
   where pathname is a fully qualified path and filename of the file that you want to store the server's standard out and standard error messages.

   The modified beasvc command will resemble the following command:

   "%WL_HOME%\server\bin\beasvc" -install
   -svcname:"%DOMAIN_NAME%_%SERVER_NAME%"
   -javahome:"%JAVA_HOME%" -execdir:"%USERDOMAIN_HOME%"
   -extrapath:"%WL_HOME%\server\bin" -password:"%WLS_PW%"
   -cmdline:%CMDLINE%
   -log:"d:\bea\user_projects\myWLSdomain\myWLSserver-stdout.txt

4. By default, every 24 hours the Windows service archives messages to a file named pathname-yyyy_mm_dd-hh_mm_ss. New messages collect in the file that you specified in the previous step.

After you install the service and restart the Windows host, to view the messages that the server writes to standard out or standard error, do one of the following:

• Make a copy of the file that you specified and view the copy. The Windows file system cannot write to files that are currently opened.

• To view the messages as they are being printed to the file, open a command prompt and use the DOS command tail -f stdout-filename.

Printing Thread Dumps to Standard Out

To cause the WebLogic Server instance to print a thread dump to standard out, do either of the following:

• Use the weblogic.Admin THREAD_DUMP command. For more information, refer to THREAD_DUMP.

• Open a command prompt and enter the following command:

  WL_HOME\bin\beasvc -dump -svcname:service-name
  where WL_HOME is the directory in which you installed WebLogic Server and
  service-name is the Windows service that is running a server instance.

For example:
D:\bea\weblogic70\server\bin\beasvc -dump -svcname:mydomain_myserver

Adding Classes to the Classpath

The classpath is a declaration of the location of Java classes that a JVM can invoke. When you use the WebLogic Server master script to install a server instance as a Windows service, the master script specifies all classes required to run a server instance. If you want to extend WebLogic Server by adding your own Java classes, you must add them to the classpath.

To add classes to the classpath:

1. Create a backup copy of the WL_HOME\server\bin\installSvc.cmd master script.

2. In a text editor, open the WL_HOME\server\bin\installSvc.cmd master script.

3. Add your class to the set CLASSPATH statement.

   For example if you archived your class in a file named c:\myJar, the modified statement will be as follows:
   set CLASSPATH=%JAVA_HOME%\lib\tools.jar;%WL_HOME%\server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\weblogic.jar;c:\myJar;%CLASSPATH%

   Note: Win32 systems have a 2K limitation on the length of the command line. If the classpath setting for the Windows service startup is very long, the 2K limitation could be exceeded.

   To work around this limitation:

   1. Place the value of the set CLASSPATH command in a separate text file and save the text file in the WL_HOME\server\bin directory.

   2. In the WL_HOME\server\bin\installSvc.cmd master script, find the set CMDLINE command.

   3. Within the set CMDLINE command, replace the -classpath \"%CLASSPATH%\" option with the following option:

      -classpath @filename
      where filename is the name of the file that contains the classpath values.

      For example:

      set CMDLINE="%JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS%
      -classpath @myClasspath.txt -Dweblogic.Name=%SERVER_NAME% -Dbea.home=\"D:\bea_70sp2\" -Dweblogic.management.username=%WLS_USER% -Dweblogic.management.server=\"%ADMIN_URL%\" -Dweblogic.ProductionModeEnabled=%STARTMODE% -Djava.security.policy=\"%WL_HOME%\server\lib\weblogic.policy\" weblogic.Server"

4. Save your changes to the WebLogic Server master script.

Run the Server-Specific Script

Note: To run the server-specific script, you must log in to the Windows computer with a user account that has privileges to modify the Windows registry.

If you install the Windows service in a production environment, BEA recommends that you do not run the service under an operating-system user account that has administrator-level privileges. For more information, see Verifying the User Account Under Which the Service Runs.

To run the server-specific script:

1. Open a command prompt and change to Administration Server's root directory, which is the directory that contains the server-specific script.

2. Enter the name of the server-specific script.

   The command prompt runs the script as a batch file.

   If the script runs successfully, it creates a Windows service named
   DOMAIN_NAME_SERVER_NAME and prints a line to standard out that is similar to the following:
   mydomain_myserver installed.

   By default, standard out is the command prompt in which you run the server-specific batch file.

3. If you modified the WL_HOME\server\bin\installSvc.cmd master script, consider undoing your modifications so the script can be used to set up other server instances.

Verifying the Setup

To verify that you successfully set up a WebLogic Server as a Windows service, do the following:

1. Open a command window and enter the following command:
   set PATH=WL_HOME\server\bin;%PATH%

2. Navigate to the directory immediately above your domain directory. For example, to verify the setup for BEA_HOME\user_domains\mydomain, navigate to BEA_HOME\user_domains.

3. Enter:
   beasvc -debug "yourServiceName"

   For example, beasvc -debug "mydomain_myserver".

If your setup was successful, the beasvc -debug command starts your server. If the script returns an error similar to the following, make sure that you specified the correct service name:
Unable to open Registry Key ....... System\CurrentControlSet\Services\beasvc example_examplesServer\Parameters

Verifying the User Account Under Which the Service Runs

In a production environment, WebLogic Server Windows services should run under a special operating-system user account that has limited access privileges. For example, the OS user should have access privileges only to BEA files and to your domain files. This should be the only user account that has access to these files.

To ensure that the WebLogic Server instance runs under the special OS user account:

1. Open the Services control panel.

   For example, from the Windows 2000 desktop:

   1. Select the Start menu.

   2. On the Start menu, select Settings —> Control Panel

   3. In the Control Panel window, open the Administrative Tools folder

   4. In the Administrative Tools window, open the Services control panel.

2. On the Services control panel, right click the WebLogic Server Windows service and click Properties.

3. In the Properties window, click the Log On tab.

4. Under Log on as, select This account. Then enter the user name and password of the special OS user account.

5. Click OK.

Using the Control Panel to Stop or Restart a Server Instance

After you set up a server instance to run as a Windows service, you can use the Service Control Panel to stop and restart the server.

By default, if you use the Windows Control Panel to stop a server instance, the Windows Service Control Manager (SCM) kills the server's Java Virtual Machine (JVM). If you kill the JVM, the server immediately stops all processing. Any session data is lost. If you kill the JVM for an Administration Server while the server is writing to the config.xml file, you can corrupt the config.xml file. For information on enabling graceful shutdowns from the Windows Control Panel, refer to Enable Graceful Shutdowns from the Control Panel.

To stop or restart a WebLogic Server instance that is installed as a Windows service:

1. Select Start—>Settings—>Control Panel.

2. On Windows 2000, open the Administrative Tools Control Panel. Then open the Services Control Panel.

   On Windows NT, open the Services Control Panel directly from the Control Panel window.

3. In the Services Control Panel, find the service that you created. By default, the service name starts with beasvc.

4. Right-click the service name and select commands from the shortcut menu.

Removing a Server as a Windows Service

To remove a Windows service that runs a WebLogic Server instance, you can use a script that causes the beasvc utility to remove the associated key from the Windows Registry. Removing the Windows service has no effect on the server instance's configuration that is saved in the domain's configuration file. After you remove the Windows service, you can start the WebLogic Server instance with start scripts or, for Managed Servers, the Node Manager.

If the Domain Configuration Wizard did not already create a script for your domain, you can create one. The script sets values for variables that identify the name of the server instance and other server-specific information. Then the script calls a master uninstall script, WL_HOME\server\bin\uninstallSvc.cmd, where WL_HOME is the directory in which you installed WebLogic Server. The master scripts invokes the beasvc utility, which removes a key from the Windows Registry.

To see an example of a server-specific uninstaller script, refer to Listing 2-3.

To create a script for removing a Windows service that runs a WebLogic Server instance:

1. In the root directory for the domain's Administration Server (the directory that contains the domain's config.xml file), create a text file.

2. Add the following, required batch commands to the text file, each command on a separate line:

   • SETLOCAL

     This is a batch command that begins the localization of environment variables in a batch file.

   • set DOMAIN_NAME=domain-name

     where domain-name is the name of your WebLogic Server domain.

   • set SERVER_NAME=server-name

     where server-name is the name of an existing server instance that you want set up as a Windows service.

   • call "WL_HOME\server\bin\uninstallSvc.cmd"

     where WL_HOME is an absolute pathname for the directory in which you installed WebLogic Server. This command calls the WebLogic Server master uninstall script.

   • ENDLOCAL

     This is a batch command that ends the localization of environment variables in a batch file.

3. Save the text file with a .cmd extension. By default, the Windows command prompt associates the .cmd extension with batch files.

4. Enter the name of the server-specific script.

   The command prompt runs the script as a batch file.

If the removal script runs successfully, it prints a line similar to the following to standard out:
mydomain_myserver removed.

By default, standard out is the command prompt in which you run the batch file.

Listing 2-3 Script to Remove a Windows Service

echo off
SETLOCAL

set DOMAIN_NAME=myWLSdomain 
set SERVER_NAME=myWLSserver 
call "D:\bea\weblogic700\server\bin\uninstallSvc.cmd"

ENDLOCAL

Changing Startup Credentials for a Server Set Up as a Windows Service

To change a Windows service so that a WebLogic Server instance runs under different user credentials, do one of the following:

• If you set up the Windows service to retrieve usernames and passwords from a boot identity file, you can overwrite the existing file with a new one that contains the new username and password. You must specify the name of an existing user in the WebLogic Server default security realm. For information, refer to Creating a Boot Identity File for an Administration Server.

• If you set up the Windows service to retrieve usernames and passwords from the Windows registry, then you must remove the Windows service and create a new one that uses your new username or password:

1. Uninstall the Windows service that runs the WebLogic Server instance. For more information, refer to Removing a Server as a Windows Service.

2. In a text editor, open the script that you used to install the service and enter the new username and password as the value for the set WLS_USER and set WLS_PW commands. WebLogic encrypts these values in the Windows Registry.

3. Save your modifications to the script.

4. Enter the name of the server-specific script.

   The command prompt runs the script as a batch file.

   If the script runs successfully, it creates a Windows service named
   DOMAIN_NAME_SERVER_NAME and prints a line to standard out that is similar to the following:
   mydomain_myserver installed.

   By default, standard out is the command prompt in which you run the server-specific batch file.

5. (Optional) Remove the username and password from the script file.