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:
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 3-1.
To create a server-specific script:
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).
server-name
where server-name
is the name of an existing server instance that you want set up as a Windows service.
batch
commands to the text file. Place each command on a separate line:set WLS_USER=
username
set WLS_PW=
password
where username
is the name of an existing user with privileges to start a server instance and password
is the user’s password. The beasvc
utility encrypts the login credentials and stores them in the Windows registry.
This is one of two possible methods for avoiding the username/password prompt when a server instance starts. The disadvantage to this method is that changing the username or password for the server instance requires you to delete the Windows service and set up a new one with the new username and password. Instead of this method, you can use a boot identity file. With a boot identity file, you can change the login credentials without needing to modify the Windows service. For more information, 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
Creating a WebLogic Domain 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. 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=[-Xms
Number
m] [-Xmx
Number
m]
where Number
is a numerical value in megabytes (MB). The-Xms
Number
m
argument establishes a minimum heap size for the JVM and the -Xmx
Number
m 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 . |
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:
SETLOCAL
command and the call
command, create the following command:
set ADMIN_URL=
protocol
://
listen-address
:
listen-port
protocol
is http
or https
listen-address
is a listen address of the Administration Serverlisten-port
is a port of the Administration ServerFor more information, see Configuring Managed Server Connections to the Administration Server.
For an example, refer to the bold text in Listing 3-1.
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
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:
WL_HOME\server\bin\installSvc.cmd
master script.SERVER_START_PENDING
to STARTED
.
-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.
WL_HOME\server\bin\installSvc.cmd
master script.installSvc.cmd
, add the following argument to the command that invokes the beasvc
utility:
-depend
:Administration-Server-service-name
where Administration-Server-service-name
is the name of the Administration Server Windows service. To verify the service name, look on the Windows Services Control Panel.
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.
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:
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.
WL_HOME\server\bin\installSvc.cmd
master script.WL_HOME\server\bin\installSvc.cmd
master script and do the following: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%
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 Listing 3-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.
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 Administration Console Online Help.
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.
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 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 more information about the ServerRuntime
MBean, refer to the WebLogic Server
Javadoc.
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();
}
}
}
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:
WL_HOME\server\bin\installSvc.cmd
master script.WL_HOME\server\bin\installSvc.cmd
master script.installSvc.cmd
, the last command in the script invokes the beasvc
utility. At the end of the beasvc
command, append the following command option:
-log:"
pathname
"
where pathname
is a fully qualified path and filename of the file that you want to store the server’s standard out and standard error messages.
The modified beasvc
command will resemble the following command:
"%WL_HOME%\server\bin\beasvc" -install
-svcname:"%DOMAIN_NAME%_%SERVER_NAME%"
-javahome:"%JAVA_HOME%" -execdir:"%USERDOMAIN_HOME%"
-extrapath:"%WL_HOME%\server\bin" -password:"%WLS_PW%"
-cmdline:%CMDLINE%-log:"d:\bea\user_projects\domains\myWLSdomain\myWLSserver-stdout.txt”
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:
tail
command, enter tail -f
stdout-filename
.
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:
-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:\bea\wlserver6.1\config\mydomain\myserver-stdout.txt
.
# 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 EnglishDay
is the 2-digit day of the Gregorian-calendar monthYear
is the 4-digit year of the Gregorian calendarHour
:
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.
# 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.
and 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:
For example:D:\bea\weblogic81\server\bin\beasvc -dump -svcname:mydomain_myserver
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:
WL_HOME\server\bin\installSvc.cmd
master script.WL_HOME\server\bin\installSvc.cmd
master script.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:
set CLASSPATH
command in a separate text file. WL_HOME\server\bin\installSvc.cmd
master script, find the set CMDLINE
command.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.
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"
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:
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.
WL_HOME\server\bin\installSvc.cmd
master script, consider undoing your modifications so the script can be used to set up other server instances.To verify that you successfully set up a WebLogic Server as a Windows service, do the following:
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
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:
For example, from the Windows 2000 desktop:
Note: | When accessing network drives, the Windows service must run under the same username as the one who shared the network drive. |
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:
On Windows NT, open the Services Control Panel directly from the Control Panel window.
beasvc
.
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 Listing 3-3.
To create a script for removing a Windows service that runs a WebLogic Server instance:
config.xml
file), create a text file. 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.
server-name
where server-name
is the name of an existing server instance that you want set up as a Windows service.
call "
WL_HOME
\server\bin\uninstallSvc.cmd"
where WL_HOME
is an absolute pathname for the directory in which you installed WebLogic Server. This command calls the WebLogic Server master uninstall script.
ENDLOCAL
This is a batch
command that ends the localization of environment variables in a batch file.
.cmd
extension. By default, the Windows command prompt associates the .cmd
extension with batch
files.
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.
echo off
SETLOCAL
set DOMAIN_NAME=myWLSdomain
set SERVER_NAME=myWLSserver
call "D:\bea\weblogic81\server\bin\uninstallSvc.cmd"
ENDLOCAL
To change a Windows service so that a WebLogic Server instance runs under different user credentials, do one of the following:
set WLS_USER
and set WLS_PW
commands. WebLogic encrypts these values in the Windows Registry.
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.