DocsKnowledge BaseAPI Explorer
Documentation›ZCF›ZStack Cloud›Explore more›API ReferenceZCF
Document navigation

Security Group Operations

CreateSecurityGroup

API Request

URLs
POST zstack/v1/security-groups
Headers
Authorization: OAuth the-session-uuid
Body
{
"params": {
"name": "sp",
"description": "test create security group"
  },
"systemTags": [],
"userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.

Curl Sample

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"name":"sp","description":"test create security group"}}' \
http://localhost:8080/zstack/v1/security-groups
Request Parameters
Name Type Location Description Optional Value Starting Version
name String body (contained in the params structure) The resource name. 0.6
description String body (contained in the params structure) Optional. The detailed description of the resource. 0.6
ipVersion Integer body (contained in the params structure) Optional. The IP version.
  • 4
  • 6
 3.1.0
resourceUuid String body (contained in the params structure) Optional. The resource UUID. If specified, the system will not allocate randomly a UUID to the resource. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response
{
"inventory": {
"uuid": "7bb070cdebf44fd8af354f25344d758b",
"name": "web",
"description": "for test",
"state": "Enabled",
"createDate": "Jun 7, 2017 9:21:20 PM",
"lastOpDate": "Jun 7, 2017 9:21:20 PM",
"internalId": 0.0
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory SecurityGroupInventory See inventory. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventory
Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
state String 0.6
ipVersion Integer The IP version. 3.1.0
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
attachedL3NetworkUuids Set 0.6
rules List See rules. 0.6
#rules
Name Type Description Starting Version
uuid String The resource UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
type String The traffic type. 0.6
ipVersion Integer The IP version. 3.1.0
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
protocol String The traffic protocol type. 0.6
state String The rule state, which is not implemented in the current version. 0.6
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 0.6
remoteSecurityGroupUuid String 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
CreateSecurityGroupAction action = new CreateSecurityGroupAction();
action.name = "sp";
action.description = "test create security group";
action.sessionId = "b5032c14210c4668a3a2bcd341d80bbf";
CreateSecurityGroupAction.Result res = action.call();
Python SDK
CreateSecurityGroupAction action = CreateSecurityGroupAction()
action.name = "sp"
action.description = "test create security group"
action.sessionId = "e34f8139af4548d5ade539ca2a5d7983"
CreateSecurityGroupAction.Result res = action.call()

DeleteSecurityGroup

API Request

URLs
DELETE zstack/v1/security-groups/{uuid}?deleteMode={deleteMode}
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 6674ae438b8646d3b4a99a7fe7a48719" \
-X DELETE http://localhost:8080/zstack/v1/security-groups/6791f54e4fb147d1b26030723efe03bd?deleteMode=Permissive
Request Parameters
Name Type Location Description Optional Value Starting Version
uuid String url The resource UUID. 0.6
deleteMode String body Optional. The delete mode. Options: Permissive | Enforcing. Default mode: Permissive.
  • Permissive: If an error occurs, or if the delete operation is refused, ZStack Cloud will stop the delete operation. In this mode, an error code that contains the failure reason will be returned.
  • Enforcing: ZStack Cloud will ignore all errors and permissions to delete directly the resource. In this mode, the delete operation will always succeed.
0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

When the API succeeded, an empty JSON structure {} is returned. When the API failed, the returned JSON structure includes an error field. For example,
{
"error": {
"code": "SYS.1001",
"description": "A message or a operation timeout",
"details": "Create VM on KVM timeout after 300s"
    }
}

SDK Sample

Java SDK
DeleteSecurityGroupAction action = new DeleteSecurityGroupAction();
action.uuid = "86efff16586b4d82bfea66deba85cc50";
action.deleteMode = "Permissive";
action.sessionId = "079653952584401b997df37fd7044433";
DeleteSecurityGroupAction.Result res = action.call();
Python SDK
DeleteSecurityGroupAction action = DeleteSecurityGroupAction()
action.uuid = "59098134c4214c79a48ced0ed7952ecd"
action.deleteMode = "Permissive"
action.sessionId = "2fb58330c68d46f6aa700740d52b02c0"
DeleteSecurityGroupAction.Result res = action.call()

QuerySecurityGroup

API Request

URLs
GET zstack/v1/security-groups
GET zstack/v1/security-groups/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 1f3fcf6a885148b69702e52d22de9606" \
-X GET http://localhost:8080/zstack/v1/security-groups?q=name=web&q=state=Enabled
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth a0c4c995a9e34c639cc72732bcd7bd2f" \
-X GET http://localhost:8080/zstack/v1/security-groups/af0d90237c084afaa16f997847579152

Queryable Fields

You can check all queryable fields and resource names that can be queried across tables by using zstack-cli, entering QuerySecurityGroup, and pressing the Tab key.

API Response

Sample Response
{
"inventories": [
    {
"uuid": "6f757e65fed243babeac0be896e77caf",
"name": "web",
"description": "for test",
"state": "Enabled",
"createDate": "Jun 7, 2017 9:20:34 PM",
"lastOpDate": "Jun 7, 2017 9:20:34 PM",
"internalId": 0.0
    }
  ]
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventories List See inventories. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventories
Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
state String 0.6
ipVersion Integer The IP version. 3.1.0
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
attachedL3NetworkUuids Set 0.6
rules List See rules. 0.6
#rules
Name Type Description Starting Version
uuid String The resource UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
type String The traffic type. 0.6
ipVersion Integer The IP version. 3.1.0
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
protocol String The traffic protocol type. 0.6
state String The rule state, which is not implemented in the current version. 0.6
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 0.6
remoteSecurityGroupUuid String 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
QuerySecurityGroupAction action = new QuerySecurityGroupAction();
action.conditions = asList("name=web","state=Enabled");
action.sessionId = "604cf540e620468fa3fad7098196bb96";
QuerySecurityGroupAction.Result res = action.call();
Python SDK
QuerySecurityGroupAction action = QuerySecurityGroupAction()
action.conditions = ["name=web","state=Enabled"]
action.sessionId = "55a3657d35f14ee4b41401bd7ada15a7"
QuerySecurityGroupAction.Result res = action.call()

UpdateSecurityGroup

API Request

URLs
PUT zstack/v1/security-groups/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
"updateSecurityGroup": {
"name": "new sg",
"description": "for test update"
  },
"systemTags": [],
"userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateSecurityGroup":{"name":"new sg","description":"for test update"}}' \
http://localhost:8080/zstack/v1/security-groups/549bb03c235a3fa8aa18fb79539d4862/actions
Request Parameters
Name Type Location Description Optional Value Starting Version
uuid String url The resource UUID. 0.6
name String body (contained in the updateSecurityGroup structure) Optional. The resource name. 0.6
description String body (contained in the updateSecurityGroup structure) Optional. The detailed description of the resource. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response
{
"inventory": {
"uuid": "def8dff9ec5046e39f57193f488d716a",
"name": "web",
"description": "for test",
"state": "Enabled",
"createDate": "Jun 7, 2017 9:20:15 PM",
"lastOpDate": "Jun 7, 2017 9:20:15 PM",
"internalId": 0.0
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory SecurityGroupInventory See inventory. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventory
Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
state String 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
attachedL3NetworkUuids Set 0.6
rules List See rules. 0.6
#rules
Name Type Description Starting Version
uuid String The resource UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
type String The traffic type. 0.6
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
protocol String The traffic protocol type. 0.6
state String The rule state, which is not implemented in the current version. 0.6
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
UpdateSecurityGroupAction action = new UpdateSecurityGroupAction();
action.uuid = "b60e66856f6c4f7ca16854cfd170fb99";
action.name = "new sg";
action.description = "for test update";
action.sessionId = "8c23751364b746628177641202ff0999";
UpdateSecurityGroupAction.Result res = action.call();
Python SDK
UpdateSecurityGroupAction action = UpdateSecurityGroupAction()
action.uuid = "f6fc05d6ba854530bd8141733d6db4ad"
action.name = "new sg"
action.description = "for test update"
action.sessionId = "f75e99d861ca4660925d72313692d663"
UpdateSecurityGroupAction.Result res = action.call()

ChangeSecurityGroupState

API Request

URLs
PUT zstack/v1/security-groups/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
"changeSecurityGroupState": {
"stateEvent": "disable"
  },
"systemTags": [],
"userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"changeSecurityGroupState":{"stateEvent":"disable"}}' \
http://localhost:8080/zstack/v1/security-groups/85a1d77188d836eab47b34e7129fb5fb/actions
Request Parameters
Name Type Location Description Optional Value Starting Version
uuid String url The resource UUID. 0.6
stateEvent String body (contained in the changeSecurityGroupState structure) The security group state. enabledisable 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response
{
"inventory": {
"uuid": "eebb81d825214555a61567f8811fca15",
"name": "web",
"description": "for test",
"state": "Enabled",
"createDate": "Jun 7, 2017 9:20:16 PM",
"lastOpDate": "Jun 7, 2017 9:20:16 PM",
"internalId": 0.0
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory SecurityGroupInventory See inventory. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventory
Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
state String 0.6
ipVersion Integer The IP version. 3.1.0
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
attachedL3NetworkUuids Set 0.6
rules List See rules. 0.6
#rules
Name Type Description Starting Version
uuid String The resource UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
type String The traffic type. 0.6
ipVersion Integer The IP version. 3.1.0
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
protocol String The traffic protocol type. 0.6
state String The rule state, which is not implemented in the current version. 0.6
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 0.6
remoteSecurityGroupUuid String 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
ChangeSecurityGroupStateAction action = new ChangeSecurityGroupStateAction();
action.uuid = "9389a923cd8c4cacb12e57b979fa1e5f";
action.stateEvent = "disable";
action.sessionId = "772deba87e7847459e5b1f428531bee2";
ChangeSecurityGroupStateAction.Result res = action.call();
Python SDK
ChangeSecurityGroupStateAction action = ChangeSecurityGroupStateAction()
action.uuid = "1ecf0093245b4a6a948d5d09983f0193"
action.stateEvent = "disable"
action.sessionId = "eb76404af2f140f993ae68bb22a80781"
ChangeSecurityGroupStateAction.Result res = action.call()

AttachSecurityGroupToL3Network

API Request

URLs
POST zstack/v1/security-groups/{securityGroupUuid}/l3-networks/{l3NetworkUuid}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {},
  "systemTags": [],
  "userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{}}' http://localhost:8080/zstack/v1/security-groups/0551a95211783295879d083216cb493b/l3-networks/35aa9f6e9a2b3f849d1631ba89d0b27d
Request Parameters
Name Type Location Description Optional Value Starting Version
securityGroupUuid String url The security group UUID. 0.6
l3NetworkUuid String url The L3 network UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response
{
"inventory": {
"uuid": "5870eab620d2487d8d0320eabe185718",
"name": "web",
"description": "for test",
"state": "Enabled",
"createDate": "Jun 7, 2017 9:20:28 PM",
"lastOpDate": "Jun 7, 2017 9:20:28 PM",
"internalId": 0
  }
}
Name Type Description Starting Version
success boolean 4.7.0
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory SecurityGroupInventory See inventory. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventory
Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
state String 0.6
ipVersion Integer The IP version. 3.1.0
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
attachedL3NetworkUuids Set 0.6
rules List See rules. 0.6
#rules
Name Type Description Starting Version
uuid String The resource UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
type String The traffic type. 0.6
ipVersion Integer The IP version. 3.1.0
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
protocol String The traffic protocol type. 0.6
state String The rule state, which is not implemented in the current version. 0.6
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 0.6
remoteSecurityGroupUuid String 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
AttachSecurityGroupToL3NetworkAction action = new AttachSecurityGroupToL3NetworkAction();
action.securityGroupUuid = "eef2d772f4e94997816fdf8512a8233a";
action.l3NetworkUuid = "6761570f790c400596839da61767f890";
action.sessionId = "efb745c9a7204e9a941608059f3c3a10";
AttachSecurityGroupToL3NetworkAction.Result res = action.call();
Python SDK
AttachSecurityGroupToL3NetworkAction action = AttachSecurityGroupToL3NetworkAction()
action.securityGroupUuid = "ae9aebcc28d1490293382c661d123c16"
action.l3NetworkUuid = "cd2fdc4303e34ead806a492d18d4b5fa"
action.sessionId = "9938bf24e1b24c39ab4dc3edc0aeb38d"
AttachSecurityGroupToL3NetworkAction.Result res = action.call()

DetachSecurityGroupFromL3Network

API Request

URLs
DELETE/v1/security-groups/{securityGroupUuid}/l3-networks/{l3NetworkUuid}
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 6edcc17febe04b9fb77059cf096f2cc5" \
-X DELETE http://localhost:8080/zstack/v1/security-groups/08d569c03f8343168f2ae80861db92f3/l3-networks/af8199498a9e4ab1be6d1fea8ec7fbee?
Request Parameters
Name Type Location Description Optional Value Starting Version
securityGroupUuid String url The security group UUID. 0.6
l3NetworkUuid String url The L3 network UUID. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response
{
"inventory": {
"uuid": "6cf7a5c5d89b4094ad912a555319d4d0",
"name": "web",
"description": "for test",
"state": "Enabled",
"createDate": "Jun 7, 2017 9:21:06 PM",
"lastOpDate": "Jun 7, 2017 9:21:06 PM",
"internalId": 0.0
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory SecurityGroupInventory See inventory. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventory
Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
state String 0.6
ipVersion Integer The IP version. 3.1.0
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
attachedL3NetworkUuids Set 0.6
rules List See rules. 0.6
#rules
Name Type Description Starting Version
uuid String The resource UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
type String The traffic type. 0.6
ipVersion Integer The IP version. 3.1.0
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
protocol String The traffic protocol type. 0.6
state String The rule state, which is not implemented in the current version. 0.6
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 0.6
remoteSecurityGroupUuid String 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
DetachSecurityGroupFromL3NetworkAction action = new DetachSecurityGroupFromL3NetworkAction();
action.securityGroupUuid = "823d378084fa445c8d180895db4dd8c1";
action.l3NetworkUuid = "cf6dd2bbd5f940d0976e8c2cd2c063c9";
action.sessionId = "915660a10fc74d509d5ef72caf5892bd";
DetachSecurityGroupFromL3NetworkAction.Result res = action.call();
Python SDK
DetachSecurityGroupFromL3NetworkAction action = DetachSecurityGroupFromL3NetworkAction()
action.securityGroupUuid = "726d6b2f8a674da681f32c66102494df"
action.l3NetworkUuid = "f32da69be7ce4918bb81b8a7ce891177"
action.sessionId = "933ada040fb14b94941997381877bacc"
DetachSecurityGroupFromL3NetworkAction.Result res = action.call()

GetCandidateVmNicForSecurityGroup

API Request

URLs
GET zstack/v1/security-groups/{securityGroupUuid}/vm-instances/candidate-nics
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth aec584233a724de089d05b8090e5a296" \
-X GET http://localhost:8080/zstack/v1/security-groups/584e70f6d3504c7a811df5eeba61839c/vm-instances/candidate-nics
Request Parameters
Name Type Location Description Optional Value Starting Version
securityGroupUuid String url The security group UUID. 0.6
systemTags List query Optional. The system tags. 0.6
userTags List query Optional. The user tags. 0.6

API Response

Sample Response
{
  "inventories": [
    {
      "uuid": "80d2eab0354c329b8257e8f9fcd76d43",
      "vmInstanceUuid": "e8af62992ec5343facac7c5fc164ddd0",
      "l3NetworkUuid": "738cc18ef5003a00937c0e17e6c67a2d",
      "ip": "192.168.0.123",
      "mac": "fa:ef:34:5c:6c:00",
      "hypervisorType": "KVM",
      "netmask": "255.255.255.0",
      "gateway": "192.168.0.1",
      "internalName": "eth0",
      "deviceId": 0.0
    }
  ]
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventories List See inventories. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventories
Name Type Description Starting Version
uuid String The resource UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
l3NetworkUuid String The L3 network UUID. 0.6
ip String 0.6
mac String 0.6
netmask String 0.6
gateway String 0.6
metaData String 0.6
ipVersion Integer The IP version. 3.1.0
deviceId Integer 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
usedIps List See usedIps. 0.6
#usedIps
Name Type Description Starting Version
uuid String The resource UUID. 0.6
ipRangeUuid String The IP range UUID. 0.6
l3NetworkUuid String The L3 network UUID. 0.6
ipVersion Integer The IP version. 3.1.0
ip String The IP address. 0.6
netmask String The netmask. 0.6
gateway String The gateway. 0.6
usedFor String 0.6
ipInLong long 0.6
vmNicUuid String The VM NIC UUID. 3.1.0
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
GetCandidateVmNicForSecurityGroupAction action = new GetCandidateVmNicForSecurityGroupAction();
action.securityGroupUuid = "4060760487504ea3b1ad25bcbabacff5";
action.sessionId = "488b3f4cc8ea4868ab0a7874c4d6358e";
GetCandidateVmNicForSecurityGroupAction.Result res = action.call();
Python SDK
GetCandidateVmNicForSecurityGroupAction action = GetCandidateVmNicForSecurityGroupAction()
action.securityGroupUuid = "c30e353b2fe0408ca3ee09a5495b5fa4"
action.sessionId = "acaa2edf939e47b1a399b413f6b26400"
GetCandidateVmNicForSecurityGroupAction.Result res = action.call()

AddVmNicToSecurityGroup

API Request

URLs
POST zstack/v1/security-groups/{securityGroupUuid}/vm-instances/nics
Headers
Authorization: OAuth the-session-uuid
Body
{
"params": {
"vmNicUuids": [
"8432b2608a8a4f639cc56a8c65ee42ef"
    ]
  },
"systemTags": [],
"userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"vmNicUuids":["c37875cec7133f41adbeb336cdd33ef8"]}}' \
http://localhost:8080/zstack/v1/security-groups/f52566f939f635629a43cd3e27f78dd9/vm-instances/nics
Request Parameters
Name Type Location Description Optional Value Starting Version
securityGroupUuid String url The security group UUID. 0.6
vmNicUuids List body (contained in the params structure) The VM NIC UUID list. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

When the API succeeded, an empty JSON structure {} is returned. When the API failed, the returned JSON structure includes an error field. For example,
{
"error": {
"code": "SYS.1001",
"description": "A message or a operation timeout",
"details": "Create VM on KVM timeout after 300s"
    }
}

SDK Sample

Java SDK
AddVmNicToSecurityGroupAction action = new AddVmNicToSecurityGroupAction();
action.securityGroupUuid = "b651075ffcac475c91d3edaa5e9ade75";
action.vmNicUuids = asList("ff0f6c13311b46ddb186a95c0d18350a");
action.sessionId = "605fca0559284eff95d78e418508ff2f";
AddVmNicToSecurityGroupAction.Result res = action.call();
Python SDK
AddVmNicToSecurityGroupAction action = AddVmNicToSecurityGroupAction()
action.securityGroupUuid = "2da1519b9b39451e8742aadaa9241952"
action.vmNicUuids = [bda4ceec2917426cb9ee20b3bcb20653]
action.sessionId = "863d503abfbc4334846d67c1eac375f9"
AddVmNicToSecurityGroupAction.Result res = action.call()

DeleteVmNicFromSecurityGroup

API Request

URLs
DELETE /v1/security-groups/{securityGroupUuid}/vm-instances/nics?vmNicUuids={vmNicUuids}
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/security-groups/2c78da48235c3015aa9f9c99e81060b2/vm-instances/nics?vmNicUuids=9aef4c831b1540e7832332972138d78c&vmNicUuids=c40dd02ddf654031aec25346626db553
Request Parameters
Name Type Location Description Optional Value Starting Version
securityGroupUuid String url The security group UUID. 0.6
vmNicUuids List body The VM NIC UUID list. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

When the API succeeded, an empty JSON structure {} is returned. When the API failed, the returned JSON structure includes an error field. For example,
{
    "error": {
        "code": "SYS.1001",
        "description": "A message or a operation timeout",
        "details": "Create VM on KVM timeout after 300s"
    }
}

SDK Sample

Java SDK
DeleteVmNicFromSecurityGroupAction action = new DeleteVmNicFromSecurityGroupAction();
action.securityGroupUuid = "2c78da48235c3015aa9f9c99e81060b2";
action.vmNicUuids = asList("f8e9c3a73e7c399ca148057f8b2897c3","ae09cd7292913bfe84e467286aaa7a9f");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteVmNicFromSecurityGroupAction.Result res = action.call();
Python SDK
DeleteVmNicFromSecurityGroupAction action = DeleteVmNicFromSecurityGroupAction()
action.securityGroupUuid = "2c78da48235c3015aa9f9c99e81060b2"
action.vmNicUuids = [f8e9c3a73e7c399ca148057f8b2897c3, ae09cd7292913bfe84e467286aaa7a9f]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
DeleteVmNicFromSecurityGroupAction.Result res = action.call()

QueryVmNicInSecurityGroup

API Request

URLs
GET zstack/v1/security-groups/vm-instances/nics
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 3f2df305cc614ecb9d0b93480cf84b33" \
-X GET http://localhost:8080/zstack/v1/security-groups/vm-instances/nics

Queryable Fields

You can check all queryable fields and resource names that can be queried across tables by using zstack-cli, entering QueryVmNicInSecurityGroup, and pressing the Tab key.

API Response

Sample Response
{
"inventories": [
    {
"uuid": "9bac6b3729ae4915bc9f4cee67753774",
"vmNicUuid": "7d0784059df64a11aef748e18b0d5fa7",
"securityGroupUuid": "d3ace95b1236482896f5d1921638ada5",
"vmInstanceUuid": "ace37e89d86c4994942f858a67172a0d",
"createDate": "Jun 7, 2017 9:20:32 PM",
"lastOpDate": "Jun 7, 2017 9:20:32 PM"
    }
  ]
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventories List See inventories. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventories
Name Type Description Starting Version
vmNicUuid String The VM NIC UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
QueryVmNicInSecurityGroupAction action = new QueryVmNicInSecurityGroupAction();
action.conditions = asList();
action.sessionId = "fc82274e695143118923150b6008bef2";
QueryVmNicInSecurityGroupAction.Result res = action.call();
Python SDK
QueryVmNicInSecurityGroupAction action = QueryVmNicInSecurityGroupAction()
action.conditions = []
action.sessionId = "32b2bfd366774b67a51ebdeb374df1cc"
QueryVmNicInSecurityGroupAction.Result res = action.call()

AddSecurityGroupRule

API Request

URLs
POST zstack/v1/security-groups/{securityGroupUuid}/rules
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "rules": [
      {
        "type": "Ingress",
         "state": "Enabled",
        "description": "test",
        "remoteSecurityGroupUuid": "7d4337c2b18339ffb6f5d1023fc2ea42",
        "ipVersion": 4,
        "protocol": "TCP",
          "srcIpRange": "10.0.0.1,10.0.0.2-10.0.0.200,10.1.1.0/24",
        "dstIpRange": "10.0.0.1,10.0.0.2-10.0.0.200,10.1.1.0/24",
        "dstPortRange": "1000,1001,1002-1005,1008",
        "action": "ACCEPT"
      }
    ],
    "priority": -1
  },
  "systemTags": [],
  "userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c"
-X POST -d '{"params":{"rules":[{"type":"Ingress","state":"Enabled","description":"test","remoteSecurityGroupUuid":"7d4337c2b18339ffb6f5d1023fc2ea42","ipVersion":4,"protocol":"TCP","srcIpRange":"10.0.0.1,10.0.0.2-10.0.0.200,10.1.1.0/24","dstIpRange":"10.0.0.1,10.0.0.2-10.0.0.200,10.1.1.0/24","dstPortRange":"1000,1001,1002-1005,1008","action":"ACCEPT"}],"priority":-1}}'
http://localhost:8080/zstack/v1/security-groups/00fdf47ec62b316a8f17c80d0ee59a01/rules
Request Parameters
Name Type Location Description Optional Value Starting Version
securityGroupUuid String url The security group UUID. 0.6
rules List body (contained in the params structure) The rules in the security group. 0.6
remoteSecurityGroupUuids List body (contained in the params structure) Optional. The security group that the rule takes effect. 2.1
priority Integer body (contained in the params structure) Optional. The priority of security group rule. 4.7.21
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response
{
  "inventory": {
    "uuid": "5949aece9cd64d5a939d6dc5e2c1f327",
    "name": "web",
    "description": "for test",
    "state": "Enabled",
    "createDate": "Sep 22, 2017 12:24:11 PM",
    "lastOpDate": "Sep 22, 2017 12:24:11 PM",
    "internalId": 0
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory SecurityGroupInventory See inventory. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventory
Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
state String 0.6
ipVersion Integer The IP version. 3.1.0
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
attachedL3NetworkUuids Set 0.6
rules List See rules. 0.6
#rules
Name Type Description Starting Version
uuid String The resource UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
type String The traffic type. 0.6
ipVersion Integer The IP version. 3.1.0
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
protocol String The traffic protocol type. 0.6
state String The rule state, which is not implemented in the current version. 0.6
priority Integer The priority of security group rule. 4.7.21
description String The description of the security group rule. 4.7.21
srcIpRange String The range of source IP. 4.7.21
dstIpRange String The range of target IP. 4.7.21
srcPortRange String The range of source port, which is not implemented in the current version. 4.7.21
dstPortRange String The range of target port. 4.7.21
action String The default action of the security group rule. 4.7.21
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 0.6
remoteSecurityGroupUuid String 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
AddSecurityGroupRuleAction action = new AddSecurityGroupRuleAction();
action.securityGroupUuid = "11a632fb43434d9582a736f538af41a0";
action.rules = asList([type:Ingress, startPort:22.0, endPort:22.0, protocol:TCP, allowedCidr:0.0.0.0/0]);
action.remoteSecurityGroupUuids = asList("22ee23f9b3924d13a11eabbe8786f0dc");
action.sessionId = "96d2a0445f4241bd823141c281fb4b3e";
AddSecurityGroupRuleAction.Result res = action.call();
Python SDK
AddSecurityGroupRuleAction action = AddSecurityGroupRuleAction()
action.securityGroupUuid = "38aa7db9d299456f8c2410a1148bb18c"
action.rules = [[type:Ingress, startPort:22.0, endPort:22.0, protocol:TCP, allowedCidr:0.0.0.0/0]]
action.remoteSecurityGroupUuids = [b4e32c0abbfb428798b48ea2cbe8103d]
action.sessionId = "3435114ce8294deea437496ccf78a1d8"
AddSecurityGroupRuleAction.Result res = action.call()

DeleteSecurityGroupRule

API Request

URLs
DELETE zstack/v1/security-groups/rules?ruleUuids={ruleUuids}
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 56ec3e843f8e48d1b3cf9e848885dc81" \
-X DELETE http://localhost:8080/zstack/v1/security-groups/rules?ruleUuids=1f0becde585e39d280acbd6c5b21bd39
Request Parameters
Name Type Location Description Optional Value Starting Version
ruleUuids List body The UUID list of the security group rule. 0.6
systemTags List body Optional. The system tags. 0.6
userTags List body Optional. The user tags. 0.6

API Response

Sample Response
{
"inventory": {
"uuid": "06abc64deb0b4c8c9dc8831743e34662",
"name": "web",
"description": "for test",
"state": "Enabled",
"createDate": "Jun 7, 2017 9:20:23 PM",
"lastOpDate": "Jun 7, 2017 9:20:23 PM",
"internalId": 0.0
  }
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory SecurityGroupInventory See inventory. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventory
Name Type Description Starting Version
uuid String The resource UUID. 0.6
name String The resource name. 0.6
description String The detailed description of the resource. 0.6
state String 0.6
ipVersion Integer The IP version. 3.1.0
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6
attachedL3NetworkUuids Set 0.6
rules List See rules. 0.6
#rules
Name Type Description Starting Version
uuid String The resource UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
type String The traffic type. 0.6
ipVersion Integer The IP version. 3.1.0
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
protocol String The traffic protocol type. 0.6
state String The rule state, which is not implemented in the current version. 0.6
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 0.6
remoteSecurityGroupUuid String 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
DeleteSecurityGroupRuleAction action = new DeleteSecurityGroupRuleAction();
action.ruleUuids = asList("5a88c1873bbf48e4a018f03f6bd055b6");
action.sessionId = "f42c32dbfc214bc58fb057d2c9cb63b1";
DeleteSecurityGroupRuleAction.Result res = action.call();
Python SDK
DeleteSecurityGroupRuleAction action = DeleteSecurityGroupRuleAction()
action.ruleUuids = [a9b41667676244e5b3da07d866869b31]
action.sessionId = "f8b0b8d01d8c4adc8058083e9f48a8a9"
DeleteSecurityGroupRuleAction.Result res = action.call()

QuerySecurityGroupRule

API Request

URLs
GET zstack/v1/security-groups/rules
GET zstack/v1/security-groups/rules/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 9aa7adfe564e4acda956ef90430b0f1b" \
-X GET http://localhost:8080/zstack/v1/security-groups/rules?q=endPort=22&q=state=Enabled
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth 36a86c5b46784b169fe82d7c990ae1a7" \
-X GET http://localhost:8080/zstack/v1/security-groups/rules/ae59353d95f744b5b4396e1783ddb918

Queryable Fields

You can check all queryable fields and resource names that can be queried across tables by using zstack-cli, entering QuerySecurityGroupRule, and pressing the Tab key.

API Response

Sample Response
{
"inventories": [
    {
"uuid": "b3a99fc1548b41778258153cfd70f4b7",
"securityGroupUuid": "629d55f78c9f4b0e8e3504b9834ca1bb",
"type": "Ingress",
"startPort": 22.0,
"endPort": 22.0,
"protocol": "TCP",
"state": "Enabled",
"allowedCidr": "0.0.0.0/0",
"createDate": "Jun 7, 2017 9:20:25 PM",
"lastOpDate": "Jun 7, 2017 9:20:25 PM"
    }
  ]
}
Name Type Description Starting Version
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventories List See inventories. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventories
Name Type Description Starting Version
uuid String The resource UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
type String The traffic type. 0.6
ipVersion Integer The IP version. 3.1.0
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 0.6
protocol String The traffic protocol type. 0.6
state String The rule state, which is not implemented in the current version. 0.6
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 0.6
remoteSecurityGroupUuid String 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
QuerySecurityGroupRuleAction action = new QuerySecurityGroupRuleAction();
action.conditions = asList("endPort=22","state=Enabled");
action.sessionId = "362452e4e8a746ce981a5a54c7390445";
QuerySecurityGroupRuleAction.Result res = action.call();
Python SDK
QuerySecurityGroupRuleAction action = QuerySecurityGroupRuleAction()
action.conditions = ["endPort=22","state=Enabled"]
action.sessionId = "37e099aa344c40ca947d11dff7ec2b91"
QuerySecurityGroupRuleAction.Result res = action.call()

ValidateSecurityGroupRule

API Request

URLs
GET zstack/v1/security-groups/{securityGroupUuid}/rules/validation
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c"
-X GET http://localhost:8080/zstack/v1/security-groups/0351d8b796bd3165967f13d1da2f9576/rules/validation?type=Ingress&protocol=TCP&remoteSecurityGroupUuid=f938bc96baae3dc4b18be6bdbf34e783&ipVersion=4&srcIpRange=10.0.0.1,10.0.0.2-10.0.0.200,10.1.1.0/24&dstIpRange=10.0.0.1,10.0.0.2-10.0.0.200,10.1.1.0/24&dstPortRange=1000,1001,1002-1005,1008&action=ACCEPT
Request Parameters
Name Type Location Description Optional Value Starting Version
securityGroupUuid String url The security group UUID. 4.7.21
type String query The type of the security group rule.
  • Ingress
  • Egress
 4.7.21
protocol String query The protocol of the security group rule.
  • TCP
  • UDP
  • ICMP
  • ALL
 4.7.21
remoteSecurityGroupUuid String query Optional. The remote security group UUID. 4.7.21
ipVersion Integer query Optional. The IP version of the security group rule.
  • 4
  • 6
 4.7.21
srcIpRange String query Optional. The range of the source IP of the security group rule. 4.7.21
dstIpRange String query Optional. The range of the target IP of the security group rule. 4.7.21
dstPortRange String query Optional. The range of the target port of the security group rule. 4.7.21
action String query Optional. The default action of the security group rule.
  • ACCEPT
  • DROP
 4.7.21
startPort Integer query Optional. The startport of the security group rule. 4.7.21
endPort Integer query Optional. The endport of the security group rule. 4.7.21
allowedCidr String query Optional. The range of IP version of the security group rule. 4.7.21
systemTags List body Optional. The system tags. 4.7.21
userTags List body Optional. The user tags. 4.7.21

API Response

Response Sample
{
  "available": true,
  "code": "SG.2000"
}
Name Type Description Starting Version
available boolean Whether the rule is valid. 4.7.21
code String The error code of the rule. 4.7.21
reason String reason 4.7.21
success boolean 4.7.21
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 4.7.21
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 4.7.21
description String The brief description of the error. 4.7.21
details String The details about the error. 4.7.21
elaboration String The reserved field. Default value: null. 4.7.21
opaque LinkedHashMap The reserved field. Default value: null. 4.7.21
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 4.7.21

SDK Sample

Java SDK
ValidateSecurityGroupRuleAction action = new ValidateSecurityGroupRuleAction();
action.securityGroupUuid = "0351d8b796bd3165967f13d1da2f9576";
action.type = "Ingress";
action.protocol = "TCP";
action.remoteSecurityGroupUuid = "f938bc96baae3dc4b18be6bdbf34e783";
action.ipVersion = 4;
action.srcIpRange = "10.0.0.1,10.0.0.2-10.0.0.200,10.1.1.0/24";
action.dstIpRange = "10.0.0.1,10.0.0.2-10.0.0.200,10.1.1.0/24";
action.dstPortRange = "1000,1001,1002-1005,1008";
action.action = "ACCEPT";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
ValidateSecurityGroupRuleAction.Result res = action.call();
Python SDK
ValidateSecurityGroupRuleAction action = ValidateSecurityGroupRuleAction()
action.securityGroupUuid = "0351d8b796bd3165967f13d1da2f9576"
action.type = "Ingress"
action.protocol = "TCP"
action.remoteSecurityGroupUuid = "f938bc96baae3dc4b18be6bdbf34e783"
action.ipVersion = 4
action.srcIpRange = "10.0.0.1,10.0.0.2-10.0.0.200,10.1.1.0/24"
action.dstIpRange = "10.0.0.1,10.0.0.2-10.0.0.200,10.1.1.0/24"
action.dstPortRange = "1000,1001,1002-1005,1008"
action.action = "ACCEPT"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
ValidateSecurityGroupRuleAction.Result res = action.call()

ChangeSecurityGroupRule

API Request

URLs
PUT zstack/v1/security-groups/rules/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "changeSecurityGroupRule": {
    "description": "test",
    "remoteSecurityGroupUuid": "bd2dcc93fbd73999bf920aeaab3c9e4e",
    "action": "DROP",
    "state": "Enabled",
    "priority": 1,
    "protocol": "TCP",
    "srcIpRange": "1.1.1.1,2.2.2.0/24,3.3.3.1-3.3.3.10",
    "dstPortRange": "1001,2000-2023,6001"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c"
-X PUT -d '{"changeSecurityGroupRule":{"description":"test","remoteSecurityGroupUuid":"bd2dcc93fbd73999bf920aeaab3c9e4e","action":"DROP","state":"Enabled","priority":1,"protocol":"TCP","srcIpRange":"1.1.1.1,2.2.2.0/24,3.3.3.1-3.3.3.10","dstPortRange":"1001,2000-2023,6001"}}'
http://localhost:8080/zstack/v1/security-groups/85a1d77188d836eab47b34e7129fb5fb/actions
Request Parameters
Name Type Location Description Optional Value Starting Version
uuid String url The security group UUID. 4.7.21
description String body (contained in the params structure) Optional. The detailed description of the rule. 4.7.21
remoteSecurityGroupUuid String body (contained in the params structure) Optional. The remote security group UUID. enabledisable 4.7.21
action String body (contained in the params structure) Optional. The default action of the rule.
  • DROP
  • ACCEPT
 4.7.21
state String body (contained in the params structure) Optional. The rule status.
  • Enabled
  • Disabled
 4.7.21
priority Integer body (contained in the params structure) Optional. The rule priority. 4.7.21
protocol String body (contained in the params structure) Optional. The protocol type.
  • ALL
  • TCP
  • UDP
  • ICMP
 4.7.21
srcIpRange String body (contained in the params structure) Optional. The range of the source IP of the rule. 4.7.21
dstIpRange String body (contained in the params structure) Optional. The range of the target IP of the rule. 4.7.21
dstPortRange String body (contained in the params structure) Optional. The range of the target port of the rule. 4.7.21
systemTags List body Optional. The system tags. 4.7.21
userTags List body Optional. The user tags. 4.7.21

API Response

Response Sample
{
  "inventory": {
    "uuid": "68e4f4b48b51369c8c2ada5cb6c2c3c3",
    "securityGroupUuid": "c80ad90499213d3b9989afdbfe498390",
    "type": "ingress",
    "protocol": "tcp",
    "state": "enable",
    "srcIpRange": "10.10.10.1-10.10.10.10",
    "dstPortRange": "2001-2023",
    "action": "RETURN",
    "createDate": "Sep 15, 2023 9:57:59 AM",
    "lastOpDate": "Sep 15, 2023 9:57:59 AM"
  }
}
Name Type Description Starting Version
success boolean 4.7.21
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 4.7.21
inventory SecurityGroupInventory See inventory. 4.7.21
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 4.7.21
description String The brief description of the error. 4.7.21
details String The details about the error. 4.7.21
elaboration String The reserved field. Default value: null. 4.7.21
opaque LinkedHashMap The reserved field. Default value: null. 4.7.21
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 4.7.21
#inventory
Name Type Description Starting Version
uuid String The resource UUID. 4.7.21
securityGroupUuid String The security group UUID. 4.7.21
type String The traffic type. 4.7.21
ipVersion Integer The IP version. 3.1.0
protocol String The traffic protocol type. 4.7.21
state String The rule state. 4.7.21
priority Integer The rule priority. 4.7.21
description String The description of the rule. 4.7.21
srcIpRange String The range of the source IP of the rule. 4.7.21
dstIpRange String The range of the target IP of the rule. 4.7.21
srcPortRange String The range of the source port of the rule, which is not implemented in the current version. 4.7.21
dstPortRange String The range of the target port of the rule. 4.7.21
action String The default action of the rule. 4.7.21
remoteSecurityGroupUuid String 4.7.21
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 4.7.21
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 4.7.21
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 4.7.21
createDate Timestamp The creation date. 4.7.21
lastOpDate Timestamp The last operation date. 4.7.21

SDK Sample

Java SDK
ChangeSecurityGroupRuleAction action = new ChangeSecurityGroupRuleAction();
action.uuid = "33869c6c323d30599da314fe1e46b01c";
action.description = "test";
action.remoteSecurityGroupUuid = "bd2dcc93fbd73999bf920aeaab3c9e4e";
action.action = "DROP";
action.state = "Enabled";
action.priority = 1;
action.protocol = "TCP";
action.srcIpRange = "1.1.1.1,2.2.2.0/24,3.3.3.1-3.3.3.10";
action.dstPortRange = "1001,2000-2023,6001";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
ChangeSecurityGroupRuleAction.Result res = action.call();
Python SDK
ChangeSecurityGroupRuleAction action = ChangeSecurityGroupRuleAction()
action.uuid = "33869c6c323d30599da314fe1e46b01c"
action.description = "test"
action.remoteSecurityGroupUuid = "bd2dcc93fbd73999bf920aeaab3c9e4e"
action.action = "DROP"
action.state = "Enabled"
action.priority = 1
action.protocol = "TCP"
action.srcIpRange = "1.1.1.1,2.2.2.0/24,3.3.3.1-3.3.3.10"
action.dstPortRange = "1001,2000-2023,6001"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
ChangeSecurityGroupRuleAction.Result res = action.call()

ChangeSecurityGroupRuleState

API Request

URLs
PUT zstack/v1/security-groups/{securityGroupUuid}/rules/state/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "changeSecurityGroupRuleState": {
    "ruleUuids": [
      "c895848e49763a85a74d0a8cee5a0720"
    ],
    "state": "Enabled"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c"
-X PUT -d '{"changeSecurityGroupRuleState":{"ruleUuids":["c895848e49763a85a74d0a8cee5a0720"],"state":"Enabled"}}'
http://localhost:8080/zstack/v1/security-groups/fbd126afdf6b32caab55327d2901170f/rules/state/actions
Request Parameters
Name Type Location Description Optional Value Starting Version
securityGroupUuid String url The security group UUID. 4.7.21
ruleUuids List body (contained in the changeSecurityGroupRuleState structure) The group UUID list. 4.7.21
state String body (contained in the changeSecurityGroupRuleState structure) The rule state.
  • Enabled
  • Disabled
 4.7.21
systemTags List body Optional. The system tags. 4.7.21
userTags List body Optional. The user tags. 4.7.21

API Response

Response Sample
{
  "inventory": {
    "uuid": "7c95c623cc983a548dcf3c9a257f23ae",
    "name": "web",
    "description": "for test",
    "state": "Enabled",
    "createDate": "Sep 15, 2023 9:58:00 AM",
    "lastOpDate": "Sep 15, 2023 9:58:00 AM",
    "internalId": 0
  }
}
Name Type Description Starting Version
success boolean 4.7.21
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 4.7.21
inventory SecurityGroupInventory See inventory. 4.7.21
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 4.7.21
description String The brief description of the error. 4.7.21
details String The details about the error. 4.7.21
elaboration String The reserved field. Default value: null. 4.7.21
opaque LinkedHashMap The reserved field. Default value: null. 4.7.21
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 4.7.21
#inventory
Name Type Description Starting Version
uuid String The resource UUID. 4.7.21
name String The resource name. 4.7.21
description String The detailed description of the resource. 4.7.21
state String 4.7.21
ipVersion Integer The IP version. 4.7.21
createDate Timestamp The creation date. 4.7.21
lastOpDate Timestamp The last operation date. 4.7.21
attachedL3NetworkUuids Set 4.7.21
rules List See rules. 4.7.21
#rules
Name Type Description Starting Version
uuid String The resource UUID. 4.7.21
securityGroupUuid String The security group UUID. 4.7.21
type String The traffic type. 4.7.21
ipVersion Integer The IP version. 4.7.21
protocol String The traffic protocol type. 4.7.21
state String The rule state. 4.7.21
priority Integer The rule priority. 4.7.21
description String The description of the rule. 4.7.21
srcIpRange String The range of the source IP of the rule. 4.7.21
dstIpRange String The range of the target IP of the rule. 4.7.21
srcPortRange String The range of the source port of the rule, which is not implemented in the current version. 4.7.21
dstPortRange String The range of the target port of the rule. 4.7.21
action String The default action of the rule. 4.7.21
remoteSecurityGroupUuid String 4.7.21
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 4.7.21
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 4.7.21
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 4.7.21
createDate Timestamp The creation date. 4.7.21
lastOpDate Timestamp The last operation date. 4.7.21

SDK Sample

Java SDK
ChangeSecurityGroupRuleStateAction action = new ChangeSecurityGroupRuleStateAction();
action.securityGroupUuid = "fbd126afdf6b32caab55327d2901170f";
action.ruleUuids = asList("c895848e49763a85a74d0a8cee5a0720");
action.state = "Enabled";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
ChangeSecurityGroupRuleStateAction.Result res = action.call();
Python SDK
ChangeSecurityGroupRuleStateAction action = ChangeSecurityGroupRuleStateAction()
action.securityGroupUuid = "fbd126afdf6b32caab55327d2901170f"
action.ruleUuids = [c895848e49763a85a74d0a8cee5a0720]
action.state = "Enabled"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
ChangeSecurityGroupRuleStateAction.Result res = action.call()

UpdateSecurityGroupRulePriority

API Request

URLs
PUT zstack/v1/security-groups/{securityGroupUuid}/rules/priority/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateSecurityGroupRulePriority": {
    "type": "Ingress",
    "rules": [
      {
        "ruleUuid": "7a73154d5d2331308f462c6bf2f725cb",
        "priority": 1
      }
    ]
  },
  "systemTags": [],
  "userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c"
-X PUT -d '{"updateSecurityGroupRulePriority":{"type":"Ingress","rules":[{"ruleUuid":"7a73154d5d2331308f462c6bf2f725cb","priority":1}]}}'
http://localhost:8080/zstack/v1/security-groups/ea321fd5d0f7388e8efd4427c9fae15f/rules/priority/actions
Request Parameters
Name Type Location Description Optional Value Starting Version
securityGroupUuid String url The security group UUID. 4.7.21
type String body (contained in the updateSecurityGroupRulePriority structure) The rule type.
  • Ingress
  • Egress
 4.7.21
rules List body (contained in the updateSecurityGroupRulePriority structure) The rule priority. 4.7.21
systemTags List body Optional. The system tags. 4.7.21
userTags List body Optional. The user tags. 4.7.21

API Response

Response Sample
{
  "inventory": {
    "uuid": "777dbc5ec0cb3b14828096daa9e04133",
    "name": "test",
    "internalId": 0
  }
}
Name Type Description Starting Version
success boolean 4.7.21
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 4.7.21
inventory SecurityGroupInventory See inventory. 4.7.21
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 4.7.21
description String The brief description of the error. 4.7.21
details String The details about the error. 4.7.21
elaboration String The reserved field. Default value: null. 4.7.21
opaque LinkedHashMap The reserved field. Default value: null. 4.7.21
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 4.7.21
#inventory
Name Type Description Starting Version
uuid String The resource UUID. 4.7.21
name String The resource name. 4.7.21
description String The detailed description of the resource. 4.7.21
state String 4.7.21
ipVersion Integer The IP version. 4.7.21
createDate Timestamp The creation date. 4.7.21
lastOpDate Timestamp The last operation date. 4.7.21
attachedL3NetworkUuids Set 4.7.21
rules List See rules. 4.7.21
#rules
Name Type Description Starting Version
uuid String The resource UUID. 4.7.21
securityGroupUuid String The security group UUID. 4.7.21
type String The traffic type. 4.7.21
ipVersion Integer The IP version. 4.7.21
protocol String The traffic protocol type. 4.7.21
state String The rule state. 4.7.21
priority Integer The rule priority. 4.7.21
description String The description of the rule. 4.7.21
srcIpRange String The range of the source IP of the rule. 4.7.21
dstIpRange String The range of the target IP of the rule. 4.7.21
srcPortRange String The range of the source port of the rule, which is not implemented in the current version. 4.7.21
dstPortRange String The range of the target port of the rule. 4.7.21
action String The default action of the rule. 4.7.21
remoteSecurityGroupUuid String 4.7.21
allowedCidr String
  • The allowed CIDR, which has different meanings according to different traffic types.
  • If the traffic type is Ingress, the allowed CIDR is a source CIDR that is allowed to access VM NICs.
  • If the traffic type is Egress, the allowed CIDR is a destination CIDR that is allowed to leave from VM NICs.
 4.7.21
startPort Integer
  • If the protocol is TCP or UDP, this parameter is the start port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 4.7.21
endPort Integer
  • If the protocol is TCP or UDP, this parameter is the end port of the port range.
  • If the protocol is ICMP, this parameter is the ICMP type.
 4.7.21
createDate Timestamp The creation date. 4.7.21
lastOpDate Timestamp The last operation date. 4.7.21

SDK Sample

Java SDK
UpdateSecurityGroupRulePriorityAction action = new UpdateSecurityGroupRulePriorityAction();
action.securityGroupUuid = "ea321fd5d0f7388e8efd4427c9fae15f";
action.type = "Ingress";
action.rules = asList([ruleUuid:7a73154d5d2331308f462c6bf2f725cb, priority:1]);
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateSecurityGroupRulePriorityAction.Result res = action.call();
Python SDK
UpdateSecurityGroupRulePriorityAction action = UpdateSecurityGroupRulePriorityAction()
action.securityGroupUuid = "ea321fd5d0f7388e8efd4427c9fae15f"
action.type = "Ingress"
action.rules = [[ruleUuid:7a73154d5d2331308f462c6bf2f725cb, priority:1]]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UpdateSecurityGroupRulePriorityAction.Result res = action.call()

QueryVmNicSecurityPolicy

API Request

URLs
GET zstack/v1/security-groups/nics/security-policy
GET zstack/security-groups/nics/{uuid}/security-policy
Headers
Authorization: OAuth the-session-uuid
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c"
-X GET http://localhost:8080/zstack/v1/security-groups/nics/security-policy?q=ingressPolicy=DROP&q=egressPolicy=DROP
curl -H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c"
-X GET http://localhost:8080/zstack/v1/security-groups/nics/a4ef9b72cb66352f9040ce0f8c180b80/security-policy

Queryable Fields

You can check all queryable fields and resource names that can be queried across tables by using zstack-cli, entering QueryVmNicSecurityPolicy, and pressing the Tab key.

API Response

Response Sample
{
  "inventories": [
    {
      "vmNicUuid": "40d02946a770317aa1edac79ef350f3f",
      "ingressPolicy": "DROP",
      "egressPolicy": "ACCEPT",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}
Name Type Description Starting Version
success boolean 4.7.21
inventories List See inventory. 4.7.21
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 4.7.21
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 4.7.21
description String The brief description of the error. 4.7.21
details String The details about the error. 4.7.21
elaboration String The reserved field. Default value: null. 4.7.21
opaque LinkedHashMap The reserved field. Default value: null. 4.7.21
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 4.7.21
#inventory
Name Type Description Starting Version
vmNicUuid String The VM NIC UUID. 4.7.21
ingressPolicy String The ingress policy of the NIC. 4.7.21
egressPolicy String The egress policy of the NIC. 4.7.21
createDate Timestamp The creation date. 4.7.21
lastOpDate Timestamp The last operation date. 4.7.21

SDK Sample

Java SDK
QueryVmNicSecurityPolicyAction action = new QueryVmNicSecurityPolicyAction();
action.conditions = asList("ingressPolicy=DROP","egressPolicy=DROP");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryVmNicSecurityPolicyAction.Result res = action.call();
Python SDK
QueryVmNicSecurityPolicyAction action = QueryVmNicSecurityPolicyAction()
action.conditions = ["ingressPolicy=DROP","egressPolicy=DROP"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryVmNicSecurityPolicyAction.Result res = action.call()

ChangeVmNicSecurityPolicy

API Request

URLs
PUT zstack/v1/security-groups/nics/{vmNicUuid}/security-policy/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "changeVmNicSecurityPolicy": {
    "ingressPolicy": "ALLOW",
    "egressPolicy": "DENY"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c"
-X PUT -d '{"changeVmNicSecurityPolicy":{"ingressPolicy":"ALLOW","egressPolicy":"DENY"}}'
http://localhost:8080/zstack/v1/security-groups/nics/5551303bee7037c8848cdb5741be7ff7/security-policy/actions
Request Parameters
Name Type Location Description Optional Value Starting Version
vmNicUuid String url The VM NIC UUID. 4.7.21
ingressPolicy String body (contained in the changeVmNicSecurityPolicy structure) Optional. The ingress policy of the NIC.
  • DENY
  • ALLOW
 4.7.21
egressPolicy String body (contained in the changeVmNicSecurityPolicy structure) Optional. The egress policy of the NIC.
  • DENY
  • ALLOW
 4.7.21
systemTags List body Optional. The system tags. 4.7.21
userTags List body Optional. The user tags. 4.7.21

API Response

Response Sample
{
  "inventory": {
    "uuid": "2c8164f7e3213f1491640a2f98d0a979",
    "vmNicUuid": "c731cb960eb635a997e58d154d3c4252",
    "ingressPolicy": "DENY",
    "egressPolicy": "ALLOW",
    "createDate": "Nov 14, 2017 10:20:57 PM",
    "lastOpDate": "Nov 14, 2017 10:20:57 PM"
  }
}
Name Type Description Starting Version
success boolean 4.7.21
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 4.7.21
inventory SecurityGroupInventory See inventory. 4.7.21
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 4.7.21
description String The brief description of the error. 4.7.21
details String The details about the error. 4.7.21
elaboration String The reserved field. Default value: null. 4.7.21
opaque LinkedHashMap The reserved field. Default value: null. 4.7.21
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 4.7.21
#inventory
Name Type Description Starting Version
vmNicUuid String The VM NIC UUID. 4.7.21
ingressPolicy String The ingress policy of the NIC. 4.7.21
egressPolicy String The egress policy of the NIC. 4.7.21
createDate Timestamp The creation date. 4.7.21
lastOpDate Timestamp The last operation date. 4.7.21

SDK Sample

Java SDK
ChangeVmNicSecurityPolicyAction action = new ChangeVmNicSecurityPolicyAction();
action.vmNicUuid = "5551303bee7037c8848cdb5741be7ff7";
action.ingressPolicy = "ALLOW";
action.egressPolicy = "DENY";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
ChangeVmNicSecurityPolicyAction.Result res = action.call();
Python SDK
ChangeVmNicSecurityPolicyAction action = ChangeVmNicSecurityPolicyAction()
action.vmNicUuid = "5551303bee7037c8848cdb5741be7ff7"
action.ingressPolicy = "ALLOW"
action.egressPolicy = "DENY"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
ChangeVmNicSecurityPolicyAction.Result res = action.call()

SetVmNicSecurityGroup

API Request

URLs
PUT zstack/v1/security-groups/nics/{vmNicUuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "setVmNicSecurityGroup": {
    "refs": [
      {
        "securityGroupUuid": "a63c3b35a6553b4a912ee60cd06d5066",
        "priority": 1
      }
    ]
  },
  "systemTags": [],
  "userTags": []
}
Note: In the preceding sample, both systemTags and userTags are optional. These two fields can be included in the body structure.
Curl Sample
curl -H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c"
-X PUT -d '{"setVmNicSecurityGroup":{"refs":[{"securityGroupUuid":"a63c3b35a6553b4a912ee60cd06d5066","priority":1}]}}'
http://localhost:8080/zstack/v1/security-groups/nics/6b7ad223ebb2328bb646f2e77b34957b/actions
Request Parameters
Name Type Location Description Optional Value Starting Version
vmNicUuid String url The VM NIC UUID. 4.7.21
refs List body (contained in the setVmNicSecurityGroup structure) The security group attached to the NIC. 4.7.21
systemTags List body Optional. The system tags. 4.7.21
userTags List body Optional. The user tags. 4.7.21

API Response

Response Sample
{
  "inventory": [
    {
      "uuid": "33aa195b943c3faa87e2c75a787cb7f5",
      "priority": 1,
      "securityGroupUuid": "63ec5dcb248138968f0153160b5b8b3a"
    }
  ]
}
Name Type Description Starting Version
success boolean 4.7.21
error ErrorCode The error code. If not null, the operation fails, or vice versa. For more information, see error. 0.6
inventory SecurityGroupInventory See inventory. 0.6
#error
Name Type Description Starting Version
code String The error code, which is a numbered or alphanumeric code that specifies an error. For example, SYS.1000, HOST.1001. 0.6
description String The brief description of the error. 0.6
details String The details about the error. 0.6
elaboration String The reserved field. Default value: null. 0.6
opaque LinkedHashMap The reserved field. Default value: null. 0.6
cause ErrorCode The root error, which is the associated root cause of the current error. If no root error exists, this parameter is null. 0.6
#inventory
Name Type Description Starting Version
priority Integer The priority of the security group. 4.7.21
vmNicUuid String The VM NIC UUID. 0.6
securityGroupUuid String The security group UUID. 0.6
vmInstanceUuid String The VM instance UUID. 0.6
createDate Timestamp The creation date. 0.6
lastOpDate Timestamp The last operation date. 0.6

SDK Sample

Java SDK
SetVmNicSecurityGroupAction action = new SetVmNicSecurityGroupAction();
action.vmNicUuid = "6b7ad223ebb2328bb646f2e77b34957b";
action.refs = asList([securityGroupUuid:a63c3b35a6553b4a912ee60cd06d5066, priority:1]);
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
SetVmNicSecurityGroupAction.Result res = action.call();
Python SDK
SetVmNicSecurityGroupAction action = SetVmNicSecurityGroupAction()
action.vmNicUuid = "6b7ad223ebb2328bb646f2e77b34957b"
action.refs = [[securityGroupUuid:a63c3b35a6553b4a912ee60cd06d5066, priority:1]]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
SetVmNicSecurityGroupAction.Result res = action.call()
PreviousVPC Firewall OperationsNextVIP Operations
API Reference | 5.4.12 | ZStack Cloud · ZCF | ZStack Resource Center