Networking v4.96.0

Firewalls List

GET https://api.linode.com/v4/networking/firewalls

Returns a paginated list of your Firewalls.

Cloud Firewall is not available in every data center region. For the current list of availability, access the Regions List ( GET /regions) endpoint or see the Cloud Firewall Product Documentation.

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/v4/networking/firewalls

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 a single Linode service at a time.

A firewall_create Event is generated when this endpoint returns successfully.

Cloud Firewall is not available in every data center region. For the current list of availability, access the Regions List ( GET /regions) endpoint or see the Cloud Firewall Product Documentation.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 a single Linode service at a time.
Additional disabled Firewalls can be assigned to a service, but they cannot be enabled if five 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

Required

string 3..32 characters

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, dashes (-), underscores (_) or periods (.).
Cannot have two dashes (--), underscores (__) or periods (..) in a row.
Must be between 3 and 32 characters.
Must be unique.

rules

Required

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.

inbound

array of objects

action

Required

string

Enum: ACCEPT DROP

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.

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. Must be in IP/mask format.
ipv6	`array of strings` A list of IPv6 addresses or networks. Must be in IP/mask format.

description

string 1..100 characters

Used to describe this rule. For display purposes only.

label

Required

string 3..32 characters

Used to identify this rule. For display purposes only.

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: TCP UDP ICMP

The type of network traffic to allow.

inbound_policy

Required

string

Enum: ACCEPT DROP

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

outbound

array of objects

action

Required

string

Enum: ACCEPT DROP

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.

addresses

object

ipv4	`array of strings` A list of IPv4 addresses or networks. Must be in IP/mask format.
ipv6	`array of strings` A list of IPv6 addresses or networks. Must be in IP/mask format.

description

string 1..100 characters

Used to describe this rule. For display purposes only.

label

Required

string 3..32 characters

Used to identify this rule. For display purposes only.

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: TCP UDP ICMP

The type of network traffic to allow.

outbound_policy

Required

string

Enum: ACCEPT DROP

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

status

string

Enum: enabled disabled deleted

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 enabled or disabled.
Use the Delete Firewall endpoint to delete a Firewall.

Request Samples

Response Samples

Responses

Firewall Delete

DELETE https://api.linode.com/v4/networking/firewalls/{firewallId}

Delete a Firewall resource by its ID. This will remove all of the Firewall’s Rules from any Linode services that the Firewall was assigned to.

A firewall_delete Event is generated when this endpoint returns successfully.

Cloud Firewall is not available in every data center region. For the current list of availability, access the Regions List ( GET /regions) endpoint or see the Cloud Firewall Product Documentation.

Authorizations

personalAccessToken
oauth	firewall:read_write

Path Parameters

firewallId

integer

Required

ID of the Firewall to access.

Request Samples

Response Samples

Responses

Firewall View

GET https://api.linode.com/v4/networking/firewalls/{firewallId}

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.

Cloud Firewall is not available in every data center region. For the current list of availability, access the Regions List ( GET /regions) endpoint or see the Cloud Firewall Product Documentation.

Authorizations

personalAccessToken
oauth	firewall:read_only

Path Parameters

firewallId

integer

Required

ID of the Firewall to access.

Request Samples

Response Samples

Responses

Firewall Update

PUT https://api.linode.com/v4/networking/firewalls/{firewallId}

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.

Cloud Firewall is not available in every data center region. For the current list of availability, access the Regions List ( GET /regions) endpoint or see the Cloud Firewall Product Documentation.

Authorizations

personalAccessToken
oauth	firewall:read_write

Path Parameters

firewallId

integer

Required

ID of the Firewall to access.

Request Body Schema

label

Filterable

string 3..32 characters

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, dashes (-), underscores (_) or periods (.).
Cannot have two dashes (--), underscores (__) or periods (..) in a row.
Must be between 3 and 32 characters.
Must be unique.

status

string

Enum: enabled disabled deleted

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 enabled or disabled.
Use the Delete Firewall endpoint to delete a Firewall.

Request Samples

Response Samples

Responses

Firewall Devices List

GET https://api.linode.com/v4/networking/firewalls/{firewallId}/devices

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.

Cloud Firewall is not available in every data center region. For the current list of availability, access the Regions List ( GET /regions) endpoint or see the Cloud Firewall Product Documentation.

Authorizations

personalAccessToken
oauth	firewall:read_only

Path Parameters

firewallId

integer

Required

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/v4/networking/firewalls/{firewallId}/devices

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 a single Linode service at a time. Additional disabled Firewalls can be assigned to a service, but they cannot be enabled if another active Firewall is 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.

Cloud Firewall is not available in every data center region. For the current list of availability, access the Regions List ( GET /regions) endpoint or see the Cloud Firewall Product Documentation.

Authorizations

personalAccessToken
oauth	firewall:read_write

Path Parameters

firewallId

integer

Required

ID of the Firewall to access.

Request Body Schema

id Required	`integer` The entity’s ID
type Required	`string` Enum: `linode` The entity’s type.

Request Samples

Response Samples

Responses

Firewall Device Delete

DELETE https://api.linode.com/v4/networking/firewalls/{firewallId}/devices/{deviceId}

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.

Cloud Firewall is not available in every data center region. For the current list of availability, access the Regions List ( GET /regions) endpoint or see the Cloud Firewall Product Documentation.

Authorizations

personalAccessToken
oauth	firewall:read_write

Path Parameters

firewallId	`integer` Required ID of the Firewall to access.
deviceId	`integer` Required ID of the Firewall Device to access.

