openstack
/
neutron-specs
Code Issues Proposed changes
neutron-specs/misc/api/firewall_as_a_service__fwaa...

26 KiB
Raw Permalink Blame History

Firewall as a Service (FWaaS)

The FWaaS extension provides OpenStack users with the ability to deploy firewalls to protect their networks. The FWaaS extension enables you to:

  • Apply firewall rules on traffic entering and leaving tenant networks.
  • Support for applying tcp, udp, icmp, or protocol agnostic rules.
  • Creation and sharing of firewall policies which hold an ordered collection of the firewall rules.
  • Audit firewall rules and policies.

This extension introduces these resources:

  • firewall: represents a logical firewall resource that a tenant can instantiate and manage. A firewall is associated with one firewall_policy.
  • firewall_policy: is an ordered collection of firewall_rules. A firewall_policy can be shared across tenants. Thus it can also be made part of an audit workflow wherein the firewall_policy can be audited by the relevant entity that is authorized (and can be different from the tenants which create or use the firewall_policy).
  • firewall_rule: represents a collection of attributes like ports, ip addresses which define match criteria and action (allow, or deny) that needs to be taken on the matched data traffic.

Firewall rules

Manage firewall rules.

Table Firewall rule attributes

Attribute

Type

Required

CRUD :sup:[a]#ftn.fwaas_rule_crud_note

Default value

Validation constraints

Notes

id

uuid-str

N/A

R

generated

N/A

Unique identifier for the firewall rule object.

tenant_id

uuid-str

Yes

CR

Derived from Authentication token

N/A

Owner of the firewall rule. Only admin users can specify a tenant identifier other than their own.

name

String

No

CRU

None

N/A

Human readable name for the firewall rule (255 characters limit). Does not have to be unique.

description

String

No

CRU

None

N/A

Human readable description for the firewall Rule (1024 characters limit).

firewall_policy_id

uuid-str

No

R

None

N/A

This is a read-only attribute which gets populated with the uuid of the firewall policy when this firewall rule is associated with a firewall policy. A firewall rule can be associated with one firewall policy at a time. The association can however be updated to a different firewall policy. This attribute can be "null" if the rule is not associated with any firewall policy.

shared

Bool

No

CRU

false

{true false}

When set to True makes this firewall rule visible to tenants other than its owner, and can be used in firewall policies not owned by its tenant.

protocol

String

No

CRU

None

{icmp tcp udp null}

IP Protocol

ip_version

Integer

No

CRU

4

{4 6}

IP Protocol Version

source_ip_address

String (IP address or CIDR)

No

CRU

None

valid IP address (v4 or v6), or CIDR

Source IP address or CIDR

destination_ip_address

String (IP address or CIDR)

No

CRU

None

Valid IP address (v4 or v6), or CIDR

Destination IP address or CIDR

source_port

Integer

No

CRU

None

Valid port number (integer or string), or port range in the format of a ':' separated range). In the case of port range, both ends of the range are included.

Source port number or a range

destination_port

Integer

No

CRU

None

Valid port number (integer or string), or port range in the format of a ':' separated range. In the case of port range, both ends of the range are included.

Destination port number or a range

position

Integer

No

R

None

N/A

This is a read-only attribute that gets assigned to this rule when the rule is associated with a firewall policy. It indicates the position of this rule in that firewall policy. This position number starts at 1. The position can be "null" if the firewall rule is not associated with any policy.

action

String

No

CRU

deny

{allow deny}

Action to be performed on the traffic matching the rule (allow, deny)

enabled

Bool

No

CRU

true

{true false}

When set to False will disable this rule in the firewall policy. Facilitates selectively turning off rules without having to disassociate the rule from the firewall policy

  • `:sup:`[a]` <#fwaas_rule_crud_note>`__C. Use the attribute in create operations.
  • R. This attribute is returned in response to show and list operations.
  • U. You can update the value of this attribute.
  • D. You can delete the value of this attribute.

List firewall rules

GET

/fw/firewall_rules

Lists firewall rules.

Normal Response Code: 200

Error Response Codes: Unauthorized (401).

