Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Authorizations
personalAccessToken
oauth
firewall:read_only
Query Parameters
page
Type:
integer
>= 1
Default:
1
Default:
1
The page of a collection to return.
page_size
Type:
integer
25..100
Default:
100
Default:
100
The number of items to return per page.
Request Samples
Response Samples
Responses
Firewall Create
POST
https://api.linode.com/v4beta/networking/firewalls
Beta
Creates a Firewall to filter network traffic. Use the rules property to
create inbound and outbound access rules. Use the devices property to assign the
Firewall to a Linode service. Currently, Firewalls can only be assigned to Linode
instances.
A Firewall can be assigned to multiple Linode services, and up to three active Firewalls
can be assigned to a single Linode service.
A firewall_create Event is generated when this endpoint returns successfully.
Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Authorizations
personalAccessToken
oauth
firewall:read_write
Request Body Schema
devices
object
A Firewall Device assigns a Firewall to a Linode service. Currently, Firewalls can only be assigned to Linode instances.
A Firewall can be assigned to multiple Linode services, and up to three active Firewalls can be assigned to a single Linode service.
Additional disabled Firewalls can be assigned to a service, but they cannot be enabled if three other active Firewalls are already assigned to the same service.
Note: When a Firewall is assigned to a Linode and you attempt to
migrate the Linode to a data center that does not support Cloud Firewalls, the migration will fail. Use the
List Regions endpoint to view a list of a data center’s capabilities.
linodes
array of integers
An array of Linode IDs. A Firewall Device will be created for each ID.
label
Filterable
string
3..32
characters
The Firewall’s label, for display purposes only. If no label is provided for a Firewall, a default will be assigned.
Firewall labels have the following constraints:
Must begin and end with an alphanumeric character.
May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
Cannot have two dashes (--), underscores (__) or periods (..) in a row.
Must be between 3 and 32 characters.
rules
Required
object
The inbound and outbound access rules to apply to the Firewall.
A minimum of one open inbound rule is required. Any inbound
traffic that is not permitted by your rules will be blocked.
Outbound rules are optional. When no outbound rules are specified,
all outbound traffic is allowed. If one or more outbound rules are
specified, all outbound traffic that is not permitted by your rules
will be blocked.
A Firewall may have up to 25 rules across its inbound and outbound rulesets.
inbound
array of objects
addresses
object
Allowed IPv4 or IPv6 addresses. A Rule can have up to 255 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.
ipv4
array of strings
A list of IPv4 addresses or networks.
ipv6
array of strings
A list of IPv6 addresses or networks.
ports
string
A string representing the port or ports on which traffic will be allowed:
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.
Ports may not be specified if a rule’s protocol is ICMP. At least one port
must be specified if a rule’s protocol is TCP or UDP.
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.
protocol
string
Enum:
TCPUDPICMP
The type of network traffic to allow.
outbound
array of objects
addresses
object
Allowed IPv4 or IPv6 addresses. A Rule can have up to 255 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.
ipv4
array of strings
A list of IPv4 addresses or networks.
ipv6
array of strings
A list of IPv6 addresses or networks.
ports
string
A string representing the port or ports on which traffic will be allowed:
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.
Ports may not be specified if a rule’s protocol is ICMP. At least one port
must be specified if a rule’s protocol is TCP or UDP.
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.
protocol
string
Enum:
TCPUDPICMP
The type of network traffic to allow.
tags
Filterable
array of strings
An array of tags applied to this object. Tags are for organizational purposes only.
Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Authorizations
personalAccessToken
oauth
firewall:read_write
Path Parameters
firewallId
integerRequired
ID of the Firewall to access.
Request Samples
Response Samples
Responses
Firewall View
GET
https://api.linode.com/v4beta/networking/firewalls/{firewallId}
Beta
Get a specific Firewall resource by its ID. The Firewall’s Devices will not be
returned in the response. Instead, use the
List Firewall Devices
endpoint to review them.
Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Authorizations
personalAccessToken
oauth
firewall:read_only
Path Parameters
firewallId
integerRequired
ID of the Firewall to access.
Request Samples
Response Samples
Responses
Firewall Update
PUT
https://api.linode.com/v4beta/networking/firewalls/{firewallId}
Beta
Updates information for a Firewall. Some parts of a Firewall’s configuration cannot
be manipulated by this endpoint:
A Firewall’s Devices cannot be set with this endpoint. Instead, use the
Create Firewall Device
and
Delete Firewall Device
endpoints to assign and remove this Firewall from Linode services.
A Firewall’s Rules cannot be changed with this endpoint. Instead, use the
Update Firewall Rules
endpoint to update your Rules.
A Firewall’s status can be set to enabled or disabled by this endpoint, but it cannot be
set to deleted. Instead, use the
Delete Firewall
endpoint to delete a Firewall.
If a Firewall’s status is changed with this endpoint, a corresponding firewall_enable or
firewall_disable Event will be generated.
Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Authorizations
personalAccessToken
oauth
firewall:read_write
Path Parameters
firewallId
integerRequired
ID of the Firewall to access.
Request Body Schema
label
Filterable
string
3..32
characters
The Firewall’s label, for display purposes only. If no label is provided for a Firewall, a default will be assigned.
Firewall labels have the following constraints:
Must begin and end with an alphanumeric character.
May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
Cannot have two dashes (--), underscores (__) or periods (..) in a row.
Must be between 3 and 32 characters.
status
string
Enum:
enableddisableddeleted
The status of this Firewall.
When a Firewall is first created its status is enabled.
Use the
Update Firewall endpoint to set a Firewall’s status to enbaled or disabled.
An array of tags applied to this object. Tags are for organizational purposes only.
Request Samples
Response Samples
Responses
Firewall Devices List
GET
https://api.linode.com/v4beta/networking/firewalls/{firewallId}/devices
Beta
Returns a paginated list of a Firewall’s Devices. A Firewall Device assigns a
Firewall to a Linode service (referred to as the Device’s entity). Currently,
only Devices with an entity of type linode are accepted.
Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Authorizations
personalAccessToken
oauth
firewall:read_only
Path Parameters
firewallId
integerRequired
ID of the Firewall to access.
Query Parameters
page
Type:
integer
>= 1
Default:
1
Default:
1
The page of a collection to return.
page_size
Type:
integer
25..100
Default:
100
Default:
100
The number of items to return per page.
Request Samples
Response Samples
Responses
Firewall Device Create
POST
https://api.linode.com/v4beta/networking/firewalls/{firewallId}/devices
Beta
Creates a Firewall Device, which assigns a Firewall to a Linode service (referred to
as the Device’s entity). Currently, only Devices with an entity of type linode are accepted.
A Firewall can be assigned to multiple Linode services, and up to three active Firewalls can
be assigned to a single Linode service. Additional disabled Firewalls can be
assigned to a service, but they cannot be enabled if three other active Firewalls
are already assigned to the same service.
Creating a Firewall Device will apply the Rules from a Firewall to a Linode service.
A firewall_device_add Event is generated when the Firewall Device is added successfully.
Note: When a Firewall is assigned to a Linode and you attempt
to
migrate the Linode to a data center that does not support Cloud Firewalls, the migration will fail.
Use the
List Regions endpoint to view a list of a data center’s capabilities.
Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Removes a Firewall Device, which removes a Firewall from the Linode service it was
assigned to by the Device. This will remove all of the Firewall’s Rules from the Linode
service. If any other Firewalls have been assigned to the Linode service, then those Rules
will remain in effect.
A firewall_device_remove Event is generated when the Firewall Device is removed successfully.
Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Authorizations
personalAccessToken
oauth
firewall:read_write
Path Parameters
firewallId
integerRequired
ID of the Firewall to access.
deviceId
integerRequired
ID of the Firewall Device to access.
Request Samples
Response Samples
Responses
Firewall Device View
GET
https://api.linode.com/v4beta/networking/firewalls/{firewallId}/devices/{deviceId}
Beta
Returns information for a Firewall Device, which assigns a Firewall
to a Linode service (referred to as the Device’s entity). Currently,
only Devices with an entity of type linode are accepted.
Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Authorizations
personalAccessToken
oauth
firewall:read_only
Path Parameters
firewallId
integerRequired
ID of the Firewall to access.
deviceId
integerRequired
ID of the Firewall Device to access.
Request Samples
Response Samples
Responses
Firewall Rules List
GET
https://api.linode.com/v4beta/networking/firewalls/{firewallId}/rules
Beta
Returns the inbound and outbound Rules for a Firewall.
Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Authorizations
personalAccessToken
oauth
firewall:read_only
Path Parameters
firewallId
integerRequired
ID of the Firewall to access.
Request Samples
Response Samples
Responses
Firewall Rules Update
PUT
https://api.linode.com/v4beta/networking/firewalls/{firewallId}/rules
Beta
Updates the inbound and outbound Rules for a Firewall. Using this endpoint will
replace all of a Firewall’s ruleset with the Rules specified in your request.
Please make sure to prepend all requests with
/v4beta instead of /v4, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
Authorizations
personalAccessToken
oauth
firewall:read_write
Path Parameters
firewallId
integerRequired
ID of the Firewall to access.
Request Body Schema
inbound
Required
array of objects
addresses
object
Allowed IPv4 or IPv6 addresses. A Rule can have up to 255 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.
ipv4
array of strings
A list of IPv4 addresses or networks.
ipv6
array of strings
A list of IPv6 addresses or networks.
ports
string
A string representing the port or ports on which traffic will be allowed:
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.
Ports may not be specified if a rule’s protocol is ICMP. At least one port
must be specified if a rule’s protocol is TCP or UDP.
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.
protocol
string
Enum:
TCPUDPICMP
The type of network traffic to allow.
outbound
array of objects
addresses
object
Allowed IPv4 or IPv6 addresses. A Rule can have up to 255 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.
ipv4
array of strings
A list of IPv4 addresses or networks.
ipv6
array of strings
A list of IPv6 addresses or networks.
ports
string
A string representing the port or ports on which traffic will be allowed:
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.
Ports may not be specified if a rule’s protocol is ICMP. At least one port
must be specified if a rule’s protocol is TCP or UDP.
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.
protocol
string
Enum:
TCPUDPICMP
The type of network traffic to allow.
Request Samples
Response Samples
Responses
IP Addresses List
GET
https://api.linode.com/v4/networking/ips
Returns a paginated list of IP Addresses on your Account, excluding private addresses.
Authorizations
personalAccessToken
oauth
ips:read_only
Request Samples
Response Samples
Responses
IP Address Allocate
POST
https://api.linode.com/v4/networking/ips
Allocates a new IPv4 Address on your Account. The Linode must be configured to support additional addresses - please
open a support ticket requesting additional addresses before attempting allocation.
Authorizations
personalAccessToken
oauth
ips:read_write,linodes:read_write
Request Body Schema
linode_id
Required
integer
The ID of a Linode you you have access to that this address will be allocated to.
public
Required
boolean
Whether to create a public or private IPv4 address.
type
Required
string
Enum:
ipv4
The type of address you are requesting. Only IPv4 addresses may be allocated through this endpoint.
Request Samples
Response Samples
Responses
IP Address View
GET
https://api.linode.com/v4/networking/ips/{address}
Returns information about a single IP Address on your Account.
Authorizations
personalAccessToken
oauth
ips:read_only
Path Parameters
address
string <ip>Required
The address to operate on.
Request Samples
Response Samples
Responses
IP Address RDNS Update
PUT
https://api.linode.com/v4/networking/ips/{address}
Sets RDNS on an IP Address. Forward DNS must already be set up for reverse DNS to be applied. If you set the RDNS to null for public IPv4 addresses, it will be reset to the default members.linode.com RDNS value.
Authorizations
personalAccessToken
oauth
ips:read_write
Path Parameters
address
string <ip>Required
The address to operate on.
Request Body Schema
rdns
string
The reverse DNS assigned to this address. For public IPv4 addresses, this will be set to a default value provided by Linode if not explicitly set.
Request Samples
Response Samples
Responses
Linodes Assign IPs
POST
https://api.linode.com/v4/networking/ipv4/assign
Assign multiple IPs to multiple Linodes in one Region. This allows swapping, shuffling, or otherwise reorganizing IPv4 Addresses to your Linodes. When the assignment is finished, all Linodes must end up with at least one public IPv4 and no more than one private IPv4.
Authorizations
personalAccessToken
oauth
ips:read_write,linodes:read_write
Request Body Schema
assignments
Required
array of objects
The list of assignments to make. You must have read_write access to all IPs being assigned and all Linodes being assigned to in order for the assignments to succeed.
address
string <ip>
Ths IP Address for this assignment. Must be a IPv4 address you can access in the Region specified. May be a public or private address.
linode_id
integer
The ID of the Linode to assign this address to. The IP’s previous Linode will lose this address, and must end up with at least one public address and no more than one private address once all assignments have been made.
region
Required
string
The ID of the Region in which these assignments are to take place. All IPs and Linodes must exist in this Region.
Request Samples
Response Samples
Responses
IP Sharing Configure
POST
https://api.linode.com/v4/networking/ipv4/share
Configure shared IPs. A shared IP may be brought up on a Linode other than the one it lists in its response. This can be used to allow one Linode to begin serving requests should another become unresponsive.
Authorizations
personalAccessToken
oauth
ips:read_write,linodes:read_write
Request Body Schema
ips
Required
array of strings
A list of IPs that will be shared with this Linode. When this is finished, the given Linode will be able to bring up these addresses in addition to the Linodes that these addresses belong to. You must have access to all of these addresses and they must be in the same Region as the Linode.
linode_id
Required
integer
The ID of the Linode that the addresses will be shared with.
Request Samples
Response Samples
Responses
IPv6 Pools List
GET
https://api.linode.com/v4/networking/ipv6/pools
Displays the IPv6 pools on your Account. A pool of IPv6 addresses are routed to all of your Linodes in a single
Region. Any Linode on your Account may bring up any address in this pool at any time, with no external configuration required.
Authorizations
personalAccessToken
oauth
ips:read_only
Query Parameters
page
Type:
integer
>= 1
Default:
1
Default:
1
The page of a collection to return.
page_size
Type:
integer
25..100
Default:
100
Default:
100
The number of items to return per page.
Request Samples
Response Samples
Responses
IPv6 Ranges List
GET
https://api.linode.com/v4/networking/ipv6/ranges
Displays the IPv6 ranges on your Account.
An IPv6 range is a /64 block of IPv6 addresses routed to a single Linode in a given
Region.
Your Linode is responsible for routing individual addresses in the range, or handling traffic for all the addresses in the range.
You must
open a support ticket to request a /64 block of IPv6 addresses to be added to your account.
