Setting Up a WebLogic Server Instance as a Windows Service

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

For each server 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, it passes the information in the registry to the JVM.

The following tasks describe setting up servers as Windows services:

• Setting Up a Windows Service
• Using a Non-Default JVM with a Windows Service
• Verifying the Setup
• Using the Control Panel to Stop or Restart the Service
• Removing a Server as a Windows Service
• Changing Startup Credentials for a Server Set Up as a Windows Service
• Viewing Messages for a Server Set Up as a Windows Service
• The WebLogic Server Windows Service Program (beasvc.exe)

 

---

Setting Up a Windows Service

WebLogic Server includes a master script, WL_HOME\server\bin\installSvc.cmd, that you can use to set up a server instance as a Windows Service. Instead of invoking the installSvc.cmd master script directly, create your own script that supplies values for a set of variables and then calls the installSvc.cmd script:

1. In the root directory for the domain's Administration Server (the directory that contains the domain's config.xml file), create a script that is similar to the one in Listing 5-1.

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

@rem *************************************************************************

@rem This script sets up a WebLogic Server instance as a Windows service.
@rem It sets variables to specify the domain name, server name, and optionally,
@rem user credentials, startup mode, and arguments for the JVM. Then the script
@rem calls the %WL_HOME%\server\bin\installSvc.cmd script.

@rem *************************************************************************

echo off
SETLOCAL

@rem Set DOMAIN_NAME to the name of the domain in which you have defined
@rem the server instance.
set DOMAIN_NAME=myWLSdomain 

@rem Set USERDOMAIN_HOME to the root directory of the domain's Administration
@rem Server, which is the directory that contains the domain's config.xml file.
@rem For more information about the root directories for servers, refer to 
@rem A Server's Root Directory.
set USERDOMAIN_HOME=D:\bea\user_projects\myWLSdomain 

@rem Set SERVER_NAME to the name of the existing server instance that you want 
@rem set up as a Windows service.
set SERVER_NAME=myWLSserver 

@rem Optional: one way of bypassing the username and password prompt during
@rem server startup is to set WLS_USER to your system username and WLS_PW to 
@rem your password. The script encrypts the login credentials and stores them
@rem in the Windows registry.
@rem The disadvantage to this method is that changing the username or password
@rem for the server instance requires you to delete the Windows service and set
@rem up a new one with the new username and password. 
@rem If you use a boot identity file to bypass the prompt, you can change the
@rem login credentials without needing to modify the Windows service. For more
@rem information about bypassing the username and password prompt, refer to 
@rem "Bypassing the Prompt for Username and Password" in the Administration
@rem Console Online Help.
set WLS_USER=
set WLS_PW=

@rem Optional: set Production Mode. When STARTMODE is set to true, the server
@rem starts in Production Mode. When not specified, or when set to false, the 
@rem server starts in Development Mode. For more information about 
@rem Development Mode and Production Mode, refer to 
@rem "Starting in Development Mode or Production Mode" in the Administration
@rem Console Online Help.
set STARTMODE=

@rem Set JAVA_OPTIONS to the Java arguments you want to pass to the JVM. Separate
@rem multiple arguments with a space.
@rem If you are using this script to set up a Managed Server as a Windows service,
@rem you must include the -Dweblogic.management.server argument, which 
@rem specifies the host name and listen port for the domain's Administration
@rem Server. For example:
@rem set JAVA_OPTIONS=-Dweblogic.management.server=http://adminserver:7501 
@rem For more information, refer to
@rem "weblogic.Server Configuration Options" in the WebLogic Server Command
@rem Reference.
set JAVA_OPTIONS=

@rem Optional: set JAVA_VM to the java virtual machine you want to run. 
@rem For example:
@rem set JAVA_VM=-server 
set JAVA_VM=

@rem Set MEM_ARGS to the memory args you want to pass to java. For example:
@rem set MEM_ARGS=-Xms32m -Xmx200m
set MEM_ARGS=

@rem Call Weblogic Server service installation script. Replace <WL_HOME> with
@rem the absolute pathname of the directory in which you installed WebLogic
@rem Server. For example:
@rem call "D:\bea\weblogic810\server\bin\installSvc.cmd"
call "<WL_HOME>\server\bin\installSvc.cmd"

ENDLOCAL

