POST /manageRequest
Use this method to manage devices. The response header includes a URI that is associated with a job that indicates that a task was started.
Authentication
Authentication with username and password is required.
Request URL
POST https://{management_server_IP}/manageRequest
Query parameters
Parameters | Required / Optional | Description |
---|---|---|
discovery={Boolean} | Optional | Indicates whether to discover endpoints as part of this management request. This can be one of the following values.
|
POST https://192.0.2.0/manageRequest?discovery=true
POST https://192.0.2.0/manageRequest
Request body
Attributes | Required / Optional | Type | Description | ||
---|---|---|---|---|---|
enableHttps | Optional | Boolean | (Rack switches running ENOS only) Indicates whether to enable HTTPS on the switch. This can be one of the following values.
| ||
enablePassword | Optional | String | (Rack switches running ENOS only) Enablepassword that is used to enter Privileged Exec Mode on the switch | ||
forceManage | Optional | Boolean | Indicates whether to force management of the device. This can be one of the following values.
Note Use this force-management option only if you previously attempted to manage the device and management was not successful due to one of the following error conditions.
Attention Devices can be managed by only one | ||
ipAddresses | Required | Array of strings | List of device IP addresses or fully-qualified domain names | ||
newPassword | Optional | String | (Chassis and servers only) New password to be used for managed authentication | ||
password | Required | String | Current password to access the device | ||
recoveryPassword | Optional | String | Recovery password to be used for the device | ||
replaceNtpConfiguration | Optional | Boolean | (Rack switches only) Indicates whether to replace the NTP configuration and time zone on the switch with settings that are defined for XClarity Administrator. This can be one of the following values.
| ||
securityDescriptor | Required | Object | Information about the authentication enablement and support the associated stored credentials for a managed device | ||
identityManagementSystem | Required if identityManagementSystemEnabled is true | String | (Servers only) Information about the identity (in the identity-management system) that is associated with this device, if applicable | ||
address | Required | String | IP address or hostname where the user account is stored as defined in CyberArk. This is typically the IP address of the Lenovo XClarity Controller or external LDAP server (if applicable). | ||
appId | Optional | String | Application ID from CyberArk If you specify the appID, you must also specify safe and folder. | ||
folder | Optional | String | Folder from CyberArk If you specify the appID, you must also specify safe and folder. If the onboarded account is not in a folder, specify an empty string. | ||
name | Optional | String | Type of the identity-management system. This value is always CyberArk | ||
safe | Optional | String | Safe from CyberArk If you specify the appID, you must also specify safe and folder. | ||
username | Required | String | Name of the user account for the device | ||
identityManagementSystemEnabled | Optional | String | Indicates whether to use an identity-management system for authentication. This can be one of the following values.
Note Identity management systems can be used to authenticate only ThinkSystem and ThinkAgile servers. | ||
managedAuthSupported | Required for ThinkServer devices | Boolean | Indicates whether the device supports the ability to choose whether managed authentication is to be used. This can be one of the following values.
| ||
managedAuthEnabled | Required for devices other than ThinkServer | Boolean | Indicates whether the device uses managed authentication. This can be one of the following values.
| ||
publicAccess | Optional | Boolean | |||
roleGroups | Optional | Array of strings | List of role groups that are permitted to view and manage the device. To get a list of available role groups, use GET /roleGroups. You can specify only role groups to which the current user belongs. If you do not specify the roleGroups attribute, the default roles groups are assigned. You can obtain the list of default role group using GET /resourceAccessControl. If you specify the roleGroups attributes= with an empty or null value, role groups are not assigned. Note If you add devices to a managed chassis, the new devices will belong to the same role groups as the chassis. | ||
storedCredentials | Required if managedAuthEnabled is set to true | Object | Information about the stored credential that is associated with this device, if applicable Note RackSwitch devices support only stored credentials for authenticating to the switches. Manual user credentials are not supported. | ||
description | Optional | String | Description of the stored credential | ||
id | Required | String | ID of the stored credential | ||
userName | Optional | String | Name of the stored credential | ||
type | Required | String | Type of device to be managed. This can be one of the following values.
| ||
sshPort | Optional | Integer | (Mellanox switches only) SSH port to use for management If not specified, port 22 is used by default. | ||
username | Required | String | User ID to be used to access the device Note RackSwitch devices support only stored credentials (using the |
[{
"ipAddresses": ["192.0.2.0"],
"forceManage": true,
"password": null,
"securityDescriptor": {
"identityManagementSystem": {
"address" : "192.0.2.0",
"appId": "LXCA",
"name" : "CyberArk",
"safe": "Test",
"username": "USERID"
},
"identityManagementSystemEnabled": true,
"managedAuthEnabled": true,
"managedAuthSupported": true,
"publicAccess": false,
"storedCredentials":null
},
"type": "Rack-Tower Server",
"username": null
}]
[{
"ipAddresses": ["10.243.3.192", "fd55:faaf:e1ab:2021:5ef3:fcff:fe25:e4e7"],
"password": "Passw0rd",
"recoveryPassword": "CME44ibm",
"securityDescriptor": {
"managedAuthEnabled": true
},
"type": "Chassis",
"username": "USERID"
}]
[{
"ipAddresses": ["10.243.3.192","fd55:faaf:e1ab:2021:5ef3:fcff:fe25:e4e7"],
"password": "",
"securityDescriptor": {
"IMSCredentialsId": "1234",
"managedAuthEnabled": true
},
"type": "Server",
"username": ""
}]
[{
"ipAddresses": ["10.243.3.192","fd55:faaf:e1ab:2021:5ef3:fcff:fe25:e4e7"],
"password": "",
"securityDescriptor": {
"managedAuthEnabled": false
"storedCredentials": {
"id": "2853"
}
},
"type": "Chassis",
"username": ""
}]
Attributes | Required / Optional | Type | Description | ||
---|---|---|---|---|---|
displayName | Optional | String | (Rack switches only) Name of the device | ||
enableHttps | Optional | Boolean | (Rack switches running ENOS only) Indicates whether to enable HTTPS on the switch. This can be one of the following values.
| ||
enclosureFormFactor | Optional | String | (IMM, IMM2, XCC, or XCC2 only) Form factor of the device. This can be one of the following values.
| ||
enablePassword | Optional | String | (Rack switches running ENOS only) Enablepassword that is used to enter Privileged Exec Mode on the switch | ||
firmware | Optional | Array of strings | Information about installed firmware | ||
build | Required | String | Build number | ||
date | Required | String | Release date | ||
version | Required | String | Version number | ||
forceManage | Optional | Boolean | Indicates whether to force management of the device. This can be one of the following values.
Note Use this force-management option only if you previously attempted to manage the device and management was not successful due to one of the following error conditions.
Attention Devices can be managed by only one | ||
fruNumber | Optional | String | (Rack switches only) FRU number | ||
hostname | Optional | String | (Rack switches only) hostname of the device | ||
ipAddresses | Required | Array of strings | List of device IP addresses or fully-qualified domain names | ||
ipv4Addresses | Optional | Array of strings | (Rack switches only) List of IPv4 IP addresses | ||
ipv6Addresses | Optional | Array of strings | (Rack switches only) List of IPv6 IP addresses | ||
machineType | Required for ThinkSystem servers; otherwise, optional | String | Machine type | ||
managementPorts | Optional for switches; otherwise, required | Array | List of device management ports | ||
enabled | Required | Boolean | Indicates whether the port enabled. This can be one of the following values.
| ||
port | Required | Integer | Port number | ||
protocol | Required | String | Protocol that is running on the port. See the GET /discoverRequest/jobs/{job_id} response body for the supported protocols for the device's management ports. | ||
managementProcessor | Required for ThinkSystem devices; otherwise, optional | String | (Chassis and servers only) Type of management controller. This can be one of the following values.
| ||
model | Optional | String | (Rack switches only) Model of the device | ||
name | Optional | String | (Rack switches only) Name of the device | ||
newPassword | Optional | String | (Chassis and servers only) New password to be used for managed authentication | ||
os | Required for CNOS and ENOS switches | String | (Rack switches only) Firmware type. This can be one of the following values.
| ||
password | Required | String | Current password to access the device | ||
recoveryPassword | Optional | String | Recovery password to be used for the device | ||
replaceNtpConfiguration | Optional | Boolean | (Rack switches only) Indicates whether to replace the NTP configuration and time zone on the switch with settings that are defined for XClarity Administrator. This can be one of the following values.
| ||
securityDescriptor | Required | Object | Information about the authentication enablement and support the associated stored credentials for a managed device | ||
identityManagementSystem | Required if identityManagementSystemEnabled is true | String | (Servers only) Information about the identity (in the identity-management system) that is associated with this device, if applicable | ||
address | Required | String | IP address where the user account is stored as defined in CyberArk. This is typically the IP address of the Lenovo XClarity Controller or external LDAP server (if applicable). | ||
appId | Optional | String | Application ID from CyberArk If you specify the appID, you must also specify safe and folder. If you do not specify appID, Lenovo XClarity Administrator uses the paths that are already defined to identify the onboarded accounts in CyberArk (see GET /identityManagementSystems/cyberark/paths) | ||
folder | Optional | String | Folder from CyberArk If you specify the appID, you must also specify safe and folder. If the onboarded account is not in a folder, specify an empty string. | ||
name | Optional | String | Type of the identity-management system. This value is always CyberArk. | ||
safe | Optional | String | Safe from CyberArk If you specify the appID, you must also specify safe and folder. | ||
username | Required | String | Name of the user account for the device | ||
uri | Optional | String | Device URI | ||
identityManagementSystemEnabled | Optional | String | Indicates whether to use an identity-management system for authentication. This can be one of the following values.
Note Identity management systems can be used to authenticate only ThinkSystem and ThinkAgile servers. | ||
managedAuthSupported | Required for ThinkServer devices | Boolean | Indicates whether the device supports the ability to choose whether managed authentication is to be used. This can be one of the following values.
| ||
managedAuthEnabled | Required for devices other than ThinkServer | Boolean | Indicates whether the device uses managed authentication. This can be one of the following values.
| ||
publicAccess | Optional | Boolean | Indicates whether the device can be accessed by all role groups. This can be one of the following values.
| ||
roleGroups | Optional | Array of strings | List of role groups that are permitted to view and manage the device. To get a list of available role groups, use GET /roleGroups. You can specify only role groups to which the current user belongs. If you do not specify the roleGroups attribute, the default roles groups are assigned. You can obtain the list of default role group using GET /resourceAccessControl. If you specify the roleGroups attribute with an empty or null value, role groups are not assigned. Note If you add devices to a managed chassis, the new devices will belong to the same role groups as the chassis. | ||
storedCredentials | Required if managedAuthEnabled is set to true | Object | Information about the stored credential that is associated with this device, if applicable Note RackSwitch devices support only stored credentials for authenticating to the switches. Manual user credentials are not supported. | ||
description | Optional | String | Description of the stored credential | ||
id | Required | String | ID of the stored credential | ||
userName | Optional | String | Name of the stored credential | ||
serialNumber | Optional | String | (Rack switches only) Serial number for the device | ||
status | Optional | Object | (Rack switches only) Current status | ||
manageable | Optional | String | Indicates whether the top-of-rack switch is manageable. This can be one of the following values.
| ||
message | Optional | String | Message | ||
name | Optional | Boolean | Name | ||
replaceNtpConfiguration | Optional | Boolean | (Rack switches only) Indicates whether to replace the NTP configuration and time zone on the switch with settings that are defined for XClarity Administrator. This can be one of the following values.
| ||
subType | Required for ThinkSystem DB series and NVIDIA Mellanox switches | String | Device subtype. This can be one of the following values.
| ||
server-type | Optional | String | (Servers only) Type of server to be managed. This can be one of the following values.
| ||
type | Required | String | Type of device to be managed. This can be one of the following values.
| ||
username | Required | String | User ID to be used to access the device Note RackSwitch devices support only stored credentials (using the | ||
uuid | Optional | String | UUID for the device |
[{
"ipAddresses": ["10.243.3.55"],
"managementPorts": [{
"enabled": false,
"port": 80,
"protocol": "http"
}, ..., {
"enabled": true,
"port": 161,
"protocol": "snmpv3"
}],
"password": "xxxxxxxx",
"recoveryPassword": "xxxxxxxx",
"securityDescriptor" : {
"managedAuthEnabled":false,
"storedCredentials": {
"description":"A valid user"
"id":" ED895B48D50D4E34B5DAF1F697CA78B3"
"userName":"user1",
}
}
"type": "Chassis",
"username": "USERID",
"uuid": "48331a223bf34fba90732b379b837b9c"
}]
[{
"displayName": "Cosmo-157",
"enclosureFormFactor": "rack-tower",
"firmware": [{
"build": "CDI352T",
"date": "2020-04-25",
"version": "4.20"
}, {
"build": "TEE155I",
"date": "2020-03-27",
"version": "2.60"
}],
"forceManage": true,
"fruNumber": "00MX680",
"hostname": "XCC-7Y02-0123456789",
"ipAddresses": [
"192.0.2.0",
"fd55:faaf:e1ab:2021:a94:efff:fe4f:5769",
"fe80::a94:efff:fe4f:5769"
],
"machineType": "7Y02",
"managementPorts": [{
"enabled": true,
"port": 5989,
"protocol": "cimxml-https"
}, ..., {
"enabled": true,
"port": 623,
"protocol": "rmcp"
}],
"managementProcessor": "lenovo-xclarity-controller",
"model": "RCZ000",
"name": "Cosmo-157",
"password": null,
"recoveryPassword": "",
"securityDescriptor": {
"identityManagementSystem": {
"address" : "192.0.2.0",
"appId": "LXCA",
"name" : "CyberArk",
"safe": "Test",
"username": "USERID"
},
"identityManagementSystemEnabled": true,
"managedAuthEnabled": true,
"managedAuthSupported": true,
"publicAccess": false,
"storedCredentials":null
},
"serialNumber": "123456789",
"status": {
"manageable": true
"message": "Unmanaged",
"name": "UNMANAGED",,
},
"subType": "",
"server-type": "Rack-Tower Server",
"type": "Rack-Tower Server",
"username": null,
"uuid": "a6df710c8b7d11e78c2786fa5e924c8c"
}]
[{
"enclosureFormFactor": "rack-tower",
"displayName": "Electron-SIT-2",
"firmware": [{
"date": "2018-05-10",
"build": "TEI325I",
"version": "1.80"
}, {
"date": "2018-04-24",
"build": "TEE123G",
"version": "1.40"
}],
"forceManage": true,
"fruNumber": "01GT946",
"hostname": "Electron-SIT-2",
"ipAddresses": ["10.240.211.155","2002:97b:c2bb:830:10:240:211:155",
"fe80::a94:efff:fe41:be01"],
"machineType": "7X19",
"managementPorts": [{
"protocol": "cimxml-https",
"port": 5989,
"enabled": true
}, ..., {
"protocol": "rmcp",
"port": 623,
"enabled": true
}],
"managementProcessor": "lenovo-xclarity-controller",
"model": "25Z000",
"name": "Electron-SIT-2",
"newPassword": null,
"password": null,
"recoveryPassword": "",
"securityDescriptor": {
"managedAuthEnabled": false,
"roleGroups": [LXC-ADMIN,LXC-HW-MANAGER],
"storedCredentials": {
"description": "test_211.155",
"id": "2852",
"userName": "test"
},
"uri": "nodes/fbb43c13103511e785f2e4a2ced78753"
},
"serialNumber": "ELEC0G604G",
"server-type": "Rack-Tower Server",
"status": {
"name": "UNMANAGED",
"message": "Unmanaged",
"manageable": true
},
"subType": "",
"type": "Rack-Tower Server",
"username": null,
"uuid": "fbb43c13103511e785f2e4a2ced78753",
}]
[{
"displayName": "SN#10.240.197.14",
"firmware": [{
"build": "Level 1",
"date": null,
"version": "1.1"
}],
"forceManage": true,
"fruNumber": null,
"hostname": "10.240.197.14",
"ipAddresses": ["10.240.197.14"],
"machineType": "70F0",
"managementPorts": [{
"enabled": true,
"port": 443,
"protocol": "https"
}, {
"enabled": true,
"port": 80,
"protocol": "http"
}],
"model": "",
"name": "SN#10.240.197.14",
"password": "",
"securityDescriptor": {
"managedAuthSupported": false,
"managedAuthEnabled": false,
"storedCredentials": {
"id": "353"
}
},
"serialNumber": " ",
"status": {
"name": "UNMANAGED",
"manageable": true
},
"type": "Lenovo ThinkServer",
"username": "",
"uuid": "fbb43c13103511e785f2e4a2ced78753"
}]
[{
"enableHttps": true,
"enablePassword": "",
"ipAddresses": ["10.243.3.192","fd55:faaf:e1ab:2021:5ef3:fcff:fe25:e4e7"],
"password": "",
"replaceNtpConfiguration": true
"securityDescriptor": {
"managedAuthEnabled": false
"storedCredentials": {
"id": "352"
}
},
"type": " Rackswitch ",
"username": ""
}]
[{
"displayName": "Gryphon",
"enableHttps": true,
"enablePassword": "",
"forceManage": true,
"fruNumber": "XXXXXXX ",
"hostname": "IBM2-40f2e9b8163d",
"ipAddresses": [
"10.243.6.68",
"fd55:faaf:e1ab:2021:42f2:e9ff:feb8:163d",
"fe80::42f2:e9ff:feb8:163d"
],
"ipv4Addresses": ["10.243.6.68"],
"ipv6Addresses": [
"fd55:faaf:e1ab:2021:42f2:e9ff:feb8:163d",
"fe80::42f2:e9ff:feb8:163d"
],
"machineType": "1234",
"model": "IBM",
"name": "Gryphon",
"os": "ENOS",
"password": "DEF",
"securityDescriptor": {
"managedAuthEnabled": false,
"roleGroups": [LXC-ADMIN,LXC-HW-MANAGER],
"storedCredentials": {
"id": "352"
},
"uri": "switches/2376f7c628fb11e1b72b5cf3fc3c1448"
},
"recoveryPassword": null,
"serialNumber": "IBM0152",
"status": {
"message": "Unmanaged",
"name": "UNMANAGED",
"manageable": true
},
"replaceNtpConfiguration": true,
"type": "Rackswitch",
"username": "",
"uuid": "fc3058cadf8b11d48c9b9b1b1b1b1b58"
}]
Response codes
Code | Description | Comments |
---|---|---|
200 | OK | The request completed successfully. |
400 | Bad Request | A query parameter or request attribute is missing or not valid, or the operation is not supported. A descriptive error message is returned in the response body. |
403 | Forbidden | The orchestrator server was prevented from fulfilling the request. A descriptive error message is returned in the response body. Ensure that you have privileges to perform the request. |
404 | Not found | A specified resource cannot be found. A descriptive error message is returned in the response body. |
409 | Conflict | There is a conflict with the current state of the resource. A descriptive error message is returned in the response body. |
500 | Internal Server Error | An internal error occurred. A descriptive error message is returned in the response body. |
Response header
If this POST method results in a job getting started, the response header includes a URI in the form /manageRequest/jobs/{job_id} (for example, /manageRequest/jobs/12) that represents the job that is monitored by the management server. You can use GET /manageRequest/jobs/{bulk_job_id} to determine the status of the job. If a job was not successfully started, refer to the response code and response body for details.
Response body
Attributes | Type | Description | ||
---|---|---|---|---|
jobID | ID of the task (job) that was created to manage the device | |||
statusCode | Return code | |||
statusDescription | Description of the return code | |||
result | String | Results of the request. This can be one of the following values.
| ||
messages | Array of objects | Information about one or more messages | ||
explanation | String | Additional information to clarify the reason for the message | ||
id | String | Message identifier of a returned message | ||
recovery | Array of objects | Recovery information | ||
text | String | User actions that can be taken to recover from the event | ||
URL | String | Link to the help system for more information, if available | ||
text | String | Message text associated with the message identifier |
{
"jobID":"42",
"statusCode":201
"statusDescription":"Bulk job 138 was created successfully.",
"result":"success",
"messages":[],
}