+

Search Tips   |   Advanced Search

WASService command

To create a Windows service, or a Linux service, for WebSphere Application Server Java processes, run...

Potential services include the following server processes:

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.

As an alternative to WASService, we can use the WASServiceHelper utility, which complements the WASService command, and reduces possible configuration errors.

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:


Command syntax for starting an existing service


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 WAS v7 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 WAS v6.1.

Specify 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 we 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.gotcha


Command syntax for deleting a service

The command syntax is as follows:


Command syntax for stopping a running service

The command syntax is as follows:


Command syntax for retrieving service status

The command syntax is as follows:


Required parameters

The following parameters are required with this command:

-profilePath server_profile_directory Directory path of the profile that defines the server process.

-serverName server_name Server that the service controls.


Optional parameters

The following parameters are optional with this command:

-add service_name Create a service named service_name or update an existing service. The syntax is the same for both cases.

-configRoot configuration_repository_directory Configuration directory of the installation root directory of a WAS product. Windows only

-encodeParams service_name 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

Windows only

-logFile service_log_file Log file that the WASService command uses to record its activity. Windows only

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

-logRoot server_log_directory Server log directory for the profile. The WASService command looks for a file named server_name.pid to determine if the server is running. Windows only

-remove service_name Delete the specified service.

-restart true | false only) Specify whether or not the existing service restarts automatically if the service fails. The existing service does not restart automatically if 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. Windows only

-start service_name [optional startServer.bat parameters] Start the existing service.

-startArgs additional_start_arguments Identify additional parameters.

-startType automatic | manual | disabled 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. We must start a manual service before the operating system can load it and make it available. We cannot start a disabled service before changing the startup type. By default, the value for this parameter is set to manual. Windows only

-status service_name Return the current status of the service, which includes whether the service is running or stopped.

-stop service_name [optional stopServer.bat parameters] Stop the specified service.

-stopArgs additional_stop_arguments Specify additional parameters.

-userid user_id -password password Identify a privileged user ID and password that the Windows service will run as. I

-wasHome app_server_root Identify the installation root directory of the product.

The following parameters are "Windows only" parameters:

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 created by the wizard

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

dmgr IBM WebSphere Application Server V8.x - node_of_the_deployment_manager_node

Application server IBM WebSphere Application Server V8.x - node_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_of_the_managed_node

After creating a custom profile, you must federate the node to create a node agent server on the node. We can also use the console of the deployment manager to create application server processes on the node. We 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. We can create a service for the node agent server process as described later.


View the services panel

To view services, open the Control panel and click...

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


Create a deployment manager service

This example creates a service called... 

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

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

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


Create a node agent service

This example creates a service called... 

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

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

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


Create an application server service

This example creates a service called... 

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

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

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


Update an existing application server service

This example for the Windows operating system updates an existing service called...

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


Start and stop 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:

If we 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:

If we 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:

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 WASServiceCmd to create Windows services for WebSphere Application Servers.


Leveraging Windows services

A Windows service can be run in the security context of a local user account, a domain user account, or the LocalSystem account. To help decide which account to use, an administrator will install the service with the minimum set of permissions required to perform the service operations, will typically create a domain user account for the service, and grant that account the specific access rights and privileges required by the service at run time.

There can be many reasons you might want to do this. Windows services typically live on each local machine and can be controlled by a local user or a domain user. In some cases, it can be beneficial to set up the service to run as a domain user. For example, if multiple machines are set up to run IBM WebSphere Application Server as a service, a domain user account can be set up to control all those services. If a password ever needs to be changed, it can be modified in just the domain controller for that user. If local system users were to run the services, the password would need to be changed in every machine instead of just once for the user in the domain controller. When the password changes for a user that is running a Windows service, the only way to get the service to work again is to update the service and repeat all the steps.

The task of setting up WebSphere Application Server to run, as a Windows service under a domain user account, can be complicated. This article explains the general information we need to accomplish this setup in Windows Server 2003. You will learn how to create the Windows service using the WASServiceCmd utility and how to change the service to log on as the domain user account.

For the purpose of this article, it is assumed that the local machine is already part of the domain. Be aware that once the machine is added to the domain, the group for Domain Admins is added by default on the local machine, shown in Figure 1.

We'll refer to two different users located in the Active Directory of the domain controller:

Figure 1. Domain Admins group gets added by default when machine is added to domain

Figure 2. Shows alainadmin is a member of Domain Admins group

Figure 3. Shows alainuser is a member of Domain Users group

Specific rights are required by the operating system to be able to run the domain user. To set up and run this function on a Microsoft Windows operating system, the user must belong to the administrator group and have these advanced user rights:

To demonstrate, let's step through the procedure:

  1. Log on to the local machine with a user that has Domain Administrator rights (alainadmin).

  2. Add the domain user to the Administrators group of the local machine (alainuser), shown in Figure 4:

    1. Right click My computer and select Manage. In the directory tree, navigate to Under Local Users and Groups > Groups.

      Figure 4. Shows path to get to Administrators Group in Windows 2003

    2. To add the user to the Administrators group, double click Administrators, then select Add.

    3. Click Advanced. If prompted for username and password, use the credentials for the domain administrator in the domain controller (alainadmin).

    4. Click Find Now. The users from the domain will display. Add your domain user to the group of Administrators (Figure 5), then click OK and Apply.

      Figure 5. Shows alainuser getting added to the Administrators group of the local machine

  3. Add the two required user rights assignments:

  4. Click the Windows Start button and navigate to Settings > Control Panel > Administrative tools > Local Security Policy.

  5. Select User Rights Assignment in the left window (if not already selected) and then double-click Act as part of the operating system (Figure 6).

    Figure 6. Security setting: Act as part of the operating system

  6. Click Add User or Group. Select the user and click OK to add the user to the policy (Figure 7).

    Figure 7. Add the local user alainuser to the security policy

  • Repeat the previous step to the user to the Log on as a service policy (Figure 8).

    Figure 8. Local security settings

  • Log off Domain Admin (alainadmin) and log in as the Domain user (alainuser).

  • Run the WASServiceCmd utility to create the service. Earlier this year, The Support Authority presented the WASService command. You can download the utility from the Using WASServiceCmd to create Windows services for WebSphere Application Servers Technote. Follow the instructions to unzip the tool to the WebSphere_root/AppServer/bin directory. WASServiceCmd.exe is a front end for WASService.exe, which is shipped with WebSphere Application Server. The creation of a service takes many parameters and this utility will help minimize any human errors that can occur during service creation.

  • Change the service to log on as the domain user. Click the Windows Start button and navigate to Settings > Control Panel > Administrative tools > Services.

  • Locate the service that was created. Double-click the service, select the Log on tab, and change the Log on as selection to This account.

    Figure 9. Shows the Domain user alainuser becoming Log on as

    The service should now be working with the domain user alainuser. Shown in Figure 9, the log on values show AUSTINL2\alainuser. This shows that the service is now being controlled by a domain user account.


    Related tasks

    Automatically restarting server processes
  • Use the WASServiceHelper utility to create Windows services for application servers
  • Access problems after enabling security