Help Center/ Bare Metal Server/ API Reference/ BMS APIs/ BMS Status Management/ Changing the BMS OS
Updated on 2024-10-22 GMT+08:00
View PDF
Share

Changing the BMS OS

Function

This API is used to change the BMS OS. Password and key pair injection are supported during OS change.

This is an asynchronous API. Calling the API successfully indicates that the task is delivered successfully. To check whether the task is successful, use the Querying Task Statuses API.

Constraints

  • Only a stopped BMS or a BMS on which changing the OS failed supports changing OS.
  • For BMSs created from private images, ensure that Cloud-Init (for Linux) or Cloudbase-Init (for Windows) has been installed for the image. If an image without Cloud-Init or Cloudbase-Init is used, this API cannot inject a key pair or password. Cloud-Init or Cloudbase-Init has been installed for public images by default.
  • You are not allowed to perform other operations when changing the OS. Otherwise, changing the OS will fail.
  • Windows images do not support password injection. For Linux images, user_data is the encrypted password.

URI

POST /v1/{project_id}/baremetalservers/{server_id}/changeos

Table 1 lists the parameters.
Table 1 Parameter description

Parameter

Mandatory

Description

X-Auth-Token

Yes

Specifies the user token. The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

project_id

Yes

Specifies the project ID.

For details about how to obtain the project ID, see Obtaining a Project ID.

server_id

Yes

Specifies the BMS ID.

You can obtain the BMS ID from the BMS console or by calling the Querying BMSs (Discarded).

Request Parameters

Parameter

Mandatory

Type

Description

os-change

Yes

Object

Specifies the operation to change the BMS OS. For details, see Table 2.
Table 2 os-change field data structure description

Parameter

Mandatory

Type

Description

adminpass

No

String

Specifies the initial login password of the BMS administrator account.

The Linux administrator is root, and the Windows administrator is Administrator.

Recommended password complexity requirements are as follows:

  • The password contains 8 to 26 characters.
  • Contains at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters !@$%^-_=+[{}]:,./?
  • The password cannot contain the username or the username in reverse.
NOTE:
  • For Windows BMSs, the password cannot contain more than two consecutive characters in the username.
  • For Linux BMSs, user_data can be used to inject a password. In this case, adminpass is invalid.
  • Either adminpass or keyname can be set.
  • If both adminpass and keyname are empty, user_data in metadata must be set.

keyname

No

String

Specifies the key pair name.

You can create a key pair using the Creating or Importing an SSH Key Pair (Native OpenStack API) API, or query existing key pairs using the Querying SSH Key Pairs (Native OpenStack API) API.

userid

No

String

Specifies the user ID. You can obtain the user ID from My Credential on the management console.

imageid

Yes

String

Specifies the image ID.

You can obtain the image ID from the IMS console or by following the instructions in Querying Images in Image Management Service API Reference.

When using the API for querying images, you can add field ?virtual_env_type=Ironic to filter BMS images.

metadata

No

Object

Specifies the BMS metadata. For details, see Table 3.
Table 3 metadata field data structure description

Parameter

Mandatory

Type

Description

user_data

No

String

Specifies the Linux image root password injected during the BMS OS change. It is a user-defined initial password.

Note: The password change script must be encoded using Base64.

Recommended password complexity requirements are as follows:

  • Contains 8 to 26 characters.
  • Contains at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters !@$%^-_=+[{}]:,./?

An example is as follows:

  • Use a plaintext password (risky in security), for example, cloud.1234. 
    1
2
    		 
    #!/bin/bash 
echo 'root:Cloud.1234' | chpasswd ;
  • Use a password. 
    1
2
    		 
    #!/bin/bash 
echo 'root:$6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig/GpOkLcOhab9smJoLKYm/Tf9Hcwa6DpiPDhdHfGEAPajFmLZa0YDd910' | chpasswd -e
  • This script must be encoded using Base64.

where, $6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig is the ciphertext password, which can be generated as follows:

  1. Generate an encrypted salt value. 
    1
2
    		 
    [root@test linux]# python -c "import crypt, getpass, pwd;print crypt.mksalt()" 
$6$V6azyeLwcD3CHlpY
  2. Generate a ciphertext password based on the salt value. 
    1
2
    		 
    [root@test linux]# python -c "import crypt, getpass, pwd;print crypt.crypt('Cloud.1234','\$6\$V6azyeLwcD3CHlpY')" 
 $6$V6azyeLwcD3CHlpY$BN3VVq18fmCkj66B4zdHLWevqcxlig/GpOkLcOhab9smJoLKYm/Tf9Hcwa6DpiPDhdHfGEAPajFmLZa0YDd910
  3. After the ciphertext is generated, the password change script must be encoded using Base64.

Example Request

1
 
POST https://{BMS Endpoint}/v1/bbf1946d374b44a0a2a95533562ba954/baremetalservers/cf2a8b97-b5c6-47ef-9714-eb27adf26e5b/changeos

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 
{
    "os-change": {
        "keyname": "$key_name", 
        "imageid": "04dc740a-5820-4ab6-9d01-8cd3a6577296",
        "userid": "7e25b1da389f4697a79df3a0e5bd494e", 
        "metadata": {
              "user_data":  "$USER_DATA"
        }
    }
}

Response Parameters

  • Normal Response
Table 4 Normal response

Parameter

Type

Description

jobId

String

Specifies the task ID returned after a task command is issued. The task ID can be used to query the execution status of the task.

For details about how to query the task execution status based on job_id, see Querying Task Statuses.
  • Abnormal Response
Table 5 Abnormal response

Parameter

Type

Description

error

dict

Specifies the error returned when a task submission encounters an exception. For details, see Table 6.
Table 6 error data structure

Parameter

Type

Description

message

String

Specifies the error message.

code

String

Specifies the error code.

Example Response

  • Normal response
{ 
    "jobId": "9288ec8d769dbc9b01769dc8f261002f"
}

Returned Values

Normal values

Returned Values

Description

200

The request has been successfully processed.

For details about other returned values, see Status Codes.

Error Codes

See Error Codes.

Parent topic: BMS Status Management