PUT /nodes/<UUID>

Use the PUT method to modify node properties or perform management actions on a specific the server or Flex System storage node.

The request body differs depending on the action that you want to perform. You can use this PUT method to perform the following management actions.

If the PUT method results in a job getting started, this method returns a URI that contains the job ID for the job that is created to perform this request. You can use GET /tasks/detail to monitor the status and progress of the job.

Authentication

Authentication with user name and password is required.

Request URL

PUT https://<management_server_IP>/nodes/<UUID>

where <UUID> is the UUID of the node to be retrieved. To obtain the node UUID, use the GET /nodes method.

Query parameters

Parameters Required / Optional Description
synchronous=<Boolean> Optional When modifying attributes, indicates when the job ID is returned
  • true. (default) Returns the job ID and job status after the job is complete.

  • false. Returns the job ID immediately. You can use GET /tasks/detail to monitor the status and progress of the job.

If the powerState=bootToF1 request attribute is specified, indicates when the job ID is returned.

  • true. (default) Returns the job ID and job status after the job is complete.
  • false. Returns the job ID immediately.
Note: This query parameter applies only when a node-properties attribute or powerState=bootToF1 attribute is specified in the request body.
The following example sets synchronous to true.
PUT https://192.0.2.0/nodes/6ED2CB368C594C66C2BB066D5A306138?synchronous=true

Request body

You can specify attributes from one of the following tables in each request.

Note: If you specify one or more request attributes in Table 1 (to modify properties), Table 2 (to modify the power state), or Table 4 (to refresh the inventory), this method starts a job that runs in the background to perform the operation. The response header includes a URI in the form /tasks/{task_id} (for example, /tasks/12) that represents the job that is created to perform this request. You can use GET /tasks/detail to monitor the status and progress of the job. If a job was not successfully started, refer to the response code and response body for details.
Attention: A successful response indicates that the request was successfully transmitted and accepted by the management server. It does not indicate that the operation that is associated with the job was successful.
Table 1. Modify node properties.
Attributes Required / Optional Type Description
cmmDisplayName Optional String Chassis name
contact Optional String The chassis contact information
hostname Optional String Hostname
ipInterfaces Optional Array Information about the CMM IP addresses
  name Required String IP Interface name
  IPv4enabled Optional Boolean Identifies whether IPv4 is enabled. This can be one of the following values.
  • true. IPv4 is enabled
  • false. IPv4 is disabled
  IPv6enabled Optional Boolean Identifies whether IPv6 is enabled. This can be one of the following values.
  • true. IPv6 is enabled
  • false. IPv6 is disabled
  IPv4DHCPmode Optional String IPv4 address assignment method. This can be one of the following values.
  • STATIC_ONLY
  • DHCP_ONLY
  • DHCP_THEN_STATIC
  • UNKNOWN
  IPv6DHCPenabled Optional Boolean Identifies whether IPv6 DHCP is enabled. This can be one of the following values.
  • true. IPv6 DHCP is enabled
  • false. IPv6 DHCP is disabled
  IPv6statelessEnabled Optional Boolean Identifies whether IPv6 stateless is enabled. This can be one of the following values.
  • true. IPv6 stateless is enabled
  • false. IPv6 stateless is disabled
  IPv6staticEnabled Optional Boolean Identifies whether IPv6 static is enabled. This can be one of the following values.
  • true. IPv6 static is enabled
  • false. IPv6 static is disabled
  IPv4assignments Optional Array Information about IPv4 assignments
    id Required Integer IPv4 assignment ID
    subnet Optional String IPv4 subnet mask
    gateway Optional String IPv4 gateway
    address Optional String IPv4 address
  IPv6assignments Optional Array Information about IPv6 assignments
    id Required Integer IPv6 assignment ID
    prefix Optional Integer IPv6 prefix
    gateway Optional String IPv6 gateway
    address Optional String IPv6 address
