3 Setting Up a WebLogic Server Instance as a Windows Service

Windows service enables Oracle WebLogic Server to start automatically when you boot a Windows host computer. Using aWindows service, you can stop or restart the server instance smoothly without any data loss and manage multiple user credentials for a single instance. 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

Windows services enable you to create long-running executable applications that run in the background without any user interface. You can set up a Windows service by running a server-specific script that invokes the weblogic.Server main class by using the information in the Windows registry key. Before running the server-specific script, you must be sure to configure or enable the required connections and java classes for the Administration Server and Managed Servers.

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. See 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. See 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. See 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. See 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. See 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. See Adding Classes to the Classpath.
  7. Run the server-specific script. See 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 wlsvc utility, which adds a key to the Windows Registry.

Note:

You can specify a service description when installing a Windows service in the wlsvc utility by using the -svcdescription:<user_specified_service_description> option. You can also specify a service description by setting the environment variable SERVICE_DESCRIPTION prior to running your installSvc.cmd script.

For more information about wlsvc, enter the following command at a command prompt: WL_HOME\server\bin\wlsvc -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.

    • set WL_HOME= wlserver

      where wlserver is the name of the WebLogic installation root directory.

  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 wlsvc 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. See Boot Identity Files.

    • set DOMAIN_PRODUCTION_MODE=[true]

      When the DOMAIN_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. See Domain Mode and JDK in Creating WebLogic 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.

    • set USER_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 USER_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\user_projects\domains\base_domain\bin\setDomainEnv.cmd"

      where WL_HOME is an absolute pathname for the directory in which you installed WebLogic Server. This command sets the domain-level environment variables.

    • 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 Managed Server as a Windows Service

echo off
SETLOCAL
set MW_HOME=C:\Oracle\Middleware\Oracle_Home
set DOMAIN_NAME=base_domain
set USERDOMAIN_HOME=C:\Oracle\Middleware\Oracle_Home\user_projects\domains\base_domain
set SERVER_NAME=ManagedServer
set ADMIN_URL=http://10.xxx.xx.xx:7001
set WL_HOME=C:\Oracle\Middleware\Oracle_Home\wlserver
set DOMAIN_PRODUCTION_MODE=true
set USER_MEM_ARGS=-Xms128m -Xmx512m
call "C:\Oracle\Middleware\Oracle_Home\user_projects\domains\base_domain\bin\setDomainEnv.cmd"
call "C:\Oracle\Middleware\Oracle_Home\wlserver\server\bin\installSvc.cmd"
ENDLOCAL

Note:

To use this example script to set up an Administration Server as a Windows service, remove the ADMIN_URL variable.

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

WLS_USER and WLS_PW are optional and can be added to the script only if boot identity file is not being used. See Creating a Server-Specific Script.

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. See 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 wlsvc, 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 wlsvc 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 wlsvc invocation for the Administration Server will resemble the following:

      "%WL_HOME%\server\bin\wlsvc" -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 wlsvc, enter the following command at a command prompt: WL_HOME\server\bin\wlsvc -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 wlsvc 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 wlsvc invocation for the Managed Server will resemble the following:

      "%WL_HOME%\server\bin\wlsvc" -install 
      -svcname:"%DOMAIN_NAME%_%SERVER_NAME%" 
      -depend:"wlsvc 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 wlsvc 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 wlsvc command will be as follows:

      "%WL_HOME%\server\bin\wlsvc" -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 wlsvc, enter the following command at a command prompt: WL_HOME\server\bin\wlsvc -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. See Control graceful shutdowns in the Oracle WebLogic Server Administration Console Online 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.

See Developing Custom Management Utilities Using JMX for Oracle WebLogic Server and Javadoc.

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

package com.myClasses;

import java.net.*;
import java.io.*;
import java.util.Hashtable;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
import javax.naming.Context;

