WASService command

The WASService command line tool enables you create a service for a product Java™ process on Linux® and Windows operating systems.

You can create services for WebSphere® Application Server Java processes. Potential services include the following server processes:

The default server1 process on an application server node
Application server processes that you create on an application server node
The nodeagent process on an application server node that is part of a deployment manager cell
The deployment manager process, dmgr

Note: Do not add an application server that is part of a federated or managed node as a Windows service. Use the node agent to manage federated nodes.

Avoid trouble: As an alternative to the WASService command, you can use the WASServiceHelper utility, which complements the WASService command and reduces possible configuration errors. For more information, see the documentation about using the WASServiceHelper to create Windows services.

To set up and run this function on a Microsoft Windows operating system, the user must belong to the administrator group and have the following advanced user rights:

Act as part of the operating system
Log on as a service

Location of the command file

[Linux] The wasservice.sh command file is located in the app_server_root\bin directory.

[Windows] The WASService.exe command file is located in the app_server_root\bin directory.

Command syntax

Command syntax for starting an existing service

The command syntax is as follows:

wasservice.sh -start service_name [optional startServer.bat parameters]

WASService.exe -start service_name [optional startServer.bat parameters]

Command syntax for creating a service or updating an existing service

The command syntax is as follows:

wasservice.sh -add service_name
   -serverName server_name
   -profilePath server_profile_directory
   [-wasHome app_server_root]
   [-startArgs additional_start_arguments]
   [-stopArgs additional_stop_arguments]
   [-userid user_id -password password]

Note: For WebSphere Application Server Version 7.0 and later versions, do not use the "@" sign as a prefix in the userid when specifying wasservice.sh. The use of the "@" sign as a prefix in the userid for wasservice.sh only applies to WebSphere Application Server Version 6.1.

Specifying wasservice.sh with -userid @myuser should not be used in Version 7.0 and later.

WASService.exe -add service_name
   -serverName server_name
   -profilePath server_profile_directory
   [-wasHome app_server_root]
   [-configRoot configuration_repository_directory]
   [-startArgs additional_start_arguments]
   [-stopArgs additional_stop_arguments]
   [-userid user_id -password password]
   [-logFile service_log_file]
   [-logRoot server_log_directory]
   [-restart true | false]
   [-startType automatic | manual | disabled]

Avoid trouble: Although the -logroot parameter is optional, it is advisable to include this optional parameter. In some cases, when you do not specify this optional parameter, you might see an error in the event log that says that the application server is attempting to create a service with the -logroot parameter.

Command syntax for deleting a service

The command syntax is as follows:

wasservice.sh -remove service_name

WASService.exe -remove service_name

Command syntax for stopping a running service

The command syntax is as follows:

wasservice.sh -stop service_name [optional stopServer.bat parameters]

WASService.exe -stop service_name [optional stopServer.bat parameters]

Command syntax for retrieving service status

The command syntax is as follows:

wasservice.sh -status service_name

WASService.exe -status service_name

Required parameters

The following parameters are required with this command:

-profilePath server_profile_directory: Use this option to specify the directory path of the profile that defines the server process.
-serverName server_name: Use this option to identify the server that the service controls.

Optional parameters

The following parameters are optional with this command:

-add service_name

Use this option to create a service named service_name or update an existing service. The syntax is the same for both cases.

-configRoot configuration_repository_directory (Windows only)

Use this option to identify the configuration directory of the installation root directory of a WebSphere Application Server product.

-encodeParams service_name (Windows only)

Use this option to force the service to encode the -startArgs and -stopArgs so that the arguments cannot be determined by editing the registry. Use the parameter when creating a service with the -add parameter by adding -encodeParams to the command line with no arguments.

Or encode the parameters of an existing service:

WASService -encodeParams service_name

-logFile service_log_file(Windows only)

Use this option to identify a log file that the WASService command uses to record its activity.

Avoid trouble: Be sure to specify the service log file as a fully qualified name having a unique path. If your system has multiple instances, then without this qualification, the results are unpredictable and WASService is not able to determine when initialization is complete.

-logRoot server_log_directory(Windows only)

Use this option to identify the server log directory for the profile. The WASService command looks for a file named server_name.pid to determine if the server is running.

-remove service_name

Use this option to delete the specified service.

-restart true | false (Windows only)

Use this parameter to specify whether or not the existing service restarts automatically if the service fails. The existing service does not restart automatically if you set the value to false. By default, the restart behavior is set to true, which enables the existing service to restart automatically if it fails.

-start service_name [optional startServer.bat parameters]

Use this option to start the existing service.

-startArgs additional_start_arguments

Use this option to identify additional parameters.

-startType automatic | manual | disabled (Windows only)

Use this option to define the startup type of the new service. An automatic startup type starts automatically when the system starts or when the service is called for the first time. You must start a manual service before the operating system can load it and make it available. You cannot start a disabled service before changing the startup type. By default, the value for this parameter is set to manual.

-status service_name

Use this option to return the current status of the service, which includes whether the service is running or stopped.

-stop service_name [optional stopServer.bat parameters]

Use this option to stop the specified service.

-stopArgs additional_stop_arguments

Use this option to specify additional parameters.

-userid user_id -password password

Use this option to identify a privileged user ID and password that the Windows service will run as.

-wasHome app_server_root

Use this option to identify the installation root directory of the product.

Note: The following parameters are "Windows only" parameters:

