Skip to main content

Firewall Rules

Take control of your virtual machine's security by configuring firewall rules. Specify which ports are open to the public to protect your resources. To ensure the security of your virtual machines designate only the ports necessary for ingress/egress. By default, no external communication with your virtual machines is permitted.

Firewall rules for your virtual machines can be created using two different methods: the Hyperstack platform and the Infrahub API.

When working with the Hyperstack platform, you can easily set up firewall rules that are based on the three most commonly used Internet protocols: TCP (Transmission Control Protocol), UDP (User Datagram Protocol), and ICMP (Internet Control Message Protocol). These protocols cover many basic use cases.

However, if your requirements involve more advanced protocols, you will need to use the Infrahub API. The Infrahub API enables you to create firewall rules based on an extensive list of protocols, catering to your unique networking needs.

In this article


Properties of firewall rules

Each firewall rule specifies the following properties:

  • Direction: Each firewall rule applies to incoming (ingress) or outgoing (egress) connections, not both.

  • Source or destination: Firewall rules support IPv4 or IPv6 connections.

  • Protocol: The protocol to allow. The most common protocols are TCP, UDP, and ICMP. Call the GET /core/sg-rules-protocols endpoint to retrieve a list of all API-supported protocols.

  • Port range: The range of ports to allow. You can specify a single port number (for example, 22), or a range of port numbers (for example, 7000-8000).

  • IP address range: The IP address range that is allowed to access the specified port.


Default firewall rules

New virtual machines are secure by default, initially configured without any firewall rules allowing incoming traffic. To enable incoming traffic, users must create firewall rules tailored to their needs.

Additionally, virtual machines come with pre-configured egress rules permitting outgoing IPv4 and IPv6 traffic using any internet protocol, on any port (1-65536), and to any destination IP address (0.0.0.0/0). If desired, these pre-configured firewall rules for incoming traffic can be deleted to restrict outgoing traffic.

Default virtual machine firewall rule configuration as shown in Hyperstack:

Default firewall rules


Creating firewall rules in Hyperstack

Using the Hyperstack platform, you can easily configure firewall rules for your virtual machines for the three most common internet protocols: TCP, UDP, and ICMP.

  • Click here for step-by-step instructions on creating a firewall rule in Hyperstack.

TCP (Transmission Control Protocol)

TCP is a connection-oriented protocol used for reliable and ordered data transmission. It ensures that data sent from one system arrives intact and correctly ordered at the destination. This protocol is commonly used to allow inbound web traffic via HTTP/HTTPS and SSH access for administrators.

UDP (User Datagram Protocol)

UDP is a connectionless protocol that is fast and efficient. This protocol does not guarantee the delivery or order of packets, making it suitable for real-time applications. This protocol is commonly used to allow DNS requests.

ICMP (Internet Control Message Protocol)

ICMP is a network layer protocol typically used for diagnostic purposes. This protocol is commonly used to create firewall rules that permit ping requests, so that error messages can be received.


If your use case involves advanced protocols beyond TCP, UDP, or ICMP, use the Infrahub API. Detailed instructions on creating firewall rules with the Infrahub API can be found below.



Creating firewall rules using the Infrahub API

The Infrahub API offers robust support for creating firewall rules by leveraging a comprehensive list of internet protocols. You can explore this extensive protocol list by calling the GET /core/sg-rules-protocols endpoint, as detailed in our documentation here.

Once you've identified the protocol you need, you can proceed to create custom firewall rules using the API, using the POST /core/virtual-machines/{virtual_machine_id}/sg-rules endpoint. For step-by-step instructions on how to achieve this, please refer to our documentation here.



API operations for firewall rules

OperationsEndpoints
Create a firewall rule /core/virtual-machines/{id}/sg-rules
Retrieve a list of firewall rule protocolsGET /core/sg-rules-protocols
Delete a firewall rule for a virtual machineDELETE /core/virtual-machines/{virtual_machine_id}/sg-rules/{sg_rule_id}


Retrieve a list of Infrahub API-supported internet protocols

GET https://infrahub-api.nexgencloud.com/v1/core/sg-rules-protocols

This operation allows you to obtain a comprehensive list of internet protocols that are available for creating new firewall rules. You can use any of these protocols from the retrieved list by specifying them in the protocol field within the request body when creating a new firewall rule.


Parameters


No parameters.


Returns


A successful response returns an array of protocols supported by the Infrahub API for the creation of firewall rules. Otherwise, an error has occurred.


