Create a firewall

post https://api.linode.com/{apiVersion}/networking/firewalls

Creates a Firewall to filter network traffic.

Use rules to create inbound and outbound access rules. Rule versions increment from 1 whenever the firewall's rules change.
Use devices to assign a firewall to a service such as a Linode that is using legacy config profiles, a Linode interface or a NodeBalancer. The firewall’s rules are then applied to that service. Requires a read_write user grant to the device.
- For Linodes using Linode interfaces, firewalls need to be assigned to interfaces and not the linodes. Firewall templates are available for both VPC Linode interfaces and public Linode interfaces, and come with pre-configured protection rules.
- For Linodes using legacy configuration profiles, firewalls are applied through the Linode. Public and VPC interfaces are subject to the firewall rules, while VLAN interfaces are not.
Currently, firewalls can be assigned to Linodes with legacy configuration profiles, Linode interfaces, and NodeBalancers.
- The same firewall can be assigned to multiple services at a time.
Use firewall_id to assign a firewall when creating a Linode or when adding a Linode interface.
A service can have one assigned firewall enabled at a time.
Assigned Linodes must not have any ongoing live migrations.
A firewall_create event is generated when this operation succeeds.

linode-cli firewalls create \
  --label example-firewall \
  --rules.outbound_policy ACCEPT \
  --rules.inbound_policy DROP \
  --rules.inbound '[{"protocol": "TCP", "ports": "22, 80, 8080, 443", "addresses": {"ipv4": ["192.0.2.0/24", "198.51.100.2/32"], "ipv6": ["2001:DB8::/128"]}, "action": "ACCEPT"}]' \
  --rules.outbound '[{"protocol": "TCP", "ports": "49152-65535", "addresses": {"ipv4": ["192.0.2.0/24", "198.51.100.2/32"],"ipv6": ["2001:DB8::/128"]}, "action": "DROP", "label": "outbound-rule123", "description": "An example outbound rule description."}]'


Learn more...

firewall:read_write


Learn more...

Path Params

apiVersion

string

required

Enum Call either the v4 URL, or v4beta for operations still in Beta.

Body Params

Creates a firewall object that can be applied to a service to filter the service's network traffic.

devices

object

Devices to create for this firewall. When a device is created, the firewall is assigned to its associated service. Currently, devices can be created for Linodes using legacy configuration profiles, Linode interfaces, and NodeBalancers. Firewall devices can't be created for individual legacy configuration profile interfaces.

Additional devices can be assigned after Firewall creation by using the Create a firewall device operation.

rules

object

required

The inbound and outbound access rules to apply to the Firewall.

A Firewall may have up to 25 rules across its inbound and outbound rulesets.

Multiple rules are applied in order. If two rules conflict, the first rule takes precedence. For example, if the first rule accepts inbound traffic from an address, and the second rule drops inbound traffic the same address, the first rule applies and inbound traffic from that address is accepted.

label

string

required

length between 3 and 32

Filterable The Firewall's label, for display purposes only.

Firewall labels have the following constraints:

Must begin and end with an alphanumeric character.
May only consist of alphanumeric characters, hyphens (-), underscores (_) or periods (.).
Cannot have two hyphens (--), underscores (__) or periods (..) in a row.
Must be between 3 and 32 characters.
Must be unique.

tags

array of strings

Filterable An array of tags applied to this object. Tags are for organizational purposes only.

tags

Responses

Response body

object

created

date-time

Filterable, Read-only When this Firewall was created.

integer

Filterable, Read-only The Firewall's unique ID.

label

string

length between 3 and 32

Filterable The Firewall's label, for display purposes only.

Firewall labels have the following constraints:

Must begin and end with an alphanumeric character.
May only consist of alphanumeric characters, hyphens (-), underscores (_) or periods (.).
Cannot have two hyphens (--), underscores (__) or periods (..) in a row.
Must be between 3 and 32 characters.
Must be unique.

rules

object

The inbound and outbound access rules to apply to the Firewall.

A Firewall may have up to 25 rules across its inbound and outbound rulesets.

fingerprint

string

Read-only The fingerprint is a 32-bit hash. It represents the firewall rules as an 8 character hex string. You can use fingerprint to compare rule versions.

inbound

array of objects

The inbound rules for the firewall, as a JSON array.

inbound

object

action

string

Controls whether traffic is accepted or dropped by this rule. Overrides the Firewall's inbound_policy if this is an inbound rule, or the outbound_policy if this is an outbound rule.