-configRoot
-encodeParams
-logFile
-logRoot
-restart
-startType

An alternative for logging and throwing errors in Linux is to use the system's standard sysvinit to run the normal startServer.sh script.

CAUTION:

Unrecognized parameters are ignored.

Default names for services that are created by the wizard

The names of the services that the Profile Management Tool can create are:

Deployment manager: IBM WebSphere Application Server V8.x - node_name_of_the_deployment_manager_node
Application server: IBM WebSphere Application Server V8.x - node_name_of_the_server1_node
Custom profile: After federating the node and creating an application server, a service can be created called IBM WebSphere Application Server V8.x - node_name_of_the_managed_node.

After creating a custom profile, you must federate the node to create a node agent server on the node. You can also use the administrative console of the deployment manager to create application server processes on the node. You can create a Windows service for the node agent server process.

A node agent server is also created after adding an application server node to a deployment manager cell. You can create a service for the node agent server process as described later.

Viewing the services panel

To view services, open the Control panel and click Administrative Tools > Services. Select a service to view information about it. Right-click the service and click Properties. Four tabs provide information and functionality. For example, select the Setup type field on the General tab to change the setup type.

Examples

Creating a deployment manager service

This example creates a service called IBM® WebSphere Application Server V8.x - name_of_the_deployment_manager_service that starts the dmgr process:

WASService -add name_of_the_deployment_manager_service
   -servername deployment_manager_server_name
   -profilePath profile_root
   -wasHome app_server_root
   -logFile WS_startManager.log
   -logRoot profile_root\logs\deployment_manager_server_name
   -restart true

where

name_of_the_deployment_manager_service is the name that you want to give to the service
deployment_manager_server_name is the name of your server

After entering the command, messages that are similar to those in the following example display in the command window:

Adding Service: name_of_the_deployment_manager_service
   Config Root: profile_root\config
   Server Name: deployment_manager_server_name
   Profile Path: profile_root
   Was Home: app_server_root
   Start Args:
   Restart: 1
IBM WebSphere Application Server V8.x - name_of_the_deployment_manager_service service successfully added.

Click Start > Settings > Control Panel > Administrative Tools > Services to work with the new service.

Creating a node agent service

This example creates a service called IBM WebSphere Application Server V8.x - name_of_the_node_agent_service that starts the node agent server process:

WASService -add name_of_the_node_agent_service
   -servername node_agent_server_name
   -profilePath profile_root
   -wasHome app_server_root
   -logFile WS_startNode.log
   -logRoot profile_root\logs\node_agent_server_name
   -restart true

where

name_of_the_node_agent_service is the name that you want to give to the service
profile_root is the location where the node agent resides on the file system
node_agent_server_name is the name of your node agent
Normally, this is simply nodeagent.

After entering the command, messages that are similar to those in the following example display in the command window:

Adding Service: name_of_the_node_agent_service
   Config Root: profile_root\config
   Server Name: node_agent_server_name
   Profile Path: profile_root
   Was Home: app_server_root
   Start Args:
   Restart: 1
IBM WebSphere Application Server V8.x - name_of_the_node_agent_service service successfully added.

Creating an application server service

This example creates a service called IBM WebSphere Application Server V8.x - name_of_the_application_server_service that starts an application server process:

WASService -add name_of_the_application_server_service
   -servername application_server_name
   -profilePath profile_root
   -wasHome app_server_root
   -logFile WS_startServer.log
   -logRoot profile_root\logs\application_server_name
   -restart true

where

name_of_the_application_server_service is the name that you want to give to the service
application_server_name is the name of your server

After entering the command, messages that are similar to those in the following example display in the command window:

Adding Service: name_of_the_application_server_service
  Config Root: profile_root\config
  Server Name: application_server_name
  Profile Path: profile_root
  Was Home: app_server_root
  Start Args:
  Restart: 1
IBM WebSphere Application Server V8.x - name_of_the_application_server_service service successfully added.

Updating an existing application server service

This example for the Windows operating system updates an existing service called IBM WebSphere Application Server V8.x - Server2 Service with additional stop arguments, the user name and password. The parameters are automatically passed into the script that the Windows service uses to shut down the system.

WASService -add "Server2 Service"
   -servername server2
   -profilePath profile_root
   -logRoot profile_root\logs\server2
   -stopArgs "-username user_name  -password password"
   -encodeParams

Starting and stopping a server process after creating a Windows service

For this Windows operating system example, if you issue the startServer server1 command or the stopServer server1 after creating a Windows service for server1, a message that is similar to the following example displays:

Because server1 is registered to run as a Windows Service, the
request to start this server will be completed by starting the
associated Windows Service.

If you issue the startNode command or the stopNode command after creating a Windows service for the nodeagent process, a message that is similar to the following example displays:

Because nodeagent is registered to run as a Windows Service, the
request to start or stop this server will be completed by 
starting or stopping the associated Windows Service. Examine 
the log files to view messages related to this command.

If you issue the startManager command or the stopManager command after creating a Windows service for the deployment manager, a message that is similar to the following example displays:

Because dmgr is registered to run as a Windows Service, the
request to start or stop this server will be completed by 
starting or stopping the associated Windows Service. Examine 
the log files to view messages related to this command.

Avoid trouble: Creating and removing a WebSphere service in Windows can be confusing and error prone. For help in any diagnosing errors, see the information on using the WASServiceHelper utility to create Windows services for WebSphere Application Servers.