2. 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 has started by doing the following:
   1. In a text editor, open the WL_HOME\server\bin\installSvc.cmd master script.

   The last command in this script invokes the beasvc utility.

   2. Add the following arguments to the command that invokes the beasvc utility:
   • -depend: service_names

   Comma-separated list of services that must start before this service starts.

   • -delay: delay_milliseconds

   Number of milliseconds to delay the JVM thread.
   The -delay argument is optional, but recommended to make sure that an Administration Server has time to complete its startup cycle before any Managed Servers start.

   For example, the modified beasvc invocation will resemble the following:

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

3. Save the script and run it from the server's root directory.

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

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

Note: If you use the Domain Configuration Wizard to create a domain and server, some of the domain templates prompt you to set up the server as a Windows service. You can choose yes to set up an Administration Server as a Windows service. However, if you want to set up a Managed Server with a dependency, you must choose no in the wizard and complete the steps in this section. Regardless of whether you choose yes or no, if the domain template includes a prompt for setting up a service, it will create a script named installService.cmd in the server's root directory, which is similar to the script in Listing 5-1.

 

---

Using a Non-Default JVM with a Windows Service

If you are not using the JVM installed with WebLogic Server, you must edit the master script so that it installs server instances that use a non-default JVM:

1. Create a backup copy of WL_HOME\server\bin\installSvc.cmd.
2. Open installSvc.cmd in a text editor.
3. Edit the set JAVA_HOME command to specify the home directory of your JVM. For example, set JAVA_HOME=C:\JRockit\JRE\1.3.1
4. Edit the set JAVA_VENDOR command so that it specifies one of the supported values.

   The supported values are listed in the line immediately preceding the set JAVA_VENDOR command.

 

---

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 the following command:
   beasvc -debug "yourServiceName"

   For example, beasvc -debug "beasvc 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

 

---

Using the Control Panel to Stop or Restart the Service

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

1. Select Start—>Settings—>Control Panel.
2. On Windows 2000, open the Administrative Tools Control Panel. Then open the Services Control Panel.

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

3. In the Services Control Panel, find the service that you created. By default, the service name starts with beasvc.
4. Right-click the service name and select commands from the shortcut menu.

 

---

Removing a Server as a Windows Service

To remove a server as a Windows service, do the following:

1. In the root directory of the domain's Administration Server (the directory that contains the domain's config.xml file), create a script similar to the one in Listing 5-2.

Listing 5-2 Script to Remove a Windows Service

@rem *************************************************************************

@rem This script is used to uninstall a WebLogic Server service for a
@rem server instance that is defined for the current domain. 
@rem The script simply sets the DOMAIN_NAME and SERVER_NAME variables and calls
@rem the %WL_HOME%\server\bin\uninstallSvc.cmd script.

@rem *************************************************************************

echo off
SETLOCAL

@rem Set DOMAIN_NAME to the name of the domain that contains the server.
set DOMAIN_NAME=myWLSdomain 

@rem Set SERVER_NAME to the name of the server that you want to remove as
@rem a service.
set SERVER_NAME=myWLSserver 

@rem Call Weblogic Server service uninstallation script. Replace <WL_HOME> with
@rem the absolute pathname of the directory in which you installed WebLogic
@rem Server. For example:
@rem call "D:\bea\weblogic810\server\bin\uninstallSvc.cmd"
call "<WL_HOME>\server\bin\uninstallSvc.cmd"

ENDLOCAL

2. Save and run the script.

If the removal script runs successfully, its output in the command window includes a line similar to the following:
beasvc mydomain_myserver removed.

 

---

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

To change passwords or add users for any WebLogic Server, you must start the server and use the security realm's administration tools. If you use the security realm that is installed with WebLogic Server, you can use the Administration Console. If you use a third-party security realm, you must use the administration tools provided in that realm.

After you change the security data, you must do the following to change the arguments that are passed to the server during the startup cycle:

• If you set up the Windows service to retrieve usernames and passwords from a boot identity file, you can overwrite the existing file with a new one that contains the new username and password. For information about creating a boot identity file, refer to "Creating a Boot Identity File" in the Administration Console Online Help.
• If you set up the Windows service to retrieve usernames and passwords from the Windows registry, then you must remove the Windows service and create a new one that uses your new username or password:
1. Uninstall the WebLogic Server as a Windows service. For more information, refer to Removing a Server as a Windows Service.
2. In a text editor, open the script that you used the install the service and enter your new password as the value for the set WLS_USER and/or set WLS_PW directive. WebLogic encrypts this value in the Windows Registry.