public class ServerStopper {
  public static void stop() {
    try {
      String servername = "AdminServer";
      String hostname = "localhost";
      int port = 7001;
      String username = "weblogic";
      String password = "password";
      //Select t3 or iiop as required
      //String protocol = "t3";
      String protocol = "iiop";
      String jndiroot = "/jndi/";
      String mserver = "weblogic.management.mbeanservers.domainruntime";
      
      // To avoid AssertionError
      URL[] urls = { new File("/").toURL() };
      Thread.currentThread().setContextClassLoader(new
         URLClassLoader(urls));

      JMXServiceURL serviceURL = new JMXServiceURL(protocol, hostname, port, jndiroot + mserver);
      Hashtable h = new Hashtable();
      h.put(Context.SECURITY_PRINCIPAL, username);
      h.put(Context.SECURITY_CREDENTIALS, password);
      h.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, "weblogic.management.remote");
      JMXConnector connector = JMXConnectorFactory.connect(serviceURL, h);
      MBeanServerConnection connection = connector.getMBeanServerConnection();
      ObjectName service = new ObjectName("com.bea:Name=DomainRuntimeService,Type=weblogic.management.mbeanservers.domainruntime.DomainRuntimeServiceMBean");
      ObjectName[] serverRuntimes = (ObjectName[]) connection.getAttribute(service, "ServerRuntimes");

    for (ObjectName serverRuntime : serverRuntimes) {
      String name = (String) connection.getAttribute(serverRuntime, "Name");

      if (name.equals(servername)) {
        String state = (String) connection.getAttribute(serverRuntime, "State");

        if (state.equals("RUNNING") || state.equals("ADMIN")) {
           connection.invoke(serverRuntime, "shutdown", new Object[0], new String[0]);
           System.out.println("Stopped the server: " + servername);
        }
        else
          System.out.println("The server is not in RUNNING or ADMIN state.  The current state is: " + state);
        return;
      }
    }
    System.out.println("The server, " + servername + " does not exist");
    connector.close();
  }
  catch (Exception ex) {
    Logger.getLogger(ServerStopper.class.getName()).log(Level.SEVERE, null, ex);
    }
  }
}

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 wlsvc utility. At the end of the wlsvc 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 wlsvc command will resemble the following command:

    "%WL_HOME%\server\bin\wlsvc" -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\user_projects\domains\myWLSdomain\myWLSserver-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

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

      Optionally, you can add the MAX_FILE_COUNT attribute to specify a rotation limit for the output files that are generated from WebLogic Server as a service. By default, MAX_FILE_COUNT=-1, meaning no limit on the number of files exists. Defining MAX_FILE_COUNT with a value greater than 0 sets a limit on the number of files to rotate.

      For example:

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

      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 
      # MAX_FILE_COUNT = 999

      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\wlsvc -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_12.1\server\bin\wlsvc -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. 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

Use the wlsvcx64 -debug command to verify that the Windows service is configured correctly.

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 ORACLE_HOME\user_projects\domains\mydomain, navigate to ORACLE_HOME\user_projects\domains.
  3. Enter:
    wlsvcx64 -debug "yourServiceName" 
    

    For example, wlsvcx64 -debug "mydomain_myserver".

    If your setup was successful, the wlsvcx64 -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\wlsvc 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

Use the Microsoft Management Console Services window to stop and restart a server instance.

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

Removing a Server as a Windows Service

You can remove a Windows service by using a script that causes the wlsvc utility to remove the associated key from the Windows Registry. It does not affect the server instance's configuration that is saved in the domain's configuration file. After removing the Windows service, you can restart the WebLogic server instance with start scripts, for Managed Servers or 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 wlsvc 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.

    • set MW_HOME=ORACLE_HOME

      where ORACLE_HOME is the absolute path to the directory you specified as Oracle Home when you installed Oracle WebLogic Server.

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

      where WL_HOME is the absolute path to 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
set MW_HOME=D:\Oracle\Middleware\Oracle_Home
call "D:\Oracle\Middleware\Oracle_Home\wlserver\server\bin\uninstallSvc.cmd"
ENDLOCAL

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

To make a WebLogic Server instance run under different user credentials, you can change a Windows service configuration to support various startup 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. 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. See 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.