Security Group¶
Table of contents
- Security Group
- Overview
- Security Group Inventory
- Security Group Rule Inventory
- Security Group And L3 Network
- Operations
- Global Configurations
- Tags
Overview¶
A security group acts as a virtual firewall that controls networking traffics of VMs. Depending on the isolation method a L2 network takes, users can use security group as firewalls or as a layer 3 isolation method. For example, if multiple tenants share a L3 network, every tenant can create a security group to protect their VMs from being accessed by other tenants. Tenants can also use security group along with EIP to control ports open to the public.
A security group consists of a set of rules that control ports’ accessibility. A security group can be attached to one or more L3 networks; VM nics on attached L3 networks can join those security groups. A VM nic can join multiple security groups, rules applied to the nic will be merged.
The implementation of security group is hypervisor specific; not all hypervisors will support security group. In this ZStack version, security group is supported in KVM hypervisor by using IPTables.
Note
A large number of security group rules may hurt network performance because the hypervisor needs to check all rules against every network packet. ZStack will try to condense security group rules as much as possible; for example, if you specify two rules for two consecutive ports, they will be merged into one IPTable(for KVM) rule using a port range match.
To use security group, a L3 network must enable security group service using AttachNetworkServiceToL3Network, for example:
AttachNetworkServiceToL3Network l3NetworkUuid=50e637dc68b7480291ba87cbb81d94ad networkServices='{"1d1d5ff248b24906a39f96aa3c6411dd": ["SecurityGroup"]}'
For VMs having multiple nics, all nics can join security groups.
The security group is essentially a distributed firewall; every rule change or nic join/leave event may lead firewall rules to be refreshed on multiple hosts. Given this fact, some security group APIs are implemented in an asynchronous manner, which may return before rules take effect on hosts. If there are more than one rules for a specific port, the most permissive rule takes effect. For example, if a rule1 allows traffic from 12.12.12.12 to access port 22 but a rule2 allows everyone to access port 22, the rule2 takes precedence.
Security Group Inventory¶
Properties¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | see Resource Properties | 0.6 | ||
name | see Resource Properties | 0.6 | ||
description | see Resource Properties | true | 0.6 | |
state | security group state; not implemented in this ZStack version |
|
0.6 | |
rules | a list of security group rule inventory | 0.6 | ||
attachedL3NetworkUuids | a list of uuid of L3 networks that this security group has been attached | 0.6 | ||
createDate | see Resource Properties | 0.6 | ||
lastOpDate | see Resource Properties | 0.6 |
For an empty security group, there are default polices for ingress traffics and egress traffics; for ingress traffics, the default policy is to deny, which means all inbound traffics to the nics in this empty security group are blocked; for egress traffics, the default policy is to allow, which means all outbound traffics from the nics in this empty security group are allowed. To change default policies, admin can change global configuration ingress.defaultPolicy and egress.defaultPolicy.
Example¶
{
"attachedL3NetworkUuids": [
"0b48770e593e400c8f54e71fd4e7f514"
],
"createDate": "Nov 16, 2015 1:02:22 AM",
"lastOpDate": "Nov 16, 2015 1:02:22 AM",
"name": "sg-in",
"rules": [
{
"allowedCidr": "0.0.0.0/0",
"createDate": "April 29, 2015 9:57:10 PM",
"state": "Enabled",
"endPort": 22,
"lastOpDate": "Nov 29, 2015 9:57:10 PM",
"protocol": "TCP",
"securityGroupUuid": "9e0a72fe64814900baa22f78a1b9d235",
"startPort": 22,
"type": "Ingress",
"uuid": "a338d11be18d4e288223597682964dc8"
}
],
"state": "Enabled",
"uuid": "9e0a72fe64814900baa22f78a1b9d235"
}
Security Group Rule Inventory¶
Properties¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | see Resource Properties | 0.6 | ||
securityGroupUuid | uuid of parent security group | 0.6 | ||
type | see traffic type |
|
0.6 | |
protocol | traffic protocol type |
|
0.6 | |
startPort | when protocol is TCP/UDP, it’s the start of port range; when protocol is ICMP, it’s ICMP type |
|
0.6 | |
endPort | when protocol is TCP/UDP, it’s the end of port range; when protocol is ICMP, it’s ICMP code |
|
0.6 | |
allowedCidr | see allowedCidr | 0.6 | ||
state | rule state, not implemented in this version |
|
0.6 | |
createDate | see Resource Properties | 0.6 | ||
lastOpDate | see Resource Properties | 0.6 |
Traffic Type¶
There are two types of traffics:
Ingress
Inbound traffics that access a VM nic
Egress
Outbound traffics that leave from a VM nic
Allowed CIDR¶
Depending on traffic types, allowed CIDR has different meanings; its format is:
ipv4_address/network_prefix
for example: 12.12.12.12/24
if the traffic type is Ingress, allowed CIDR is a source CIDR that’s allowed to reach VM nics; for example, a rule:
startPort: 22
endPort: 22
protocol: TCP
type: Ingress
allowedCidr: 12.12.12.12/32
means only TCP traffic from IP(12.12.12.12) is allowed to access port 22.
if the traffic type is Egress, allowed CIDR is a destination CIDR that’s allowed to leave VM nics; for example, a rule:
startPort: 22
endPort: 22
protocol: TCP
type: Egress
allowedCidr: 12.12.12.12/32
means only TCP traffic to port 22 of IP 12.12.12.12 is allowed to leave.
The special CIDR 0.0.0.0/0 means all IP addresses.
Note
Allowed CIDR only controls IPs outside a security group. Rules are automatically applied to IPs of VM nics that are on the same L3 network and in the same security group. For example, if two nics: nic1(10.10.1.5) and nic2(10.10.1.6) are in the same security group which has a rule:
startPort: 22
endPort: 22
protocol: TCP
type: Ingress
allowedCidr: 12.12.12.12/32
nic1 and nic2 can reach port 22 of each other in spite of allowedCidr is set to 12.12.12.12/32.
Example¶
{
"allowedCidr": "0.0.0.0/0",
"state": "Enabled",
"startPort": 22,
"endPort": 22,
"protocol": "TCP",
"type": "Ingress",
"createDate": "Nov 29, 2015 9:57:10 PM",
"lastOpDate": "Nov 29, 2015 9:57:10 PM",
"uuid": "a338d11be18d4e288223597682964dc8"
"securityGroupUuid": "9e0a72fe64814900baa22f78a1b9d235",
}
Security Group And L3 Network¶
As having said, a security group can be attached to multiple L3 networks. The design consideration is that a security group is a set of firewall rules and can be applied to any L3 networks. For example, two different L3 networks may have the same set of firewall rules which make much sense to be put into the same security group.
VM nics from different L3 networks in the same security group are irrelevant. As mentioned in Allowed CIDR, VM nics of the same L3 network in a security group are not affected by rules’ allowedCIDR, they can always reach ports opened of each other. However, if two nics in a security group are from different L3 networks, then the allowedCIDR will take effect when they try to reach each other.
If you find it’s confusing to have a security group attached to multiple L3 networks, you can always create a security group per each L3 network.
Operations¶
Create Security Group¶
Users can use CreateSecurityGroup to create a security group. For example:
CreateSecurityGroup name=web
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
name | resource name, see Resource Properties | 0.6 | ||
resourceUuid | resource uuid, see Create Resources | true | 0.6 | |
description | resource description, see Resource Properties | true | 0.6 |
Add Rules To Security Group¶
Users can use AddSecurityGroupRule to add rules to a security group. For example:
AddSecurityGroupRule securityGroupUuid=29a0f801f77b4b4f866fb4c9503d0fe9 rules="[{'type':'Ingress', 'protocol':'TCP', 'startPort':'22', 'endPort':'22', 'allowedCidr':'0.0.0.0/0'}]"
This command executes asynchronously, it may return before rules are applied to all VM nics.
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
securityGroupUuid | uuid of security group | 0.6 | ||
rules | a list of SecurityGroupRuleAO | 0.6 |
SecurityGroupRuleAO¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
type | traffic type, see traffic type |
|
0.6 | |
startPort | start port or ICMP type |
|
0.6 | |
endPort | end port or ICMP code |
|
0.6 | |
protocol | protocol type |
|
0.6 | |
allowedCidr | see allowed CIDR; default to 0.0.0.0/0 | true | 0.6 |
Delete Rules From Security Group¶
User can uses DeleteSecurityGroupRule to delete rules from a security group. For example:
DeleteSecurityGroupRule ruleUuids=a338d11be18d4e288223597682964dc8,9e0a72fe64814900baa22f78a1b9d235
This command executes asynchronously, it may return before rules are refreshed on all hosts.
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
ruleUuids | a list of uuid of rule inventory | 0.6 |
Add VM Nics Into Security Group¶
Users can use AddVmNicToSecurityGroup to add VM nics to a security group. For example:
AddVmNicToSecurityGroup securityGroupUuid=0b48770e593e400c8f54e71fd4e7f514 vmNicUuids=b429625fe2704a3e94d698ccc0fae4fb,6572ce44c3f6422d8063b0fb262cbc62,d07066c4de02404a948772e131139eb4
This command executes asynchronously, it may return before rules are applied on those nics.
Note
VM nics can only join security groups that have been attached to their L3 networks.
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
securityGroupUuid | security group uuid | 0.6 | ||
vmNicUuids | a list of uuid of vm nic inventory | 0.6 |
Remove VM Nics from Security Group¶
Users can use DeleteVmNicFromSecurityGroup to delete VM nics from a security group. For example:
DeleteVmNicFromSecurityGroup securityGroupUuid=0b48770e593e400c8f54e71fd4e7f514 vmNicUuids=b429625fe2704a3e94d698ccc0fae4fb,6572ce44c3f6422d8063b0fb262cbc62,d07066c4de02404a948772e131139eb4
This command executes asynchronously, it may return before rules are refreshed on rest nics in the security group.
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
securityGroupUuid | security group uuid | 0.6 | ||
vmNicUuids | a list of uuid of vm nic inventory | 0.6 |
Attach Security Group To L3 Network¶
Users can use AttachSecurityGroupToL3Network to attach a security group to a L3 network. For example:
AttachSecurityGroupToL3Network securityGroupUuid=0b48770e593e400c8f54e71fd4e7f514 l3NetworkUuid=95dede673ddf41119cbd04bcb5d73660
Note
A security group can only be attached to L3 networks that have security group network service enabled
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
securityGroupUuid | security group uuid | 0.6 | ||
l3NetworkUuid | L3 network uuid | 0.6 |
Detach Security Group From L3 Network¶
Users can use DetachSecurityGroupFromL3Network to detach a security group from a L3 network:
DetachSecurityGroupFromL3Network securityGroupUuid=0b48770e593e400c8f54e71fd4e7f514 l3NetworkUuid=95dede673ddf41119cbd04bcb5d73660
After detaching, all rules will be removed from VM nics of the L3 network and in this security group. This command executes asynchronously, it may return before rules are refreshed on those nics.
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
securityGroupUuid | security group uuid | 0.6 | ||
l3NetworkUuid | L3 network uuid | 0.6 |
Delete Security Group¶
Users can use DeleteSecurityGroup to delete a security group. For example:
DeleteSecurityGroup uuid=0b48770e593e400c8f54e71fd4e7f514
After deleting, all rules will be removed from VM nics in this security group. This command executes asynchronously, it may return before rules are refreshed on those VM nics.
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
deleteMode | see Delete Resources | true |
|
0.6 |
uuid | security group uuid | 0.6 |
Query Security Group¶
Users can use QuerySecurityGroup to query security groups. For example:
QuerySecurityGroup rules.startPort=22 rules.type=Ingress rules.protocol=TCP
QuerySecurityGroup vmNic.ip=192.168.0.205
Nested And Expanded Fields¶
Field | Inventory | Description | Since |
---|---|---|---|
rules | security group rule inventory | rules the security group has | 0.6 |
vmNic | VM nic inventory | VM nics that have joined this security group | 0.6 |
l3Network | L3 network inventory | L3 networks this security group is attached | 0.6 |
Global Configurations¶
ingress.defaultPolicy¶
Name | Category | Default Value | Choices |
---|---|---|---|
ingress.defaultPolicy | securityGroup | deny |
|
The default ingress policy for empty security groups.
egress.defaultPolicy¶
Name | Category | Default Value | Choices |
---|---|---|---|
egress.defaultPolicy | securityGroup | accept |
|
The default egress policy for empty security groups.