Attributes of the Protocols object


status boolean

Indicates the status of the retrieving of protocols. If the value is true, it means that the list of protocols has been successfully retrieved. false indicates that an error has occurred.


message string

Describes the status of the protocol list retrieval.


protocols array

An array of internet protocols that can be used in the protocol field when creating a new firewall rule for a virtual machine.

Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/sg-rules-protocols" \
-H "accept: application/json"\
-H "authorization: YOUR API KEY"
Response
{
"status": true,
"message": "Getting security rule protocols successful",
"protocols": [
"any",
"ah",
"dccp",
"egp",
"esp",
...
]
}

To view a comprehensive list of protocols along with their validation schemes, including corresponding ethertype and port restrictions, click the drop-down below:

See protocols and validation schemes
ProtocolEthertypePorts
anyNoneNone
tcpIPv4/IPv61 - 65535
udpIPv4/IPv61 - 65535
icmpIPv4/IPv6None
ahIPv4/IPv6None
dccpIPv4/IPv61 - 65535
egpIPv4/IPv6None
espIPv4/IPv6None
greIPv4/IPv6None
icmpv6IPv4/IPv6None
igmpIPv4/IPv6None
ipipIPv4/IPv6None
ipv6-encapIPv6None
ipv6-fragIPv6None
ipv6-icmpIPv6None
ipv6-nonxtIPv6None
ipv6-optsIPv6None
ipv6-routeIPv6None
ospfIPv4/IPv6None
pgmIPv4/IPv6None
rsvpIPv4/IPv6None
sctpIPv4/IPv61 - 65535
udpliteIPv4/IPv61 - 65535
vrrpIPv4/IPv6None
note

When dealing with the icmp and ipv6-icmp protocols, it's important to note that the values for port_range_min and port_range_max correspond to ICMP type and ICMP code, respectively. These values should fall within the range of 0 to 255.



Create a firewall rule for a virtual machine

POST https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/{virtual_machine_id}/sg-rules

This endpoint can be used to establish a firewall rule, granting custom security permissions for a virtual machine.

To create a custom firewall rule for a specific virtual machine, simply include the virtual machine's ID in the request path and provide the firewall rule configuration details as request body parameters, as outlined below.


Path parameters


virtual_machine_id integer REQUIRED

The ID of the virtual machine for which a firewall rule is being created. In this case, a firewall rule is being added to virtual_machine_id "193".


Request body parameters


direction string REQUIRED

The direction of traffic that the firewall rule applies to. In this case, "ingress" (incoming).
Possible values: one of ingress or egress.


protocol string REQUIRED

The network protocol associated with the rule. In this example, "tcp" for TCP/IP protocol.
Possible values: Any one of the protocol values retrieved by calling the GET /core/sg-rules-protocols endpoint.


**ethertype string REQUIRED

The Ethernet type associated with the rule. In this case, the standard "IPv4" is used. Possible values: one of IPv4 or IPv6.


remote_ip_prefix string REQUIRED

The IP address range that is allowed to access the specified port. In this case, "0.0.0.0/0" means any IP address is allowed.


port_range_min integer optional

The minimum port number in the range of ports to be allowed by the firewall rule. In this example, the only permitted port is "22".


port_range_max integer optional

The maximum port number in the range of ports to be allowed by the firewall rule. In this case, the only permitted port is "22".


Returns

Returns the status of the firewall rule creation operation, along with the configuration details that were specified in the request body.

This response indicates the successful addition of a firewall rule that will grant access permissions for incoming traffic (ingress) on port "22", using the TCP protocol and Ethernet type "IPv4" for the virtual machine with the ID "193".


Attributes of the Security Rule object

Returns the security_rule object with additional information: time of rule creation, rule ID, and the status of the firewall rule being created.

Example request
curl -X POST "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines/193/sg-rules" \
-H "accept: application/json"\
-H "content-type: application/json" \
-d '{
"direction": "ingress",
"protocol": "tcp",
"port_range_min": 22,
"port_range_max": 22,
"ethertype": "IPv4",
"remote_ip_prefix": "0.0.0.0/0"
}'
Response
{
"status": true,
"message": "Security Rule created successfully",
"security_rule": {
"port_range_min": 22,
"port_range_max": 22,
"created_at": "2023-05-17T13:18:00",
"protocol": "tcp",
"ethertype": "IPv4",
"direction": "ingress",
"id": 193,
"remote_ip_prefix": "0.0.0.0/0",
"status": "pending"
}
}

Back to top