location Optional String (Flex System compute nodes only) Location in the chassis
Important: Changes made to the location of the server or storage device using this API method are not reflected in the rack view.
location Optional Object (Rack and tower servers only) Information about the location in the rack
Important: Changes made to the location of the server using this API method are not reflected in the rack view.
  location Optional String Location of the server
  rack Optional String Rack
  room Optional String Room
  lowestRackUnit Optional Integer LRU
name Optional String Server name
userDescription Optional String The server description
The following example modifies the hostname, location, and contact information for the target server.
{
   "contact": "new contact",
   "hostname":"", 
   "location": { 
      "location":"new location"
   }
}
Table 2. Modifying the power state
Attributes Required / Optional Type Description
powerState Optional String Performs a power operation on the device. This can be one of the following values:
  • powerOn. Powers on the server.
  • powerOff. Powers off the server immediately.
  • powerCycleHard. .
  • powerCycleSoft. Restarts the server immediately.
  • powerCycleSoftGrace. Restarts the server gracefully (shuts down the operating system where applicable).
  • virtualReseat. Calls the CMM function to simulate removing power from the bay.
  • powerNMI. Restarts the server with non-maskable interrupt (performs a diagnostic interrupt).
  • bootToF1. (Lenovo devices only) Restarts the server to BIOS/UEFI (F1) Setup. This is supported for non-ThinkServer servers that are supported without limitations
  • PXEHard. (Lenovo Flex System, System x, and ThinkSystem servers only) Restarts the server immediately, and boots the server to the Preboot Execution Environment (PXE) network.
    Note: PXE-boot related UEFI settings must be configured on the server.
If you specify this attribute, this method starts a job that runs in the background to perform the operation. The response header includes a URI in the form /tasks/<task_id> (for example, /tasks/12) that represents the job that is created to perform this request. You can use GET /tasks/detail to monitor the status and progress of the job. If a job was not successfully started, refer to the response code and response body for details.
Attention: A successful response indicates that the request was successfully transmitted and accepted by the management server. It does not indicate that the operation that is associated with the job was successful.
The following example restarts the target server:
{
   "powerState": "powerCycleSoft"
}
Table 3. Configure device authentication and access control.
Note: Only users with lxc-supervisor or lxc-security-admin authority can modify the access-control settings.
Attributes Required / Optional Type Description
securityDescriptor Required Object Information about the authentication enablement and support the associated stored credentials for a managed device
  managedAuthEnabled Optional Boolean Indicates whether the device uses managed authentication. This can be one of the following values.
  • true. The device uses managed authentication.

  • false. The device uses local authentication

  publicAccess Optional Boolean Indicates whether the resource can be accessed by all role groups. This can be one of the following values.
  • true. The resource is can be access by all role group.

  • false. The resource is restricted to specific role groups.

  roleGroups Optional Array of strings List of role groups that are permitted to view and manage this device
  storedCredentials Required if managedAuthEnabled is set to true Object Information about the stored credential that is associated with this device, if applicable.
    id Required if managedAuthEnabled is set to true String ID of the stored credential to associated with the device
The following example enables managed authentication and associates a stored credential account with the device.
{
   "securityDescriptor" : {
      "managedAuthEnabled" : true,
      "storedCredential": {
         "id":"249721...",
      }
   }
}
The following example disables managed authentication to use local authentication instead.
{
   "securityDescriptor": {
      "managedAuthEnabled" : false,
   }
}
The following example restricts access to the managed device to members of the specified role groups:
{
   "securityDescriptor": {
      "publicAccess": false,
      "roleGroups": ["sales-os-admin","corp_fw_admin"]
   }
}
Table 4. Refresh the inventory
Attributes Required / Optional Type Description
refreshInventory Optional String Refreshes inventory for the device.
If you specify this attribute, this method starts a job that runs in the background to perform the operation. The response header includes a URI in the form /tasks/<task_id> (for example, /tasks/12) that represents the job that is created to perform this request. You can use GET /tasks/detail to monitor the status and progress of the job. If a job was not successfully started, refer to the response code and response body for details.
Attention: A successful response indicates that the request was successfully transmitted and accepted by the management server. It does not indicate that the operation that is associated with the job was successful.
The following example refreshes inventory for the target server.
{
   "refreshInventory": "true" 
}
Table 5. Configure the boot order.
Attributes Required / Optional Type Description
bootOrder Optional Array Boot order settings
  bootOrderList Required Array  
    currentBootOrderDevices Required Array of strings List of potential boot devices
