Network settings (experiment)
What a Space can reach: its network preset, the allow and deny lists, and deleting a Space together with its children.
These calls belong to the Secure Spaces experiment (cua experiments enable secure-spaces) and are refused while it is off. Spaces.network says what a Space can reach and where that is enforced, set_network changes it (a child Space stays within its parent's unless widened), and delete_tree deletes a Space with or without its children. See A Space's network.
Network#
Methods of Spaces.
Spaces.network#
A Space's network: its settings, what they open, where they are enforced (or why its network is cut), and what is always blocked.
async def network(self, space: str) -> SpaceNetworkInfo| Parameter | Type | Default |
|---|---|---|
space | String | required |
Returns SpaceNetworkInfo · Async · Raises CuaError
Spaces.ack_network_notice#
Marks the one-time notice about the new network defaults as shown
for space (SpaceNetworkInfo.notice_pending).
async def ack_network_notice(self, space: str) -> None| Parameter | Type | Default |
|---|---|---|
space | String | required |
Async · Raises CuaError
Spaces.set_network#
Replaces a Space's network settings (see NetworkSettings). A
child stays within its parent's unless widen; tree gives its
children the same settings. They hold at once where the runtime can
change a running guest's network, else from its next start
(applied). A Space another computer runs is Unsupported.
async def set_network(self, space: str, settings: NetworkSettings, widen: bool, tree: bool) -> SetNetworkResult| Parameter | Type | Default |
|---|---|---|
space | String | required |
settings | NetworkSettings | required |
widen | bool | required |
tree | bool | required |
Returns SetNetworkResult · Async · Raises CuaError (Unsupported)
Spaces.delete_tree#
Spaces.delete, with keep_children: its child Spaces become
top-level Spaces and keep running instead of being deleted first.
async def delete_tree(self, space: str, keep_children: bool) -> str| Parameter | Type | Default |
|---|---|---|
space | String | required |
keep_children | bool | required |
Returns String · Async · Raises CuaError
NetworkSettings record#
A Space's network settings: a preset and the user's own lists. The host the Space runs on compiles them to rules it enforces outside the guest.
internet(the default): the public internet and the Space's own tree; this computer, your local network, cloud metadata, other trees and the cua daemon are blocked;none: no network;localhost:internet, plus this computer's localhost onlocalhost_ports(every port only withall_localhost_ports);lan:internet, plus your local network (not this computer);custom:custom_base(internetornone) plusallowanddeny;unprotected: everything but cloud metadata, other trees and the daemon.
A runtime that can't protect a Space yet starts it without network and
says so (SpaceInfo.network_note); it never starts it open unless the
preset is unprotected.
| Field | Type | Default | Description |
|---|---|---|---|
preset | String | "" | internet, none, localhost, lan, custom or unprotected; empty is internet. |
localhost_ports / localhostPorts | Vec<u16> | [] | localhost: the ports of this computer's localhost the Space may reach. |
all_localhost_ports / allLocalhostPorts | bool | false | localhost: every port (the daemon's stay blocked). |
allow | Vec<String> | [] | Destinations that stay reachable (addresses or CIDRs). |
deny | Vec<String> | [] | Destinations that are blocked (addresses, CIDRs or all). |
custom_base / customBase | String | "" | custom: what it starts from, internet (empty) or none. |
widened_by / widenedBy | Option<String> | None | Set when the Space was allowed more than its parent: who and when. |
SpaceNetworkInfo record#
A Space's network as cua network show says it (Spaces.network).
Returned by Spaces.network.
| Field | Type | Default | Description |
|---|---|---|---|
settings | NetworkSettings | Its settings. | |
summary | String | One plain line ("Internet only"). | |
widenings | Vec<String> | What the settings open beyond internet, one plain line each. | |
enforcement | String | enforced (rules on the host, outside the guest), no_network (its runtime can't protect it yet), open (No protection) or refused; empty when unknown (a Space another computer runs). | |
point | String | Where the rules are enforced, or why its network is cut. | |
note | Option<String> | Why its network is not what was asked; None otherwise. | |
parent | Option<String> | Its parent and its tree's top-level Space; None for a top-level Space. | |
root | Option<String> | ||
always_blocked / alwaysBlocked | Vec<String> | What no setting opens, in plain words. | |
notice_pending / noticePending | bool | An update changed its settings: say so once. |
SetNetworkResult record#
What Spaces.set_network did.
Returned by Spaces.set_network.
| Field | Type | Default | Description |
|---|---|---|---|
applied | String | now (the running guest is under them) or next_start. | |
network | SpaceNetworkInfo | The Space's network after the change. |