Operations of the firewall tag of the native REST API.
Distributed firewall at the vNIC (docs/network/DFW-HOSTBRIDGE.md, ADR-011)
GET /v1/firewall/bypass
The emergency bypasses in force.
- CLI
kyvernon firewall bypass list
Responses
POST /v1/firewall/bypass
Opens every vNIC of a host for a limited time with an audited Emergency rule (a task; Kyvernon.Firewall.Bypass). Enabling it again extends it.
- CLI
kyvernon firewall bypass --host <host> --reason <reason> --for <duration> [--wait]
Request body
application/json: BypassBody
| Name | Type | Required | Description |
|---|
durationSeconds | integer (int64) or null | | How long, seconds (60 to 86,400; default 1,800). |
|---|
host | string | yes | Host id (host-N). |
|---|
reason | string | yes | Why (kept in the policy and the events; 1 to 500 characters). |
|---|
Responses
| Status | Description | Schema |
|---|
| 202 | Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) | TaskRef |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
DELETE /v1/firewall/bypass/{id}
Ends a bypass before its time.
- CLI
kyvernon firewall bypass remove <id> [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall bypass |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
GET /v1/firewall/groups
Firewall groups of a scope (a tenant user: its own and the shared provider groups, name only).
- CLI
kyvernon firewall groups list [--tenant <tenant>]
Parameters
| Name | In | Type | Required | Description |
|---|
tenant | query | string or null | | Tenant id (tenant-N); absent: the provider (a tenant user: its tenant). |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | array of GroupView |
|---|
POST /v1/firewall/groups
Creates a group (Kyvernon.Firewall.ManageGroups; a shared provider group needs Kyvernon.Firewall.ManageProvider).
- CLI
kyvernon firewall groups create --name <name> [--criterion <tags>] [--vm <vm>] [--prefix <prefix>] [--tenant <tenant>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: GroupBody
| Name | Type | Required | Description |
|---|
criteria | array of array of TagView | | Tag criteria: a vNIC is a member when its VM carries every tag of one criterion. |
|---|
description | string | | Description (tenants see it with the name for shared provider groups). |
|---|
groups | array of string | | Nested groups. |
|---|
macs | array of string | | Every vNIC with one of these MAC addresses (00:50:56:aa:bb:cc). |
|---|
name | string | yes | Name (unique in its scope; sys: is reserved). |
|---|
networks | array of string | | Every vNIC on these host-bridge networks. |
|---|
prefixes | array of string | | Addresses and prefixes (endpoints outside the platform). |
|---|
shared | boolean | | Provider groups only: tenants may use it as source or destination (name only). |
|---|
vms | array of string | | Every vNIC of these VMs. |
|---|
vnics | array of VnicView | | These vNICs. |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | GroupView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
GET /v1/firewall/groups/{id}
One group.
- CLI
kyvernon firewall groups show <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall group |
|---|
Responses
PUT /v1/firewall/groups/{id}
Replaces a group.
- CLI
kyvernon firewall groups update <id> [--name <name>] [--criterion <tags>] [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall group |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: GroupBody
| Name | Type | Required | Description |
|---|
criteria | array of array of TagView | | Tag criteria: a vNIC is a member when its VM carries every tag of one criterion. |
|---|
description | string | | Description (tenants see it with the name for shared provider groups). |
|---|
groups | array of string | | Nested groups. |
|---|
macs | array of string | | Every vNIC with one of these MAC addresses (00:50:56:aa:bb:cc). |
|---|
name | string | yes | Name (unique in its scope; sys: is reserved). |
|---|
networks | array of string | | Every vNIC on these host-bridge networks. |
|---|
prefixes | array of string | | Addresses and prefixes (endpoints outside the platform). |
|---|
shared | boolean | | Provider groups only: tenants may use it as source or destination (name only). |
|---|
vms | array of string | | Every vNIC of these VMs. |
|---|
vnics | array of VnicView | | These vNICs. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | GroupView |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
DELETE /v1/firewall/groups/{id}
Deletes a group (refused while it is referenced).
- CLI
kyvernon firewall groups delete <id> [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall group |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
GET /v1/firewall/groups/{id}/members
Resolved members of a group: vNICs and addresses.
- CLI
kyvernon firewall groups members <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall group |
|---|
Responses
GET /v1/firewall/logs
Firewall log records of every host, newest first (kept in memory, bounded).
- CLI
kyvernon firewall logs [--host <host>] [--rule <n>] [--limit <n>]
Parameters
| Name | In | Type | Required | Description |
|---|
limit | query | integer or null | | Most records (default 500, at most 5,000). |
|---|
host | query | string or null | | Host id. |
|---|
rule | query | integer (int32) or null | | Rule number. |
|---|
Responses
GET /v1/firewall/policies
Policies with their rules, in evaluation order.
- CLI
kyvernon firewall policies list [--tenant <tenant>]
Parameters
| Name | In | Type | Required | Description |
|---|
tenant | query | string or null | | Tenant id (tenant-N); absent: the provider (a tenant user: its tenant). |
|---|
Responses
POST /v1/firewall/policies
Creates a policy (Environment and Application: Kyvernon.Firewall.ManagePolicies; Emergency and Infrastructure: Kyvernon.Firewall.ManageProvider).
- CLI
kyvernon firewall policies create --name <name> --category application [--tenant <tenant>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: PolicyBody
| Name | Type | Required | Description |
|---|
appliedTo | array of string | | Groups the policy applies to (empty: every vNIC; a tenant's: its own vNICs). |
|---|
category | CategoryView | yes | Category; tenants may use environment and application only. |
|---|
description | string | | Description. |
|---|
enabled | boolean | | Enabled (default true). |
|---|
name | string | yes | Name (unique in its scope; sys: is reserved). |
|---|
rules | array of RuleBody or null | | Rules in order. |
|---|
sequence | integer (int32) or null | | Order inside the category (lower first). Default: after the scope's last policy. |
|---|
stateful | boolean | | Replies are allowed automatically (default true). |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | PolicyView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
GET /v1/firewall/policies/{id}
One policy with its rules.
- CLI
kyvernon firewall policies show <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall policy |
|---|
Responses
PUT /v1/firewall/policies/{id}
Replaces a policy (with rules: its rules too; a rule with the id of an existing one keeps its number and counters).
- CLI
kyvernon firewall policies update <id> [--sequence <n>] [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall policy |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: PolicyBody
| Name | Type | Required | Description |
|---|
appliedTo | array of string | | Groups the policy applies to (empty: every vNIC; a tenant's: its own vNICs). |
|---|
category | CategoryView | yes | Category; tenants may use environment and application only. |
|---|
description | string | | Description. |
|---|
enabled | boolean | | Enabled (default true). |
|---|
name | string | yes | Name (unique in its scope; sys: is reserved). |
|---|
rules | array of RuleBody or null | | Rules in order. |
|---|
sequence | integer (int32) or null | | Order inside the category (lower first). Default: after the scope's last policy. |
|---|
stateful | boolean | | Replies are allowed automatically (default true). |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | PolicyView |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
DELETE /v1/firewall/policies/{id}
Deletes a policy and its rules.
- CLI
kyvernon firewall policies delete <id> [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall policy |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
GET /v1/firewall/policies/{id}/rules
The rules of a policy.
- CLI
kyvernon firewall rules list --policy <policy>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall policy |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | array of RuleView |
|---|
POST /v1/firewall/policies/{id}/rules
Adds a rule (?position=: default last); the control plane gives it its number.
- CLI
kyvernon firewall rules add --policy <policy> --action allow [--service <service>] [--position <n>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall policy |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: RuleBody
| Name | Type | Required | Description |
|---|
action | ActionView | yes | Action. |
|---|
appliedTo | array of string | | Groups the rule applies to (empty: the policy's). |
|---|
destinations | array of string | | Destinations (empty: any). |
|---|
destinationsNegated | boolean | | Match everything except the destinations. |
|---|
direction | DirectionView | | Direction (default in-out). |
|---|
enabled | boolean | | Enabled (default true). |
|---|
id | string or null | | Id of an existing rule (policy PUT: keeps its number and counters); ignored when a rule is added. |
|---|
ipVersion | IpVersionView | | IP families (default any). |
|---|
logged | boolean | | Log matches. |
|---|
name | string | | Display name. |
|---|
services | array of ServiceEntryView | | Services (empty: any IP traffic). |
|---|
sources | array of string | | Sources: group ids, addresses or prefixes (empty: any). |
|---|
sourcesNegated | boolean | | Match everything except the sources. |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | RuleView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
GET /v1/firewall/policies/{id}/rules/{rid}
One rule (by id or number).
- CLI
kyvernon firewall rules show <rule> --policy <policy>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall policy |
|---|
rid | path | string | yes | Id of the rule in the policy |
|---|
Responses
PUT /v1/firewall/policies/{id}/rules/{rid}
Replaces a rule (keeps its number and position). If-Match is the policy's version.
- CLI
kyvernon firewall rules update <rule> --policy <policy> [--action drop] [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall policy |
|---|
rid | path | string | yes | Id of the rule in the policy |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: RuleBody
| Name | Type | Required | Description |
|---|
action | ActionView | yes | Action. |
|---|
appliedTo | array of string | | Groups the rule applies to (empty: the policy's). |
|---|
destinations | array of string | | Destinations (empty: any). |
|---|
destinationsNegated | boolean | | Match everything except the destinations. |
|---|
direction | DirectionView | | Direction (default in-out). |
|---|
enabled | boolean | | Enabled (default true). |
|---|
id | string or null | | Id of an existing rule (policy PUT: keeps its number and counters); ignored when a rule is added. |
|---|
ipVersion | IpVersionView | | IP families (default any). |
|---|
logged | boolean | | Log matches. |
|---|
name | string | | Display name. |
|---|
services | array of ServiceEntryView | | Services (empty: any IP traffic). |
|---|
sources | array of string | | Sources: group ids, addresses or prefixes (empty: any). |
|---|
sourcesNegated | boolean | | Match everything except the sources. |
|---|
Responses
DELETE /v1/firewall/policies/{id}/rules/{rid}
Deletes a rule.
- CLI
kyvernon firewall rules delete <rule> --policy <policy> [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall policy |
|---|
rid | path | string | yes | Id of the rule in the policy |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
POST /v1/firewall/policies/{id}/rules/{rid}/move
Moves a rule inside its policy.
- CLI
kyvernon firewall rules move <rule> --policy <policy> --position <n> [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall policy |
|---|
rid | path | string | yes | Id of the rule in the policy |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: MoveRuleBody
| Name | Type | Required | Description |
|---|
position | integer (int32) | yes | New position (0 first; beyond the end: last). |
|---|
Responses
GET /v1/firewall/policies/{id}/stats
Hit counters of a policy's rules: packets, bytes, per host and total, last hit.
- CLI
kyvernon firewall stats --policy <policy>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall policy |
|---|
Responses
GET /v1/firewall/profiles
Default profiles (a tenant user: the selectable ones).
- CLI
kyvernon firewall profiles list
Responses
POST /v1/firewall/profiles
Creates a provider profile.
- CLI
kyvernon firewall profiles create --name <name> --inbound drop --outbound allow [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: ProfileBody
| Name | Type | Required | Description |
|---|
baseline | string or null | | Baseline policy (a provider Application policy evaluated after every tenant rule). |
|---|
inbound | DefaultActionView | yes | Default for traffic arriving at the vNIC. |
|---|
name | string | yes | Name. |
|---|
outbound | DefaultActionView | yes | Default for traffic leaving the vNIC. |
|---|
selectable | boolean | | Tenants may choose it. |
|---|
Responses
GET /v1/firewall/profiles/{id}
One profile.
- CLI
kyvernon firewall profiles show <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall profile |
|---|
Responses
PUT /v1/firewall/profiles/{id}
Replaces a profile (a built-in name stores a replacement of the built-in).
- CLI
kyvernon firewall profiles set <id> [--inbound drop] [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall profile |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: ProfileBody
| Name | Type | Required | Description |
|---|
baseline | string or null | | Baseline policy (a provider Application policy evaluated after every tenant rule). |
|---|
inbound | DefaultActionView | yes | Default for traffic arriving at the vNIC. |
|---|
name | string | yes | Name. |
|---|
outbound | DefaultActionView | yes | Default for traffic leaving the vNIC. |
|---|
selectable | boolean | | Tenants may choose it. |
|---|
Responses
DELETE /v1/firewall/profiles/{id}
Deletes a provider profile (a replaced built-in comes back).
- CLI
kyvernon firewall profiles delete <id> [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall profile |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
GET /v1/firewall/realization
Realization per host: wanted and applied plan version, error, flows, preconditions.
- CLI
kyvernon firewall realization [--host <host>]
Parameters
| Name | In | Type | Required | Description |
|---|
host | query | string or null | | Host id. |
|---|
Responses
GET /v1/firewall/rules/{number}/stats
Hit counters of one rule by number.
- CLI
kyvernon firewall stats --rule <n>
Parameters
| Name | In | Type | Required | Description |
|---|
number | path | integer (int32) | yes | Rule number, as the effective rules and the logs show it |
|---|
Responses
GET /v1/firewall/services
Named services (a tenant user: its own and the provider's).
- CLI
kyvernon firewall services list [--tenant <tenant>]
Parameters
| Name | In | Type | Required | Description |
|---|
tenant | query | string or null | | Tenant id (tenant-N); absent: the provider (a tenant user: its tenant). |
|---|
Responses
POST /v1/firewall/services
Creates a named service.
- CLI
kyvernon firewall services create --name <name> --entry <entry> [--tenant <tenant>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: ServiceBody
| Name | Type | Required | Description |
|---|
description | string | | Description. |
|---|
entries | array of ServiceEntryView | yes | Entries (no named services inside). |
|---|
name | string | yes | Name. |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | ServiceView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
GET /v1/firewall/services/{id}
One named service.
- CLI
kyvernon firewall services show <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall service |
|---|
Responses
PUT /v1/firewall/services/{id}
Replaces a named service.
- CLI
kyvernon firewall services update <id> [--entry <entry>] [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall service |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: ServiceBody
| Name | Type | Required | Description |
|---|
description | string | | Description. |
|---|
entries | array of ServiceEntryView | yes | Entries (no named services inside). |
|---|
name | string | yes | Name. |
|---|
Responses
DELETE /v1/firewall/services/{id}
Deletes a named service (refused while a rule uses it).
- CLI
kyvernon firewall services delete <id> [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall service |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
GET /v1/firewall/settings
The firewall settings.
- CLI
kyvernon firewall settings show
Responses
PUT /v1/firewall/settings
Changes the firewall settings.
- CLI
kyvernon firewall settings set [--log-rate-pps <n>] [--if-match <version>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: SettingsView
| Name | Type | Required | Description |
|---|
ctLimitPerPort | integer (int32) | yes | Connection-tracking entries per vNIC. |
|---|
enforceNew | boolean | yes | vNICs added to VMs from now on start in mode enforce (default false: mode off); existing vNICs are not changed. |
|---|
flowLimitPerBridge | integer (int32) | yes | Firewall flows per host bridge. |
|---|
logRatePps | integer (int32) | yes | Log rate per host (packets per second, meter kyv-fw-log). |
|---|
monitorReportDays | integer (int32) | yes | Days a monitor report covers. |
|---|
rejectRatePps | integer (int32) | yes | Reject answers per second per bridge (meter kyv-fw-reject). |
|---|
version | integer (int64) | | Record version (ignored in requests). |
|---|
Responses
POST /v1/firewall/simulate
Verdict and deciding rule for a described packet at a vNIC (reference evaluator).
- CLI
kyvernon firewall simulate --vm <vm> --in --proto tcp --port <n> --peer <peer>
Request body
application/json: SimulateBody
| Name | Type | Required | Description |
|---|
direction | string | yes | in (to the vNIC) or out (from it). |
|---|
icmpCode | integer (int32) or null | | ICMP code. |
|---|
icmpType | integer (int32) or null | | ICMP type. |
|---|
local | string or null | | The vNIC's own address (default: its first address of the peer's family). |
|---|
nic | string or null | | NIC key (default: the VM's first host-bridge NIC). |
|---|
peer | string | yes | The other end's address. |
|---|
port | integer (int32) or null | | Destination port (TCP, UDP). |
|---|
protocol | string | yes | tcp, udp, icmp4, icmp6 or a protocol number. |
|---|
state | string or null | | Connection state: new (default), established. |
|---|
vm | string | yes | VM id. |
|---|
Responses
GET /v1/firewall/tag-categories
Tag categories and whether they are provider-managed.
- CLI
kyvernon firewall tag-categories list
Responses
PUT /v1/firewall/tag-categories/{id}
Marks a tag category provider-managed: only the provider attaches its tags, and only such categories count in provider groups' tag criteria.
- CLI
kyvernon firewall tag-categories set <id> --provider-managed true [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the tag category |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: TagCategoryBody
| Name | Type | Required | Description |
|---|
providerManaged | boolean | yes | Provider-managed. |
|---|
Responses
GET /v1/firewall/templates
The rule templates.
- CLI
kyvernon firewall templates list
Responses
GET /v1/firewall/templates/{id}
One template.
- CLI
kyvernon firewall templates show <template>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall template |
|---|
Responses
PUT /v1/firewall/templates/{id}
Creates or replaces a provider template (built-in ids are refused with error.firewall.builtin).
- CLI
kyvernon firewall templates set <template> --body-file <file>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall template |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: TemplateBody
| Name | Type | Required | Description |
|---|
description | string | | What it opens. |
|---|
note | string or null | | What to know before applying it. |
|---|
rules | array of TemplateRuleBody | yes | The rules (1 to 50). |
|---|
Responses
DELETE /v1/firewall/templates/{id}
Deletes a provider template.
- CLI
kyvernon firewall templates delete <template>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall template |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
POST /v1/firewall/templates/{id}/apply
Applies a template to a VM: its rules go into the VM's own policy (a task).
- CLI
kyvernon firewall templates apply <template> <vm> [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the firewall template |
|---|
Request body
application/json: ApplyTemplateBody
| Name | Type | Required | Description |
|---|
vm | string | yes | VM id. |
|---|
Responses
| Status | Description | Schema |
|---|
| 202 | Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) | TaskRef |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
GET /v1/vms/{id}/firewall
The firewall of every vNIC of a VM: mode, profile, protection, effective rules with counters, realization.
- CLI
kyvernon firewall effective <vm>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the virtual machine (vm-N) |
|---|
Responses
GET /v1/vms/{id}/firewall/logs
Firewall log records of a VM, newest first.
- CLI
kyvernon firewall logs --vm <vm> [--limit <n>]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the virtual machine (vm-N) |
|---|
limit | query | integer or null | | Most records (default 500, at most 5,000). |
|---|
host | query | string or null | | Host id. |
|---|
rule | query | integer (int32) or null | | Rule number. |
|---|
Responses
POST /v1/vms/{id}/firewall/mode
Switches the firewall mode of a VM's vNICs (a task; Kyvernon.Firewall.ManageProvider). With confirmWithin the previous mode comes back unless confirmed in time.
- CLI
kyvernon firewall mode <vm> enforce [--confirm-within <duration>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the virtual machine (vm-N) |
|---|
Request body
application/json: ModeBody
| Name | Type | Required | Description |
|---|
confirmWithin | integer (int64) or null | | Seconds until the previous mode comes back unless confirmed (30 to 86,400; absent: no timer). |
|---|
mode | ModeView | yes | The new mode. |
|---|
nics | array of string | | NIC keys (default: every host-bridge NIC of the VM). |
|---|
reason | string or null | | Why (kept in the event). |
|---|
Responses
| Status | Description | Schema |
|---|
| 202 | Accepted: the body names the task to poll (GET /v1/tasks/{id}/wait) | TaskRef |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
POST /v1/vms/{id}/firewall/mode/confirm
Confirms the mode switches of a VM that wait for confirmation.
- CLI
kyvernon firewall mode confirm <vm>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the virtual machine (vm-N) |
|---|
Responses
GET /v1/vms/{id}/firewall/monitor
What the vNICs' rules would have dropped in mode monitor, and a proposal.
- CLI
kyvernon firewall monitor <vm>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the virtual machine (vm-N) |
|---|
Responses
POST /v1/vms/{id}/firewall/open-port
Opens a port of a VM: an inbound allow rule in the VM's own policy vm-N (an equal rule that exists is returned).
- CLI
kyvernon firewall open-port <vm> --tcp <ports> [--from <prefix>] [--wait]
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the virtual machine (vm-N) |
|---|
tenant | query | string or null | | Tenant id of a new object (create only). |
|---|
wait | query | string or null | | realized: answer when the hosts concerned applied the change. |
|---|
timeoutSeconds | query | integer (int64) or null | | Longest wait in seconds (default 30, at most 300). |
|---|
position | query | integer (int32) or null | | Position of a new rule (default: last). |
|---|
Request body
application/json: OpenPortBody
| Name | Type | Required | Description |
|---|
from | array of string | | Sources allowed (addresses or prefixes; empty: any). |
|---|
ipVersion | IpVersionView | | IP families (default any). |
|---|
name | string or null | | Rule name (default open <protocol> <ports>). |
|---|
ports | string | yes | Port or range (443, 8000-8100). |
|---|
protocol | string | yes | tcp or udp. |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | RuleView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
GET /v1/vms/{id}/nics/{key}/firewall
The firewall of one vNIC.
- CLI
kyvernon firewall effective <vm> --nic <key>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the virtual machine (vm-N) |
|---|
key | path | string | yes | Device key of the network adapter (for example 4000) |
|---|
Responses
PUT /v1/vms/{id}/nics/{key}/firewall
Sets the profile of a vNIC (null: the profile of its kind). A tenant user may choose a selectable profile only.
- CLI
kyvernon firewall vnic-profile <vm> <key> --profile <profile>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the virtual machine (vm-N) |
|---|
key | path | string | yes | Device key of the network adapter (for example 4000) |
|---|
Request body
application/json: NicProfileBody
| Name | Type | Required | Description |
|---|
profile | string or null | | Profile id; null: the profile of the NIC kind. |
|---|
Responses
Version 0.1.