This operation does not require a request body.

This operation returns a response body.

Example 4.44. List firewall rules: JSON request

GET /v2.0/fw/firewall_rules.json
User-Agent: python-neutronclient
Accept: application/json

Example List firewall rules: JSON response

{
    "firewall_rules": [
        {
            "action": "allow",
            "description": "",
            "destination_ip_address": null,
            "destination_port": "80",
            "enabled": true,
            "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
            "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0",
            "ip_version": 4,
            "name": "ALLOW_HTTP",
            "position": 1,
            "protocol": "tcp",
            "shared": false,
            "source_ip_address": null,
            "source_port": null,
            "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
        }
    ]
}

Show firewall rule details

GET

/fw/firewall_rules/``firewall_rule-id``

Shows firewall rule details.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Forbidden (403), Not Found (404)

This operation does not require a request body.

This operation returns a response body.

Example 4.46. Show firewall rule: JSON request

GET /v2.0/fw/firewall_rules/9faaf49f-dd89-4e39-a8c6-101839aa49bc.json
User-Agent: python-neutronclient
Accept: application/json

Example Show firewall rule: JSON response

{
    "firewall_rule": {
        "action": "allow",
        "description": "",
        "destination_ip_address": null,
        "destination_port": "80",
        "enabled": true,
        "firewall_policy_id": null,
        "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0",
        "ip_version": 4,
        "name": "ALLOW_HTTP",
        "position": null,
        "protocol": "tcp",
        "shared": false,
        "source_ip_address": null,
        "source_port": null,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}

Create firewall rule

POST

/fw/firewall_rules

Creates a firewall rule.

Normal Response Code: 201

Error Response Codes: Unauthorized (401), Bad Request (400)

This operation requires a request body.

This operation returns a response body.

Example 4.48. Create firewall rule: JSON request

POST /v2.0/fw/firewall_rules.json
User-Agent: python-neutronclient
Accept: application/json
{
    "firewall_rule": {
        "action": "allow",
        "destination_port": "80",
        "enabled": true,
        "name": "ALLOW_HTTP",
        "protocol": "tcp"
    }
}

Example Create firewall rule: JSON response

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
{
    "firewall_rule": {
        "action": "allow",
        "description": "",
        "destination_ip_address": null,
        "destination_port": "80",
        "enabled": true,
        "firewall_policy_id": null,
        "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0",
        "ip_version": 4,
        "name": "ALLOW_HTTP",
        "position": null,
        "protocol": "tcp",
        "shared": false,
        "source_ip_address": null,
        "source_port": null,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}

Update firewall rule

PUT

/fw/firewall_rules/``firewall_rule-id``

Updates a firewall rule.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404)

Example Update firewall rule: JSON request

PUT /v2.0/fw/firewall_rules/41bfef97-af4e-4f6b-a5d3-4678859d2485.json
User-Agent: python-neutronclient
Accept: application/json
{
    "firewall_rule": {
        "shared": "true"
    }
}

Example Update firewall rule: JSON response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "firewall_rule": {
        "action": "allow",
        "description": "",
        "destination_ip_address": null,
        "destination_port": "80",
        "enabled": true,
        "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "id": "8722e0e0-9cc9-4490-9660-8c9a5732fbb0",
        "ip_version": 4,
        "name": "ALLOW_HTTP",
        "position": 1,
        "protocol": "tcp",
        "shared": true,
        "source_ip_address": null,
        "source_port": null,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}

Delete firewall rule

DELETE

/fw/firewall_rules/``firewall_rule-id``

Deletes a firewall rule.

Normal Response Code: 204

Error Response Codes: Unauthorized (401), Not Found (404), Conflict (409). The Conflict error response is returned when an operation is performed while the firewall is in a PENDING state.

This operation does not require a request body.

This operation does not return a response body.

Example Delete firewall rule: JSON request

DELETE /v2.0/fw/firewall_rules/1be5e5f7-c45e-49ba-85da-156575b60d50.json
User-Agent: python-neutronclient
Accept: application/json

Example 4.53. Delete firewall rule: JSON response

HTTP/1.1 204 No Content
Content-Length: 0

Firewall policies

Manage firewall policies.

Table 4.6. Firewall policy attributes

Attribute

Type

Required

CRUD :sup:[a]#ftn.fwaas_policy_crud_note

Default value

Validation constraints

Notes

id

uuid-str

N/A

R

generated

N/A

Unique identifier for the firewall policy object.

tenant_id

uuid-str

Yes

CR

Derived from Authentication token

N/A

Owner of the firewall policy. Only admin users can specify a tenant identifier other than their own.

name

String

No

CRU

None

N/A

Human readable name for the firewall policy (255 characters limit). Does not have to be unique.

description

String

No

CRU

None

N/A

Human readable description for the firewall policy (1024 characters limit)

shared

Bool

No

CRU

false

{true false}

When set to True makes this firewall policy visible to tenants other than its owner.

firewall_rules

List

No

CRU

Empty list

JSON list of firewall rule uuids

This is an ordered list of firewall rule uuids. The firewall applies the rules in the order in which they appear in this list.

audited

Bool

No

CRU

false

{true false}

When set to True by the policy owner indicates that the firewall policy has been audited. This attribute is meant to aid in the firewall policy audit workflows. Each time the firewall policy or the associated firewall rules are changed, this attribute will be set to False and will have to be explicitly set to True through an update operation.

  • `:sup:`[a]` <#fwaas_policy_crud_note>`__C. Use the attribute in create operations.
  • R. This attribute is returned in response to show and list operations.
  • U. You can update the value of this attribute.
  • D. You can delete the value of this attribute.

List firewall policies

GET

/fw/firewall_policies

Lists firewall policies.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Forbidden (403)

This operation does not require a request body.

This operation returns a response body.

Example List firewall policies: JSON request

GET /v2.0/fw/firewall_policies.json
User-Agent: python-neutronclient
Accept: application/json

Example List firewall policies: JSON response

{
    "firewall_policies": [
        {
            "audited": false,
            "description": "",
            "firewall_rules": [
                "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
            ],
            "id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
            "name": "test-policy",
            "shared": false,
            "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
        }
    ]
}

Show firewall policy details

GET

/fw/firewall_policies/``firewall_policy-id``

Shows firewall policy details.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Not Found (404)

This operation does not require a request body.

This operation returns a response body.

Example Show firewall policy: JSON request

GET /v2.0/fw/firewall_policies/9faaf49f-dd89-4e39-a8c6-101839aa49bc.json
User-Agent: python-neutronclient
Accept: application/json

Example Show firewall policy: JSON response

{
    "firewall_policy": {
        "audited": false,
        "description": "",
        "firewall_rules": [
            "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
        ],
        "id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "name": "test-policy",
        "shared": false,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}

Create firewall policy

POST

/fw/firewall_policies

Creates a firewall policy.

Normal Response Code: 201

Error Response Codes: Unauthorized (401).

This operation requires a request body.

This operation returns a response body.

Example 4.58. Create firewall policy: JSON request

POST /v2.0/fw/firewall_policies.json
User-Agent: python-neutronclient
Accept: application/json
{
    "firewall_policy": {
        "firewall_rules": [
            "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
        ],
        "name": "test-policy"
    }
}

Example Create firewall policy: JSON response

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
{
    "firewall_policy": {
        "audited": false,
        "description": "",
        "firewall_rules": [
            "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
        ],
        "id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "name": "test-policy",
        "shared": false,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}

Update firewall policy

PUT

/fw/firewall_policies/``firewall_policy-id``

Updates a firewall policy.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Not Found (404)

Example Update firewall policy: JSON request

PUT /v2.0/fw/firewall_policies/41bfef97-af4e-4f6b-a5d3-4678859d2485.json
User-Agent: python-neutronclient
Accept: application/json
{
    "firewall_policy": {
        "firewall_rules": [
            "a08ef905-0ff6-4784-8374-175fffe7dade",
            "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
        ]
    }
}

Example Update firewall policy: JSON response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "firewall_policy": {
        "audited": false,
        "description": "",
        "firewall_rules": [
            "a08ef905-0ff6-4784-8374-175fffe7dade",
            "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
        ],
        "id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "name": "test-policy",
        "shared": false,
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}

Delete firewall policy

DELETE

/fw/firewall_policies/``firewall_policy-id``

Deletes a firewall policy.

Normal Response Code: 204

Error Response Codes: Unauthorized (401), Not Found (404), Conflict (409 ). Conflict error code is returned the firewall policy is in use.

This operation does not require a request body.

This operation does not return a response body.

Example Delete firewall policy: JSON request

DELETE /v2.0/fw/firewall_policies/1be5e5f7-c45e-49ba-85da-156575b60d50.json
User-Agent: python-neutronclient
Accept: application/json

Example Delete firewall policy: JSON response

HTTP/1.1 204 No Content
Content-Length: 0

Insert firewall rule in firewall policy

PUT

/fw/firewall_policies/``firewall_policy-id``/insert_rule

Inserts a firewall rule in a firewall policy relative to the position of other rules.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404). Bad Request error is returned in the case the rule information is missing.

Example Insert firewall rule in firewall policy: JSON request

PUT /v2.0/fw/firewall_policies/41bfef97-af4e-4f6b-a5d3-4678859d2485/insert_rule.json
User-Agent: python-neutronclient
Accept: application/json
{
    "firewall_rule_id": "7bc34b8c-8d3b-4ada-a9c8-1f4c11c65692",
    "insert_after": "a08ef905-0ff6-4784-8374-175fffe7dade",
    "insert_before": ""
}

Example Insert firewall rule in firewall policy: Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "audited": false,
    "description": "",
    "firewall_list": [],
    "firewall_rules": [
        "a08ef905-0ff6-4784-8374-175fffe7dade",
        "7bc34b8c-8d3b-4ada-a9c8-1f4c11c65692",
        "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
    ],
    "id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
    "name": "test-policy",
    "shared": false,
    "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
}

insert_before and insert_after parameters refer to firewall rule uuids already associated with the firewall policy. firewall_rule_id refers to uuid of the rule being inserted. insert_before takes precedence over insert_after and if neither is specified, firewall_rule_is inserted at the first position.

Remove firewall rule from firewall policy

PUT

/fw/firewall_policies/``firewall_policy-id``/remove_rule

Removes a firewall rule from a firewall policy.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404). Bad Request error is returned if the rule information is missing or when a firewall rule is tried to be removed from a firewall policy to which it is not associated.

