3 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.

In Windows, the Microsoft Management Console (MMC), specifically Services, is where you start, stop, and configure Windows services.

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 Microsoft Management Console uses the information in the Windows Registry key to invoke the weblogic.Server main class. The MMC cannot be configured to use Node Manager to start Managed Servers, 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

To set up a Windows service:

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

  2. If you are installing a Managed Server as a Windows service, add a variable to the server specific script that specifies the location of the domain's Administration Server. For more information, refer to Configuring a Connection to the Administration Server.

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

  4. If you want a server instance to shut down gracefully when you stop the Windows service, create a Java class and modify the master script so that the Microsoft Management Console will invoke the class. For more information, refer to Enabling Graceful Shutdowns.

  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, 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.

Creating a Server-Specific Script

The script that you create must set values for variables that identify the name of the server instance and other server-specific information. Then it must call 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 Example 3-1.

To create a server-specific script:

  1. In the root directory for the domain's Administration Server 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). See "Specifying a Server Root Directory" in Understanding Domain Configuration for Oracle WebLogic Server.

    • 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 user name/password prompt when a server instance starts. The disadvantage to this method is that changing the user name or password for the server instance requires you to delete the Windows service and set up a new one with the new user name 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, see Boot Identity Files.

    • set PRODUCTION_MODE=[true]

      When the PRODUCTION_MODE 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, see "Configure Server Start Mode" in Creating Domains Using the Configuration Wizard.

    • 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 "weblogic.Server Command-Line Reference" in the Command Reference for Oracle 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. For example, the Sun JDK can run a -hotspot, -client or -server JVM. If you use the Sun JDK 1.3.1, the default value is -hotspot. If you use the Sun JDK 1.4.1, the default value is -client. If you use the JRockit JVM, the default value is -jrockit. For more information, refer to "Starting and Configuring JRockit JVM" in the JRockit User Guide.

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

      where Numberm 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.

      Note:

      To specify a non-default JVM heap size, set the MEM_ARGS values in WL_HOME\common\bin\commEnv.cmd; however, this change affects all the domains under the same WL_HOME.
    • set MAX_CONNECT_RETRIES=number_of_attempts

    • set HOST=ip_address

    • set PORT=port_number

      where number_of_attempts is the number of times that the Windows service will perform a status check to determine if a WebLogic Server instance is started. If you specify this variable along with HOST and PORT, the Windows service will wait until the WebLogic Server instance is started. ip_address is the IP address of the WebLogic Server instance and port_number is the port on which the WebLogic Server instance is listening for requests.

  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.

Configuring a Connection to the Administration Server

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.

The Administration Server (which is not a service) must be started before installing and starting Managed Server as a Windows service.

To configure a connection to the Administration Server:

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

  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:

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

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

echo off
SETLOCAL
set DOMAIN_NAME=myWLSdomain
set USERDOMAIN_HOME=d:\Oracle\Middleware\user_projects\domains\myWLSdomain
set SERVER_NAME=myWLSserver
set PRODUCTION_MODE=true
set
JAVA_OPTIONS=-Dweblogic.Stdout="d:\Oracle\Middleware\user_projects\domains\myWLSdomain\
stdout.txt" -Dweblogic.Stderr="d:\Oracle\Middleware\user_projects\domains\myWLSdomain\
stderr.txt"
set ADMIN_URL=http://adminserver:7501
set MEM_ARGS=-Xms40m -Xmx250m
call "d:\Oracle\Middleware\wlserver_10.3\server\bin\installSvc.cmd"
ENDLOCAL

Note:

If you copy and paste examples, make sure that there are no trailing spaces in them.

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

  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 Microsoft Management Console 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 Microsoft Management Console 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 in the Microsoft Management Console under Services.

      With this option, the Microsoft Management Console 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 Microsoft Management Console reports a status of STARTED for the service.

Enabling Graceful Shutdowns

By default, if you use the Microsoft Management Console to stop a server instance, it 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 Microsoft Management Console:

  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 in-flight 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 Example 3-2 in com.myClasses, the modified beasvc command will be as follows:

      "%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. In the WebLogic Server Administration Console, on the server's Control page, configure the Managed Server's graceful shutdown behavior.

    You can determine whether a graceful shutdown operation drops all HTTP sessions immediately and you can configure the amount of time that a graceful shutdown operation waits before forcing a shut down. For more information, refer to "Control graceful shutdowns" in the Oracle WebLogic Server Administration Console Help.

  5. Consider modifying the default timeout value that the Windows service specifies.

    By default, when you use the Microsoft Management Console to stop a Windows service, it 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, 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.

  6. 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 Example 3-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 Developing Custom Management Utilities With JMX for Oracle WebLogic Server. For more information about the ServerRuntime MBean, refer to the WebLogic Server Javadoc.

Example 3-2 Java Class that Shuts Down a Server Instance

import java.util.Set;
import java.util.Iterator;
import java.rmi.RemoteException;
import javax.naming.Context;
import javax.management.ObjectName;

import weblogic.jndi.Environment;
import weblogic.management.MBeanHome;
import weblogic.management.WebLogicMBean;
import weblogic.management.configuration.ServerMBean;
import weblogic.management.runtime.ServerRuntimeMBean;
import weblogic.management.runtime.ServerStates;
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(ServerStates.RUNNING)){
            serverRuntime.shutdown();
        }
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Note:

