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//--------------------------------------------------------------------------------------------------
22// Constants: Guest Init Environment Variables
23//--------------------------------------------------------------------------------------------------
24
25/// Environment variable carrying tmpfs mount specs for guest init.
26///
27/// Format: `path[,key=value,...][;path[,key=value,...];...]`
28///
29/// - `path` — guest mount path (required, always the first element)
30/// - `size=N` — size limit in MiB (optional)
31/// - `noexec` — mount with noexec flag (optional)
32/// - `mode=N` — permission mode as octal integer (optional, e.g. `mode=1777`)
33///
34/// Entries are separated by `;`. Within an entry, the path comes first
35/// followed by comma-separated options.
36///
37/// Examples:
38/// - `MSB_TMPFS=/tmp,size=256` — 256 MiB tmpfs at `/tmp`
39/// - `MSB_TMPFS=/tmp,size=256;/var/tmp,size=128` — two tmpfs mounts
40/// - `MSB_TMPFS=/tmp` — tmpfs at `/tmp` with defaults
41/// - `MSB_TMPFS=/tmp,size=256,noexec` — with noexec flag
42pub const ENV_TMPFS: &str = "MSB_TMPFS";
43
44/// Environment variable specifying the block device for rootfs switch.
45///
46/// Format: `device[,key=value,...]`
47/// - `device` — block device path (required, always first element)
48/// - `fstype=TYPE` — filesystem type (optional; auto-detected if absent)
49pub const ENV_BLOCK_ROOT: &str = "MSB_BLOCK_ROOT";
50
51/// Environment variable carrying the guest network interface configuration.
52///
53/// Format: `key=value,...`
54///
55/// - `iface=NAME` — interface name (required)
56/// - `mac=AA:BB:CC:DD:EE:FF` — MAC address (required)
57/// - `mtu=N` — MTU (optional)
58///
59/// Example:
60/// - `MSB_NET=iface=eth0,mac=02:5a:7b:13:01:02,mtu=1500`
61pub const ENV_NET: &str = "MSB_NET";
62
63/// Environment variable carrying the guest IPv4 network configuration.
64///
65/// Format: `key=value,...`
66///
67/// - `addr=A.B.C.D/N` — address with prefix length (required)
68/// - `gw=A.B.C.D` — default gateway (required)
69/// - `dns=A.B.C.D` — DNS server (optional)
70///
71/// Example:
72/// - `MSB_NET_IPV4=addr=100.96.1.2/30,gw=100.96.1.1,dns=100.96.1.1`
73pub const ENV_NET_IPV4: &str = "MSB_NET_IPV4";
74
75/// Environment variable carrying the guest IPv6 network configuration.
76///
77/// Format: `key=value,...`
78///
79/// - `addr=ADDR/N` — address with prefix length (required)
80/// - `gw=ADDR` — default gateway (required)
81/// - `dns=ADDR` — DNS server (optional)
82///
83/// Example:
84/// - `MSB_NET_IPV6=addr=fd42:6d73:62:2a::2/64,gw=fd42:6d73:62:2a::1,dns=fd42:6d73:62:2a::1`
85pub const ENV_NET_IPV6: &str = "MSB_NET_IPV6";
86
87/// Guest-side path to the CA certificate for TLS interception.
88///
89/// Placed by the supervisor via the runtime virtiofs mount.
90/// agentd checks for this file during init and installs it into the guest
91/// trust store.
92pub const GUEST_TLS_CA_PATH: &str = "/.msb/tls/ca.pem";
93
94//--------------------------------------------------------------------------------------------------
95// Exports
96//--------------------------------------------------------------------------------------------------
97
98pub mod codec;
99pub mod core;
100pub mod exec;
101pub mod fs;
102pub mod heartbeat;
103pub mod message;
104
105pub use error::*;