Example Remove firewall rule from firewall policy: JSON request

PUT /v2.0/fw/firewall_policies/41bfef97-af4e-4f6b-a5d3-4678859d2485/remove_rule.json
User-Agent: python-neutronclient
Accept: application/json
{
    "firewall_rule_id": "7bc34b8c-8d3b-4ada-a9c8-1f4c11c65692"
}

Example Remove firewall rule from firewall policy: JSON response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "audited": false,
    "description": "",
    "firewall_list": [],
    "firewall_rules": [
        "a08ef905-0ff6-4784-8374-175fffe7dade",
        "8722e0e0-9cc9-4490-9660-8c9a5732fbb0"
    ],
    "id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
    "name": "test-policy",
    "shared": false,
    "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
}

Firewalls

Manage firewalls.

Table Firewall attributes

Attribute

Type

Required

CRUD:sup:[a]#ftn.fwaas_firewall_crud_note

Default value

Validation constraints

Notes

id

uuid-str

N/A

R

generated

N/A

Unique identifier for the firewall object.

tenant_id

uuid-str

Yes

CR

Derived from Authentication token

N/A

Owner of the firewall. Only admin users can specify a tenant identifier other than their own.

name

String

No

CRU

None

N/A

Human readable name for the firewall (255 characters limit). Does not have to be unique.

