Send OS Command

The Send OS Command operation sends a command to the operating system running in a partition.

HTTP method and URI

POST /api/partitions/{partition-id}/operations/send-os-cmd

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

Request body contents

The request body is expected to contain a JSON object with the following fields:

Field name Type Rqd/Opt Description
is-priority Boolean Optional An indication of whether this is a priority operating system command. Set to true for priority operating system commands or false for non-priority operating system commands. The default is false.
operating-system-command-text String (1-200) Required The text of the operating system command.

Description

This operation sends a command to the operating system running in the Partition targeted by the request URI.

The URI path must designate an existing Partition object and the API user must have object-access permission to it. If either of these conditions is not met, status code 404 (Not Found) is returned. In addition to having object-access permission to the Partition, the API user must also have permission to the Operating System Messages task, otherwise status code 403 (Forbidden) is returned. Status code 409 (Conflict) is returned when the message interface for the operating system running in the targeted partition is not available. Some examples are when the Partition is not active, there is no operating system running in the partition, or when the operating system is not enabled for console integration.

On successful execution, the command is sent to the operating system running in the target Partition object and status code 204 (No Content) is returned without supplying a response body.

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the Partition object designated by {partition-id}
  • Action/task permission for the Operating System Messages task.

HTTP status and reason codes

On success, HTTP status code 204 (No Content) is returned and no response body is provided.

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
403 (Forbidden) 1 The user under which the API request was authenticated does not have the required action/task permission to this operation.
404 (Not Found) 1 The object ID in the URI ({partition-id}) does not designated an existing Partition object, or the API user does not have object-access permission to the object.
409 (Conflict) 332 The messages interface is not available.
503 (Service Unavailable) 1 The request could not be processed because the HMC is not currently communicating with an SE needed to perform the requested operation.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Send OS Command: Request
POST /api/partitions/458e44e1-b0c2-391b-83ff-ecfd847295bd/operations/
   send-os-cmd HTTP/1.1
x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4qymqa8ktzjep7dbyrll0k
content-type: application/json
content-length: 69
{
  “is-priority”: false,
  “operating-system-command-text”: “help”
}
Figure 2. Send OS Command: Response
204 No Content
server: zSeries management console API web server / 2.0
cache-control: no-cache
date: Mon, 01 Feb 2016 09:57:18 GMT

<No response body>