Networking v4.141.0
Firewalls List
Returns a paginated list of accessible Firewalls.
Authorizations
personalAccessToken | |
oauth | firewall:read_only |
Query Parameters
page |
The page of a collection to return. |
page_size |
The number of items to return per page. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/firewalls
linode-cli firewalls list
Response Samples
{
"data": [
{
"created": "2018-01-01T00:01:01",
"id": 123,
"label": "firewall123",
"rules": {
"inbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"inbound_policy": "DROP",
"outbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"outbound_policy": "DROP"
},
"status": "enabled",
"tags": [
"example tag",
"another example"
],
"updated": "2018-01-02T00:01:01"
}
],
"page": 1,
"pages": 1,
"results": 1
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
data | array
of objects
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
page | integer The current page. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
pages | integer The total number of pages. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
results | integer The total number of results. |
errors | array
of objects
|
Firewall Create
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 service and apply its Rules to the device. Requiresread_write
User’s Grants to the device. Currently, Firewalls can only be assigned to Linode instances.A Firewall can be assigned to multiple Linode instances at a time.
A Linode instance can have one active, assigned Firewall 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.
A
firewall_create
Event is generated when this endpoint returns successfully.
Authorizations
personalAccessToken | |
oauth | firewall:read_write |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "firewall123",
"rules": {
"inbound_policy": "DROP",
"inbound": [
{
"protocol": "TCP",
"ports": "22, 80, 443",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"action": "ACCEPT",
"label": "inbound-rule123",
"description": "An example inbound rule description."
}
],
"outbound_policy": "DROP",
"outbound": [
{
"protocol": "TCP",
"ports": "49152-65535",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"action": "ACCEPT",
"label": "outbound-rule123",
"description": "An example outbound rule description."
}
]
},
"devices": {
"linodes": [
123
]
},
"tags": [
"example tag",
"another example"
]
}' \
https://api.linode.com/v4/networking/firewalls
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.1", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}, "action": "ACCEPT"}]' \
--rules.outbound '[{"protocol": "TCP", "ports": "49152-65535", "addresses": {"ipv4": ["192.0.2.0/24"],"ipv6": ["2001:DB8::/32"]}, "action": "DROP", "label": "outbound-rule123", "description": "An example outbound rule description."}]'
Request Body Schema
devices | object Devices to create for this Firewall. When a Device is created, the Firewall is assigned to its associated service. Currently, Devices can only be created for Linode instances.
| ||||||||||||||||||||||||||||||||||||||||
label Filterable Required | string
3..32
charactersThe Firewall’s label, for display purposes only. Firewall labels have the following constraints:
| ||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||
tags Filterable | array
of strings An array of tags applied to this object. Tags are for organizational purposes only. |
Response Samples
{
"created": "2018-01-01T00:01:01",
"id": 123,
"label": "firewall123",
"rules": {
"inbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"inbound_policy": "DROP",
"outbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"outbound_policy": "DROP"
},
"status": "enabled",
"tags": [
"example tag",
"another example"
],
"updated": "2018-01-02T00:01:01"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
created Filterable | string<date-time> When this Firewall was created. | ||||||||||||||||||||||||||||||||||||||||
id Filterable | integer The Firewall’s unique ID. | ||||||||||||||||||||||||||||||||||||||||
label Filterable | string
3..32
charactersThe Firewall’s label, for display purposes only. Firewall labels have the following constraints:
| ||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||
status | string Enum:
enabled
disabled
deleted The status of this Firewall.
| ||||||||||||||||||||||||||||||||||||||||
tags Filterable | array
of strings An array of tags applied to this object. Tags are for organizational purposes only. | ||||||||||||||||||||||||||||||||||||||||
updated Filterable | string<date-time> When this Firewall was last updated. |
errors | array
of objects
|
Firewall Delete
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.
Authorizations
personalAccessToken | |
oauth | firewall:read_write |
Path Parameters
firewallId | integer RequiredID of the Firewall to access. |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/networking/firewalls/123
linode-cli firewalls delete 123
Response Samples
{}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
errors | array
of objects
|
Firewall View
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.
Authorizations
personalAccessToken | |
oauth | firewall:read_only |
Path Parameters
firewallId | integer RequiredID of the Firewall to access. |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/firewalls/123
linode-cli firewalls view 123
Response Samples
{
"created": "2018-01-01T00:01:01",
"id": 123,
"label": "firewall123",
"rules": {
"inbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"inbound_policy": "DROP",
"outbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"outbound_policy": "DROP"
},
"status": "enabled",
"tags": [
"example tag",
"another example"
],
"updated": "2018-01-02T00:01:01"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
created Filterable | string<date-time> When this Firewall was created. | ||||||||||||||||||||||||||||||||||||||||
id Filterable | integer The Firewall’s unique ID. | ||||||||||||||||||||||||||||||||||||||||
label Filterable | string
3..32
charactersThe Firewall’s label, for display purposes only. Firewall labels have the following constraints:
| ||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||
status | string Enum:
enabled
disabled
deleted The status of this Firewall.
| ||||||||||||||||||||||||||||||||||||||||
tags Filterable | array
of strings An array of tags applied to this object. Tags are for organizational purposes only. | ||||||||||||||||||||||||||||||||||||||||
updated Filterable | string<date-time> When this Firewall was last updated. |
errors | array
of objects
|
Firewall Update
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
ordisabled
by this endpoint, but it cannot be set todeleted
. 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.
Authorizations
personalAccessToken | |
oauth | firewall:read_write |
Path Parameters
firewallId | integer RequiredID of the Firewall to access. |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"status": "disabled"
}' \
https://api.linode.com/v4/networking/firewalls/123
linode-cli firewalls update 123 \
--status disabled
Request Body Schema
label Filterable | string
3..32
charactersThe Firewall’s label, for display purposes only. Firewall labels have the following constraints:
|
status | string Enum:
enabled
disabled The status to be applied to this Firewall.
|
tags Filterable | array
of strings An array of tags applied to this object. Tags are for organizational purposes only. |
Response Samples
{
"created": "2018-01-01T00:01:01",
"id": 123,
"label": "firewall123",
"rules": {
"inbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"inbound_policy": "DROP",
"outbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"outbound_policy": "DROP"
},
"status": "enabled",
"tags": [
"example tag",
"another example"
],
"updated": "2018-01-02T00:01:01"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
created Filterable | string<date-time> When this Firewall was created. | ||||||||||||||||||||||||||||||||||||||||
id Filterable | integer The Firewall’s unique ID. | ||||||||||||||||||||||||||||||||||||||||
label Filterable | string
3..32
charactersThe Firewall’s label, for display purposes only. Firewall labels have the following constraints:
| ||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||
status | string Enum:
enabled
disabled
deleted The status of this Firewall.
| ||||||||||||||||||||||||||||||||||||||||
tags Filterable | array
of strings An array of tags applied to this object. Tags are for organizational purposes only. | ||||||||||||||||||||||||||||||||||||||||
updated Filterable | string<date-time> When this Firewall was last updated. |
errors | array
of objects
|
Firewall Devices List
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.
Authorizations
personalAccessToken | |
oauth | firewall:read_only |
Path Parameters
firewallId | integer RequiredID of the Firewall to access. |
Query Parameters
page |
The page of a collection to return. |
page_size |
The number of items to return per page. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/firewalls/123/devices
linode-cli firewalls devices-list 123
Response Samples
{
"data": [
{
"created": "2018-01-01T00:01:01",
"entity": {
"id": 123,
"label": "my-linode",
"type": "linode",
"url": "/v4/linode/instances/123"
},
"id": 123,
"updated": "2018-01-02T00:01:01"
}
],
"page": 1,
"pages": 1,
"results": 1
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
data | array
of objects
| ||||||||||||||||
page | integer The current page. | ||||||||||||||||
pages | integer The total number of pages. | ||||||||||||||||
results | integer The total number of results. |
errors | array
of objects
|
Firewall Device Create
Creates a Firewall Device, which assigns a Firewall to a service (referred to
as the Device’s entity
) and applies the Firewall’s Rules to the device.
Currently, only Devices with an entity of type
linode
are accepted.A Firewall can be assigned to multiple Linode instances at a time.
A Linode instance can have one active, assigned Firewall 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.
A
firewall_device_add
Event is generated when the Firewall Device is added successfully.
Authorizations
personalAccessToken | |
oauth | firewall:read_write |
Path Parameters
firewallId | integer RequiredID of the Firewall to access. |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"type": "linode",
"id": 123
}' \
https://api.linode.com/v4/networking/firewalls/123/devices
linode-cli firewalls device-create 123 \
--id 456 \
--type "linode"
Request Body Schema
id Required | integer The entity’s ID |
type Required | string Enum:
linode The entity’s type. |
Response Samples
{
"created": "2018-01-01T00:01:01",
"entity": {
"id": 123,
"label": "my-linode",
"type": "linode",
"url": "/v4/linode/instances/123"
},
"id": 123,
"updated": "2018-01-02T00:01:01"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
created Filterable | string<date-time> When this Device was created. | ||||||||
entity | object The Linode service that this Firewall has been applied to.
| ||||||||
id Filterable | integer The Device’s unique ID | ||||||||
updated Filterable | string<date-time> When this Device was last updated. |
errors | array
of objects
|
Firewall Device Delete
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.
Authorizations
personalAccessToken | |
oauth | firewall:read_write |
Path Parameters
firewallId | integer RequiredID of the Firewall to access. |
deviceId | integer RequiredID of the Firewall Device to access. |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/networking/firewalls/123/devices/456
linode-cli firewalls device-delete 123 456
Response Samples
{}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
errors | array
of objects
|
Firewall Device View
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.
Authorizations
personalAccessToken | |
oauth | firewall:read_only |
Path Parameters
firewallId | integer RequiredID of the Firewall to access. |
deviceId | integer RequiredID of the Firewall Device to access. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/firewalls/123/devices/456
linode-cli firewalls device-view \
123 456
Response Samples
{
"created": "2018-01-01T00:01:01",
"entity": {
"id": 123,
"label": "my-linode",
"type": "linode",
"url": "/v4/linode/instances/123"
},
"id": 123,
"updated": "2018-01-02T00:01:01"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
created Filterable | string<date-time> When this Device was created. | ||||||||
entity | object The Linode service that this Firewall has been applied to.
| ||||||||
id Filterable | integer The Device’s unique ID | ||||||||
updated Filterable | string<date-time> When this Device was last updated. |
errors | array
of objects
|
Firewall Rules List
Returns the inbound and outbound Rules for a Firewall.
Authorizations
personalAccessToken | |
oauth | firewall:read_only |
Path Parameters
firewallId | integer RequiredID of the Firewall to access. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/firewalls/123/rules
linode-cli firewalls rules-list 123
Response Samples
{
"inbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"inbound_policy": "DROP",
"outbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"outbound_policy": "DROP"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
inbound | array
of objects The inbound rules for the firewall, as a JSON array.
| ||||||||||||||||
inbound_policy | string Enum:
ACCEPT
DROP The default behavior for inbound traffic. This setting can be overridden by
updating the | ||||||||||||||||
outbound | array
of objects The outbound rules for the firewall, as a JSON array.
| ||||||||||||||||
outbound_policy | string Enum:
ACCEPT
DROP The default behavior for outbound traffic. This setting can be overridden by
updating the |
errors | array
of objects
|
Firewall Rules Update
Updates the inbound and outbound Rules for a Firewall.
Note: This command replaces all of a Firewall’s inbound
and/or outbound
rulesets with the values specified in your request.
Authorizations
personalAccessToken | |
oauth | firewall:read_write |
Path Parameters
firewallId | integer RequiredID of the Firewall to access. |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"inbound_policy": "DROP",
"inbound": [
{
"protocol": "TCP",
"ports": "22, 80, 443",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"action": "ACCEPT",
"label": "inbound-rule123",
"description": "An example inbound rule description."
}
],
"outbound_policy": "DROP",
"outbound": [
{
"protocol": "TCP",
"ports": "49152-65535",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"action": "ACCEPT",
"label": "outbound-rule123",
"description": "An example outbound rule description."
}
]
}' \
https://api.linode.com/v4/networking/firewalls/123/rules
linode-cli firewalls rules-update 123 \
--inbound '[{"action":"ACCEPT", "protocol": "TCP", "ports": "22, 80, 8080, 443", "addresses": {"ipv4": ["192.0.2.1/32", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]' \
--outbound '[{"action":"DROP","protocol": "TCP", "ports": "49152-65535", "addresses": {"ipv4": ["192.0.2.1/32", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]'
Request Body Schema
inbound | array
of objects The inbound rules for the firewall, as a JSON array.
| ||||||||||||||||
inbound_policy | string Enum:
ACCEPT
DROP The default behavior for inbound traffic. This setting can be overridden by
updating the | ||||||||||||||||
outbound | array
of objects The outbound rules for the firewall, as a JSON array.
| ||||||||||||||||
outbound_policy | string Enum:
ACCEPT
DROP The default behavior for outbound traffic. This setting can be overridden by
updating the |
Response Samples
{
"inbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"inbound_policy": "DROP",
"outbound": [
{
"action": "ACCEPT",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"description": "An example firewall rule description.",
"label": "firewallrule123",
"ports": "22-24, 80, 443",
"protocol": "TCP"
}
],
"outbound_policy": "DROP"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
inbound | array
of objects The inbound rules for the firewall, as a JSON array.
| ||||||||||||||||
inbound_policy | string Enum:
ACCEPT
DROP The default behavior for inbound traffic. This setting can be overridden by
updating the | ||||||||||||||||
outbound | array
of objects The outbound rules for the firewall, as a JSON array.
| ||||||||||||||||
outbound_policy | string Enum:
ACCEPT
DROP The default behavior for outbound traffic. This setting can be overridden by
updating the |
errors | array
of objects
|
IP Addresses List
Returns a paginated list of IP Addresses on your Account, excluding private addresses.
Authorizations
personalAccessToken | |
oauth | ips:read_only |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/ips
linode-cli networking ips-list
Response Samples
{
"data": [
{
"address": "97.107.143.141",
"gateway": "97.107.143.1",
"linode_id": 123,
"prefix": 24,
"public": true,
"rdns": "test.example.org",
"region": "us-east",
"subnet_mask": "255.255.255.0",
"type": "ipv4"
}
],
"page": 1,
"pages": 1,
"results": 1
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
data | array
of objects
| ||||||||||||||||||
page | integer The current page. | ||||||||||||||||||
pages | integer The total number of pages. | ||||||||||||||||||
results | integer The total number of results. |
errors | array
of objects
|
IP Address Allocate
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 Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"type": "ipv4",
"public": true,
"linode_id": 123
}' \
https://api.linode.com/v4/networking/ips
linode-cli networking ip-add \
--type ipv4 \
--public true \
--linode_id 123
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. |
Response Samples
{
"address": "97.107.143.141",
"gateway": "97.107.143.1",
"linode_id": 123,
"prefix": 24,
"public": true,
"rdns": "test.example.org",
"region": "us-east",
"subnet_mask": "255.255.255.0",
"type": "ipv4"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
address | string<ip> The IP address. |
gateway Nullable | string<ip> The default gateway for this address. |
linode_id | integer The ID of the Linode this address currently belongs to. For IPv4 addresses, this is by default the Linode that this address was assigned to on creation, and these addresses my be moved using the /networking/ipv4/assign endpoint. For SLAAC and link-local addresses, this value may not be changed. |
prefix | integer The number of bits set in the subnet mask. |
public | boolean Whether this is a public or private IP address. |
rdns Nullable | 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. |
region Filterable | string The Region this IP address resides in. |
subnet_mask | string<ip> The mask that separates host bits from network bits for this address. |
type | string Enum:
ipv4
ipv6
ipv6/pool
ipv6/range The type of address this is. |
errors | array
of objects
|
IP Addresses Assign
Assign multiple IPv4 addresses and/or IPv6 ranges to multiple Linodes in one Region. This allows swapping, shuffling, or otherwise reorganizing IPs to your Linodes.
The following restrictions apply:
- All Linodes involved must have at least one public IPv4 address after assignment.
- Linodes may have no more than one assigned private IPv4 address.
- Linodes may have no more than one assigned IPv6 range.
Open a Support Ticket to request additional IPv4 addresses or IPv6 ranges beyond standard account limits.
Note: Removing an IP address that has been set as a Managed Linode’s ssh.ip
causes the Managed Linode’s SSH access settings to reset to their default values. To view and configure Managed Linode SSH settings, use the following commands:
- Linode’s Managed Settings View ( GET /managed/linode-settings/{linodeId})
- Linode’s Managed Settings Update ( PUT /managed/linode-settings/{linodeId})
Authorizations
personalAccessToken | |
oauth | ips:read_write,linodes:read_write |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"region": "us-east",
"assignments": [
{
"address": "192.0.2.1",
"linode_id": 123
},
{
"address": "2001:db8:3c4d:15::/64",
"linode_id": 234
}
]
}' \
https://api.linode.com/v4/networking/ips/assign
linode-cli networking ip-assign \
--region us-east \
--assignments.address 192.0.2.1 \
--assignments.linode_id 123 \
--assignments.address 2001:db8:3c4d:15::/64 \
--assignments.linode_id 234
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.
| ||||
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. |
Response Samples
{}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
errors | array
of objects
|
IP Addresses Share
Configure shared IPs.
IP sharing allows IP address reassignment (also referred to as IP failover) from one Linode to another if the primary Linode becomes unresponsive. This means that requests to the primary Linode’s IP address can be automatically rerouted to secondary Linodes at the configured shared IP addresses.
IP failover requires configuration of a failover service (such as Keepalived) within the internal system of the primary Linode.
Authorizations
personalAccessToken | |
oauth | ips:read_write,linodes:read_write |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"linode_id": 123,
"ips": [
"192.0.2.1",
"2001:db8:3c4d:15::"
]
}' \
https://api.linode.com/v4/networking/ips/share
linode-cli networking ip-share \
--linode_id 123 \
--ips 192.0.2.1 \
--ips 2001:db8:3c4d:15::
Request Body Schema
ips Required | array
of strings A list of secondary Linode IPs to share with the primary Linode.
|
linode_id Required | integer The ID of the primary Linode that the addresses will be shared with. |
Response Samples
{}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
errors | array
of objects
|
IP Address View
Returns information about a single IP Address on your Account.
Authorizations
personalAccessToken | |
oauth | ips:read_only |
Path Parameters
address | string<ip> RequiredThe address to operate on. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/ips/97.107.143.141
linode-cli networking ip-view 97.107.143.141
Response Samples
{
"address": "97.107.143.141",
"gateway": "97.107.143.1",
"linode_id": 123,
"prefix": 24,
"public": true,
"rdns": "test.example.org",
"region": "us-east",
"subnet_mask": "255.255.255.0",
"type": "ipv4"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
address | string<ip> The IP address. |
gateway Nullable | string<ip> The default gateway for this address. |
linode_id | integer The ID of the Linode this address currently belongs to. For IPv4 addresses, this is by default the Linode that this address was assigned to on creation, and these addresses my be moved using the /networking/ipv4/assign endpoint. For SLAAC and link-local addresses, this value may not be changed. |
prefix | integer The number of bits set in the subnet mask. |
public | boolean Whether this is a public or private IP address. |
rdns Nullable | 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. |
region Filterable | string The Region this IP address resides in. |
subnet_mask | string<ip> The mask that separates host bits from network bits for this address. |
type | string Enum:
ipv4
ipv6
ipv6/pool
ipv6/range The type of address this is. |
errors | array
of objects
|
IP Address RDNS Update
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 ip.linodeusercontent.com RDNS value.
Authorizations
personalAccessToken | |
oauth | ips:read_write |
Path Parameters
address | string<ip> RequiredThe address to operate on. |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"rdns": "test.example.org"
}' \
https://api.linode.com/v4/networking/ips/203.0.113.1
linode-cli networking ip-update \
203.0.113.1 \
--rdns "test.example.org"
Request Body Schema
rdns Nullable Required | 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. |
Response Samples
{
"address": "97.107.143.141",
"gateway": "97.107.143.1",
"linode_id": 123,
"prefix": 24,
"public": true,
"rdns": "test.example.org",
"region": "us-east",
"subnet_mask": "255.255.255.0",
"type": "ipv4"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
address | string<ip> The IP address. |
gateway Nullable | string<ip> The default gateway for this address. |
linode_id | integer The ID of the Linode this address currently belongs to. For IPv4 addresses, this is by default the Linode that this address was assigned to on creation, and these addresses my be moved using the /networking/ipv4/assign endpoint. For SLAAC and link-local addresses, this value may not be changed. |
prefix | integer The number of bits set in the subnet mask. |
public | boolean Whether this is a public or private IP address. |
rdns Nullable | 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. |
region Filterable | string The Region this IP address resides in. |
subnet_mask | string<ip> The mask that separates host bits from network bits for this address. |
type | string Enum:
ipv4
ipv6
ipv6/pool
ipv6/range The type of address this is. |
errors | array
of objects
|
Linodes Assign IPv4s
This command is equivalent to IP Addresses Assign ( POST /networking/ips/assign).
Assign multiple IPv4 addresses and/or IPv6 ranges to multiple Linodes in one Region. This allows swapping, shuffling, or otherwise reorganizing IPs to your Linodes.
The following restrictions apply:
- All Linodes involved must have at least one public IPv4 address after assignment.
- Linodes may have no more than one assigned private IPv4 address.
- Linodes may have no more than one assigned IPv6 range.
Open a Support Ticket to request additional IPv4 addresses or IPv6 ranges beyond standard account limits.
Note: Removing an IP address that has been set as a Managed Linode’s ssh.ip
causes the Managed Linode’s SSH access settings to reset to their default values. To view and configure Managed Linode SSH settings, use the following commands:
- Linode’s Managed Settings View ( GET /managed/linode-settings/{linodeId})
- Linode’s Managed Settings Update ( PUT /managed/linode-settings/{linodeId})
Authorizations
personalAccessToken | |
oauth | ips:read_write,linodes:read_write |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"region": "us-east",
"assignments": [
{
"address": "192.0.2.1",
"linode_id": 123
},
{
"address": "2001:db8:3c4d:15::/64",
"linode_id": 234
}
]
}' \
https://api.linode.com/v4/networking/ipv4/assign
linode-cli networking ip-assign \
--region us-east \
--assignments.address 192.0.2.1 \
--assignments.linode_id 123 \
--assignments.address 2001:db8:3c4d:15::/64 \
--assignments.linode_id 234
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.
| ||||
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. |
Response Samples
{}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
errors | array
of objects
|
IPv4 Sharing Configure
This command is equivalent to IP Addresses Share ( POST /networking/ips/share).
Configure shared IPs.
IP sharing allows IP address reassignment (also referred to as IP failover) from one Linode to another if the primary Linode becomes unresponsive. This means that requests to the primary Linode’s IP address can be automatically rerouted to secondary Linodes at the configured shared IP addresses.
IP failover requires configuration of a failover service (such as Keepalived) within the internal system of the primary Linode.
Authorizations
personalAccessToken | |
oauth | ips:read_write,linodes:read_write |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"linode_id": 123,
"ips": [
"192.0.2.1",
"192.0.2.2"
]
}' \
https://api.linode.com/v4/networking/ipv4/share
linode-cli networking ip-share \
--linode_id 123 \
--ips 192.0.2.1 \
--ips 192.0.2.2
Request Body Schema
ips Required | array
of strings A list of secondary Linode IPs to share with the primary Linode.
|
linode_id Required | integer The ID of the primary Linode that the addresses will be shared with. |
Response Samples
{}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
errors | array
of objects
|
IPv6 Pools List
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 |
The page of a collection to return. |
page_size |
The number of items to return per page. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/ipv6/pools
linode-cli networking v6-pools
Response Samples
{
"data": [
{
"prefix": 124,
"range": "2600:3c01::2:5000:0",
"region": "us-east",
"route_target": "2600:3c01::2:5000:f"
}
],
"page": 1,
"pages": 1,
"results": 1
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
data | array
of objects
| ||||||||
page | integer The current page. | ||||||||
pages | integer The total number of pages. | ||||||||
results | integer The total number of results. |
errors | array
of objects
|
IPv6 Ranges List
Displays the IPv6 ranges on your Account.
An IPv6 range is a
/64
or/54
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.
Access the IPv6 Range Create ( POST /networking/ipv6/ranges) endpoint to add a
/64
or/56
block of IPv6 addresses to your account.
Authorizations
personalAccessToken | |
oauth | ips:read_only |
Query Parameters
page |
The page of a collection to return. |
page_size |
The number of items to return per page. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/ipv6/ranges
linode-cli networking v6-ranges
Response Samples
{
"data": [
{
"prefix": 64,
"range": "2600:3c01::",
"region": "us-east",
"route_target": "2600:3c01::ffff:ffff:ffff:ffff"
}
],
"page": 1,
"pages": 1,
"results": 1
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
data | array
of objects
| ||||||||
page | integer The current page. | ||||||||
pages | integer The total number of pages. | ||||||||
results | integer The total number of results. |
errors | array
of objects
|
IPv6 Range Create
Creates an IPv6 Range and assigns it based on the provided Linode or route target IPv6 SLAAC address. See the ipv6
property when accessing the Linode View (
GET /linode/instances/{linodeId}) endpoint to view a Linode’s IPv6 SLAAC address.
- Either
linode_id
orroute_target
is required in a request. linode_id
androute_target
are mutually exclusive. Submitting values for both properties in a request results in an error.- Upon a successful request, an IPv6 range is created in the
Region that corresponds to the provided
linode_id
orroute_target
. - Your Linode is responsible for routing individual addresses in the range, or handling traffic for all the addresses in the range.
- Access the IP Addresses Assign ( POST /networking/ips/assign) endpoint to re-assign IPv6 Ranges to your Linodes.
Note: The following restrictions apply:
- A Linode can only have one IPv6 range targeting its SLAAC address.
- An account can only have one IPv6 range in each Region.
- Open a Support Ticket to request expansion of these restrictions.
Authorizations
personalAccessToken | |
oauth | ips:read_write,linodes:read_write |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"linode_id": 123,
"prefix_length": 64
}' \
https://api.linode.com/v4/networking/ipv6/ranges
linode-cli networking v6-range-create \
--linode_id 123 \
--prefix_length 64
Request Body Schema
linode_id | integer The ID of the Linode to assign this range to. The SLAAC address for the provided Linode is used as the range’s
|
prefix_length Required | integer Enum:
56
64 The prefix length of the IPv6 range. |
route_target | string<ipv6> The IPv6 SLAAC address to assign this range to.
|
Response Samples
{
"range": "2001:0db8::/64",
"route_target": "2001:0db8::1"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
range | string<ipv6/prefix_length> The IPv6 network range, including subnet and prefix length. |
route_target | string<ipv6> The route target IPV6 SLAAC address for this range. Does not include the prefix length. |
errors | array
of objects
|
IPv6 Range Delete
Removes this IPv6 range from your account and disconnects the range from any assigned Linodes.
Note: Shared IPv6 ranges cannot be deleted at this time. Please contact Customer Support for assistance.
Authorizations
personalAccessToken | |
oauth | ips:read_write |
Path Parameters
range | string<ipv6> RequiredThe IPv6 range to access. Corresponds to the Note: Omit the prefix length of the IPv6 range. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/networking/ipv6/ranges/2001:0db8::
linode-cli networking v6-range-delete 2001:0db8::
Response Samples
{}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
errors | array
of objects
|
IPv6 Range View
View IPv6 range information.
Authorizations
personalAccessToken | |
oauth | ips:read |
Path Parameters
range | string<ipv6> RequiredThe IPv6 range to access. Corresponds to the Note: Omit the prefix length of the IPv6 range. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" https://api.linode.com/v4/networking/ipv6/ranges/2001:0db8::
linode-cli networking v6-range-view 2001:0db8::
Response Samples
{
"is_bgp": false,
"linodes": [
123
],
"prefix": 64,
"range": "2600:3c01::",
"region": "us-east"
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
is_bgp | boolean Whether this IPv6 range is shared. |
linodes | array
of integers A list of Linodes targeted by this IPv6 range. Includes Linodes with IP sharing. |
prefix | integer The prefix length of the address, denoting how many addresses can be assigned from this range calculated as 2 128-prefix. |
range | string The IPv6 range of addresses in this pool. |
region | string The region for this range of IPv6 addresses. |
errors | array
of objects
|
VLANs List
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.
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.
Note: See our guide on Getting Started with VLANs to view additional limitations.
Authorizations
personalAccessToken | |
oauth | linodes:read_only |
Query Parameters
page |
The page of a collection to return. |
page_size |
The number of items to return per page. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4beta/networking/vlans/
linode-cli networking vlans-list
Response Samples
{
"data": [
{
"created": "2020-01-01T00:01:01",
"label": "vlan-example",
"linodes": [
111,
222
],
"region": "ap-west"
}
],
"page": 1,
"pages": 1,
"results": 1
}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
data | array
of objects
| ||||||||
page | integer The current page. | ||||||||
pages | integer The total number of pages. | ||||||||
results | integer The total number of results. |
errors | array
of objects
|