microsandbox_protocol/
lib.rs

1//! `microsandbox-protocol` defines the shared protocol types used for communication
2//! between the host and the guest agent over CBOR-over-virtio-serial.
3
4#![warn(missing_docs)]
5
6mod error;
7
8//--------------------------------------------------------------------------------------------------
9// Constants: Host↔Guest Protocol
10//--------------------------------------------------------------------------------------------------
11
12/// Virtio-console port name for the agent channel.
13pub const AGENT_PORT_NAME: &str = "agent";
14
15/// Virtiofs tag for the runtime filesystem (scripts, heartbeat).
16pub const RUNTIME_FS_TAG: &str = "msb_runtime";
17
18/// Guest mount point for the runtime filesystem.
19pub const RUNTIME_MOUNT_POINT: &str = "/.msb";
20
21/// Guest path for named scripts (added to PATH by agentd).
22pub const SCRIPTS_PATH: &str = "/.msb/scripts";
23
24//--------------------------------------------------------------------------------------------------
25// Constants: Guest Init Environment Variables
26//--------------------------------------------------------------------------------------------------
27
28/// Environment variable carrying tmpfs mount specs for guest init.
29///
30/// Format: `path[,key=value,...][;path[,key=value,...];...]`
31///
32/// - `path` — guest mount path (required, always the first element)
33/// - `size=N` — size limit in MiB (optional)
34/// - `noexec` — mount with noexec flag (optional)
35/// - `mode=N` — permission mode as octal integer (optional, e.g. `mode=1777`)
36///
37/// Entries are separated by `;`. Within an entry, the path comes first
38/// followed by comma-separated options.
39///
40/// Examples:
41/// - `MSB_TMPFS=/tmp,size=256` — 256 MiB tmpfs at `/tmp`
42/// - `MSB_TMPFS=/tmp,size=256;/var/tmp,size=128` — two tmpfs mounts
43/// - `MSB_TMPFS=/tmp` — tmpfs at `/tmp` with defaults
44/// - `MSB_TMPFS=/tmp,size=256,noexec` — with noexec flag
45pub const ENV_TMPFS: &str = "MSB_TMPFS";
46
47/// Environment variable specifying the block device for rootfs switch.
48///
49/// Format: `device[,key=value,...]`
50/// - `device` — block device path (required, always first element)
51/// - `fstype=TYPE` — filesystem type (optional; auto-detected if absent)
52pub const ENV_BLOCK_ROOT: &str = "MSB_BLOCK_ROOT";
53
54/// Environment variable carrying the guest network interface configuration.
55///
56/// Format: `key=value,...`
57///
58/// - `iface=NAME` — interface name (required)
59/// - `mac=AA:BB:CC:DD:EE:FF` — MAC address (required)
60/// - `mtu=N` — MTU (optional)
61///
62/// Example:
63/// - `MSB_NET=iface=eth0,mac=02:5a:7b:13:01:02,mtu=1500`
64pub const ENV_NET: &str = "MSB_NET";
65
66/// Environment variable carrying the guest IPv4 network configuration.
67///
68/// Format: `key=value,...`
69///
70/// - `addr=A.B.C.D/N` — address with prefix length (required)
71/// - `gw=A.B.C.D` — default gateway (required)
72/// - `dns=A.B.C.D` — DNS server (optional)
73///
74/// Example:
75/// - `MSB_NET_IPV4=addr=100.96.1.2/30,gw=100.96.1.1,dns=100.96.1.1`
76pub const ENV_NET_IPV4: &str = "MSB_NET_IPV4";
77
78/// Environment variable carrying the guest IPv6 network configuration.
79///
80/// Format: `key=value,...`
81///
82/// - `addr=ADDR/N` — address with prefix length (required)
83/// - `gw=ADDR` — default gateway (required)
84/// - `dns=ADDR` — DNS server (optional)
85///
86/// Example:
87/// - `MSB_NET_IPV6=addr=fd42:6d73:62:2a::2/64,gw=fd42:6d73:62:2a::1,dns=fd42:6d73:62:2a::1`
88pub const ENV_NET_IPV6: &str = "MSB_NET_IPV6";
89
90/// Environment variable carrying virtiofs volume mount specs for guest init.
91///
92/// Format: `tag:guest_path[:ro][;tag:guest_path[:ro];...]`
93///
94/// - `tag` — virtiofs tag name (required, matches the tag used in `--mount`)
95/// - `guest_path` — mount point inside the guest (required)
96/// - `ro` — mount read-only (optional suffix)
97///
98/// Entries are separated by `;`.
99///
100/// Examples:
101/// - `MSB_MOUNTS=data:/data` — mount virtiofs tag `data` at `/data`
102/// - `MSB_MOUNTS=data:/data:ro` — mount read-only
103/// - `MSB_MOUNTS=data:/data;cache:/cache:ro` — two mounts
104pub const ENV_MOUNTS: &str = "MSB_MOUNTS";
105
106/// Environment variable carrying the default guest user for agentd execs.
107///
108/// Format: `USER[:GROUP]` or `UID[:GID]`
109///
110/// - `USER`
111/// - `UID`
112/// - `USER:GROUP`
113/// - `UID:GID`
114///
115/// Example:
116/// - `MSB_USER=alice` — default to user `alice`
117/// - `MSB_USER=1000` — default to UID 1000
118/// - `MSB_USER=alice:developers` — default to user `alice` and group `developers`
119/// - `MSB_USER=1000:100` — default to UID 1000 and GID 100
120pub const ENV_USER: &str = "MSB_USER";
121
122/// Environment variable carrying the guest hostname for agentd.
123///
124/// Format: bare string
125///
126/// Example:
127/// - `MSB_HOSTNAME=worker-01`
128///
129/// agentd calls `sethostname()` and adds the name to `/etc/hosts`.
130/// Defaults to the sandbox name when not explicitly set.
131pub const ENV_HOSTNAME: &str = "MSB_HOSTNAME";
132
133/// Guest-side path to the CA certificate for TLS interception.
134///
135/// Placed by the sandbox process via the runtime virtiofs mount.
136/// agentd checks for this file during init and installs it into the guest
137/// trust store.
138pub const GUEST_TLS_CA_PATH: &str = "/.msb/tls/ca.pem";
139
140//--------------------------------------------------------------------------------------------------
141// Exports
142//--------------------------------------------------------------------------------------------------
143
144pub mod codec;
145pub mod core;
146pub mod exec;
147pub mod fs;
148pub mod heartbeat;
149pub mod message;
150
151pub use error::*;
microsandbox_protocol/lib.rs

microsandbox_protocol/
lib.rs
