Send OS Command
The Send OS Command operation sends a command to the operating system running in a logical partition. This operation is supported using the BCPii interface.
HTTP method and URI
POST /api/logical-partitions/{logical-partition-id}/operations/send-os-cmd
In this request, the URI variable {logical-partition-id} is the object ID of the target Logical 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 Logical Partition targeted by the request URI.
The URI path must designate an existing Logical Partition object and the API user must have access permission to it. If either of these conditions is not met, status code 404 (Not Found) is returned. For the web services interface, in addition to having object-access permission to the Logical 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 target logical partition is not available. Some examples are when the Logical 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 Logical Partition object and status code 204 (No Content) is returned without supplying a response body.
Authorization requirements
- For the web services interface:
- Object-access permission to the Logical Partition object designated by {logical-partition-id}
- Action/task permission for the Operating System Messages task.
- For the BCPii interface the source partition must have receive BCPii security controls permissions for the Logical Partition object designated by {logical-partition-id}.
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) | 0 | The request used the BCPii interface and the source partition does not have receive BCPii security controls permission for the Logical Partition object. |
1 | The user under which the API request was authenticated does not have the required authority to perform this operation. | |
404 (Not Found) | 1 | The object ID in the URI ({logical-partition-id}) does not designated an existing Logical 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.