OpenZiti Documentation

Transwarp is a high-performance data plane protocol for the Ziti fabric, designed for long-haul deployments where a network link can be mostly dedicated to the Ziti data plane. It integrates the westworld3 protocol from the Dilithium project to achieve throughput that can be multiple times greater than standard TCP.

Key Considerations:

• Deployment: Unlike TCP, Transwarp requires intelligent profile selection. It does not have a one-size-fits-all configuration.
• Loopback Warning: Transwarp (specifically westworld3 profiles) performs significantly worse than TCP on loopback interfaces.
• Protocol: westworld3 is a UDP-based protocol; ensure firewall rules allow UDP traffic.

OpenZiti is an open-source zero-trust networking platform that makes network services invisible to unauthorized users. It provides cryptographic identity, policy-based authorization, and end-to-end encryption for every connection.

OpenZiti supports both:

• Existing applications: Using lightweight tunnelers with no code changes required.
• New applications: Using embedded SDKs for a strong zero-trust model.

The CtrlDialer uses a state machine to manage connections between the controller and routers. Understanding these states helps in troubleshooting connection stability and retry behavior.

States

• (none): No entry in the states map. The router is either unknown, already connected, or has no matching endpoints.
• NeedsDial: The router requires a connection. It is currently in the retry queue with a scheduled nextDial time.
• Dialing: A dial attempt has been submitted to the worker pool and is currently in progress.
• Connected: The dial succeeded. The state is tracked until the FastFailureWindow expires to confirm the connection is stable.

As of version 0.20, the Edge REST API is split into two distinct APIs with separate URL paths and responsibilities:

1. Edge Client API: Contains functionality required by endpoints connected to and using services. It is primarily used by Ziti SDKs. Path: /edge/client/v1.
2. Edge Management API: Contains all administrative configuration capabilities. It is intended for use by the Ziti Admin Console (ZAC) or other administrative integrations. Path: /edge/management/v1.

Legacy Support:

• The Client API supports legacy paths (No Prefix /* and Edge Prefix /edge/v1/*) temporarily. This support will be removed once all Ziti SDKs migrate to the new prefixed paths.
• The Management API does not support legacy URL paths.

OpenZiti provides experimental support for advanced SDK capabilities:

1. Multi-underlay Support: For supported SDKs, the edge router can maintain a separate control channel connection alongside the data connection. If the SDK does not explicitly request separate channels, the router defaults to a single connection.
2. SDK Flow-control: For supported SDKs, the edge router can delegate flow control to the SDK.

Warning: These features are experimental and may be subject to bugs, changes, or removal.

OpenZiti is moving towards a unified Router type that replaces the previous hierarchy of Edge Router and Transit Router. In the unified model, a router's capabilities are determined by its associated configuration rather than its database type.

• Edge capabilities: Determined by the presence of a router.xgress.edge configuration.
• Tunneling capabilities: Determined by the presence of a router.xgress.tunnel configuration.

This consolidation collapses the API surface to a single /routers endpoint and a single enrollment method, replacing the previous erott (Edge) and trott (Transit) methods.

The controller/storage/ast package provides an Abstract Syntax Tree (AST) for filter expressions and an Antlr listener/visitor to transform ZitiQL into this AST.

AST Construction Pattern:

1. Leaf nodes are processed into filter AST nodes and pushed onto a stack.
2. Non-leaf nodes pop the required nodes from the stack, create their corresponding filter node, and push the result back onto the stack.
3. A second pass performs Typing, converting UntypedSymbolNode into typed symbol nodes and generic nodes (like BinaryExprNode) into specific typed nodes (like Int64BinaryExprNode).

Placeholder Node Types (used before typing pass):

• BinaryExprNode
• InArrayExprNode
• BetweenExprNode
• UntypedSymbolNode
• SetFunctionNode

The Ziti router architecture relies on several core components to manage the control plane and data movement:

• NetworkControllers: Manages connections to Ziti controllers, including discovery, connection establishment, failover, and heartbeats. It routes control plane messages.
• Link Registry: Maintains the registry of active links to other routers in the mesh, tracking link states and managing lifecycles for routing decisions.
• Forwarder: The packet forwarding engine that routes data between xgress instances, delivering payloads to links, xgress instances, or edge forwarders.
• Faulter: Monitors link health, detects failures, reports faults to controllers, and triggers recovery processes.
• Scanner: Performs maintenance by scanning the forwarder's state to clean up stale forwarding entries and remove inactive circuits.

Ziti is composed of two main domains that run in the same process space:

• Ziti Fabric: The core set of features used to define and manage services, routers, and sessions to route traffic across a secure overlay network. These features are always enabled.
• Ziti Edge: An optional set of features built on top of the Fabric. It enables the enrollment and management of endpoints using the Ziti SDK. Enabling Edge features allows for configurable policy management and endpoint enrollment.

Both Fabric and Edge features are built into the ziti binary.

OpenZiti's overlay network consists of three core components:

• Controller: The management plane. Handles identity management (x509 certificates), policy enforcement, and network state via a REST API and web-based admin console.
• Edge Routers: The data plane. A mesh fabric of public routers (internet-facing) and private/dark routers (inside private networks with outbound-only connections) that use smart routing to select paths.
• Endpoints:
  • SDKs (Go, C, Python, Node.js, Java, Swift, C#): For in-process zero-trust.
  • Tunnelers (Linux, Windows, macOS, iOS, Android): For connecting unmodified software via transparent interception.

The Ziti router data plane uses Xgress components to handle ingress and egress traffic.

Xgress Components

• Xgress Listeners: Accept incoming connections from clients and services.
• Xgress Dialers: Establish outbound connections to services.
• Xgress Factories: Create protocol-specific xgress instances (edge, transport, proxy, tunnel).
• Xgress Registry: A global registry that manages all xgress factory types.

Xgress Types

• edge: Handles Ziti SDK connections.
• transport: Used for router-to-router communication.
• proxy: Handles TCP/UDP proxy connections.
• tunnel: Handles intercepted traffic from tunneling clients.