From 61dc2b51867553ec8a84dae08f2b5f0c71bd1cd7 Mon Sep 17 00:00:00 2001 From: hzoppetti Date: Mon, 26 Aug 2019 12:30:56 -0400 Subject: [PATCH 01/23] Adding POST/Firewall Work in Progress DO NOT MERGE --- openapi.yaml | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index b0fc56bd3..c345b6d96 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2593,6 +2593,66 @@ paths: - lang: CLI source: > linode-cli domains records-delete 123 234 + /firewalls: + x-linode-cli-command: firewalls + post: + x-linode-grant: read_write + tags: + - Firewalls + summary: Create Firewalls + description: > + Accepts a firewall setup and creates a new firewall for the user. At minimum, + the firewall config requires a label and 1 rule in either the inbound or outbound direction. + Other information is optional. + operationId: createFirewalls + x-linode-cli-action: create + security: + - personalAccessToken: [] + - oauth: + - firewalls:read_write + requestBody: + description: > + Information about the firewall you are creating. + content: + application/json: + schema: + $ref: '#/components/schemas/Firewall' + responses: + '200': + description: Creates a firewall_created event with a status of enabled. + content: + application/json: + schema: + $ref: '#/components/schemas/Firewall' + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -X POST -d '{ + "label": "this_is_a_label", + "rules": { + "inbound": [ + { + "type": "TCP", + "protocol": "HTTPS", + "start_port": 443 + } + ], + "outbound": [] + }, + "devices": { + "linodes": [], + "nodebalancers": [] + }, + "tags": [] + }' \ + https://api.linode.com/v4/firewalls + - lang: CLI + source: > + linode-cli firewalls create /images: x-linode-cli-command: images get: @@ -13110,6 +13170,112 @@ components: The username of the User who caused the Event. example: exampleUser x-linode-cli-display: 2 + Firewall: + type: object + description: > + A firewall object that controls incoming and outgoing network traffic. + properties: + label: + type: string + description: > + The current label of the firewall, for display purposes. + example: example-firewall + rules: + type: object + description: > + A structure containing the + oneOf: + - $ref: '#/components/schemas/FirewallInboundRule' + - $ref: '#/components/schemas/FirewallOutboundRule' + devices: + type: object + description: > + A dictionary of devices, Linodes and Nodebalancers, to use when setting up the firewalls. + properties: + linodes: + type: array + description: An array of Linode ids + example: [123, 345] + nodebalancers: + type: array + description: An array of NodeBalancer ids + example: [123] + tags: + x-linode-filterable: true + description: > + An array of tags applied to this object. Tags are for organizational + purposes only. + type: array + items: + type: string + example: + - example tag + - another example + required: + - label + - rules + FirewallInboundRule: + type: object + description: > + Rules passed to create or modify firewalls. + properties: + type: + type: string + enum: + - "TCP" + - "UDP" + description: > + Something here + example: "TCP" + protocol: + type: string + enum: + - "SSH" + - "HTTPS" + description: > + Something here + example: "HTTPS" + start_port: + type: integer + description: > + Inbound Start Port + example: + 443 + end_port: + type: integer + description: > + Optional. Must be greater than the start_port + FirewallOutboundRule: + type: object + description: > + Rules passed to create or modify firewalls. + properties: + type: + type: string + enum: + - "TCP" + - "UDP" + description: > + Something here + example: "TCP" + protocol: + type: string + enum: + - "SSH" + - "HTTPS" + description: > + Something here + example: "HTTPS" + start_port: + type: integer + description: > + Outbound Start Port + example: + 200 + end_port: + type: integer + description: > + Optional. Must be greater than the start_port Grant: type: object description: > From 403eb606c27b548e2e52589c12a65441df4f1e3e Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 11 Sep 2019 18:34:37 -0400 Subject: [PATCH 02/23] First changes --- openapi.yaml | 202 ++++++++++++++++++++++++++++----------------------- 1 file changed, 112 insertions(+), 90 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index c345b6d96..b34979468 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2593,66 +2593,6 @@ paths: - lang: CLI source: > linode-cli domains records-delete 123 234 - /firewalls: - x-linode-cli-command: firewalls - post: - x-linode-grant: read_write - tags: - - Firewalls - summary: Create Firewalls - description: > - Accepts a firewall setup and creates a new firewall for the user. At minimum, - the firewall config requires a label and 1 rule in either the inbound or outbound direction. - Other information is optional. - operationId: createFirewalls - x-linode-cli-action: create - security: - - personalAccessToken: [] - - oauth: - - firewalls:read_write - requestBody: - description: > - Information about the firewall you are creating. - content: - application/json: - schema: - $ref: '#/components/schemas/Firewall' - responses: - '200': - description: Creates a firewall_created event with a status of enabled. - content: - application/json: - schema: - $ref: '#/components/schemas/Firewall' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -X POST -d '{ - "label": "this_is_a_label", - "rules": { - "inbound": [ - { - "type": "TCP", - "protocol": "HTTPS", - "start_port": 443 - } - ], - "outbound": [] - }, - "devices": { - "linodes": [], - "nodebalancers": [] - }, - "tags": [] - }' \ - https://api.linode.com/v4/firewalls - - lang: CLI - source: > - linode-cli firewalls create /images: x-linode-cli-command: images get: @@ -7867,6 +7807,67 @@ paths: - lang: CLI source: > linode-cli networking v6-ranges + /networking/firewalls: + x-linode-cli-command: firewalls + post: + x-linode-grant: read_write + tags: + - Networking + summary: Create Firewall + description: > + Creates a firewall to filter traffic for the devices you specify. The `rules` property. + operationId: createFirewalls + x-linode-cli-action: create + security: + - personalAccessToken: [] + - oauth: + - firewalls:read_write + requestBody: + description: > + Information about the firewall you are creating. + content: + application/json: + schema: + required: + - rules + allOf: + - $ref: '#/components/schemas/Firewall' + responses: + '200': + description: Creates a firewall_created event with a status of enabled. + content: + application/json: + schema: + $ref: '#/components/schemas/Firewall' + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -X POST -d '{ + "label": "this_is_a_label", + "rules": { + "inbound": [ + { + "type": "TCP", + "protocol": "HTTPS", + "start_port": 443 + } + ], + "outbound": [] + }, + "devices": { + "linodes": [], + "nodebalancers": [] + }, + "tags": [] + }' \ + https://api.linode.com/v4/firewalls + - lang: CLI + source: > + linode-cli firewalls create /nodebalancers: x-linode-cli-command: nodebalancers get: @@ -13175,31 +13176,47 @@ components: description: > A firewall object that controls incoming and outgoing network traffic. properties: + id: + x-linode-filterable: true + type: integer + readOnly: true + description: > + The Id of the Firewall. + example: 123 label: + x-linode-filterable: true type: string description: > The current label of the firewall, for display purposes. example: example-firewall - rules: - type: object + created: + x-linode-filterable: true + type: string + format: date-time + readOnly: true description: > - A structure containing the - oneOf: - - $ref: '#/components/schemas/FirewallInboundRule' - - $ref: '#/components/schemas/FirewallOutboundRule' - devices: + When this Firewall was created. + example: '2018-01-01T00:01:01' + x-linode-cli-display: 5 + status: + type: string + readOnly: true + description: > + The status of this Firewall service. + enum: + - "enabled" + - "disabled" + - "deleted" + rules: type: object description: > - A dictionary of devices, Linodes and Nodebalancers, to use when setting up the firewalls. + Inbound and outbound rules configurations to apply to the service. properties: - linodes: - type: array - description: An array of Linode ids - example: [123, 345] - nodebalancers: - type: array - description: An array of NodeBalancer ids - example: [123] + inbound: + $ref: '#/components/schemas/FirewallInboundRule' + outbound: + type: object + $ref: '#/components/schemas/FirewallOutboundRule' tags: x-linode-filterable: true description: > @@ -13211,29 +13228,34 @@ components: example: - example tag - another example - required: - - label - - rules + devices: + type: object + description: > + A dictionary of devices to use when setting up the firewalls. + properties: + linodes: + description: An array of Linode ids + type: array + items: + type: integer + example: + - 123 + - 456 FirewallInboundRule: type: object description: > - Rules passed to create or modify firewalls. + Rules passed to create or modify firewalls. If you are included on the Firewall set of rules, + you are allowed by default, and all others will be denied. properties: - type: + protocol: type: string enum: + - "ALL" - "TCP" - "UDP" + - "ICMP" description: > - Something here - example: "TCP" - protocol: - type: string - enum: - - "SSH" - - "HTTPS" - description: > - Something here + The protocol of the rule. example: "HTTPS" start_port: type: integer From ec67327bef52a55476951eba12d10cd201579648 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 12 Sep 2019 15:12:36 -0400 Subject: [PATCH 03/23] More edits to Post Firewalls --- openapi.yaml | 76 +++++++++++++++++++++++----------------------------- 1 file changed, 34 insertions(+), 42 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index b34979468..5899a0361 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7815,7 +7815,9 @@ paths: - Networking summary: Create Firewall description: > - Creates a firewall to filter traffic for the devices you specify. The `rules` property. + Creates a firewall whitelist to filter network traffic for the devices you specify. When the Firewall service + is added for a specific device, all inbound and outbound ports are blocked by default. Use the `rules` property to + create access rules to open traffic specific ports. operationId: createFirewalls x-linode-cli-action: create security: @@ -13210,13 +13212,12 @@ components: rules: type: object description: > - Inbound and outbound rules configurations to apply to the service. + The inbound and outbound access rules to apply to the Firewall. properties: inbound: - $ref: '#/components/schemas/FirewallInboundRule' + $ref: '#/components/schemas/FirewallRuleConfig' outbound: - type: object - $ref: '#/components/schemas/FirewallOutboundRule' + $ref: '#/components/schemas/FirewallRuleConfig' tags: x-linode-filterable: true description: > @@ -13241,13 +13242,15 @@ components: example: - 123 - 456 - FirewallInboundRule: + FirewallRuleConfig: type: object description: > - Rules passed to create or modify firewalls. If you are included on the Firewall set of rules, - you are allowed by default, and all others will be denied. + This Firewall's inbound and outbound access rules. + required: + - type + - start_port properties: - protocol: + type: type: string enum: - "ALL" @@ -13255,49 +13258,38 @@ components: - "UDP" - "ICMP" description: > - The protocol of the rule. + The type of network traffic to allow. example: "HTTPS" start_port: type: integer description: > - Inbound Start Port + Start Port example: 443 end_port: type: integer description: > - Optional. Must be greater than the start_port - FirewallOutboundRule: - type: object - description: > - Rules passed to create or modify firewalls. - properties: - type: - type: string - enum: - - "TCP" - - "UDP" - description: > - Something here - example: "TCP" - protocol: - type: string - enum: - - "SSH" - - "HTTPS" - description: > - Something here - example: "HTTPS" - start_port: - type: integer - description: > - Outbound Start Port - example: - 200 - end_port: - type: integer + The end port must be greater than or equal to the start port. + addresses: + type: object description: > - Optional. Must be greater than the start_port + Whitelisted IPv4 or IPv6 addresses. + properties: + ipv4: + description: A list of ipv4 addresses. + type: array + items: + type: string + example: + - "192.0.2.0" + - "192.0.2.1" + ipv6: + description: A list of ipv6 addresses. + type: array + items: + type: string + example: + - "2001:DB8::/32" Grant: type: object description: > From 3341d10b6753e5196be14371e51196e04e0d5947 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Mon, 16 Sep 2019 18:54:57 -0400 Subject: [PATCH 04/23] Update POST /networking/firewalls Updates reflect latest dev changes to collection. --- openapi.yaml | 70 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 43 insertions(+), 27 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 5899a0361..190743026 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7815,18 +7815,16 @@ paths: - Networking summary: Create Firewall description: > - Creates a firewall whitelist to filter network traffic for the devices you specify. When the Firewall service - is added for a specific device, all inbound and outbound ports are blocked by default. Use the `rules` property to - create access rules to open traffic specific ports. + Creates a Firewall to filter network traffic. When the Firewall service + is added to a specific device, all inbound and outbound ports are blocked by default. Use the `rules` property to + create access rules that open network traffic to specific ports. operationId: createFirewalls x-linode-cli-action: create security: - personalAccessToken: [] - oauth: - - firewalls:read_write + - firewall:read_write requestBody: - description: > - Information about the firewall you are creating. content: application/json: schema: @@ -7836,7 +7834,7 @@ paths: - $ref: '#/components/schemas/Firewall' responses: '200': - description: Creates a firewall_created event with a status of enabled. + description: Returns information about the created Firewall. content: application/json: schema: @@ -7849,7 +7847,7 @@ paths: curl -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -X POST -d '{ - "label": "this_is_a_label", + "label": "firewall123", "rules": { "inbound": [ { @@ -7861,8 +7859,7 @@ paths: "outbound": [] }, "devices": { - "linodes": [], - "nodebalancers": [] + "linodes": [123, 456], }, "tags": [] }' \ @@ -13183,14 +13180,26 @@ components: type: integer readOnly: true description: > - The Id of the Firewall. + The Firewall's unique ID. example: 123 + x-linode-cli-display: 1 label: x-linode-filterable: true type: string description: > - The current label of the firewall, for display purposes. - example: example-firewall + 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. + example: "firewall123" + minLength: 3 + maxLength: 32 + pattern: '^[a-zA-Z]((?!--|__|..)[a-zA-Z0-9-_.])+$' + x-linode-cli-display: 2 created: x-linode-filterable: true type: string @@ -13199,7 +13208,7 @@ components: description: > When this Firewall was created. example: '2018-01-01T00:01:01' - x-linode-cli-display: 5 + x-linode-cli-display: 4 status: type: string readOnly: true @@ -13209,6 +13218,8 @@ components: - "enabled" - "disabled" - "deleted" + example: "enabled" + x-linode-cli-display: 3 rules: type: object description: > @@ -13227,12 +13238,12 @@ components: items: type: string example: - - example tag - - another example + - "example tag" + - "another example" devices: type: object description: > - A dictionary of devices to use when setting up the firewalls. + The devices that this Firewall will be applied to. properties: linodes: description: An array of Linode ids @@ -13242,15 +13253,17 @@ components: example: - 123 - 456 + x-linode-cli-display: 5 FirewallRuleConfig: type: object description: > - This Firewall's inbound and outbound access rules. + This Firewall's inbound and outbound access rules. To open traffic on a range of ports + specify a `start_port` and an `end_port`. required: - - type + - protocol - start_port properties: - type: + protocol: type: string enum: - "ALL" @@ -13259,32 +13272,35 @@ components: - "ICMP" description: > The type of network traffic to allow. - example: "HTTPS" + example: "TCP" start_port: type: integer description: > - Start Port + The port on which traffic will be allowed. Must be a value of `1-65535`. example: - 443 + - 20 end_port: type: integer description: > - The end port must be greater than or equal to the start port. + The end port for a range of ports on which traffic will be allowed. This port must be greater than or equal to the `start_port` + and must be a value of `1-65535`. + example: + - 22 addresses: type: object description: > Whitelisted IPv4 or IPv6 addresses. properties: ipv4: - description: A list of ipv4 addresses. + description: A list of IPv4 addresses or networks. type: array items: type: string example: - - "192.0.2.0" - "192.0.2.1" + - "192.0.2.0/24" ipv6: - description: A list of ipv6 addresses. + description: A list of IPv6 addresses or networks. type: array items: type: string From 1251b1a6180ff7df08f1ad1b855a681a06a033ac Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Tue, 17 Sep 2019 12:09:41 -0400 Subject: [PATCH 05/23] Improve description text for POST /networking/firewalls Add information about inbound and outbound behavior. --- openapi.yaml | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 190743026..4b190a40a 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7815,9 +7815,9 @@ paths: - Networking summary: Create Firewall description: > - Creates a Firewall to filter network traffic. When the Firewall service - is added to a specific device, all inbound and outbound ports are blocked by default. Use the `rules` property to - create access rules that open network traffic to specific ports. + Creates a Firewall to filter network traffic. Use the `rules` property to + create inbound and outbound access rules. A single Firewall can be applied to + Linode services by specifying them in the `devices` object. operationId: createFirewalls x-linode-cli-action: create security: @@ -13224,11 +13224,19 @@ components: type: object description: > The inbound and outbound access rules to apply to the Firewall. + + * A minimum of one open inbound port is required. Any inbound + port that is not open will be blocked. + * Outbound rules are optional. When no outbound ports are open, all outbound + ports are allowed. If you open one outbound port or more, all + remaining outbound ports will be blocked. properties: inbound: $ref: '#/components/schemas/FirewallRuleConfig' outbound: $ref: '#/components/schemas/FirewallRuleConfig' + required: + - inbound tags: x-linode-filterable: true description: > @@ -13243,7 +13251,8 @@ components: devices: type: object description: > - The devices that this Firewall will be applied to. + The devices that this Firewall will be applied to. Currently, you + can only add a Firewall to Linodes. properties: linodes: description: An array of Linode ids @@ -13257,7 +13266,7 @@ components: FirewallRuleConfig: type: object description: > - This Firewall's inbound and outbound access rules. To open traffic on a range of ports + This Firewall's access rules. To open traffic on a range of ports specify a `start_port` and an `end_port`. required: - protocol From f29d146a4468b8b9417aace62e7dae2b02cedced Mon Sep 17 00:00:00 2001 From: hzoppetti Date: Tue, 17 Sep 2019 13:57:55 -0400 Subject: [PATCH 06/23] added beta server and indents --- openapi.yaml | 55 ++++++++++++++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 4b190a40a..7373ed44e 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7811,6 +7811,8 @@ paths: x-linode-cli-command: firewalls post: x-linode-grant: read_write + servers: + - url: https://api.linode.com/v4beta tags: - Networking summary: Create Firewall @@ -7818,6 +7820,12 @@ paths: Creates a Firewall to filter network traffic. Use the `rules` property to create inbound and outbound access rules. A single Firewall can be applied to Linode services by specifying them in the `devices` object. + + + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with + `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + updates in the future. This notice will be removed when this endpoint is out of + beta. operationId: createFirewalls x-linode-cli-action: create security: @@ -13195,7 +13203,7 @@ components: * 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. - example: "firewall123" + example: firewall123 minLength: 3 maxLength: 32 pattern: '^[a-zA-Z]((?!--|__|..)[a-zA-Z0-9-_.])+$' @@ -13215,10 +13223,10 @@ components: description: > The status of this Firewall service. enum: - - "enabled" - - "disabled" - - "deleted" - example: "enabled" + - enabled + - disabled + - deleted + example: enabled x-linode-cli-display: 3 rules: type: object @@ -13231,16 +13239,16 @@ components: ports are allowed. If you open one outbound port or more, all remaining outbound ports will be blocked. properties: - inbound: - $ref: '#/components/schemas/FirewallRuleConfig' - outbound: - $ref: '#/components/schemas/FirewallRuleConfig' + inbound: + $ref: '#/components/schemas/FirewallRuleConfig' + outbound: + $ref: '#/components/schemas/FirewallRuleConfig' required: - inbound tags: x-linode-filterable: true description: > - An array of tags applied to this object. Tags are for organizational + An array of tags applied to this object. Tags are for organizational purposes only. type: array items: @@ -13269,32 +13277,30 @@ components: This Firewall's access rules. To open traffic on a range of ports specify a `start_port` and an `end_port`. required: - - protocol - - start_port + - protocol + - start_port properties: protocol: type: string enum: - - "ALL" - - "TCP" - - "UDP" - - "ICMP" + - ALL + - TCP + - UDP + - ICMP description: > The type of network traffic to allow. - example: "TCP" + example: TCP start_port: type: integer description: > The port on which traffic will be allowed. Must be a value of `1-65535`. - example: - - 20 + example: 20 end_port: type: integer description: > The end port for a range of ports on which traffic will be allowed. This port must be greater than or equal to the `start_port` and must be a value of `1-65535`. - example: - - 22 + example: 22 addresses: type: object description: > @@ -13306,15 +13312,14 @@ components: items: type: string example: - - "192.0.2.1" - - "192.0.2.0/24" + - "192.0.2.1" + - "192.0.2.0/24" ipv6: description: A list of IPv6 addresses or networks. type: array items: type: string - example: - - "2001:DB8::/32" + example: "2001:DB8::/32" Grant: type: object description: > From 6376f47b5b13a3da7f41e5ba9b2a0e8c61e728db Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Tue, 17 Sep 2019 14:21:13 -0400 Subject: [PATCH 07/23] Remove unnecessary quotations from examples --- openapi.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 7373ed44e..5d79673a0 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -13254,8 +13254,8 @@ components: items: type: string example: - - "example tag" - - "another example" + - example tag + - another example devices: type: object description: > @@ -13312,14 +13312,14 @@ components: items: type: string example: - - "192.0.2.1" - - "192.0.2.0/24" + - 192.0.2.1 + - 192.0.2.0/24 ipv6: description: A list of IPv6 addresses or networks. type: array items: type: string - example: "2001:DB8::/32" + example: 2001:DB8::/32 Grant: type: object description: > From a03d80d583ed05a9970501c3f0b8e06dff037581 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 18 Sep 2019 13:06:36 -0400 Subject: [PATCH 08/23] Add GET /networking/firewalls/{firewallId} --- openapi.yaml | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 5d79673a0..dfd1b8a61 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7875,6 +7875,47 @@ paths: - lang: CLI source: > linode-cli firewalls create + /networking/firewalls/{firewallId}: + parameters: + - name: firewallId + in: path + description: ID of the Firewall to look up + required: true + schema: + type: integer + x-linode-cli-command: firewalls + get: + x-linode-grant: read_only + servers: + - url: https://api.linode.com/v4beta + tags: + - Networking + summary: View Firewall + operationId: getFirewall + x-linode-cli-action: view + security: + - personalAccessToken: [] + - oauth: + - firewall:read_only + description: Get a specific Firewall resource by its ID. + responses: + '200': + description: Returns information about this Firewall. + content: + application/json: + schema: + $ref: '#/components/schemas/Firewall' + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4beta/firewalls/123 + - lang: CLI + source: > + linode-cli firewalls view 123 /nodebalancers: x-linode-cli-command: nodebalancers get: @@ -13217,6 +13258,15 @@ components: When this Firewall was created. example: '2018-01-01T00:01:01' x-linode-cli-display: 4 + updated: + x-linode-filterable: true + type: string + format: date-time + readOnly: true + description: > + When this Firewall was last updated. + example: '2018-01-02T00:01:01' + x-linode-cli-display: 5 status: type: string readOnly: true @@ -13270,7 +13320,7 @@ components: example: - 123 - 456 - x-linode-cli-display: 5 + x-linode-cli-display: 6 FirewallRuleConfig: type: object description: > From 9d71a0cec4e145fba14153a04da5edbdd31f67d0 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 18 Sep 2019 14:37:52 -0400 Subject: [PATCH 09/23] Update Shell request example for POST /networking/firewalls --- openapi.yaml | 41 +++++++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index dfd1b8a61..023fb473b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7859,17 +7859,46 @@ paths: "rules": { "inbound": [ { - "type": "TCP", - "protocol": "HTTPS", - "start_port": 443 + "protocol": "TCP", + "start_port": 20, + "end_port": 22, + "addresses": { + "ipv4": [ + "192.0.2.1", + "192.0.2.0/24" + ], + "ipv6": [ + "2001:DB8::/32" + ] + } } ], - "outbound": [] + "outbound": [ + "protocol": "TCP", + "start_port": 20, + "end_port": 22, + "addresses": { + "ipv4": [ + "192.0.2.1", + "192.0.2.0/24" + ], + "ipv6": [ + "2001:DB8::/32" + ] + } + } + ] }, "devices": { - "linodes": [123, 456], + "linodes": [ + 123, + 456 + ] }, - "tags": [] + "tags": [ + "example tag", + "another example" + ] }' \ https://api.linode.com/v4/firewalls - lang: CLI From 6bde0693263fec0657c18613ea809c9a67a4860e Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 18 Sep 2019 14:39:28 -0400 Subject: [PATCH 10/23] Update ipv6 example to display as list. --- openapi.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 023fb473b..4e5d61c49 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -13398,7 +13398,8 @@ components: type: array items: type: string - example: 2001:DB8::/32 + example: + - 2001:DB8::/32 Grant: type: object description: > From d24d09020b3dda5a8d5a22c3d5cc21a114bc79f7 Mon Sep 17 00:00:00 2001 From: Andy Stevens Date: Tue, 1 Oct 2019 15:14:07 -0400 Subject: [PATCH 11/23] Added DELETE /firewalls/:id endpoint Also: - Add Beta endpoint notice to GET /firewalls/:id endpoint - Change path parameter description to read something more generic, as it's shared now with DELETE --- openapi.yaml | 47 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 4e5d61c49..356734d26 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7908,7 +7908,8 @@ paths: parameters: - name: firewallId in: path - description: ID of the Firewall to look up + description: > + ID of the Firewall to interact with. required: true schema: type: integer @@ -7926,7 +7927,14 @@ paths: - personalAccessToken: [] - oauth: - firewall:read_only - description: Get a specific Firewall resource by its ID. + description: > + Get a specific Firewall resource by its ID. + + + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with + `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + updates in the future. This notice will be removed when this endpoint is out of + beta. responses: '200': description: Returns information about this Firewall. @@ -7945,6 +7953,41 @@ paths: - lang: CLI source: > linode-cli firewalls view 123 + delete: + x-linode-grant: read_write + servers: + - url: https://api.linode.com/v4beta + tags: + - networking + summary: Delete Firewall + operationId: deleteFirewall + x-linode-cli-action: delete + security: + - personalAccessToken: [] + - oauth: + - firewall:read_write + description: > + Delete a Firewall resource by its ID. + + + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with + `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + updates in the future. This notice will be removed when this endpoint is out of + beta. + responses: + '200': + description: Delete Successful. + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Content-Type: application/json" \ + -X DELETE \ + https://api.linode.com/v4beta/firewalls/123 + - lang: CLI + source: > + linode-cli firewalls delete 123 /nodebalancers: x-linode-cli-command: nodebalancers get: From f80bc2fa3479971eb7c38c139b216b51e28ab5af Mon Sep 17 00:00:00 2001 From: nmelehan Date: Fri, 4 Oct 2019 06:52:12 -0400 Subject: [PATCH 12/23] PUT Firewall endpoint --- openapi.yaml | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 356734d26..c86c069da 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7900,7 +7900,7 @@ paths: "another example" ] }' \ - https://api.linode.com/v4/firewalls + https://api.linode.com/v4beta/firewalls - lang: CLI source: > linode-cli firewalls create @@ -7953,6 +7953,58 @@ paths: - lang: CLI source: > linode-cli firewalls view 123 + put: + x-linode-grant: read_write + servers: + - url: https://api.linode.com/v4beta + tags: + - Networking + summary: Update Firewall + description: > + Updates information for a Firewall. A Firewall's Devices cannot be manipulated by + this endpoint. A Firewall's status can be set by this endpoint, but it cannot be + set to `deleted`. Instead, use the Delete Firewall endpoint to delete a Firewall. + + + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with + `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + updates in the future. This notice will be removed when this endpoint is out of + beta. + operationId: updateFirewall + x-linode-cli-action: update + security: + - personalAccessToken: [] + - oauth: + - firewall:read_write + requestBody: + description: The Firewall information to update. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Firewall' + responses: + '200': + description: Firewall updated successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/Firewall' + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -X PUT -d '{ + "status": "disabled", + }' \ + https://api.linode.com/v4beta/firewalls/123 + - lang: CLI + source: > + linode-cli firewalls update 123 \ + --status disabled delete: x-linode-grant: read_write servers: @@ -13385,7 +13437,7 @@ components: can only add a Firewall to Linodes. properties: linodes: - description: An array of Linode ids + description: An array of Linode IDs type: array items: type: integer From 6fc0238c9426a65c73d9272918f79441c04948d0 Mon Sep 17 00:00:00 2001 From: nmelehan Date: Fri, 4 Oct 2019 06:59:56 -0400 Subject: [PATCH 13/23] Update example request URLs to match endpoints --- openapi.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index c86c069da..1690da9d3 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7900,7 +7900,7 @@ paths: "another example" ] }' \ - https://api.linode.com/v4beta/firewalls + https://api.linode.com/v4beta/networking/firewalls - lang: CLI source: > linode-cli firewalls create @@ -7949,7 +7949,7 @@ paths: source: > curl -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4beta/firewalls/123 + https://api.linode.com/v4beta/networking/firewalls/123 - lang: CLI source: > linode-cli firewalls view 123 @@ -8000,7 +8000,7 @@ paths: -X PUT -d '{ "status": "disabled", }' \ - https://api.linode.com/v4beta/firewalls/123 + https://api.linode.com/v4beta/networking/firewalls/123 - lang: CLI source: > linode-cli firewalls update 123 \ @@ -8036,7 +8036,7 @@ paths: source: > curl -H "Content-Type: application/json" \ -X DELETE \ - https://api.linode.com/v4beta/firewalls/123 + https://api.linode.com/v4beta/networking/firewalls/123 - lang: CLI source: > linode-cli firewalls delete 123 From 3711b19afca1e6e0b217f2d29b7bc2b543d2860d Mon Sep 17 00:00:00 2001 From: Andy Stevens Date: Fri, 4 Oct 2019 09:58:31 -0400 Subject: [PATCH 14/23] Added GET /networking/firewalls endpoint --- openapi.yaml | 44 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 1690da9d3..e14cd7eb9 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7809,6 +7809,47 @@ paths: linode-cli networking v6-ranges /networking/firewalls: x-linode-cli-command: firewalls + get: + x-linode-grant: read_only + parameters: + - $ref: '#/components/parameters/pageOffset' + - $ref: '#/components/parameters/pageSize' + servers: + - url: https://api.linode.com/v4beta + tags: + - Networking + summary: List Firewalls + description: | + Returns a paginated list of your Firewalls. + operationId: getFirewalls + x-linode-cli-action: list + responses: + '200': + description: Returns an array of Firewalls. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Firewall' + page: + $ref: '#/components/schemas/PaginationEnvelope/properties/page' + pages: + $ref: '#/components/schemas/PaginationEnvelope/properties/pages' + results: + $ref: '#/components/schemas/PaginationEnvelope/properties/results' + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl https://api.linode.com/v4beta/networking/firewalls + - lang: CLI + source: > + linode-cli firewalls list post: x-linode-grant: read_write servers: @@ -8019,7 +8060,8 @@ paths: - oauth: - firewall:read_write description: > - Delete a Firewall resource by its ID. + Delete a Firewall resource by its ID. This will also remove all rules from the + device it was attched to, returning it to its default state. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with From 8880c1e81298ac045d45bb331d104934ed0d6eea Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 16 Oct 2019 18:45:25 -0400 Subject: [PATCH 15/23] Update PUT /firewalls/{firewallId} --- openapi.yaml | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index e14cd7eb9..295fbbb76 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7881,6 +7881,10 @@ paths: - rules allOf: - $ref: '#/components/schemas/Firewall' + - type: object + properties: + status: + readOnly: true responses: '200': description: Returns information about the created Firewall. @@ -8022,8 +8026,16 @@ paths: content: application/json: schema: - allOf: - - $ref: '#/components/schemas/Firewall' + type: object + properties: + rules: + $ref: '#/components/schemas/Firewall/properties/rules' + tags: + $ref: '#/components/schemas/Firewall/properties/tags' + label: + $ref: '#/components/schemas/Firewall/properties/label' + status: + $ref: '#/components/schemas/Firewall/properties/status' responses: '200': description: Firewall updated successfully. @@ -13435,7 +13447,6 @@ components: x-linode-cli-display: 5 status: type: string - readOnly: true description: > The status of this Firewall service. enum: From ae4cf450112fc77a5ea138c7e9495dd347243c25 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 17 Oct 2019 13:39:10 -0400 Subject: [PATCH 16/23] Fix typo in Delete Firewall endpoint --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 295fbbb76..8aa0118fd 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -8063,7 +8063,7 @@ paths: servers: - url: https://api.linode.com/v4beta tags: - - networking + - Networking summary: Delete Firewall operationId: deleteFirewall x-linode-cli-action: delete From 2839142e9a0d5539500ffb2b22f22dcd762dcb0c Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 17 Oct 2019 16:50:23 -0400 Subject: [PATCH 17/23] Added Add Firewall Devices endpoint POST /networking/firewalls/{firewallId}/devices --- openapi.yaml | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 8aa0118fd..ff5478b43 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -8094,6 +8094,69 @@ paths: - lang: CLI source: > linode-cli firewalls delete 123 + /networking/firewalls/{firewallId}/devices: + parameters: + - name: firewallId + in: path + description: > + ID of the Firewall to interact with. + required: true + schema: + type: integer + x-linode-cli-command: firewalls + post: + x-linode-grant: read_write + servers: + - url: https://api.linode.com/v4beta + tags: + - Networking + summary: Add Firewall Devices + description: > + Applies this Firewall to a new device. Currently, only devices of type `linode` + are accepted. A `firewall_device_add` event is created when the Firewall device is added + successfully. + + + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with + `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + updates in the future. This notice will be removed when this endpoint is out of + beta. + operationId: createFirewallDevices + x-linode-cli-action: create + security: + - personalAccessToken: [] + - oauth: + - firewall:read_write + requestBody: + content: + application/json: + schema: + required: + - id + - type + $ref: '#/components/schemas/FirewallDevices' + responses: + '200': + description: Returns information about the created Firewall. + content: + application/json: + schema: + $ref: '#/components/schemas/FirewallDevices' + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -X POST -d '{ + "type": "linode", + "id": "123" + }' \ + https://api.linode.com/v4beta/networking/firewalls/123/devices + - lang: CLI + source: > + linode-cli netowrking firewalls-create-devices /nodebalancers: x-linode-cli-command: nodebalancers get: @@ -13548,6 +13611,67 @@ components: type: string example: - 2001:DB8::/32 + FirewallDevices: + type: object + description: > + A firewall object that controls incoming and outgoing network traffic. + properties: + type: + x-linode-filterable: true + type: string + description: > + The device type. + example: linode + x-linode-cli-display: 1 + id: + x-linode-filterable: true + type: integer + description: > + The device's unique ID + example: 123 + x-linode-cli-display: 2 + created: + x-linode-filterable: true + type: string + format: date-time + readOnly: true + description: > + When this device was created. + example: '2018-01-01T00:01:01' + x-linode-cli-display: 3 + updated: + x-linode-filterable: true + type: string + format: date-time + readOnly: true + description: > + When this device was last updated. + example: '2018-01-02T00:01:01' + x-linode-cli-display: 4 + entity: + type: object + readOnly: true + description: > + The entity that this Firewall has been applied to. + properties: + id: + description: The entity's ID + type: integer + example: 123 + type: + description: The entity's type. + type: string + example: linode + label: + description: The entity's label. + type: string + example: my-linode + url: + description: > + The URL you can use to access this entity. + type: string + format: url + example: /v4/linode/instances/123 Grant: type: object description: > From abef84ae181e3643a76eaf1be2d50217a40a81be Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 17 Oct 2019 16:52:08 -0400 Subject: [PATCH 18/23] Add `firewall_device_add` event --- openapi.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi.yaml b/openapi.yaml index ff5478b43..275989e4e 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -13205,6 +13205,7 @@ components: - dns_zone_delete - dnz_zone_import - dns_zone_update + - firewall_device_add - host_reboot - image_delete - image_update From e960049959fb80e17f2d2907f6c9a1fdb8cf5964 Mon Sep 17 00:00:00 2001 From: nmelehan Date: Wed, 30 Oct 2019 10:26:46 -0400 Subject: [PATCH 19/23] Firewall collection updates Reviewed existing Firewall endpoints and schemas Added: - GET /networking/firewalls/{firewallId}/devices - POST /networking/firewalls/{firewallId}/devices - GET /networking/firewalls/{firewallId}/devices/{deviceId} - DELETE /networking/firewalls/{firewallId}/devices/{deviceId} - GET /networking/firewalls/{firewallId}/rules - POST /networking/firewalls/{firewallId}/rules --- openapi.yaml | 404 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 346 insertions(+), 58 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 275989e4e..54cf1a49b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7859,9 +7859,12 @@ paths: summary: Create Firewall description: > Creates a Firewall to filter network traffic. Use the `rules` property to - create inbound and outbound access rules. A single Firewall can be applied to - Linode services by specifying them in the `devices` object. + 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 multiple Firewalls can be + assigned to a single Linode service. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking @@ -7881,6 +7884,23 @@ paths: - rules allOf: - $ref: '#/components/schemas/Firewall' + - type: object + properties: + devices: + type: object + description: > + A Firewall Device assigns a Firewall to a Linode service. Currently, Firewalls + can only be assigned to Linode instances. + properties: + linodes: + description: > + An array of Linode IDs. A Firewall Device will be created for each ID. + type: array + items: + type: integer + example: + - 123 + - 456 - type: object properties: status: @@ -7954,7 +7974,7 @@ paths: - name: firewallId in: path description: > - ID of the Firewall to interact with. + ID of the Firewall to access. required: true schema: type: integer @@ -7972,9 +7992,11 @@ paths: - personalAccessToken: [] - oauth: - firewall:read_only - description: > - Get a specific Firewall resource by its ID. - + description: | + 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](http://developers.linode.com/api/v4/networking-firewalls-firewall-id-devices/#get) + endpoint to review them. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking @@ -8005,11 +8027,23 @@ paths: tags: - Networking summary: Update Firewall - description: > - Updates information for a Firewall. A Firewall's Devices cannot be manipulated by - this endpoint. A Firewall's status can be set by this endpoint, but it cannot be - set to `deleted`. Instead, use the Delete Firewall endpoint to delete a Firewall. + description: | + Updates information for a Firewall. Some parts of a Firewall's configuration cannot + be manipuslated by this endpoint: + + - A Firewall's Devices cannot be set with this endpoint. Instead, use the + [Create Firewall Device](http://developers.linode.com/api/v4/networking-firewalls-firewall-id-devices/#post) + and [Delete Firewall Device](http://developers.linode.com/api/v4/networking-firewalls-firewall-id-devices/#delete) + 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](http://developers.linode.com/api/v4/networking-firewalls-firewall-id-rules/#put) + endpoint to update your Rules. + + - A Firewall's status can be set by this endpoint, but it cannot be + set to `deleted`. Instead, use the + [Delete Firewall](http://developers.linode.com/api/v4/networking-firewalls-firewall-id/#delete) + endpoint to delete a Firewall. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking @@ -8028,8 +8062,6 @@ paths: schema: type: object properties: - rules: - $ref: '#/components/schemas/Firewall/properties/rules' tags: $ref: '#/components/schemas/Firewall/properties/tags' label: @@ -8071,10 +8103,9 @@ paths: - personalAccessToken: [] - oauth: - firewall:read_write - description: > - Delete a Firewall resource by its ID. This will also remove all rules from the - device it was attched to, returning it to its default state. - + description: | + Delete a Firewall resource by its ID. This will remove all of the Firewall's Rules + from any Linode services that it was assigned to. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking @@ -8099,30 +8130,82 @@ paths: - name: firewallId in: path description: > - ID of the Firewall to interact with. + ID of the Firewall to access. required: true schema: type: integer x-linode-cli-command: firewalls + get: + x-linode-grant: read_only + tags: + - Networking + parameters: + - $ref: '#/components/parameters/pageOffset' + - $ref: '#/components/parameters/pageSize' + summary: List Firewall Devices + description: | + 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. + + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with + `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + updates in the future. This notice will be removed when this endpoint is out of + beta. + operationId: getFirewallDevices + x-linode-cli-action: devices-list + security: + - personalAccessToken: [] + - oauth: + - firewall:read_only + responses: + '200': + description: A paginated list of Firewall Devices + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/FirewallDevices' + page: + $ref: '#/components/schemas/PaginationEnvelope/properties/page' + pages: + $ref: '#/components/schemas/PaginationEnvelope/properties/pages' + results: + $ref: '#/components/schemas/PaginationEnvelope/properties/results' + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/firewalls/123/devices + - lang: CLI + source: > + linode-cli firewalls devices-list 123 post: x-linode-grant: read_write servers: - url: https://api.linode.com/v4beta tags: - Networking - summary: Add Firewall Devices - description: > - Applies this Firewall to a new device. Currently, only devices of type `linode` - are accepted. A `firewall_device_add` event is created when the Firewall device is added - successfully. + summary: Create Firewall Device + description: | + 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. + 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. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking updates in the future. This notice will be removed when this endpoint is out of beta. - operationId: createFirewallDevices - x-linode-cli-action: create + operationId: createFirewallDevice + x-linode-cli-action: device-create security: - personalAccessToken: [] - oauth: @@ -8134,10 +8217,10 @@ paths: required: - id - type - $ref: '#/components/schemas/FirewallDevices' + $ref: '#/components/schemas/FirewallDevices/properties/entity' responses: '200': - description: Returns information about the created Firewall. + description: Returns information about the created Firewall Device. content: application/json: schema: @@ -8156,7 +8239,222 @@ paths: https://api.linode.com/v4beta/networking/firewalls/123/devices - lang: CLI source: > - linode-cli netowrking firewalls-create-devices + linode-cli networking device-create 123 + /networking/firewalls/{firewallId}/devices/{deviceId}: + parameters: + - name: firewallId + in: path + description: > + ID of the Firewall to access. + required: true + schema: + type: integer + - name: deviceId + in: path + description: > + ID of the Firewall Device to access. + required: true + schema: + type: integer + x-linode-cli-command: firewalls + get: + x-linode-grant: read_only + tags: + - Networking + summary: View Firewall Device + description: | + 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. + + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with + `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + updates in the future. This notice will be removed when this endpoint is out of + beta. + operationId: getFirewallDevice + x-linode-cli-action: device-view + security: + - personalAccessToken: [] + - oauth: + - firewall:read_only + responses: + '200': + description: The requested Firewall Device. + content: + application/json: + schema: + $ref: '#/components/schemas/FirewallDevices' + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4beta/networking/firewalls/123/devices/456 + - lang: CLI + source: > + linode-cli firewalls device-view \ + 123 456 + delete: + x-linode-grant: read_write + servers: + - url: https://api.linode.com/v4beta + tags: + - Networking + summary: Delete Firewall Device + operationId: deleteFirewallDevice + x-linode-cli-action: device-delete + security: + - personalAccessToken: [] + - oauth: + - firewall:read_write + description: | + 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. + + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with + `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + updates in the future. This notice will be removed when this endpoint is out of + beta. + responses: + '200': + description: Delete Successful. + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Content-Type: application/json" \ + -X DELETE \ + https://api.linode.com/v4beta/networking/firewalls/123/devices/456 + - lang: CLI + source: > + linode-cli firewalls device-delete 123 456 + /networking/firewalls/{firewallId}/rules: + parameters: + - name: firewallId + in: path + description: > + ID of the Firewall to access. + required: true + schema: + type: integer + x-linode-cli-command: firewalls + get: + x-linode-grant: read_only + tags: + - Networking + summary: List Firewall Rules + description: | + Returns the inbound and outbound Rules for a Firewall. + + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with + `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + updates in the future. This notice will be removed when this endpoint is out of + beta. + operationId: getFirewallRules + x-linode-cli-action: rules-list + security: + - personalAccessToken: [] + - oauth: + - firewall:read_only + responses: + '200': + description: The requested Firewall Rules. + content: + application/json: + schema: + $ref: '#/components/schemas/Firewall/properties/rules' + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/firewalls/123/rules + - lang: CLI + source: > + linode-cli firewalls rules-list 123 + put: + x-linode-grant: read_write + servers: + - url: https://api.linode.com/v4beta + tags: + - Networking + summary: Update Firewall Rules + description: | + Updates the inbound and outbound Rules for a Firewall. + + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with + `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + updates in the future. This notice will be removed when this endpoint is out of + beta. + operationId: updateFirewallRules + x-linode-cli-action: rules-update + security: + - personalAccessToken: [] + - oauth: + - firewall:read_write + requestBody: + description: The Firewall Rules information to update. + content: + application/json: + schema: + $ref: '#/components/schemas/Firewall/properties/rules' + responses: + '200': + description: Firewall Rules updated successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/Firewall/properties/rules' + default: + $ref: '#/components/responses/ErrorResponse' + x-code-samples: + - lang: Shell + source: > + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -X PUT -d '{ + "inbound": [ + { + "protocol": "TCP", + "start_port": 80, + "addresses": { + "ipv4": [ + "192.0.2.1", + "192.0.2.0/24" + ], + "ipv6": [ + "2001:DB8::/32" + ] + } + } + ], + "outbound": [ + "protocol": "TCP", + "start_port": 20, + "end_port": 22, + "addresses": { + "ipv4": [ + "192.0.2.1", + "192.0.2.0/24" + ], + "ipv6": [ + "2001:DB8::/32" + ] + } + } + ] + }' \ + https://api.linode.com/v4beta/networking/firewalls/123/rules + - lang: CLI + source: > + linode-cli firewalls rules-update 123 \ + --inbound '[{"protocol": "TCP", "start_port": 80, "addresses": {"ipv4": ["192.0.2.1", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]' \ + --outbound '[{"protocol": "TCP", "start_port": 20, "addresses": {"ipv4": ["192.0.2.1", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]' /nodebalancers: x-linode-cli-command: nodebalancers get: @@ -13206,6 +13504,7 @@ components: - dnz_zone_import - dns_zone_update - firewall_device_add + - firewall_device_remove - host_reboot - image_delete - image_update @@ -13464,7 +13763,10 @@ components: Firewall: type: object description: > - A firewall object that controls incoming and outgoing network traffic. + A resource that controls incoming and outgoing network traffic to a Linode service. A Firewall can + be assigned to multiple Linode services, and multiple Firewalls can be assigned to a single Linode service. + [Create a Firewall Device](http://developers.linode.com/api/v4/networking-firewalls-firewall-id-devices/#post) + to assign a Firewall to a Linode service. Currently, Firewalls can only be assigned to Linode instances. properties: id: x-linode-filterable: true @@ -13478,7 +13780,7 @@ components: x-linode-filterable: true type: string description: > - The Firewall's label for display purposes only. If no label is provided for a Firewall, + 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: @@ -13531,9 +13833,13 @@ components: remaining outbound ports will be blocked. properties: inbound: - $ref: '#/components/schemas/FirewallRuleConfig' + type: array + items: + $ref: '#/components/schemas/FirewallRuleConfig' outbound: - $ref: '#/components/schemas/FirewallRuleConfig' + type: array + items: + $ref: '#/components/schemas/FirewallRuleConfig' required: - inbound tags: @@ -13547,21 +13853,6 @@ components: example: - example tag - another example - devices: - type: object - description: > - The devices that this Firewall will be applied to. Currently, you - can only add a Firewall to Linodes. - properties: - linodes: - description: An array of Linode IDs - type: array - items: - type: integer - example: - - 123 - - 456 - x-linode-cli-display: 6 FirewallRuleConfig: type: object description: > @@ -13615,20 +13906,13 @@ components: FirewallDevices: type: object description: > - A firewall object that controls incoming and outgoing network traffic. + Associates a Firewall with a Linode service. properties: - type: - x-linode-filterable: true - type: string - description: > - The device type. - example: linode - x-linode-cli-display: 1 id: x-linode-filterable: true type: integer description: > - The device's unique ID + The Device's unique ID example: 123 x-linode-cli-display: 2 created: @@ -13637,7 +13921,7 @@ components: format: date-time readOnly: true description: > - When this device was created. + When this Device was created. example: '2018-01-01T00:01:01' x-linode-cli-display: 3 updated: @@ -13646,14 +13930,14 @@ components: format: date-time readOnly: true description: > - When this device was last updated. + When this Device was last updated. example: '2018-01-02T00:01:01' x-linode-cli-display: 4 entity: type: object readOnly: true description: > - The entity that this Firewall has been applied to. + The Linode service that this Firewall has been applied to. properties: id: description: The entity's ID @@ -13662,16 +13946,20 @@ components: type: description: The entity's type. type: string + enum: + - linode example: linode label: description: The entity's label. type: string + readOnly: true example: my-linode url: description: > The URL you can use to access this entity. type: string format: url + readOnly: true example: /v4/linode/instances/123 Grant: type: object From 4c703a547a29e5989174fedaeef041636c17a09e Mon Sep 17 00:00:00 2001 From: nmelehan Date: Mon, 4 Nov 2019 12:23:49 -0500 Subject: [PATCH 20/23] Add events for firewalls --- openapi.yaml | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 54cf1a49b..fb0df2a1a 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7857,7 +7857,7 @@ paths: tags: - Networking summary: Create Firewall - description: > + description: | 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 @@ -7866,6 +7866,8 @@ paths: A Firewall can be assigned to multiple Linode services, and multiple Firewalls can be assigned to a single Linode service. + A `firewall_create` Event is generated when this endpoint returns successfully. + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking updates in the future. This notice will be removed when this endpoint is out of @@ -8029,7 +8031,7 @@ paths: summary: Update Firewall description: | Updates information for a Firewall. Some parts of a Firewall's configuration cannot - be manipuslated by this endpoint: + be manipulated by this endpoint: - A Firewall's Devices cannot be set with this endpoint. Instead, use the [Create Firewall Device](http://developers.linode.com/api/v4/networking-firewalls-firewall-id-devices/#post) @@ -8045,6 +8047,9 @@ paths: [Delete Firewall](http://developers.linode.com/api/v4/networking-firewalls-firewall-id/#delete) 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. + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking updates in the future. This notice will be removed when this endpoint is out of @@ -8107,6 +8112,8 @@ paths: Delete a Firewall resource by its ID. This will remove all of the Firewall's Rules from any Linode services that it was assigned to. + A `firewall_delete` Event is generated when this endpoint returns successfully. + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking updates in the future. This notice will be removed when this endpoint is out of @@ -8198,7 +8205,7 @@ paths: as the Device's `entity`). Currently, only Devices with an entity of type `linode` are accepted. 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. + A `firewall_device_add` Event is generated when the Firewall Device is added successfully. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking @@ -8314,6 +8321,8 @@ paths: 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. + **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking updates in the future. This notice will be removed when this endpoint is out of @@ -13503,6 +13512,11 @@ components: - dns_zone_delete - dnz_zone_import - dns_zone_update + - firewall_create + - firewall_delete + - firewall_disable + - firewall_enable + - firewall_update - firewall_device_add - firewall_device_remove - host_reboot @@ -13642,6 +13656,7 @@ components: - community - disks - domain + - firewall - image - ipaddress - linode From 6e669af98989c967dd05358926c99167b3568fd9 Mon Sep 17 00:00:00 2001 From: nmelehan Date: Mon, 4 Nov 2019 15:53:32 -0500 Subject: [PATCH 21/23] Fix typo that appears across firewall endpoints --- openapi.yaml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index fb0df2a1a..bed452ea8 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7869,7 +7869,7 @@ paths: A `firewall_create` Event is generated when this endpoint returns successfully. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with - `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + `/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. operationId: createFirewalls @@ -8001,7 +8001,7 @@ paths: endpoint to review them. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with - `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + `/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. responses: @@ -8051,7 +8051,7 @@ paths: `firewall_disable` Event will be generated. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with - `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + `/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. operationId: updateFirewall @@ -8115,7 +8115,7 @@ paths: A `firewall_delete` Event is generated when this endpoint returns successfully. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with - `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + `/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. responses: @@ -8156,7 +8156,7 @@ paths: only Devices with an entity of type `linode` are accepted. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with - `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + `/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. operationId: getFirewallDevices @@ -8208,7 +8208,7 @@ paths: A `firewall_device_add` Event is generated when the Firewall Device is added successfully. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with - `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + `/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. operationId: createFirewallDevice @@ -8275,7 +8275,7 @@ paths: only Devices with an entity of type `linode` are accepted. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with - `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + `/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. operationId: getFirewallDevice @@ -8324,7 +8324,7 @@ paths: A `firewall_device_remove` Event is generated when the Firewall Device is removed successfully. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with - `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + `/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. responses: @@ -8360,7 +8360,7 @@ paths: Returns the inbound and outbound Rules for a Firewall. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with - `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + `/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. operationId: getFirewallRules @@ -8397,7 +8397,7 @@ paths: Updates the inbound and outbound Rules for a Firewall. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with - `/v4beta` instead of `/v4`, and be aware that this endpoint may receiving breaking + `/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. operationId: updateFirewallRules From 9f7536ef01b268bcd1a9698785ad1633faf96eca Mon Sep 17 00:00:00 2001 From: nmelehan Date: Tue, 14 Jan 2020 21:27:22 -0500 Subject: [PATCH 22/23] [Update] FirewallRuleConfig - Refactor the start_port and end_port properties into a single ports property - Remove the ALL protocol - Copy edit of some other firewall endpoints and schemas --- openapi.yaml | 63 ++++++++++++++++++++++++++-------------------------- 1 file changed, 31 insertions(+), 32 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index bed452ea8..0cff5db79 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7927,8 +7927,7 @@ paths: "inbound": [ { "protocol": "TCP", - "start_port": 20, - "end_port": 22, + "ports": "22, 80, 443", "addresses": { "ipv4": [ "192.0.2.1", @@ -7942,8 +7941,7 @@ paths: ], "outbound": [ "protocol": "TCP", - "start_port": 20, - "end_port": 22, + "ports": "49152-65535", "addresses": { "ipv4": [ "192.0.2.1", @@ -8042,7 +8040,7 @@ paths: [Update Firewall Rules](http://developers.linode.com/api/v4/networking-firewalls-firewall-id-rules/#put) endpoint to update your Rules. - - A Firewall's status can be set by this endpoint, but it cannot be + - 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](http://developers.linode.com/api/v4/networking-firewalls-firewall-id/#delete) endpoint to delete a Firewall. @@ -8110,7 +8108,7 @@ paths: - firewall:read_write description: | Delete a Firewall resource by its ID. This will remove all of the Firewall's Rules - from any Linode services that it was assigned to. + from any Linode services that the Firewall was assigned to. A `firewall_delete` Event is generated when this endpoint returns successfully. @@ -8394,7 +8392,8 @@ paths: - Networking summary: Update Firewall Rules description: | - Updates the inbound and outbound Rules for a Firewall. + 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. **Beta**: This endpoint is in beta. Please make sure to prepend all requests with `/v4beta` instead of `/v4`, and be aware that this endpoint may receive breaking @@ -8430,7 +8429,7 @@ paths: "inbound": [ { "protocol": "TCP", - "start_port": 80, + "ports": "22, 80, 8080, 443" "addresses": { "ipv4": [ "192.0.2.1", @@ -8444,8 +8443,7 @@ paths: ], "outbound": [ "protocol": "TCP", - "start_port": 20, - "end_port": 22, + "ports": "49152-65535" "addresses": { "ipv4": [ "192.0.2.1", @@ -8462,8 +8460,8 @@ paths: - lang: CLI source: > linode-cli firewalls rules-update 123 \ - --inbound '[{"protocol": "TCP", "start_port": 80, "addresses": {"ipv4": ["192.0.2.1", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]' \ - --outbound '[{"protocol": "TCP", "start_port": 20, "addresses": {"ipv4": ["192.0.2.1", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]' + --inbound '[{"protocol": "TCP", "ports": "22, 80, 8080, 443", "addresses": {"ipv4": ["192.0.2.1", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]' \ + --outbound '[{"protocol": "TCP", "ports": "49152-65535", "addresses": {"ipv4": ["192.0.2.1", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]' /nodebalancers: x-linode-cli-command: nodebalancers get: @@ -13841,11 +13839,12 @@ components: description: > The inbound and outbound access rules to apply to the Firewall. - * A minimum of one open inbound port is required. Any inbound - port that is not open will be blocked. - * Outbound rules are optional. When no outbound ports are open, all outbound - ports are allowed. If you open one outbound port or more, all - remaining outbound ports will be blocked. + * 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. properties: inbound: type: array @@ -13871,33 +13870,33 @@ components: FirewallRuleConfig: type: object description: > - This Firewall's access rules. To open traffic on a range of ports - specify a `start_port` and an `end_port`. + One of a Firewall's inbound or outbound access rules. The `ports` property + can be used to allow traffic on a comma-separated list of different ports. required: - protocol - - start_port properties: protocol: type: string enum: - - ALL - TCP - UDP - ICMP description: > The type of network traffic to allow. example: TCP - start_port: - type: integer - description: > - The port on which traffic will be allowed. Must be a value of `1-65535`. - example: 20 - end_port: - type: integer - description: > - The end port for a range of ports on which traffic will be allowed. This port must be greater than or equal to the `start_port` - and must be a value of `1-65535`. - example: 22 + ports: + type: string + description: | + 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. + - 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`. + example: '22-24, 80, 443' addresses: type: object description: > From 65f5e74d55d55545f1358a8d87974a3d21544615 Mon Sep 17 00:00:00 2001 From: nmelehan Date: Tue, 14 Jan 2020 23:13:33 -0500 Subject: [PATCH 23/23] [Update] Firewall limits Inserting descriptions for these limits: - Up to three active Firewalls per Device - Up to 25 Rules per Firewall - Up to 255 addresses or networks per Rule - Up to 15 pieces in a Rule's ports string Did not include a description of how an Account's Firewall limit is the same as the Account's thing limit, as we do not describe the thing limit in other areas of the API reference. --- openapi.yaml | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 0cff5db79..d2e9c9a87 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7863,8 +7863,10 @@ paths: Firewall to a Linode service. Currently, Firewalls can only be assigned to Linode instances. - A Firewall can be assigned to multiple Linode services, and multiple Firewalls can be - assigned to a single Linode service. + 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. A `firewall_create` Event is generated when this endpoint returns successfully. @@ -8201,6 +8203,10 @@ paths: description: | 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. @@ -13777,7 +13783,7 @@ components: type: object description: > A resource that controls incoming and outgoing network traffic to a Linode service. A Firewall can - be assigned to multiple Linode services, and multiple Firewalls can be assigned to a single Linode service. + be assigned to multiple Linode services, and up to three active Firewalls can be assigned to a single Linode service. [Create a Firewall Device](http://developers.linode.com/api/v4/networking-firewalls-firewall-id-devices/#post) to assign a Firewall to a Linode service. Currently, Firewalls can only be assigned to Linode instances. properties: @@ -13836,8 +13842,8 @@ components: x-linode-cli-display: 3 rules: type: object - description: > - The inbound and outbound access rules to apply to the Firewall. + description: | + 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. @@ -13845,6 +13851,8 @@ components: 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. properties: inbound: type: array @@ -13896,11 +13904,16 @@ components: - Ports must be within 1 and 65535. - 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. example: '22-24, 80, 443' addresses: type: object description: > - Whitelisted IPv4 or IPv6 addresses. + Whitelisted 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. properties: ipv4: description: A list of IPv4 addresses or networks. @@ -13920,7 +13933,11 @@ components: FirewallDevices: type: object description: > - Associates a Firewall with a Linode service. + Associates a Firewall with a Linode service. 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. properties: id: x-linode-filterable: true