description

String

No

CRU

None

N/A

Human readable description for the firewall (1024 characters limit)

admin_state_up

Bool

N/A

CRU

true

{true false }

Administrative state of the firewall. If false (down), firewall does not forward packets and will drop all traffic to/from VMs behind the firewall.

status

String

N/A

R

N/A

N/A

Indicates whether firewall resource is currently operational. Possible values include: ACTIVE, DOWN, BUILD, ERROR, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE.

shared

Bool

No

CRU

false

{true false}

When set to True makes this firewall rule visible to tenants other than its owner, and can be used in firewall policies not owned by its tenant.

firewall_policy_id

uuid-str

No

CRU

None

valid firewall policy uuid

The firewall policy uuid that this firewall is associated with. This firewall will implement the rules contained in the firewall policy represented by this uuid.

  • `:sup:`[a]` <#fwaas_firewall_crud_note>`__C. Use the attribute in create operations.
  • R. This attribute is returned in response to show and list operations.
  • U. You can update the value of this attribute.
  • D. You can delete the value of this attribute.

List firewalls

GET

/fw/firewalls

Lists firewalls.

Normal Response Code: 200

Error Response Codes: Unauthorized (401)

This operation does not require a request body.

This operation returns a response body.

Example 4.68. List firewalls: JSON request

