From 9d9b11606c24f64f4c80eab2f495fd4defad467a Mon Sep 17 00:00:00 2001 From: hzoppetti Date: Mon, 26 Aug 2019 12:30:56 -0400 Subject: [PATCH 01/43] 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 673c505cf..fe6a257fe 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2836,6 +2836,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: @@ -14612,6 +14672,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 4ca033b3097e0245f6fcebf63b9bcff53af1b4f7 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 11 Sep 2019 18:34:37 -0400 Subject: [PATCH 02/43] First changes --- openapi.yaml | 202 ++++++++++++++++++++++++++++----------------------- 1 file changed, 112 insertions(+), 90 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index fe6a257fe..d3499b87e 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2836,66 +2836,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: @@ -9209,6 +9149,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: @@ -14677,31 +14678,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: > @@ -14713,29 +14730,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 f6301a72778115167222d576df60d3140d4e7f9a Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 12 Sep 2019 15:12:36 -0400 Subject: [PATCH 03/43] More edits to Post Firewalls --- openapi.yaml | 76 +++++++++++++++++++++++----------------------------- 1 file changed, 34 insertions(+), 42 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index d3499b87e..df1ad4b19 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9157,7 +9157,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: @@ -14712,13 +14714,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: > @@ -14743,13 +14744,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" @@ -14757,49 +14760,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 8bad1d495f0163fa0eafe96933584b876ad88f6f Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Mon, 16 Sep 2019 18:54:57 -0400 Subject: [PATCH 04/43] 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 df1ad4b19..8ccd7f7ad 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9157,18 +9157,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: @@ -9178,7 +9176,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: @@ -9191,7 +9189,7 @@ paths: curl -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -X POST -d '{ - "label": "this_is_a_label", + "label": "firewall123", "rules": { "inbound": [ { @@ -9203,8 +9201,7 @@ paths: "outbound": [] }, "devices": { - "linodes": [], - "nodebalancers": [] + "linodes": [123, 456], }, "tags": [] }' \ @@ -14685,14 +14682,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 @@ -14701,7 +14710,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 @@ -14711,6 +14720,8 @@ components: - "enabled" - "disabled" - "deleted" + example: "enabled" + x-linode-cli-display: 3 rules: type: object description: > @@ -14729,12 +14740,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 @@ -14744,15 +14755,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" @@ -14761,32 +14774,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 9ea19f666fb8e182dbd18da1036beaf2d6e5649e Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Tue, 17 Sep 2019 12:09:41 -0400 Subject: [PATCH 05/43] 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 8ccd7f7ad..cfa522c3f 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9157,9 +9157,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: @@ -14726,11 +14726,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: > @@ -14745,7 +14753,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 @@ -14759,7 +14768,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 f75fef1b03ef1284d90ef5ef7423171001d9958f Mon Sep 17 00:00:00 2001 From: hzoppetti Date: Tue, 17 Sep 2019 13:57:55 -0400 Subject: [PATCH 06/43] added beta server and indents --- openapi.yaml | 55 ++++++++++++++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index cfa522c3f..7566fd0af 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9153,6 +9153,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 @@ -9160,6 +9162,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: @@ -14697,7 +14705,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-_.])+$' @@ -14717,10 +14725,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 @@ -14733,16 +14741,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: @@ -14771,32 +14779,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: > @@ -14808,15 +14814,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 fd9fc27fd0c820f8572b6a4526ac21377be10601 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Tue, 17 Sep 2019 14:21:13 -0400 Subject: [PATCH 07/43] Remove unnecessary quotations from examples --- openapi.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 7566fd0af..e0670eed4 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -14756,8 +14756,8 @@ components: items: type: string example: - - "example tag" - - "another example" + - example tag + - another example devices: type: object description: > @@ -14814,14 +14814,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 6c64db100a79b02182b49d17cc78a9a64193cb79 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 18 Sep 2019 13:06:36 -0400 Subject: [PATCH 08/43] Add GET /networking/firewalls/{firewallId} --- openapi.yaml | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index e0670eed4..5d066a500 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9217,6 +9217,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: @@ -14719,6 +14760,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 @@ -14772,7 +14822,7 @@ components: example: - 123 - 456 - x-linode-cli-display: 5 + x-linode-cli-display: 6 FirewallRuleConfig: type: object description: > From 697fcbb6c7d3e03e46798fd0bfbb46bb184d246a Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 18 Sep 2019 14:37:52 -0400 Subject: [PATCH 09/43] 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 5d066a500..883c5095d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9201,17 +9201,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 5decc21f5080b4a0864762999f262a7f7263f6f7 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 18 Sep 2019 14:39:28 -0400 Subject: [PATCH 10/43] 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 883c5095d..ed13256bd 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -14900,7 +14900,8 @@ components: type: array items: type: string - example: 2001:DB8::/32 + example: + - 2001:DB8::/32 Grant: type: object description: > From 19bcdeab76de998913400dbfd217b8694a16fc5c Mon Sep 17 00:00:00 2001 From: Andy Stevens Date: Tue, 1 Oct 2019 15:14:07 -0400 Subject: [PATCH 11/43] 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 ed13256bd..34d756e91 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9250,7 +9250,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 @@ -9268,7 +9269,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. @@ -9287,6 +9295,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 9f1e5cf986f4adf5400c909a81baf936f0ddc567 Mon Sep 17 00:00:00 2001 From: nmelehan Date: Fri, 4 Oct 2019 06:52:12 -0400 Subject: [PATCH 12/43] PUT Firewall endpoint --- openapi.yaml | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 34d756e91..97e8d4b02 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9242,7 +9242,7 @@ paths: "another example" ] }' \ - https://api.linode.com/v4/firewalls + https://api.linode.com/v4beta/firewalls - lang: CLI source: > linode-cli firewalls create @@ -9295,6 +9295,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: @@ -14887,7 +14939,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 9a6019ee1393c1c0da9374a48f6f909e4c60f582 Mon Sep 17 00:00:00 2001 From: nmelehan Date: Fri, 4 Oct 2019 06:59:56 -0400 Subject: [PATCH 13/43] 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 97e8d4b02..94564d4b9 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9242,7 +9242,7 @@ paths: "another example" ] }' \ - https://api.linode.com/v4beta/firewalls + https://api.linode.com/v4beta/networking/firewalls - lang: CLI source: > linode-cli firewalls create @@ -9291,7 +9291,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 @@ -9342,7 +9342,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 \ @@ -9378,7 +9378,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 10a6caeefc51ec9e1da893b09acf998c35ac0c1a Mon Sep 17 00:00:00 2001 From: Andy Stevens Date: Fri, 4 Oct 2019 09:58:31 -0400 Subject: [PATCH 14/43] Added GET /networking/firewalls endpoint --- openapi.yaml | 44 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 94564d4b9..0dc2b801e 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9151,6 +9151,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: @@ -9361,7 +9402,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 06bbc8c24215a75a277a81df8ad92bb31d8ecc75 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 16 Oct 2019 18:45:25 -0400 Subject: [PATCH 15/43] Update PUT /firewalls/{firewallId} --- openapi.yaml | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 0dc2b801e..f4481f499 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9223,6 +9223,10 @@ paths: - rules allOf: - $ref: '#/components/schemas/Firewall' + - type: object + properties: + status: + readOnly: true responses: '200': description: Returns information about the created Firewall. @@ -9364,8 +9368,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. @@ -14937,7 +14949,6 @@ components: x-linode-cli-display: 5 status: type: string - readOnly: true description: > The status of this Firewall service. enum: From c09cc69edde77d10b47f05fe9f59a8bfed485c64 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 17 Oct 2019 13:39:10 -0400 Subject: [PATCH 16/43] 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 f4481f499..89d111cac 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9405,7 +9405,7 @@ paths: servers: - url: https://api.linode.com/v4beta tags: - - networking + - Networking summary: Delete Firewall operationId: deleteFirewall x-linode-cli-action: delete From 2d1811507ce431862bc57ed0bbd16a2279a1f244 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 17 Oct 2019 16:50:23 -0400 Subject: [PATCH 17/43] 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 89d111cac..24ec142ef 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9436,6 +9436,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: @@ -15050,6 +15113,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 36a555b28acfe2b2933e8ab09f6eb0f830984322 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 17 Oct 2019 16:52:08 -0400 Subject: [PATCH 18/43] Add `firewall_device_add` event --- openapi.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi.yaml b/openapi.yaml index 24ec142ef..1ae8b5099 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -14698,6 +14698,7 @@ components: - dns_zone_delete - dns_zone_import - dns_zone_update + - firewall_device_add - host_reboot - image_delete - image_update From b053f471affb5f4beb8ce9f025af84521371d40e Mon Sep 17 00:00:00 2001 From: nmelehan Date: Wed, 30 Oct 2019 10:26:46 -0400 Subject: [PATCH 19/43] 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 1ae8b5099..3ef5660f6 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9201,9 +9201,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 @@ -9223,6 +9226,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: @@ -9296,7 +9316,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 @@ -9314,9 +9334,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 @@ -9347,11 +9369,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 @@ -9370,8 +9404,6 @@ paths: schema: type: object properties: - rules: - $ref: '#/components/schemas/Firewall/properties/rules' tags: $ref: '#/components/schemas/Firewall/properties/tags' label: @@ -9413,10 +9445,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 @@ -9441,30 +9472,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: @@ -9476,10 +9559,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: @@ -9498,7 +9581,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: @@ -14699,6 +14997,7 @@ components: - dns_zone_import - dns_zone_update - firewall_device_add + - firewall_device_remove - host_reboot - image_delete - image_update @@ -14966,7 +15265,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 @@ -14980,7 +15282,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: @@ -15033,9 +15335,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: @@ -15049,21 +15355,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: > @@ -15117,20 +15408,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: @@ -15139,7 +15423,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: @@ -15148,14 +15432,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 @@ -15164,16 +15448,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 3ed96e3fc20842368aab684777d065ffa8ac9e8e Mon Sep 17 00:00:00 2001 From: nmelehan Date: Mon, 4 Nov 2019 12:23:49 -0500 Subject: [PATCH 20/43] Add events for firewalls --- openapi.yaml | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 3ef5660f6..721d38867 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9199,7 +9199,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 @@ -9208,6 +9208,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 @@ -9371,7 +9373,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) @@ -9387,6 +9389,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 @@ -9449,6 +9454,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 @@ -9540,7 +9547,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 @@ -9656,6 +9663,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 @@ -14996,6 +15005,11 @@ components: - dns_zone_delete - dns_zone_import - dns_zone_update + - firewall_create + - firewall_delete + - firewall_disable + - firewall_enable + - firewall_update - firewall_device_add - firewall_device_remove - host_reboot @@ -15144,6 +15158,7 @@ components: - community - disks - domain + - firewall - image - ipaddress - linode From 8c012b4eb67c9a8d45ce826a2e8f373f04d73949 Mon Sep 17 00:00:00 2001 From: nmelehan Date: Mon, 4 Nov 2019 15:53:32 -0500 Subject: [PATCH 21/43] 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 721d38867..bba7fd5f8 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9211,7 +9211,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 @@ -9343,7 +9343,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: @@ -9393,7 +9393,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 @@ -9457,7 +9457,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: @@ -9498,7 +9498,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 @@ -9550,7 +9550,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 @@ -9617,7 +9617,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 @@ -9666,7 +9666,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: @@ -9702,7 +9702,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 @@ -9739,7 +9739,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 6a0662f9f3c452a39e0982f9180401631623a5aa Mon Sep 17 00:00:00 2001 From: nmelehan Date: Tue, 14 Jan 2020 21:27:22 -0500 Subject: [PATCH 22/43] [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 bba7fd5f8..4409b2042 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9269,8 +9269,7 @@ paths: "inbound": [ { "protocol": "TCP", - "start_port": 20, - "end_port": 22, + "ports": "22, 80, 443", "addresses": { "ipv4": [ "192.0.2.1", @@ -9284,8 +9283,7 @@ paths: ], "outbound": [ "protocol": "TCP", - "start_port": 20, - "end_port": 22, + "ports": "49152-65535", "addresses": { "ipv4": [ "192.0.2.1", @@ -9384,7 +9382,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. @@ -9452,7 +9450,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. @@ -9736,7 +9734,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 @@ -9772,7 +9771,7 @@ paths: "inbound": [ { "protocol": "TCP", - "start_port": 80, + "ports": "22, 80, 8080, 443" "addresses": { "ipv4": [ "192.0.2.1", @@ -9786,8 +9785,7 @@ paths: ], "outbound": [ "protocol": "TCP", - "start_port": 20, - "end_port": 22, + "ports": "49152-65535" "addresses": { "ipv4": [ "192.0.2.1", @@ -9804,8 +9802,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: @@ -15343,11 +15341,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 @@ -15373,33 +15372,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 8cc418bcad9e6234d625b96941c4c176f43047ef Mon Sep 17 00:00:00 2001 From: nmelehan Date: Tue, 14 Jan 2020 23:13:33 -0500 Subject: [PATCH 23/43] [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 4409b2042..5de2cd6a7 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9205,8 +9205,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. @@ -9543,6 +9545,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. @@ -15279,7 +15285,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: @@ -15338,8 +15344,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. @@ -15347,6 +15353,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 @@ -15398,11 +15406,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. @@ -15422,7 +15435,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 From 38db9e9f442ff1254154b913f50d7a6e473dd2a3 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 19 Mar 2020 12:34:53 -0400 Subject: [PATCH 24/43] Update List Firewalls shell example --- openapi.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 5de2cd6a7..004dce958 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9188,7 +9188,8 @@ paths: x-code-samples: - lang: Shell source: > - curl https://api.linode.com/v4beta/networking/firewalls + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4beta/networking/firewalls - lang: CLI source: > linode-cli firewalls list From 89cffb039d7618b9ddc2ceff7ecdb37202843876 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 19 Mar 2020 14:33:15 -0400 Subject: [PATCH 25/43] Add List Firewalls OAuth scope. --- openapi.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 004dce958..2946afc87 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9165,6 +9165,10 @@ paths: Returns a paginated list of your Firewalls. operationId: getFirewalls x-linode-cli-action: list + security: + - personalAccessToken: [] + - oauth: + - firewalls:read_only responses: '200': description: Returns an array of Firewalls. From ae05094322bc14902dc27c9b97d3ddb5f4ff646b Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Fri, 20 Mar 2020 14:11:04 -0400 Subject: [PATCH 26/43] Fix Delete Firewall and Delete Firwall Device response This also fixes CLI build error. --- openapi.yaml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 2946afc87..2107546bb 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9468,6 +9468,10 @@ paths: responses: '200': description: Delete Successful. + content: + application/json: + schema: + type: object default: $ref: '#/components/responses/ErrorResponse' x-code-samples: @@ -9681,6 +9685,10 @@ paths: responses: '200': description: Delete Successful. + content: + application/json: + schema: + type: object default: $ref: '#/components/responses/ErrorResponse' x-code-samples: From e99a1612432aee06ca202ce4e5d3b7ed7a0e7193 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Fri, 20 Mar 2020 15:44:34 -0400 Subject: [PATCH 27/43] Update Create Firewall Device's CLI example --- openapi.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 2107546bb..c77a545a8 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9601,7 +9601,9 @@ paths: https://api.linode.com/v4beta/networking/firewalls/123/devices - lang: CLI source: > - linode-cli networking device-create 123 + linode-cli firewalls device-create 123 \ + --id 456 \ + --type "linode" /networking/firewalls/{firewallId}/devices/{deviceId}: parameters: - name: firewallId From 0a8676dcb8cfa7fa0d9fd86c16515e3e9132aedf Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Fri, 20 Mar 2020 16:01:20 -0400 Subject: [PATCH 28/43] Update Create Firewall's CLI example --- openapi.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index c77a545a8..5caec0f4d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9317,7 +9317,8 @@ paths: https://api.linode.com/v4beta/networking/firewalls - lang: CLI source: > - linode-cli firewalls create + linode-cli firewalls create \ + --rules '{"inbound": [{"protocol": "TCP", "ports": "22, 80, 8080, 443", "addresses": {"ipv4": ["192.0.2.1", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]}' \ /networking/firewalls/{firewallId}: parameters: - name: firewallId From 5083a2d2a508c3b722155085484276ed43e6e3e0 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Tue, 7 Jul 2020 17:29:28 -0400 Subject: [PATCH 29/43] Fix Travis errors POST /{firewall_id}/devices missing allOf array --- openapi.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 5caec0f4d..51fb991d6 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9577,10 +9577,12 @@ paths: content: application/json: schema: + type: object required: - id - type - $ref: '#/components/schemas/FirewallDevices/properties/entity' + allOf: + - $ref: '#/components/schemas/FirewallDevices/properties/entity' responses: '200': description: Returns information about the created Firewall Device. From ba678ae7dc3db8e5a0623d73533f28378597e5b4 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 8 Jul 2020 15:42:54 -0400 Subject: [PATCH 30/43] Add label character limits to Firewall collection. --- openapi.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi.yaml b/openapi.yaml index 51fb991d6..ebbd69c27 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -15327,6 +15327,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. + * Must be between 3 and 32 characters. example: firewall123 minLength: 3 maxLength: 32 From 3cbffedc4c60db503a176f9967495e6f0069f3fc Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 8 Jul 2020 16:43:26 -0400 Subject: [PATCH 31/43] Update status field for Firewall schema Added information about the different available Firewall statuses. --- openapi.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index ebbd69c27..8559c7fc0 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -15354,7 +15354,11 @@ components: status: type: string description: > - The status of this Firewall service. + The status of this Firewall. + + * When a Firewall is first created its status is `enabled`. + * Use the [Update Firewall](/api/v4/networking-firewalls-firewall-id/#put) endpoint to set a Firewall's status to `enbaled` or `disabled`. + * Use the [Delete Firewall](/api/v4/networking-firewalls-firewall-id/#delete) endpoint to delete a Firewall. enum: - enabled - disabled From 42417c150c02c675c9db631d2c9267ee3a5e8fea Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 8 Jul 2020 16:46:04 -0400 Subject: [PATCH 32/43] Update PUT /firewalls/{firewallId} Shell example had incorrect formatting. --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 8559c7fc0..56f90dbd3 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9436,7 +9436,7 @@ paths: curl -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -X PUT -d '{ - "status": "disabled", + "status": "disabled" }' \ https://api.linode.com/v4beta/networking/firewalls/123 - lang: CLI From 76a132031ad9d68cf4fe61e4cfb53f3997dff4f8 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 8 Jul 2020 17:01:01 -0400 Subject: [PATCH 33/43] Fix Shell example for /firewalls/{firewallId}/devices --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 56f90dbd3..b8b782a09 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9541,7 +9541,7 @@ paths: - lang: Shell source: > curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/firewalls/123/devices + https://api.linode.com/v4beta/networking/firewalls/123/devices - lang: CLI source: > linode-cli firewalls devices-list 123 From f2475cd1b83ff278bd905ddb95d5589c4ef9e7a3 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 9 Jul 2020 09:43:46 -0400 Subject: [PATCH 34/43] Fix shell example for PUT /firewalls/{firewallId}/rules --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index b8b782a09..7ae031a69 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9746,7 +9746,7 @@ paths: - lang: Shell source: > curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/firewalls/123/rules + https://api.linode.com/v4beta/networking/firewalls/123/rules - lang: CLI source: > linode-cli firewalls rules-list 123 From 3d8b86e0840cfade414b342b088769bc63b77ffd Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 9 Jul 2020 10:17:10 -0400 Subject: [PATCH 35/43] Fix shell example POST /firewalls Missing curly brace --- openapi.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi.yaml b/openapi.yaml index 7ae031a69..2dcd385aa 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9289,6 +9289,7 @@ paths: } ], "outbound": [ + { "protocol": "TCP", "ports": "49152-65535", "addresses": { From 2dc02e05f5d0e45de924ba33a312b23ff8f84357 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Thu, 9 Jul 2020 12:04:36 -0400 Subject: [PATCH 36/43] Update requestBody for POST /firewalls status field is readOnly for this endpoint. Created the request body by referencing individual Firewall Schema properties. status field is not readOnly for all Firewall endpoints (i.e. PUT /firewalls/{firewallId} --- openapi.yaml | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 2dcd385aa..c73fcf8ea 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9228,34 +9228,35 @@ paths: - oauth: - firewall:read_write requestBody: + description: Creates a Firewall object that can be applied to a Linode service to filter the service's network traffic. content: application/json: schema: + type: object required: - rules - allOf: - - $ref: '#/components/schemas/Firewall' - - type: object + properties: + label: + $ref: '#/components/schemas/Firewall/properties/label' + rules: + $ref: '#/components/schemas/Firewall/properties/rules' + tags: + $ref: '#/components/schemas/Firewall/properties/tags' + devices: + type: object + description: > + A Firewall Device assigns a Firewall to a Linode service. Currently, Firewalls + can only be assigned to Linode instances. properties: - devices: - type: object + linodes: 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: - readOnly: true + An array of Linode IDs. A Firewall Device will be created for each ID. + type: array + items: + type: integer + example: + - 123 + - 456 responses: '200': description: Returns information about the created Firewall. From 627aea9741084dba9858f7595f9de26d74c32971 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Fri, 24 Jul 2020 15:49:10 -0400 Subject: [PATCH 37/43] Add note: Linode migration will fail if DC does not support Firewalls --- openapi.yaml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index c73fcf8ea..069459109 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9247,6 +9247,17 @@ paths: description: > A Firewall Device assigns a Firewall to a Linode service. Currently, Firewalls can only be assigned to Linode instances. + + * A Firewall can be assigned to multiple Linode services, and up to three active Firewalls can + be assigned to a single Linode service. + + * Additional disabled Firewalls can be assigned to a service, but they cannot be enabled if three other active Firewalls + are already assigned to the same service. + + + **Note:** When a Firewall is assigned to a Linode and you attempt + to [migrate the Linode to a data center](/api/v4/linode-instances-linode-id-migrate/#post) that does not support Cloud Firewalls, the migration will fail. + Use the [List Regions](/api/v4/regions) endpoint to view a list of a data center's capabilities. properties: linodes: description: > @@ -9565,6 +9576,10 @@ paths: Creating a Firewall Device will apply the Rules from a Firewall to a Linode service. A `firewall_device_add` Event is generated when the Firewall Device is added successfully. + **Note:** When a Firewall is assigned to a Linode and you attempt + to [migrate the Linode to a data center](/api/v4/linode-instances-linode-id-migrate/#post) that does not support Cloud Firewalls, the migration will fail. + Use the [List Regions](/api/v4/regions) endpoint to view a list of a data center's capabilities. + **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 updates in the future. This notice will be removed when this endpoint is out of From 8cf2213c543ff7c75d98e1bed38646aaa10290c7 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Fri, 24 Jul 2020 17:26:46 -0400 Subject: [PATCH 38/43] Fix Delete Firewall shell example --- openapi.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi.yaml b/openapi.yaml index 069459109..25f97678a 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9492,6 +9492,7 @@ paths: - lang: Shell source: > curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ -X DELETE \ https://api.linode.com/v4beta/networking/firewalls/123 - lang: CLI From 33d380a3d50f9b18e296ad29e40a35917edb79bc Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Fri, 24 Jul 2020 17:39:34 -0400 Subject: [PATCH 39/43] Fix shell example: Create Firewall Device --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 25f97678a..9b3c9c2df 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9617,7 +9617,7 @@ paths: -H "Authorization: Bearer $TOKEN" \ -X POST -d '{ "type": "linode", - "id": "123" + "id": 123 }' \ https://api.linode.com/v4beta/networking/firewalls/123/devices - lang: CLI From 4e565854836cb4fdaa80df0a79a2de77950214b9 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Fri, 24 Jul 2020 17:50:16 -0400 Subject: [PATCH 40/43] Fix shell example: Delete Firewall Device --- openapi.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi.yaml b/openapi.yaml index 9b3c9c2df..1321c3f9d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9718,6 +9718,7 @@ paths: - lang: Shell source: > curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ -X DELETE \ https://api.linode.com/v4beta/networking/firewalls/123/devices/456 - lang: CLI From 6ec58f2f6f0c5f0677ff18d604b990c38f64f885 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Fri, 24 Jul 2020 18:24:30 -0400 Subject: [PATCH 41/43] Fix shell example: Update Firewall Rules --- openapi.yaml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 1321c3f9d..7deb6a3d6 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9814,8 +9814,8 @@ paths: "inbound": [ { "protocol": "TCP", - "ports": "22, 80, 8080, 443" - "addresses": { + "ports": "22, 80, 443", + "addresses": { "ipv4": [ "192.0.2.1", "192.0.2.0/24" @@ -9827,8 +9827,9 @@ paths: } ], "outbound": [ + { "protocol": "TCP", - "ports": "49152-65535" + "ports": "49152-65535", "addresses": { "ipv4": [ "192.0.2.1", @@ -9840,7 +9841,7 @@ paths: } } ] - }' \ + }' \ https://api.linode.com/v4beta/networking/firewalls/123/rules - lang: CLI source: > From 3fa6eaac00adea2ac3dfb714681bc43f2ac582ce Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Wed, 29 Jul 2020 16:50:26 -0400 Subject: [PATCH 42/43] Minor copy edit --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 7deb6a3d6..2c0bc4edb 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -15456,7 +15456,7 @@ components: addresses: type: object description: > - Whitelisted IPv4 or IPv6 addresses. A Rule can have up to 255 addresses + Allowed IPv4 or IPv6 addresses. A Rule can have up to 255 addresses or networks listed across its IPv4 and IPv6 arrays. A network and a single IP are treated as equivalent when accounting for this limit. properties: From e9333683e73b7ebf8f2126ba8ccf0128afd3f3f3 Mon Sep 17 00:00:00 2001 From: leslitagordita Date: Mon, 17 Aug 2020 11:20:21 -0400 Subject: [PATCH 43/43] Small copy edit suggested by jottinger. --- openapi.yaml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 2c0bc4edb..7d0f3c9c5 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9211,9 +9211,7 @@ paths: instances. A Firewall can be assigned to multiple Linode services, and up to three active Firewalls - can be assigned to a single Linode service. Additional disabled Firewalls can be - assigned to a service, but they cannot be enabled if three other active Firewalls - are already assigned to the same service. + can be assigned to a single Linode service. A `firewall_create` Event is generated when this endpoint returns successfully.