# Firewalls

## Create

**post** `/v2/firewalls`

To create a new firewall, send a POST request to `/v2/firewalls`. The request
must contain at least one inbound or outbound access rule.

### Returns

- **firewall:** `Firewall`

## Retrieve

**get** `/v2/firewalls/{firewall_id}`

To show information about an existing firewall, send a GET request to `/v2/firewalls/$FIREWALL_ID`.

### Returns

- **firewall:** `Firewall`

## Update

**put** `/v2/firewalls/{firewall_id}`

To update the configuration of an existing firewall, send a PUT request to
`/v2/firewalls/$FIREWALL_ID`. The request should contain a full representation
of the firewall including existing attributes. **Note that any attributes that
are not provided will be reset to their default values.**
<br><br>You must have read access (e.g. `droplet:read`) to all resources attached
to the firewall to successfully update the firewall.

### Returns

- **firewall:** `Firewall`

## List

**get** `/v2/firewalls`

To list all of the firewalls available on your account, send a GET request to `/v2/firewalls`.

### Returns

- **meta:** `MetaProperties`

  Information about the response itself.

- **firewalls:** `array of Firewall`

- **links:** `PageLinks`

## Delete

**delete** `/v2/firewalls/{firewall_id}`

To delete a firewall send a DELETE request to `/v2/firewalls/$FIREWALL_ID`.

No response body will be sent back, but the response code will indicate
success. Specifically, the response code will be a 204, which means that the
action was successful with no returned body data.

## Domain Types

### Firewall

- **Firewall:** `object { id, created_at, droplet_ids, 6 more }`

  - **id:** `string`

    A unique ID that can be used to identify and reference a firewall.

  - **created\_at:** `string`

    A time value given in ISO8601 combined date and time format that represents when the firewall was created.

  - **droplet\_ids:** `array of number`

    An array containing the IDs of the Droplets assigned to the firewall. <br><br>Requires `droplet:read` scope.

  - **inbound\_rules:** `array of object { ports, protocol, sources }`

    - **ports:** `string`

      The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "0" when all ports are open for a protocol. For ICMP rules this parameter will always return "0".

    - **protocol:** `"tcp" or "udp" or "icmp"`

      The type of traffic to be allowed. This may be one of `tcp`, `udp`, or `icmp`.

      - `"tcp"`

      - `"udp"`

      - `"icmp"`

    - **sources:** `FirewallRuleTarget`

      An object specifying locations from which inbound traffic will be accepted.

  - **name:** `string`

    A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-).

  - **outbound\_rules:** `array of object { destinations, ports, protocol }`

    - **destinations:** `FirewallRuleTarget`

      An object specifying locations to which outbound traffic that will be allowed.

    - **ports:** `string`

      The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "0" when all ports are open for a protocol. For ICMP rules this parameter will always return "0".

    - **protocol:** `"tcp" or "udp" or "icmp"`

      The type of traffic to be allowed. This may be one of `tcp`, `udp`, or `icmp`.

      - `"tcp"`

      - `"udp"`

      - `"icmp"`

  - **pending\_changes:** `array of object { droplet_id, removing, status }`

    An array of objects each containing the fields "droplet_id", "removing", and "status". It is provided to detail exactly which Droplets are having their security policies updated. When empty, all changes have been successfully applied.

    - **droplet\_id:** `number`

    - **removing:** `boolean`

    - **status:** `string`

  - **status:** `"waiting" or "succeeded" or "failed"`

    A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed".

    - `"waiting"`

    - `"succeeded"`

    - `"failed"`

  - **tags:** `array of string`

    A flat array of tag names as strings to be applied to the resource. Tag names must exist in order to be referenced in a request. <br><br>Requires `tag:create` and `tag:read` scopes.