SA Management Commands

VICI commands for initiating, terminating, and rekeying IKE and CHILD Security Associations.

These commands control the lifecycle of IKE and CHILD Security Associations (SAs) in the running daemon.

initiate

Initiate a CHILD_SA while streaming control-log events. The command blocks (or times out) until the initiation completes or fails.

Input

child · string

Name of the CHILD_SA configuration to initiate.

ike · string

Name of the IKE_SA configuration to initiate, or to search under when looking up child.

timeout · string

Timeout in milliseconds before returning. 0 (default) waits indefinitely. -1 returns immediately without waiting for a result.

init-limits · string

Set to yes to allow configured limits (e.g. half-open SA limits) to prevent initiation.

loglevel · string

Log level (0–4) at which to emit control-log events during initiation.

Response

success · string

yes if the CHILD_SA was established, no on failure or timeout.

errmsg · string

Human-readable error description on failure or timeout.

Python example

for log in v.initiate({"child": "net-net", "loglevel": "2"}):
    print(log[b"msg"].decode())

---

terminate

Terminate one or more SAs while streaming control-log events. You can select SAs by configuration name or unique identifier.

Input

child · string

Terminate all CHILD_SAs with this configuration name.

ike · string

Terminate the IKE_SA with this configuration name (and its CHILD_SAs).

child-id · string

Terminate the CHILD_SA with this unique numeric identifier.

ike-id · string

Terminate the IKE_SA with this unique numeric identifier.

force · string

Set to yes to terminate the IKE_SA without waiting for a proper DELETE exchange. If timeout is also given, waits for a response until the timeout is reached.

timeout · string

Timeout in milliseconds before returning. 0 (default) waits indefinitely. -1 returns immediately.

loglevel · string

Log level (0–4) at which to emit control-log events during termination.

Response

success · string

yes on success, no on failure.

matches · string

Number of SAs that matched the selection criteria.

terminated · string

Number of SAs that were actually terminated.

errmsg · string

Human-readable error description on failure or timeout.

---

rekey

Initiate rekeying of an existing SA. For IKEv2 IKE_SAs, reauthentication can be triggered instead of rekeying.

Input

child · string

Rekey the CHILD_SA with this configuration name.

ike · string

Rekey the IKE_SA with this configuration name.

child-id · string

Rekey the CHILD_SA with this unique identifier.

ike-id · string

Rekey the IKE_SA with this unique identifier.

reauth · string

Set to yes to trigger reauthentication instead of rekeying for an IKEv2 IKE_SA.

Response

success · string

yes on success, no on failure.

matches · string

Number of SAs that matched the selection criteria.

errmsg · string

Human-readable error description on failure.

---

redirect

Redirect a client-initiated IKE_SA to another gateway. Only applies to IKEv2 and requires peer support.

Input

ike · string

Redirect the IKE_SA with this configuration name.

ike-id · string

Redirect the IKE_SA with this unique identifier.

peer-ip · string

Redirect IKE_SAs with a matching peer IP address. Accepts a single IP, a CIDR subnet, or an IP range.

peer-id · string

Redirect IKE_SAs with a matching peer IKE identity. Wildcards are supported.

Response

success · string

yes on success, no on failure.

matches · string

Number of IKE_SAs that matched the selection criteria.

errmsg · string

Human-readable error description on failure.

---

install

Install a trap, drop, or bypass policy defined by a CHILD_SA configuration without initiating an IKE exchange.

Input

child · string · required

Name of the CHILD_SA configuration whose policy to install.

ike · string

Optional IKE_SA configuration name to narrow the search for child.

Response

success · string

yes on success, no on failure.

errmsg · string

Human-readable error description on failure.

---

uninstall

Uninstall a trap, drop, or bypass policy previously installed for a CHILD_SA configuration.

Input

child · string · required

Name of the CHILD_SA configuration whose policy to uninstall.

ike · string

Optional IKE_SA configuration name. If omitted, the first matching policy for child is removed.

Response

success · string

yes on success, no on failure.

errmsg · string

Human-readable error description on failure.

---

list-sas

Stream all active IKE_SAs and their CHILD_SAs as list-sa events.

This is a streaming command. Register for the list-sa event before issuing this command.

Input

noblock · string

Set to any value to use non-blocking mode (skip locked SAs instead of waiting).

ike · string

Filter results to IKE_SAs with this configuration name.

ike-id · string

Filter results to the IKE_SA with this unique identifier.

child · string

Filter results to IKE_SAs containing a CHILD_SA with this name.

child-id · string

Filter results to IKE_SAs containing a CHILD_SA with this unique identifier.

Response

An empty message ({}). All SA data arrives via list-sa events.

Python example

for sa in v.list_sas():
    for name, details in sa.items():
        print(name, details[b"state"])

---

list-policies

Stream all installed trap, drop, and bypass policies as list-policy events.

This is a streaming command. Register for the list-policy event before issuing this command.

Input

drop · string

Set to yes to include drop policies.

pass · string

Set to yes to include bypass (pass) policies.

trap · string

Set to yes to include trap policies.

child · string

Filter by CHILD_SA configuration name.

ike · string

Filter by IKE_SA configuration name.

Response

An empty message ({}). All policy data arrives via list-policy events.