Tip: To obtain the boot-order device values, use in GET /nodes method.
    bootType Optional String Boot type of the boot order setting. This can be one of the following values.
  • BootOrder

  • CDDVDROMBootOrder

  • HardDiskBootOrder

  • NetworkBootOrder

  • Permanent

  • SingleUse

  • USBBootOrder

  • WakeOnLan

The following example changes the boot order.
{
   "bootOrder": {
      "bootOrderList": [{
         "currentBootOrderDevices": [
            "HardDrive 0",
            "CDROM 0",
            "Hard Drive 1"
         ],
         "bootType": "BootOrder"
      }]
   }
}
Table 6. Configure the TLS protocol and NIST compliance.
Attributes Required / Optional Type Description
nist Optional Object Information about NIST
  currentValue Required String Cryptography mode that is set. This can be one of the following values.
  • Unknown
  • Compatibility
  • Nist_800_131A_Strict
  • Nist_800_131A_Custom
tlsVersion Optional Object Information about the SSL or TLS protocol
  currentValue Required String SSL or TLS protocol and version that is set. This can be one of the following values.
  • Unknown
  • SSL_30
  • TLS_10. IMM - TLS1.0
  • TLS_11. IMM - TLS1.1
  • TLS_12. IMM - TLS1.2
  • TLS_12_Server_Client
  • TLS_12_Server
The following example changes the cryptography settings:
{
    "nist": {
      "currentValue": "Compatibility"
    }
}
Table 7. Configure the encapsulation mode
Attributes Required / Optional Type Description
encapsulationMode Optional String Encapsulation mode. This can be one of the following values.
  • normal. Encapsulation is disabled for this node.

    The global encapsulation setting is disabled by default. When disabled, the device encapsulation mode is set to "normal" and the firewall rules are not changed as part of the management process.

  • encapsulationLite. Encapsulation is enabled for this node.

    When the global encapsulation setting is enabled and the device supports encapsulation, XClarity Administrator communicates with the device during the management process to change the device encapsulation mode to "encapsulationLite" and to change the firewall rules on the device to limit incoming requests to those only from XClarity Administrator.

The following example updates the encapsulation mode:
{
   "encapsulationMode": "encapsulationLite
}
Table 8. Configure LED states.
Attributes Required / Optional Type Description
leds Optional Object State of the location LED.
  name Required String Description of the LED (for example, "Fault" or "Power". To obtain the names of LEDs for a specific server, use the GET /nodes/<UUID_list> method.
  state Required String State of LED. This can be one of the following values.
  • off
  • on
  • blinking

To obtain the current state of the LED, use the GET /nodes/<UUID_list> method.

Note: Location LED on ThinkServer servers can be on or off. Blinking is not supported.
The following example turns on the Information LED.
{
   "leds":[{
      "name":"Information",
      "state":"on"
   }]
}

Response codes

Code Description
200 OK
400 Bad request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
500 Internal server error

Response body

The response body provides information about the success or failure of the request. The attributes in the response body differ depending on the specified request attributes.

Note: A response body is not returned for some requests.

Response example

The following example is returned when the "refreshInventory": "true" is specified in the request body to refresh the device inventory.

{
   "statusCode": 200,
   "statusDescription": "The request completed successfully.",
   "messages": [{
      "explanation": "refreshInventory request for target 6ED2CB368C594C66C2BB066D5A306138 has
                      completed successfully.",
      "id": "FQXDM0200",
      "recovery": "",
      "recoveryUrl": "",
      "text": "The request completed successfully."
   }]
}