POST /FQDNConfigRequest

Use this method to modify the management server’s fully-qualified domain name (FQDN) and DNS configuration on managed devices with IMM2, XCC, and CMM or validates communication between the management server and managed devices using the set values.

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/{job_list} 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.
Important: You must be a member of a user group to which the predefined Supervisor role is assigned.
Note: This REST API requires Lenovo XClarity Administrator v4.0.0 or later.

Authentication

Authentication with user name and password is required.

Request URL

POST https://{management_server_IP}/FQDNConfigRequest

Query parameters

Parameter Required / Optional Description
validationOnly={Boolean} Optional Indicates whether to validate communication or push FQDN and DNS configuration to managed devices. This can be one of the following values.
  • true. Validates and returns a list of UUIDs for applicable managed devices to modify the management server’s FQDN and DNS configuration.
  • false. (default) Modifies the management server’s FQDN and DNS configuration on managed devices
The following example validates communication with managed devices.
POST https://192.0.2.0/FQDNConfigRequest?validationOnly=true
The following example modifies the management server’s FQDN and DNS configuration on managed devices.
POST https://192.0.2.0/FQDNConfigRequest

Request body

If validationOnly=false, specify the following attributes in the request body. Otherwise, there is no request body.

Attributes Required / Optional Type Description
dns_action Required String Indicates the action to use to modify DNS entries on managed devices. This can be one of the following values.
  • NONE. No action is taken.
  • ADD. Appends entries if different than existing. This is applicable only if fqdnEnabled is set to true.
  • UPDATE. Replace existing with given entries. This is applicable only if fqdnEnabled is set to true.
  • DELETE. Removes DNS entries that matches with the given entries. This is applicable only if fqdnEnabled is set to false.
  • DELETE_ALL. Removes all DNS entries. This is applicable only if fqdnEnabled is set to false.
dns_servers Required Array of objects Information about IP addresses that are used to resolve DNS queries
  ip Required String IP address of the DNS entry
  priority Required Integer Relative priority of the DNS entry into available slots

This is applicable only if fqdnEnabled is set to true.

fqdn Required String Fully qualified domain name of the management server
fqdnEnabled Required Boolean Indicates whether to use the management servers’ FQDN to communicate with managed devices.
  • true
  • False.
uuids Required Array of strings List of UUIDs of managed devices for which FQDN and DNS configuration to be modified
The following example adds the management server’s FQDN and DNS configuration to three specific managed devices.
{
   "dns_action": "ADD",
   "dns_servers": [{
      "ip": "192.0.2.10",
      "priority": 1
   },
   {
      "ip": "192.0.2.11",
      "priority": 2
   }],
   "fqdn": "labs.company.com",
   "fqdnEnabled": true,
   "uuids": [ "20220629175643902E1606DE5E262002", "14DEE51A0682433FB1D5B4A6B5DB282F",
              "20220629175643902E1606DE5E262002" ]
}

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.
401 Unauthorized The user cannot be authenticated. Authentication has not been provided or has failed. 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.

For XClarity Administrator advanced functions, ensure that you have active licenses for each managed server that supports the advanced functions.

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 body

The following attribute is returned if the request is successful and validationOnly=true. Otherwise, no response is returned.

Attributes Type Description
uuids Array of strings List of UUIDs of managed devices for which FQDN and DNS configuration was updated
The following example is returned if the request is successful.
{
   "uuids": [ "20220629175643902E1606DE5E262002", "14DEE51A0682433FB1D5B4A6B5DB282F",
              "20220629175643902E1606DE5E262002" ]
}