Request Samples

Response Samples

Responses

Firewall Device View

GET https://api.linode.com/v4/networking/firewalls/{firewallId}/devices/{deviceId}

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.

Cloud Firewall is not available in every data center region. For the current list of availability, access the Regions List ( GET /regions) endpoint or see the Cloud Firewall Product Documentation.

Authorizations

personalAccessToken
oauth	firewall:read_only

Path Parameters

firewallId	`integer` Required ID of the Firewall to access.
deviceId	`integer` Required ID of the Firewall Device to access.

Request Samples

Response Samples

Responses

Firewall Rules List

GET https://api.linode.com/v4/networking/firewalls/{firewallId}/rules

Returns the inbound and outbound Rules for a Firewall.

This endpoint is in beta.

Gain access to Linode Cloud Firewall by signing up for our Greenlight Beta program.
During the beta, Cloud Firewall is not available in every data center region. For the current list of availability, see the Cloud Firewall Product Documentation.
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

integer

Required

ID of the Firewall to access.

Request Samples

Response Samples

Responses

Firewall Rules Update

PUT https://api.linode.com/v4/networking/firewalls/{firewallId}/rules

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.

Cloud Firewall is not available in every data center region. For the current list of availability, access the Regions List ( GET /regions) endpoint or see the Cloud Firewall Product Documentation.

Authorizations

personalAccessToken
oauth	firewall:read_write

Path Parameters

firewallId

integer

Required

ID of the Firewall to access.

Request Body Schema

inbound

array of objects

action

string

Enum: ACCEPT DROP

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.

addresses

object

ipv4	`array of strings` A list of IPv4 addresses or networks. Must be in IP/mask format.
ipv6	`array of strings` A list of IPv6 addresses or networks. Must be in IP/mask format.

description

string 1..100 characters

Used to describe this rule. For display purposes only.

label

string 3..32 characters

Used to identify this rule. For display purposes only.

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: TCP UDP ICMP

The type of network traffic to allow.

inbound_policy

string

Enum: ACCEPT DROP

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

outbound

array of objects

action

string

Enum: ACCEPT DROP

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.

addresses

object

ipv4	`array of strings` A list of IPv4 addresses or networks. Must be in IP/mask format.
ipv6	`array of strings` A list of IPv6 addresses or networks. Must be in IP/mask format.

description

string 1..100 characters

Used to describe this rule. For display purposes only.

label

string 3..32 characters

Used to identify this rule. For display purposes only.

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: TCP UDP ICMP

The type of network traffic to allow.

outbound_policy

string

Enum: ACCEPT DROP

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

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

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.

personalAccessToken
oauth	ips:read_write,linodes:read_write

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.

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.

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

VLANs List

GET https://api.linode.com/v4/networking/vlans

Returns a list of all Virtual Local Area Networks (VLANs) on your Account. VLANs provide a mechanism for secure communication between two or more Linodes that are assigned to the same VLAN and are both within the same Layer 2 broadcast domain.

VLANs are created and attached to Linodes by using the interfaces property for the following endpoints:

Linode Create ( POST /linode/instances)
Configuration Profile Create ( POST /linode/instances/{linodeId}/configs)
Configuration Profile Update ( PUT /linode/instances/{linodeId}/configs/{configId})

There are several ways to detach a VLAN from a Linode:

Update the active Configuration Profile to remove the VLAN interface, then reboot the Linode.
Create a new Configuration Profile without the VLAN interface, then reboot the Linode into the new Configuration Profile.
Delete the Linode.

VLANs cannot be manually renamed. If a VLAN’s label must be changed, create a new VLAN and attach all required Linodes to it.

VLANs cannot be manually deleted. There is no need to manually delete a VLAN. If a VLAN is no longer needed, detach it from all Linodes. A VLANs that are not attached to any Linodes are automatically deleted within a short timeframe.

Note: Only Next Generation Network (NGN) data centers support VLANs. Use the Regions ( /regions) endpoint to view the capabilities of data center regions. If a VLAN is attached to your Linode and you attempt to migrate or clone it to a non-NGN data center, the migration or cloning will not initiate. If a Linode cannot be migrated because of an incompatibility, you will be prompted to select a different data center or contact support.

Authorizations

personalAccessToken
oauth	linodes: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.

Filters

Networking v4.96.0

Firewalls List

Authorizations

Query Parameters

Request Samples

Response Samples

Responses

Firewall Create

Authorizations

Request Body Schema

Request Samples

Response Samples

Responses

Firewall Delete

Authorizations

Path Parameters

Request Samples

Response Samples

Responses

Firewall View

Authorizations

Path Parameters

Request Samples

Response Samples

Responses

Firewall Update

Authorizations

Path Parameters

Request Body Schema

Request Samples

Response Samples

Responses

Firewall Devices List

Authorizations

Path Parameters

Query Parameters

Request Samples

Response Samples

Responses

Firewall Device Create

Authorizations

Path Parameters

Request Body Schema

Request Samples

Response Samples

Responses

Firewall Device Delete

Authorizations

Path Parameters

Request Samples

Response Samples

Responses

Firewall Device View

Authorizations

Path Parameters

Request Samples

Response Samples

Responses

Firewall Rules List

Authorizations

Path Parameters

Request Samples

Response Samples

Responses

Firewall Rules Update

Authorizations

Path Parameters

Request Body Schema

Request Samples

Response Samples

Responses

IP Addresses List

Authorizations

Request Samples

Response Samples

Responses

IP Address Allocate

Authorizations

Request Body Schema