ACCEPT DROP

addresses

object

The IPv4 or IPv6 addresses affected by this rule. A rule can have up to 255 total addresses or networks listed across its ipv4 and ipv6 arrays. A network and a single IP are treated as equivalent when accounting for this limit.

Must contain ipv4, ipv6, or both.

description

string

length between 1 and 100

Used to describe this rule. For display purposes only.

label

string

length between 3 and 32

Used to identify this rule. For display purposes only.

ports

string | null

A string representing the port or ports affected by this rule:

The string may be a single port, a range of ports, or a comma-separated list of single ports and port ranges. A space is permitted following each comma.
A range of ports is inclusive of the start and end values for the range. The end value of the range must be greater than the start value.
Ports must be within 1 and 65535, and may not contain any leading zeroes. For example, port 080 is not allowed.
The ports string can have up to 15 pieces, where a single port is treated as one piece, and a port range is treated as two pieces. For example, the string "22-24, 80, 443" has four pieces.
If no ports are configured, all ports are affected.
Only allowed for the TCP and UDP protocols. Ports are not allowed for the ICMP and IPENCAP protocols.

protocol

string

The type of network traffic affected by this rule.

TCP UDP ICMP IPENCAP

inbound_policy

string

The default behavior for inbound traffic. This setting can be overridden by updating the inbound.action property of the Firewall Rule.

ACCEPT DROP

outbound

array of objects

The outbound rules for the firewall, as a JSON array.

outbound

object

action

string

Controls whether traffic is accepted or dropped by this rule. Overrides the Firewall's inbound_policy if this is an inbound rule, or the outbound_policy if this is an outbound rule.

ACCEPT DROP

addresses

object

Must contain ipv4, ipv6, or both.

description

string

length between 1 and 100

Used to describe this rule. For display purposes only.

label

string

length between 3 and 32

Used to identify this rule. For display purposes only.

ports

string | null

A string representing the port or ports affected by this rule:

The string may be a single port, a range of ports, or a comma-separated list of single ports and port ranges. A space is permitted following each comma.
A range of ports is inclusive of the start and end values for the range. The end value of the range must be greater than the start value.
Ports must be within 1 and 65535, and may not contain any leading zeroes. For example, port 080 is not allowed.
The ports string can have up to 15 pieces, where a single port is treated as one piece, and a port range is treated as two pieces. For example, the string "22-24, 80, 443" has four pieces.
If no ports are configured, all ports are affected.
Only allowed for the TCP and UDP protocols. Ports are not allowed for the ICMP and IPENCAP protocols.

protocol

string

The type of network traffic affected by this rule.

TCP UDP ICMP IPENCAP

outbound_policy

string

The default behavior for outbound traffic. This setting can be overridden by updating the outbound.action property of the Firewall Rule.

ACCEPT DROP

version

integer

Read-only The firewall's rule version. The first version is 1. The version number is incremented when the firewall's rules change.

status

string

Read-only The status of this Firewall.

When a Firewall is first created its status is enabled.
Run the Update a firewall operation to set a Firewall's status to enabled or disabled.
Run the Delete a firewall operation to delete a Firewall.

enabled disabled deleted

tags

array of strings

Filterable An array of tags applied to this object. Tags are for organizational purposes only.

tags

updated

date-time

Filterable, Read-only When this Firewall was last updated.

Language

Credentials


xxxxxxxxxx
12
1
curl --request POST \
2
     --url https://api.linode.com/v4/networking/firewalls \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "rules": {
8
    "inbound_policy": "ACCEPT",
9
    "outbound_policy": "ACCEPT"
10
  }
11
}
12
'


xxxxxxxxxx
53
}
1
{
2
  "created": "2018-01-01T00:01:01",
3
  "id": 123,
4
  "label": "firewall123",
5
  "rules": {
6
    "fingerprint": "997dd135",
7
    "inbound": [
8
      {
9
        "action": "ACCEPT",
10
        "addresses": {
11
          "ipv4": [
12
            "192.0.2.0/24",
13
            "198.51.100.2/32"
14
          ],
15
          "ipv6": [
16
            "2001:DB8::/128"
17
          ]
18
        },
19
        "description": "An example firewall rule description.",
20
        "label": "firewallrule123",
21
        "ports": "22-24, 80, 443",
22
        "protocol": "TCP"
23
      }
24
    ],
25
    "inbound_policy": "DROP",

200Returns information about the created Firewall.

defaultSee Errors for the range of possible error response codes.