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 with user name and password is required.
POST https://{management_server_IP}/manageRequest
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
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 XClarity Administrator instance at a time. Management by multiple XClarity Administrator instances is not supported. If a device is managed by
one XClarity Administrator, and you want to manage it with another XClarity Administrator, you must first unmanage the device from the original XClarity Administrator, and then manage it with the new XClarity Administrator.
|
||
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.
|
||
username | Required | String | User ID to be used to access the device Note: RackSwitch devices support only stored credentials (using the storedCredentials attribute) for authenticating to the
switches. Manual user credentials using the username and password attributes are not supported and
must be empty or null..
|
[{
"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 XClarity Administrator instance at a time. Management by multiple XClarity Administrator instances is not supported. If a device is managed by
one XClarity Administrator, and you want to manage it with another XClarity Administrator, you must first unmanage the device from the original XClarity Administrator, and then manage it with the new XClarity Administrator.
|
||
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 storedCredentials attribute) for authenticating to the
switches. Manual user credentials using the username and password attributes are not supported and
must be empty or null.
|
||
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"
}]
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. |
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/{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.
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":[],
}