此操作用来初始化HBlock,如果服务端返回202响应码,则表示开始执行初始化操作。
说明安装完所有服务器后,需要初始化HBlock。
注意
使用API初始化时,需要使用默认用户名和初始密码进行签名,默认用户名为storuser,初始密码为123456。初始化时必须重新设置密码,后续使用其他接口时使用新设置的密码进行签名。
请确保Linux用户具有所需要端口的权限。Linux系统默认小于1024的端口不对没有root权限的Linux普通用户开放。
设置端口范围(portRange)时,请避免和Linux系统的本地临时端口(ip_local_port_range)范围重合,否则可能会导致HBlock服务所用的端口被占用。使用命令行cat /proc/sys/net/ipv4/ip_local_port_range可以查看本地临时端口范围。
请求语法
单机版
POST /rest/v1/system/setup HTTP/1.1
Date: date
Content-Type: application/json; charset=utf-8
Content-Length: length
Host: ip:port
Authorization: authorization
{
"storName": storName,
"userName": userName,
"newPassword": newPassword,
"iSCSIPort": iSCSIPort,
"portRange": port1-port2,
"faultDomain": "faultDomain",
"ports": {
"dataPort1": dataPort1,
"managementPort1": managementPort1,
"managementPort2": managementPort2,
"managementPort3": managementPort3,
"managementPort4": managementPort4,
"managementPort5": managementPort5,
"managementPort6": managementPort6,
"metadataPort1": metadataPort1,
"metadataPort2": metadataPort2,
"metadataPort3": metadataPort3,
"metadataPort4": metadataPort4,
"metadataPort5": metadataPort5,
"metadataPort6": metadataPort6,
"metadataPort7": metadataPort7,
"metadataPort8": metadataPort8
},
"servers": [
{
"nodeName": servername,
"ip": ip,
"apiPort": apiPort,
"diskPaths": [
{
"path": path,
"capacityQuota": capacityvalue
},
{
"path": path,
"capacityQuota": capacityvalue
},
……
]
},
……
{
"nodeName": servername,
"ip": ip,
"apiPort": apiPort,
"diskPaths": [
{
"path": path,
" path ": capacityvalue
},
{
"path": path,
"capacityQuota": capacityvalue
},
……
]
}
],
"services": {
"mdm": [ip,ip],
"ls": [ip,ip,ip],
"cs": [ip,ip,ip]
},
"clusterNetwork": clusterNetwork,
"publicNetwork": publicNetwork
}
集群版(服务器IP导入)
POST /rest/v1/system/setup HTTP/1.1
Date: date
Content-Type: application/json; charset=utf-8
Content-Length: length
Host: ip:port
Authorization: authorization
{
"storName": storName,
"userName": userName,
"newPassword": newPassword,
"iSCSIPort": iSCSIPort,
"portRange": port1-port2,
"faultDomain": "faultDomain",
"ports": {
"dataPort1": dataPort1,
"managementPort1": managementPort1,
"managementPort2": managementPort2,
"managementPort3": managementPort3,
"managementPort4": managementPort4,
"managementPort5": managementPort5,
"managementPort6": managementPort6,
"metadataPort1": metadataPort1,
"metadataPort2": metadataPort2,
"metadataPort3": metadataPort3,
"metadataPort4": metadataPort4,
"metadataPort5": metadataPort5,
"metadataPort6": metadataPort6,
"metadataPort7": metadataPort7,
"metadataPort8": metadataPort8
},
"servers": [
{
"nodeName": servername,
"ip": ip,
"apiPort": apiPort,
"diskPaths": [
{
"path": path,
"capacityQuota": capacityvalue
},
{
"path": path,
"capacityQuota": capacityvalue
},
……
]
},
……
{
"nodeName": servername,
"ip": ip,
"apiPort": apiPort,
"diskPaths": [
{
"path": path,
" path ": capacityvalue
},
{
"path": path,
"capacityQuota": capacityvalue
},
……
]
}
],
"services": {
"mdm": [ip,ip],
"ls": [ip,ip,ip],
"cs": [ip,ip,ip]
},
"clusterNetwork": clusterNetwork,
"publicNetwork": publicNetwork
}
集群版(导入拓扑文件)
POST /rest/v1/system/setup HTTP/1.1
Date: date
Content-Type: application/json; charset=utf-8
Content-Length: length
Host: ip:port
Authorization: authorization
{
"storName": storName,
"userName": userName,
"newPassword": newPassword,
"iSCSIPort": iSCSIPort,
"portRange": port1-port2,
"faultDomain": "faultDomain",
"ports": {
"dataPort1": dataPort1,
"managementPort1": managementPort1,
"managementPort2": managementPort2,
"managementPort3": managementPort3,
"managementPort4": managementPort4,
"managementPort5": managementPort5,
"managementPort6": managementPort6,
"metadataPort1": metadataPort1,
"metadataPort2": metadataPort2,
"metadataPort3": metadataPort3,
"metadataPort4": metadataPort4,
"metadataPort5": metadataPort5,
"metadataPort6": metadataPort6,
"metadataPort7": metadataPort7,
"metadataPort8": metadataPort8
},
"servers": [
{
"nodeName": servername,
"ip": ip,
"apiPort": apiPort,
"diskPaths": [
{
"path": path,
"capacityQuota": capacityvalue
},
{
"path": path,
"capacityQuota": capacityvalue
},
……
]
},
……
{
"nodeName": servername,
"ip": ip,
"apiPort": apiPort,
"diskPaths": [
{
"path": path,
" path ": capacityvalue
},
{
"path": path,
"capacityQuota": capacityvalue
},
……
]
}
],
"services": {
"mdm": [ip,ip],
"ls": [ip,ip,ip],
"cs": [ip,ip,ip]
},
"clusterNetwork": clusterNetwork,
"publicNetwork": publicNetwork
}
请求参数
参数 描述 是否必须 storName HBlock名称。
类型:字符串
取值:长度范围是1~64,可以包含字母、数字、下划线(_)和短横线(-),字母区分大小写,且仅支持以字母或数字开头。
是 userName HBlock的管理员用户名。
类型:字符串
取值:长度范围是5~16,只能由数字和字母组成,字母区分大小。默认值为storuser。
否 newPassword 设置的新密码。初始化时必须修改密码。
类型:字符串
取值:长度范围8~16,至少包含以下字符中的3种:大写字母、小写字母、数字、特殊字符 (~ ! @ # $ % ^ & * ( ) _ + [ ] { } | ; : , . / < > ?),区分大小写。不能包含:3个连续重复的字符,3个连续或反序的数字、或字母(不区分大小写),3个连续或反序的键盘序列(不区分大小写)。
是 iSCSIPort iSCSI端口。
类型:整型
取值:[1, 65535],默认值为3260。
否 portRange 指定端口范围。存储服务以及未指定端口的服务将从此范围中自动取值。
类型:整型
取值:[1, 65535],port1为端口范围最小值,port2为端口范围最大值,且port1 < port2。port1默认取值为20000,port2默认取值为20500。
说明建议指定的端口范围至少包含500个端口。
否 faultDomain 设置基础存储池的故障域级别(仅集群版支持)。初始化时设置的集群拓扑中,包含的数据目录节点都加入到基础存储池中。
类型:枚举
取值:
room:机房级别。
rack:机架级别。
path:数据目录级别。
server:服务器级别。
默认值为server。
注意如果故障域级别为room或者rack,则必须使用拓扑文件导入方式进行初始化。
否 ports.dataPort1 数据端口1(仅集群版支持)。
类型:整型
取值:[1, 65535]。
否 ports.managementPort1 管理服务端口1。
类型:整型
取值:[1, 65535]。
否 ports.managementPort2 管理服务端口2。
类型:整型
取值:[1, 65535]。
否 ports.managementPort3 管理服务端口3。
类型:整型
取值:[1, 65535]。
否 ports.managementPort4 管理服务端口4。
类型:整型
取值:[1, 65535]。
否 ports.managementPort5 管理服务端口5(仅集群版支持)。
类型:整型
取值:[1, 65535]。
否 ports.managementPort6 管理服务端口6。
类型:整型
取值:[1, 65535]。
否 ports.metadataPort1 元数据端口1(仅集群版支持)。
类型:整型
取值:[1, 65535]。
否 ports.metadataPort2 元数据端口2(仅集群版支持)。
类型:整型
取值:[1, 65535]。
否 ports.metadataPort3 元数据端口3(仅集群版支持)。
类型:整型
取值:[1, 65535]。
否 ports.metadataPort4 元数据端口4(仅集群版支持)。
类型:整型
取值:[1, 65535]。
否 ports.metadataPort5 元数据端口5(仅集群版支持)。
类型:整型
取值:[1, 65535]。
否 ports.metadataPort6 元数据端口6(仅集群版支持)。
类型:整型
取值:[1, 65535]。
否 ports.metadataPort7 元数据端口7(仅集群版支持)。
类型:整型
取值:[1, 65535]。
否 ports.metadataPort8 元数据端口8(仅集群版支持)。
类型:整型
取值:[1, 65535]。
否 topology 导入集群拓扑文件内容(仅集群版支持)。
类型:字符串
取值:拓扑文件需要采用UTF-8编码,且为JSON文件格式,然后转换成字符串格式复制给该参数。拓扑文件的构成详见集群拓扑文件。
注意“topology”与“servers”必须选一种,且只能选一种。如果故障域级别为room或者rack,则必须使用拓扑文件导入方式进行初始化。
否 servers HBlock服务器的属性集合,包含:nodeName(仅集群版支持)、ip、apiPort、diskPaths。
注意“topology”与“servers”必须选一种,且只能选一种。如果故障域级别为room或者rack,则必须使用拓扑文件导入方式进行初始化。
类型:数组
否 nodeName 拓扑节点名称。
类型:字符串
取值:字符串形式,长度范围1~63,只能由字母、数字、句点(.)、下划线(_)和短横线(-)组成,字母区分大小写,且仅支持以字母或数字开头。
否 ip HBlock的服务器IP。
取值:IPv4或[IPv6]地址。
是 apiPort 管理API端口。
类型:整型
取值:[1, 65535],默认值为1443。需要和该服务器安装HBlock时设置的API端口号保持一致。
否 diskPaths 数据目录属性集合。包括path、capacityQuota。
类型:数组
否 path 指定数据目录。数据目录用于存储数据,建议不要与操作系统共用磁盘或文件系统。数据目录中不能有逗号(,)。
说明对于单机版,第一个数据目录为默认数据目录。对于集群版,需要至少有一个数据目录。
注意如果故障域是server和path级别,此项必填。
类型:字符串列表
否 capacityQuota 指定数据目录的容量配额,即针对加入到服务器中的每个数据目录,HBlock可写入的数据总量。当HBlock的使用空间一旦达到配额,就立刻阻止数据写入,不允许再使用超出配额的空间。
类型:长整型
取值:小于数据目录所在磁盘的总容量,单位是字节。负整数表示无限制写入,0表示禁止写入。默认不限制写入。
注意如果相同的数据目录出现多次,以第一次出现的数据目录的容量配额为准。
否 services 服务地址的集合(仅集群版支持)。包括mdm、ls、cs。
类型:数组
否 mdm 元数据管理服务的地址(仅集群版支持)。如果填写,必须填写集群中的2个IP地址。如果不填写,元数据管理服务的地址默认为集群中的前2个IP地址。
取值:IPv4或[IPv6]地址。
否 ls 日志服务的地址(仅集群版支持)。如果填写,必须填写集群中的3个IP地址。日志服务的地址默认为集群中的前3个IP地址。
取值:IPv4或[IPv6]地址。
否 cs 协调服务的地址(仅集群版支持)。如果填写,必须填写集群中的3个IP地址。协调服务的地址默认为集群中的前3个IP地址。
取值:IPv4或[IPv6]地址。
否 clusterNetwork 集群网络(仅集群版支持),用于集群间的数据通信。
如果指定集群网络,为了保证HBlock的各个服务器之间能够正常通信,请确保每个服务器上都有与指定网段相符的IP,系统会自动选取该IP进行通信。
如果未指定集群网络,默认使用服务器列表中HBlock服务器IP,此时HBlock的服务器IP不能指定为localhost、127.0.0.1或0:0:0:0:0:0:0:1。
类型:CIDR格式
取值:如果指定地址范围,IP地址后加掩码表示,如192.163.1.5/24。
否 publicNetwork 业务网络,用于客户端和HBlock之间的数据传输式。
如果指定业务网络,请确保每个服务器上都有与指定网段相符的IP,系统会自动选取该IP和客户端进行通信。
如果未指定业务网络,或指定了业务网络,但指定的网段与服务器所有IP均不相符,默认使用服务器列表中HBlock服务器IP,此时HBlock服务器IP不能指定为localhost、127.0.0.1或0:0:0:0:0:0:0:1。
类型:CIDR格式
取值:如果指定地址范围,IP地址后加掩码表示,如192.163.1.5/24列表。
否
请求示例1
单机版:初始化。
POST /rest/v1/system/setup HTTP/1.1
Date: Mon, 11 Dec 2023 06: 06: 47 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 543
Host: 192.168.0.32: 1443
Authorization: HBlock storuser:signature
{
"storName": "stor1",
"newPassword": "*********",
"portRange": "20000-20500",
"iSCSIPort": 3260,
"servers": [
{
"ip": "192.168.0.32",
"apiPort": 1443,
"diskPaths": [
{
"path": "/mnt/storage01",
"capacityQuota": 96636764160
},
{
"path": "/mnt/dskb",
"capacityQuota": 96636764160
}
]
}
]
}
响应示例1
HTTP/1.1 202 Accepted
x-hblock-request-id: 6589a0abcbde4bc5a4db3a6b9315008f
Connection: keep-alive
Date: Mon, 11 Dec 2023 06:06:47 GMT
Content-Length: 0
Server: HBlockqi
请求示例2
集群版:输入服务器IP,初始化。
POST /rest/v1/system/setup HTTP/1.1
Date: Wed, 24 Jan 2024 06: 59: 48 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1344
Host: 192.168.0.110: 1443
Authorization: HBlock storuser:signature
{
"storName": "stor1",
"userName": "storuser1",
"newPassword": "********",
"iSCSIPort": 3260,
"portRange": "20000-20500",
"faultDomain": "path",
"servers": [
{
"ip": "192.168.0.110",
"apiPort": 1443,
"diskPaths": [
{
"path": "/mnt/storage01",
"capacityQuota": 96636764160
}
]
},
{
"ip": "192.168.0.192",
"apiPort": 1443,
"diskPaths": [
{
"path": "/mnt/stor",
"capacityQuota": 96636764160
}
]
},
{
"ip": "192.168.0.102",
"apiPort": 1443,
"diskPaths": [
{
"path": "/mnt/stor",
"capacityQuota": 96636764160
}
]
}
],
"services": {
"mdm": [
"192.168.0.110",
"192.168.0.192"
],
"ls": [
"192.168.0.110",
"192.168.0.192",
"192.168.0.102"
],
"cs": [
"192.168.0.110",
"192.168.0.192",
"192.168.0.102"
]
}
}
响应示例2
HTTP/1.1 202 Accepted
x-hblock-request-id: 096e457a5c26465590ff8f312a493f2c
Connection: keep-alive
Date: Wed, 24 Jan 2024 06: 59: 48 GMT
Content-Length: 0
Server: HBlock
请求示例3
集群版:导入拓扑文件进行初始化。
POST /rest/v1/system/setup HTTP/1.1
Date: Wed, 3 Jul 2024 09: 47: 16 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 2302
Host: 192.168.0.110: 1443
Authorization: HBlock storuser:signature
{
"storName": "stor1",
"UserName": "storuser",
"newPassword": "hblock12@",
"iSCSIPort": 3260,
"portRange": "20000-20500",
"faultDomain": "room",
"topology": "{\r\n \"name\": \"default\",\r\n \"childNodes\": [\r\n {\r\n \"name\": \"room1\",\r\n \"type\": \"room\",\r\n \"childNodes\": [\r\n {\r\n \"type\": \"server\",\r\n \"name\": \"server1\",\r\n \"ip\": \"192.168.0.192\",\r\n \"apiPort\": 1443,\r\n \"childNodes\": [\r\n {\r\n \"name\": \"/mnt/stor\",\r\n \"type\": \"path\"\r\n },\r\n {\r\n \"name\": \"/mnt/storage01\",\r\n \"type\": \"path\"\r\n }\r\n ]\r\n },\r\n {\r\n \"type\": \"server\",\r\n \"name\": \"server2\",\r\n \"ip\": \"192.168.0.110\",\r\n \"apiPort\": 1443,\r\n \"childNodes\": [\r\n {\r\n \"name\": \"/mnt/stor\",\r\n \"type\": \"path\"\r\n }\r\n ]\r\n },\r\n {\r\n \"type\": \"server\",\r\n \"name\": \"server3\",\r\n \"ip\": \"192.168.0.102\",\r\n \"apiPort\": 1443,\r\n \"childNodes\": [\r\n {\r\n \"name\": \"/mnt/stor\",\r\n \"type\": \"path\"\r\n }\r\n ]\r\n }\r\n ]\r\n }\r\n ]\r\n}",
"services": {
"mdm": [
"192.168.0.110",
"192.168.0.192"
],
"ls": [
"192.168.0.110",
"192.168.0.192",
"192.168.0.102"
],
"cs": [
"192.168.0.110",
"192.168.0.192",
"192.168.0.102"
]
}
}
说明拓扑文件内容为转换为字符串后的符合UTF-8编码格式的JSON文件。拓扑文件的源码如下。
{
"name": "default",
"childNodes": [
{
"name": "room1",
"type": "room",
"childNodes": [
{
"type": "server",
"name": "server1",
"ip": "192.168.0.192",
"apiPort": 1443,
"childNodes": [
{
"name": "/mnt/stor",
"type": "path"
},
{
"name": "/mnt/storage01",
"type": "path"
}
]
},
{
"type": "server",
"name": "server2",
"ip": "192.168.0.110",
"apiPort": 1443,
"childNodes": [
{
"name": "/mnt/stor",
"type": "path"
}
]
},
{
"type": "server",
"name": "server3",
"ip": "192.168.0.102",
"apiPort": 1443,
"childNodes": [
{
"name": "/mnt/stor",
"type": "path"
}
]
}
]
}
]
}
响应示例3
HTTP/1.1 202 Accepted
x-hblock-request-id: 068e0a8e16884bf28104b0e84fdbc50e
Connection: keep-alive
Date: Wed, 3 Jul 2024 09: 47: 16 GMT
Content-Length: 0
Server: HBlock