Guidance wanted: ESP32/embedded “Lite” client profile and safe handling of unsupported NetworkConfig features

[Boilerplate4u]

Hi ZeroTier team,

We are working on an experimental ESP32/FreeRTOS/lwIP port of ZeroTierOne and would appreciate guidance on how to design a safe constrained “Lite” client profile.

The goal is not full feature parity with the Linux client, since there is not enough flash space or RAM for that. Instead, we want to understand which parts of NetworkConfig are strictly required for safe basic operation, which parts can be omitted in a constrained embedded profile, and how a client should fail safely when a network requires features it cannot support.

The main question is:

How should an embedded ZeroTier client safely handle NetworkConfig features that it cannot store or enforce, especially security-relevant features such as rules, capabilities, tags, certificates of ownership, SSO, bridging, or specialist roles?

We do not want to silently ignore any field that affects access control or network security. If a controller sends a config containing policy features that the ESP32 client cannot enforce, we want the client to reject or defer that config in a way that is consistent with ZeroTier’s architecture.

Our initial target profile is an “ESP32 Lite” client:

• externally provisioned identity
• one ZeroTier network
• managed IPv4 address
• basic managed routes
• basic ARP/IPv4 dataplane
• small peer/path limits
• no bridging
• no SSO
• no DNS push
• no advanced rules/capabilities/tags support in the first version

The reason we are looking at this is memory predictability. On ESP32, repeated large NetworkConfig allocations and full feature arrays are risky because of limited heap, flash size, and fragmentation. We are therefore considering a compact runtime representation of NetworkConfig that keeps only the fields needed for the Lite profile.

Our current working assumption is that the Lite profile should keep/support:

• network ID
• timestamp/revision/stale-config protection
• issuedTo
• network type/status
• MTU
• flags relevant to broadcast/NDP/basic dataplane
• managed/static IPs, with small fixed limits
• routes, with small fixed limits
• CertificateOfMembership / private-network authorization material needed for safe operation

And initially not support:

• flow rules
• capabilities
• tags
• certificates of ownership
• SSO/OIDC
• DNS push
• remote trace
• bridging / active bridge behavior
• multicast replicator / advanced specialist behavior, unless required for basic connectivity

The security-sensitive part is rules/capabilities/tags. Since ZeroTier rules are enforced by the endpoints, we assume it would be unsafe for an embedded client to simply ignore non-trivial policy fields that the controller expects the node to enforce.

Questions:

1. Is there a recommended way for a constrained client to declare or signal that it does not support specific NetworkConfig features such as rules, capabilities, tags, SSO, certificates of ownership, bridging, or specialist roles?

2. If a client receives a NetworkConfig containing non-trivial rules/capabilities/tags that it cannot enforce, what is the safest expected behavior?

   Should it reject the config locally, keep the previous known-good config, stay in REQUESTING_CONFIGURATION, return an error from the virtual network config callback and enter PORT_ERROR, or use some other status/path?

3. Is there an upstream-supported status or error path for “unsupported NetworkConfig feature,” or should an embedded port implement a local diagnostic such as LITE_UNSUPPORTED_CONFIG and avoid applying the config?

4. Which NetworkConfig fields are mandatory for safe basic membership in a private network with a managed IP?

   In particular, is it safe to keep CertificateOfMembership but omit runtime storage for rules/capabilities/tags if the network is configured with no such policy features?

5. Are rules/capabilities/tags ever required even for a simple private network with default-accept behavior, or can an embedded Lite client require that these counts be zero/trivial?

6. Are specialists/network relays/multicast replicators required for ordinary peer-to-peer operation in common Central-managed networks, or can an embedded Lite client initially treat them as unsupported?

7. Would the ZeroTier project be open to a documented embedded/Lite profile, for example a compile-time configuration that explicitly limits unsupported NetworkConfig features and fails safely when a network requires them?

Our intended safe behavior is:

• never silently ignore security policy fields
• accept only empty/trivial rules/capabilities/tags initially
• reject or defer configs requiring unsupported policy features
• keep previous known-good config on refresh failure
• log a clear local reason such as unsupported: nontrivial rules
• avoid repeated large heap allocations by using a persistent or compact NetworkConfig representation

Any guidance on which fields are truly required by ZeroTier core after config apply, and what error/status path you would prefer for unsupported features, would be very helpful.

Thanks!

[Boilerplate4u]

May 22, 2026 -- Quick project update / proof-of-life from the ESP32 porting project:

We now have a working experimental ESP32-class ZeroTier client prototype: ESP32 ZeroTier Lite.

Github repository: https://github.com/boilerplate4u/zerotier-esp32

ZeroTier "Lite" for ESP32 has a working control and data plane implementation running on our ESP-IDF / lwIP / QEMU test environment:

Control Plane

• All control verbs working (e.g., WHOIS)
• Successful network JOIN and transition to ONLINE state
• ZeroTier managed IPs and routes
• ZeroTier ARP functionality
• Managed IPv4 assignment and routing

Data Plane

• ICMP ping capabilities
• UDP and TCP payload traffic routing
• Direct-path dataplane verification in a routed no-NAT test topology

This is still experimental and not production-ready, but it is now a functioning ESP32-oriented ZeroTier client prototype rather than only an architecture sketch.

The current work is focused on making it smaller, safer, and more predictable for constrained devices.

The main theme now is memory optimization and defining a practical “Lite” profile for ESP32-class targets: one network, managed IPv4, basic routes, bounded peer/path tables, no bridging, no SSO, and no silent ignoring of security-relevant NetworkConfig features.

Worth reading in the repo:

• ESP32_ZEROTIER_LITE_ARCHITECTURE.md
  https://github.com/boilerplate4u/zerotier-esp32/blob/main/ESP32_ZEROTIER_LITE_ARCHITECTURE.md

• POTENTIAL_MEMORY_OPTIMIZATIONS.md
  https://github.com/boilerplate4u/zerotier-esp32/blob/main/POTENTIAL_MEMORY_OPTIMIZATIONS.md

• ESP32_MEMORY_ANALYSIS_AND_DEBUGGING.md
  https://github.com/boilerplate4u/zerotier-esp32/blob/main/ESP32_MEMORY_ANALYSIS_AND_DEBUGGING.md

The current memory-optimization approach is deliberately conservative: first remove diagnostic/test overhead and rebalance stack usage, then test higher-risk reductions one by one. We are trying hard not to trade correctness or security for RAM savings.

The big open design question remains the same as in this issue:

What is the safest upstream-compatible behavior for a constrained embedded client when a NetworkConfig contains features that the device cannot store or enforce?

Our current intended behavior is:

• never silently ignore security policy fields
• accept only trivial/empty rules, capabilities, and tags in the first Lite profile
• reject or defer configs requiring unsupported policy features
• keep previous known-good config on refresh failure
• expose clear local diagnostics such as LITE_UNSUPPORTED_CONFIG
• keep runtime state compact and bounded

Any guidance from the ZeroTier team on the preferred failure/status path for unsupported NetworkConfig features would be very valuable.

If there is interest from the ZeroTier maintainers, this project could be a useful concrete testbed for discussing and documenting an embedded / Lite ZeroTier profile.

Thanks!