GET /v2.0/fw/firewalls.json
User-Agent: python-neutronclient
Accept: application/json

Example List firewalls: JSON response

{
    "firewalls": [
        {
            "admin_state_up": true,
            "description": "",
            "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
            "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977",
            "name": "",
            "status": "ACTIVE",
            "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
        }
    ]
}

Show firewall details

GET

/fw/firewalls/``firewall-id``

Shows firewall details.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Forbidden (403), Not Found (404)

This operation does not require a request body.

This operation returns a response body.

Example 4.70. Show firewall: JSON request

GET /v2.0/fw/firewalls/9faaf49f-dd89-4e39-a8c6-101839aa49bc.json
User-Agent: python-neutronclient
Accept: application/json

Example Show firewall: JSON response

{
    "firewall": {
        "admin_state_up": true,
        "description": "",
        "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977",
        "name": "",
        "status": "ACTIVE",
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}

Create firewall

POST

/fw/firewalls

Creates a firewall.

Normal Response Code: 201

Error Response Codes: Unauthorized (401), Bad Request (400)

This operation requires a request body.

This operation returns a response body.

Example Create firewall: JSON request

POST /v2.0/fw/firewalls.json
User-Agent: python-neutronclient
Accept: application/json
{
    "firewall": {
        "admin_state_up": true,
        "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c"
    }
}

Example Create firewall: JSON response

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
{
    "firewall": {
        "admin_state_up": true,
        "description": "",
        "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977",
        "name": "",
        "status": "PENDING_CREATE",
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}

Update firewall

PUT

/fw/firewalls/``firewall-id``

Updates a firewall, provided status is not PENDING_*.

Normal Response Code: 200

Error Response Codes: Unauthorized (401), Bad Request (400), Not Found (404)

Example 4.74. Update firewall: JSON request

PUT /v2.0/fw/firewalls/41bfef97-af4e-4f6b-a5d3-4678859d2485.json
User-Agent: python-neutronclient
Accept: application/json
{
    "firewall": {
        "admin_state_up": "false"
    }
}

Example Update firewall: JSON response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "firewall": {
        "admin_state_up": false,
        "description": "",
        "firewall_policy_id": "c69933c1-b472-44f9-8226-30dc4ffd454c",
        "id": "3b0ef8f4-82c7-44d4-a4fb-6177f9a21977",
        "name": "",
        "status": "PENDING_UPDATE",
        "tenant_id": "45977fa2dbd7482098dd68d0d8970117"
    }
}

Delete firewall

DELETE

/fw/firewalls/``firewall-id``

Deletes a firewall.

Normal Response Code: 204

Error Response Codes: Unauthorized (401), Not Found (404)

This operation does not require a request body.

This operation does not return a response body.

Example Delete firewall: JSON request

DELETE /v2.0/fw/firewalls/1be5e5f7-c45e-49ba-85da-156575b60d50.json
User-Agent: python-neutronclient
Accept: application/json

Example Delete firewall: JSON response

HTTP/1.1 204 No Content
Content-Length: 0