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 directory for file mount virtiofs shares.
22pub const FILE_MOUNTS_DIR: &str = "/.msb/file-mounts";
23
24/// Guest path for named scripts (added to PATH by agentd).
25pub const SCRIPTS_PATH: &str = "/.msb/scripts";
26
27//--------------------------------------------------------------------------------------------------
28// Constants: Guest Init Environment Variables
29//--------------------------------------------------------------------------------------------------
30
31/// Environment variable carrying tmpfs mount specs for guest init.
32///
33/// Format: `path[,key=value,...][;path[,key=value,...];...]`
34///
35/// - `path` — guest mount path (required, always the first element)
36/// - `size=N` — size limit in MiB (optional)
37/// - `noexec` — mount with noexec flag (optional)
38/// - `mode=N` — permission mode as octal integer (optional, e.g. `mode=1777`)
39///
40/// Entries are separated by `;`. Within an entry, the path comes first
41/// followed by comma-separated options.
42///
43/// Examples:
44/// - `MSB_TMPFS=/tmp,size=256` — 256 MiB tmpfs at `/tmp`
45/// - `MSB_TMPFS=/tmp,size=256;/var/tmp,size=128` — two tmpfs mounts
46/// - `MSB_TMPFS=/tmp` — tmpfs at `/tmp` with defaults
47/// - `MSB_TMPFS=/tmp,size=256,noexec` — with noexec flag
48pub const ENV_TMPFS: &str = "MSB_TMPFS";
49
50/// Environment variable specifying the block device for rootfs switch.
51///
52/// Format: `device[,key=value,...]`
53/// - `device` — block device path (required, always first element)
54/// - `fstype=TYPE` — filesystem type (optional; auto-detected if absent)
55pub const ENV_BLOCK_ROOT: &str = "MSB_BLOCK_ROOT";
56
57/// Environment variable carrying the guest network interface configuration.
58///
59/// Format: `key=value,...`
60///
61/// - `iface=NAME` — interface name (required)
62/// - `mac=AA:BB:CC:DD:EE:FF` — MAC address (required)
63/// - `mtu=N` — MTU (optional)
64///
65/// Example:
66/// - `MSB_NET=iface=eth0,mac=02:5a:7b:13:01:02,mtu=1500`
67pub const ENV_NET: &str = "MSB_NET";
68
69/// Environment variable carrying the guest IPv4 network configuration.
70///
71/// Format: `key=value,...`
72///
73/// - `addr=A.B.C.D/N` — address with prefix length (required)
74/// - `gw=A.B.C.D` — default gateway (required)
75/// - `dns=A.B.C.D` — DNS server (optional)
76///
77/// Example:
78/// - `MSB_NET_IPV4=addr=100.96.1.2/30,gw=100.96.1.1,dns=100.96.1.1`
79pub const ENV_NET_IPV4: &str = "MSB_NET_IPV4";
80
81/// Environment variable carrying the guest IPv6 network configuration.
82///
83/// Format: `key=value,...`
84///
85/// - `addr=ADDR/N` — address with prefix length (required)
86/// - `gw=ADDR` — default gateway (required)
87/// - `dns=ADDR` — DNS server (optional)
88///
89/// Example:
90/// - `MSB_NET_IPV6=addr=fd42:6d73:62:2a::2/64,gw=fd42:6d73:62:2a::1,dns=fd42:6d73:62:2a::1`
91pub const ENV_NET_IPV6: &str = "MSB_NET_IPV6";
92
93/// Environment variable carrying virtiofs directory volume mount specs for guest init.
94///
95/// Format: `tag:guest_path[:ro][;tag:guest_path[:ro];...]`
96///
97/// - `tag` — virtiofs tag name (required, matches the tag used in `--mount`)
98/// - `guest_path` — mount point inside the guest (required)
99/// - `ro` — mount read-only (optional suffix)
100///
101/// Entries are separated by `;`.
102///
103/// Examples:
104/// - `MSB_DIR_MOUNTS=data:/data` — mount virtiofs tag `data` at `/data`
105/// - `MSB_DIR_MOUNTS=data:/data:ro` — mount read-only
106/// - `MSB_DIR_MOUNTS=data:/data;cache:/cache:ro` — two mounts
107pub const ENV_DIR_MOUNTS: &str = "MSB_DIR_MOUNTS";
108
109/// Environment variable carrying virtiofs **file** volume mount specs for guest init.
110///
111/// Used when the host path is a single file rather than a directory. The SDK
112/// wraps each file in an isolated staging directory (hard-linked to preserve
113/// the same inode) and shares that directory via virtiofs. Agentd mounts the
114/// share at [`FILE_MOUNTS_DIR`]`/<tag>/` and bind-mounts the file to the
115/// guest path.
116///
117/// Format: `tag:filename:guest_path[:ro][;tag:filename:guest_path[:ro];...]`
118///
119/// - `tag` — virtiofs tag name (required, matches the tag used in `--mount`)
120/// - `filename` — name of the file inside the virtiofs share (required)
121/// - `guest_path` — final file path inside the guest (required)
122/// - `ro` — mount read-only (optional suffix)
123///
124/// Entries are separated by `;`.
125///
126/// Examples:
127/// - `MSB_FILE_MOUNTS=fm_config:app.conf:/etc/app.conf`
128/// - `MSB_FILE_MOUNTS=fm_config:app.conf:/etc/app.conf:ro`
129/// - `MSB_FILE_MOUNTS=fm_a:a.sh:/usr/bin/a.sh;fm_b:b.sh:/usr/bin/b.sh`
130pub const ENV_FILE_MOUNTS: &str = "MSB_FILE_MOUNTS";
131
132/// Environment variable carrying the default guest user for agentd execs.
133///
134/// Format: `USER[:GROUP]` or `UID[:GID]`
135///
136/// - `USER`
137/// - `UID`
138/// - `USER:GROUP`
139/// - `UID:GID`
140///
141/// Example:
142/// - `MSB_USER=alice` — default to user `alice`
143/// - `MSB_USER=1000` — default to UID 1000
144/// - `MSB_USER=alice:developers` — default to user `alice` and group `developers`
145/// - `MSB_USER=1000:100` — default to UID 1000 and GID 100
146pub const ENV_USER: &str = "MSB_USER";
147
148/// Environment variable carrying the guest hostname for agentd.
149///
150/// Format: bare string
151///
152/// Example:
153/// - `MSB_HOSTNAME=worker-01`
154///
155/// agentd calls `sethostname()` and adds the name to `/etc/hosts`.
156/// Defaults to the sandbox name when not explicitly set.
157pub const ENV_HOSTNAME: &str = "MSB_HOSTNAME";
158
159/// Guest-side path to the CA certificate for TLS interception.
160///
161/// Placed by the sandbox process via the runtime virtiofs mount.
162/// agentd checks for this file during init and installs it into the guest
163/// trust store.
164pub const GUEST_TLS_CA_PATH: &str = "/.msb/tls/ca.pem";
165
166//--------------------------------------------------------------------------------------------------
167// Exports
168//--------------------------------------------------------------------------------------------------
169
170pub mod codec;
171pub mod core;
172pub mod exec;
173pub mod fs;
174pub mod heartbeat;
175pub mod message;
176
177pub use error::*;