Skip navigation.

eDocs Home > BEA WebLogic Server 8.1 Documentation > Configuring and Managing WebLogic Server > Setting Up a WebLogic Server Instance as a Windows Service

Configuring and Managing WebLogic Server

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

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

To set up a Windows service:

  1. Do one of the following:
  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 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 Enabling Graceful Shutdowns from the Windows 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, 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

If the Configuration Wizard did not already create a server-specific script for your domain, you can create one. 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 Listing 6-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:
  3. Add the following optional batch commands to the text file. Place each command on a separate line:

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.

  1. Add the following required commands to the end of the script:
  2. 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.

To configure a connection to the Administration Server:

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

    2. If you are modifying a script that the 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:

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

    where

    For more information, refer to "Configuring a Connection to the Administration Server" in the Administration Console Online Help.

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

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

Listing 6-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\domains\myWLSdomain
set SERVER_NAME=myWLSserver 
set PRODUCTION_MODE=true
set
JAVA_OPTIONS=-Dweblogic.Stdout="d:\bea\user_projects\domains\myWLSdomain\
stdout.txt" -Dweblogic.Stderr="d:\bea\user_projects\domains\myWLSdomain\
stderr.txt" 
set ADMIN_URL=http://adminserver:7501 
set MEM_ARGS=-Xms40m -Xmx250m
call "d:\bea\weblogic81\server\bin\installSvc.cmd"
ENDLOCAL

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.

      2. 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:

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

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

Enabling Graceful Shutdowns from the Windows 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:

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

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

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

      3. For example, if you packaged the class in Listing 6-2 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. In the Administration Console, on the server's Control —> Start/Stop tab, configure the Managed Server's graceful shutdown behavior.

    5. 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 "Controlling Graceful Shutdowns" in the Administration Console Online Help.

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

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

  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 Listing 6-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. For more information about the ServerRuntime MBean, refer to the WebLogic Server Javadoc.

Listing 6-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();
    }
  }
}

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:

    4. -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\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.

    5. 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:

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.

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

  3. Do one of the following:

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

For example:
D:\bea\weblogic81\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.

    4. 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:

      4. -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, BEA recommends that you do not run the service under an operating-system user account that has administrator-level priveleges. 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.

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

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

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

Note: When accessing network drives, the Windows service must run under the same username as the one who shared the network drive.

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 Enabling Graceful Shutdowns from the Windows 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.

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

    5. 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 6-3 Script to Remove a Windows Service

echo off
SETLOCAL
set DOMAIN_NAME=myWLSdomain 
set SERVER_NAME=myWLSserver 
call "D:\bea\weblogic81\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:

  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.

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

 

Skip navigation bar  Back to Top Previous Next