4.13.10 Operate OS Service
Function
This plug-in performs operations on OS services in a Windows or Linux environment.
The following terms are used in this document:
- OS services
Windows services and Linux services are referred to as "OS services" to avoid confusion with the services executed in JP1/AO.
This plug-in requires the following server:
- Execution-target server
A server on which this plug-in is executed
The property common.serviceName specifies the name of the OS service for which the operation is to be performed. The values that can be specified vary based on the OS of the execution-target server.
- If the OS is Windows, you can specify names (service display names) that are displayed in the [Name] column of the Services administrative tool in the Control Panel.
- If the OS is Linux, you can specify the names of service scripts in the directory /etc/init.d.
The property common.serviceCommand specifies the operation to be performed on the target OS service. The operations that can be performed (regardless of whether the OS is Windows or Linux) are as follows:
- start
- stop
- restart
- status (status acquisition)
- suspend*
- resume*
*Available only if Windows is used for the execution target server.
The specifications for each of these operations conform to the OS specifications of the execution-target server. For example, if the start operation is performed on an OS service that is already running or if the stop operation is performed on an OS service that is not running, the operation terminates normally instead of ending in an error. If the restart operation is performed on an OS service that is not running, the operation is treated as the start operation.
When the status operation is performed, the operation result is stored as a numeric value in the property common.serviceStatus. The meanings of the numeric values that can be stored are shown below.
- For Windows:
1: The service is not running.
2: The service is in the process of starting.
3: The service is in the process of stopping.
4: The service is running.
5: Continuation of the service is suspended.
6: The service is stopping temporarily.
7: The service is temporarily stopped.
99: The status of the service is unknown.
- For Linux:
The meanings of numeric values vary based on the specifications of the service script specified as the OS service. For example, the following shows the meanings in Red Hat Enterprise Linux:
0: The program is running.
1: The program is not running, but the process ID file still exists.
2: The program is not running, but the lock file still exists.
3: The program is not running.
4: The execution status of the program cannot be determined, because this plug-in does not have permission to read the process ID file.
Executing a suspend operation results in the following, depending on the status of the specified OS service:
Status of the OS service Result of the suspend operation
--------------------- -----------------------------
halt The plug-in terminates normally, and the OS service remains in "halt" status.
start The plug-in terminates normally, and the OS service enters "halt" status.
stop The plug-in stops abnormally, and the OS service remains in "stop" status.
Depending on the status of the specified OS service, executing a resume operation results in the following:
Status of the OS service Result of the resume operation
---------------------- -----------------------------
halt The plug-in terminates normally, and the OS service remains in "start" status.
start The plug-in terminates normally, and the OS service enters "start" status.
stop The plug-in stops abnormally, and the OS service remains in "stop" status.
Use situation
This plug-in can be used to obtain the status of an OS service or to control an OS service.
Prerequisites
For the most recent information about the prerequisite products for the system, prerequisite products for the execution-target server, and the supported OSs for the execution-target server, see the Release Notes.
Prerequisite products for the system:
JP1/Automatic Operation 11-00 or later
Prerequisite products for the execution-target server:
None.
Supported OSs for the execution-target server:
(1) Windows Server 2008 R2 Standard/Enterprise/Datacenter
(2) Windows Server 2012 Standard/Datacenter, Windows Server 2012 R2 Standard/Datacenter
(3) Windows Server 2016 Standard/Datacenter
(4) Windows Server 2019 Standard/Datacenter
(5) Red Hat Enterprise Linux Server 6 (32-bit x86), Red Hat Enterprise Linux Server 6 (64-bit x86_64)
(6) Red Hat Enterprise Linux Server 7 (64-bit x86_64)
(7) Red Hat Enterprise Linux Server 8 (64-bit x86_64)
(8) CentOS 6 (64-bit x86_64)
(9) CentOS 7 (64-bit x86_64)
(10) CentOS 8 (64-bit x86_64)
(11) Oracle Linux 8 (64-bit x86_64)
Conditions for using the execution-target server:
None.
Cautions
(1) If the OS of the execution-target server is Windows, the connecting user defined on the agentless connection destination must have permission to access the OS service for which the operation is to be performed.
(2) If the OS of the execution-target server is Windows, the start and restart operations can be performed only for OS services whose startup type is "Manual" or "Automatic". These operations cannot be performed for OS services whose startup type is "Disabled".
(3) If the OS of the execution-target server is Windows, an operation performed on the specified OS service is not performed for other OS services that have a dependence relationship with the specified OS service. For this reason, the operation performed on the specified OS service might fail.
(4) If the OS of the execution-target server is Windows, this plug-in terminates abnormally when both of the following conditions are met:
- Another OS service is dependent on the OS service for which the stop or restart operation is performed.
- "False" is specified for the property Windows.dependOnServiceStop, which determines whether to stop OS services that have a dependence relationship with the OS service for which the operation is performed.
(5) If the OS of the execution-target server is Windows, when specifying properties, do not specify any string that includes a double quotation mark (") or single quotation mark ('). If you specify such a string, this plug-in terminates abnormally.
(6) If the OS of the execution-target server is Linux, when specifying properties, do not specify any string that includes a double quotation mark ("). If you specify such a string, this plug-in terminates abnormally.
(7) Regardless of the OS of the execution-target server, when specifying the OS service name for the property common.serviceName, specify the complete name.
You cannot specify only part of an OS service name or include any wildcard characters. In particular, if the OS is Linux, OS service names are case sensitive.
(8) If you specify an OS service that supports neither suspend nor resume when executing a suspend or resume operation, this plug-in terminates abnormally.
Execution privilege
For Windows: Administrator privileges
For Linux: Root privileges
Version
02.01.00
Plug-in tags
Control OS,Windows,Linux
Plug-in name displayed in the task log
osOperateService
Return code
0: Normal
12: Error (Mistake by user): Invalid property
21: Error (Environmental error): No command was found or could be executed (An error was detected in the component script)
27: Error (Check the task log for details of the error): Unidentified error
41: Error (An error has been detected in the component): Property not entered (An error has been detected in the component script)
Property list
The following table lists the properties:
|
Property key |
Property name |
Description |
Default value |
I/O type |
Required |
|---|---|---|---|---|---|
|
plugin.destinationHost |
Host name of the execution target server |
Specify the host name or IP address of the server on which this plugin will be executed. IPv6 addresses are not supported. |
-- |
Input |
R |
|
common.serviceName |
OS Service Name |
Specify the name of the OS service for which operations are to be performed. If the OS is Windows, specify a service display name. If the OS is Linux, specify a service script name. |
-- |
Input |
R |
|
common.serviceCommand |
Operation to the OS service |
Specify operation (start / stop / restart / status / suspend / resume) to execute to the OS service. |
status |
Input |
R |
|
Windows.dependOnServiceStop |
Whether to Stop Dependent OS Service (Windows only) |
If the OS of the execution-target server is Windows, specify "true" to stop or restart the specified OS service even if other OS services depend on this service. If not stop or restart the specified OS service, specify "false". The default set is "false". |
-- |
Input |
O |
|
common.serviceStatus |
OS Service Status |
Stores the OS service status if the status was obtained. |
-- |
Output |
O |
|
common.returnValue |
Return value for the plugin |
The return value of this plugin stored. |
-- |
Output |
O |