After you run the script, you can remove the password from this file.

3. Save and execute the script. This will create a new service with the updated password.

 

---

Viewing Messages for a Server Set Up as a Windows Service

All WebLogic Server instances maintain log files, which you can view through the Administration Console. By default, the log files are located on server's host computer. For information about viewing log messages, refer to "Viewing Server Logs" in the Administration Console Online Help.

In addition to writing messages to a log file, server instances print a subset of those messages to standard out. The JVM that runs the server also can print its own set of messages to the server's standard out. By default, if you start a server as a Windows service, you cannot view the server's standard out or standard error. For more information about messages that are sent to standard out and standard error, refer to "Specifying Which Messages a Server Sends to Standard Out" in the Administration Console Online Help.

To redirect a standard out to a file for a server that is set up as a Windows service:

1. If you havealready set up the server as a Windows service, you must uninstall the WebLogic Server as a Windows service. For more information, refer to Removing a Server as a Windows Service.
2. In a text editor, open the script that you used the install the service. If you used the Domain Configuration Wizard to install the server as a Windows service, open my_domain\installService.cmd, where my_domain is the directory in which you created the domain.
3. Add the following Java options to the JAVA_OPTIONS variable:

   -Dweblogic.Stdout="stdout-filename"
   -Dweblogic.Stderr="stderr-filename"

   Where stdout-filename is the name of a file that you want to save standard out messages and stderr-filename is the name of a file that you want to save standard error messages.

   For example,

@rem Set JAVA_OPTIONS to the java flags you want to pass to the vm. i.e.: 
@rem set JAVA_OPTIONS=-Dweblogic.attribute=value -Djava.attribute=value
set JAVA_OPTIONS= -Dweblogic.Stdout="c:\myDomain\stdout.txt"  -Dweblogic.Stderr="c:\myDomain\stdout.txt" 

4. Save and execute the script. This will create a new service that writes standard out and standard error to a file.
5. To view the messages as they are being printed to the file, open a command prompt and use the DOS command tail -f stdout-filename.

 

---

The WebLogic Server Windows Service Program (beasvc.exe)

The installSvc.cmd and uninstallSvc.cmd master scripts are convenience wrappers for the WebLogic Server Windows Service program, beasvc.exe. You can modify those scripts or create your own scripts that invoke beasvc.exe and install WebLogic Servers or Node Managers as Windows services. If you want to uninstall a service, you can invoke beasvc.exe directly without creating a script.

For information on how to install or remove the Node Manager as a Windows service, see "Starting Node Manager as a Windows Service" in the Configuring and Managing WebLogic Serve guide.

beasvc.exe is located in WL_HOME\server\bin and your script can pass any of the following parameters:

-install

Install the specified service.

-remove

Remove the specified service.

-svcname: service_name

The user-specified name of the service to be installed or removed.

-javahome: java_directory

Root directory of the Java installation. The start command will be formed by appending \bin\java to java_directory.

-execdir: domain_name

Directory where this startup command will be executed.

-extrapath: additional_env_settings

Additional path settings that will be prepended to the path applicable to this command execution.

-help

Prints out the usage for the beasvc.exe command.

-depend: service_names

Comma-separated list of services that this service depends on.

-delay: delay_milliseconds

Number of milliseconds to delay the JVM thread.

-cmdline: variable

The java command-line parameters to be used when starting a WebLogic Server as a Windows service. For example:
-cmdline:"-ms64m -mx64m
-classpath C:\bea\wweblogic8.1\lib\weblogic.jar
-Dweblogic.Name=myserver weblogic.Server"

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, you can do the following when using the beasvc command:

1. Place the classpath values in a text file.
2. Place your beasvc command in a script. In this script, assign the parameters for the beasvc command to a variable. For the classpath parameter, use the following syntax:
   -classpath @filename
3. Then, specify the variable as the value of the -cmdline parameter. For example:

   set CMDLINE="-ms64m -mx64m -Dweblogic.Name=myserver -Dbea.home=\"c:\bea\" -classpath @C:\temp\myclasspath.txt weblogic.Server"

   "c:\bea\weblogic810\server\bin\beasvc" -install -svcname:myserver -cmdline:%CMDLINE%

Run the script.