If two or more server instances are running, this sample Java class shuts down all server instances.

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:\Oracle\Middleware\user_projects\domains\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.

    For information on changing the default behavior, see Changing the Default Rotation Criteria.

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, using a DOS utility that supports the tail command, enter tail -f stdout-filename.

Changing the Default Rotation Criteria

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 when you set up the service.

You can change the time interval or you can set up rotation to occur based on the size of the message file instead of a time interval.

To change the default criteria at which the Windows service rotates message files:

  1. If the Windows service is running, shut it down.

  2. Edit the file you specified in the -log: pathname argument. If a file does not exist, create one.

    For example, if you issued the example command in step 3 in the previous section, create a file named d:\Oracle\Middleware\wlserver_10.3\config\mydomain\myserver-stdout.txt.

  3. Do one of the following:

    • If you want the Windows service to rotate the message file at a specific time interval regardless of file size, add the following statements at the top of the file, each statement on a separate line (make sure to press the Enter or Return key after typing the last line):

      # ROTATION_TYPE = TIME
      # TIME_START_DATE = date-in-required-format 
      # TIME_INTERVAL_MINS = number-of-minutes 
      

      where TIME_START_DATE specifies when the first rotation should take place. If the specified time has already passed, the first rotation occurs when the time interval specified in TIME_INTERVAL_MINS expires. You must use the following format to specify the start time: Month Day Year Hour:Minutes:Seconds

      where Month is the first 3 letters of a Gregorian-calendar month as written in English

      Day is the 2-digit day of the Gregorian-calendar month

      Year is the 4-digit year of the Gregorian calendar

      Hour:Minutes:Seconds expresses time in a 24-hour format

      and TIME_INTERVAL_MINS specifies how frequently (in minutes) the Windows service rotates the file.

      For example:

      # ROTATION_TYPE = TIME
      # TIME_START_DATE = Jul 17 2003 05:25:30
      # TIME_INTERVAL_MINS = 1440 
      

      When the time interval expires, the Windows service saves the file as pathname-yyyy_mm_dd-hh_mm_ss. It then creates a new file named pathname. This new file, which contains all of the headers that you specified originally, collects new standard out and standard error messages.

      If you specify # ROTATION_TYPE = TIME but do not include the other lines, the Windows service rotates the message file every 24 hours.

    • If you want the Windows service to rotate the message file after the file grows beyond a specified size, add the following statements at the top of the file, each statement on its own line (make sure to press the Enter or Return key after typing the last line):

      # ROTATION_TYPE = SIZE
      # SIZE_KB = file-size-in-kilobytes  
      # SIZE_TRIGGER_INTERVAL_MINS = polling-interval 
      

      where SIZE_KB specifies the minimal file size (in kilobytes) that triggers the Windows service to move messages to a separate file.

      SIZE_TRIGGER_INTERVAL_MINS specifies (in minutes) how frequently the Windows service checks the file size. If you do not include this header, the Windows service checks the file size every 5 minutes.

      For example:

      # ROTATION_TYPE = SIZE
      # SIZE_KB = 1024
      # SIZE_TRIGGER_INTERVAL_MINS = 3 
      

      When the Windows service checks the file size, if the file is larger than the size you specify, it saves the file as pathname-yyyy_mm_dd-hh_mm_ss. It then creates a new file named pathname. This new file, which contains all of the headers that you specified originally, collects new standard out and standard error messages.

      If you specify # ROTATION_TYPE = SIZE but do not include the other lines, the Windows service checks the size of the message file every 5 minutes. If the file is larger than 1 megabytes, it rotates the file.

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

  • Use the WLST threadDump command.

  • 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:\Oracle\Middleware\wlserver_10.3\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.

    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 @pathname\filename
      

      where pathname\filename is the absolute path and name of the file that contains the classpath values.

      For example:

      set CMDLINE="%JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% 
      -classpath @c:\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, Oracle 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 MW_HOME\user_domains\mydomain, navigate to MW_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 Oracle 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 Services in the Microsoft Management Console.

    For example, from the Windows XP desktop:

    1. Select the Start menu.

    2. On the Start menu, select Programs > Administrative Tools > Services.

  2. In the Services window, right click the WebLogic Server Windows service and select Properties.

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

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

  5. Click OK.

    Note:

    When accessing network drives, the Windows service must run under the same user name as the one who shared the network drive.

Using the Services Window to Stop or Restart a Server Instance

After you set up a server instance to run as a Windows service, you can use the Microsoft Management Console, Services window, to stop and restart the server.

By default, if you use the Microsoft Management Console to stop a server instance, it 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, refer to Enabling Graceful Shutdowns.

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

  1. Select Start > Programs > Administrative Tools > Services.

  2. In the Services window, find the service that you created. By default, the service name starts with beasvc.

  3. Right-click the service name and select commands from the 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.

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 Example 3-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 remove 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.

Example 3-3 Script to Remove a Windows Service

echo off
SETLOCAL
set DOMAIN_NAME=myWLSdomain 
set SERVER_NAME=myWLSserver 
call "D:\Oracle\Middleware\wlserver_10.3\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 user names and passwords from a boot identity file, you can overwrite the existing file with a new one that contains the new user name and password. You must specify the name of an existing user in the WebLogic Server default security realm. For more information, see Boot Identity Files.

  • If you set up the Windows service to retrieve user names and passwords from the Windows registry, then you must remove the Windows service and create a new one that uses your new user name 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 user name and password as the value for the set WLS_USER and set WLS_PW commands. WebLogic Server 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 user name and password from the script file.