English | 简体中文

🌐 What is OpenLAN?

OpenLAN is a multiple-tenant networking solution that carries LAN packets over WAN links, allowing you to build and operate multiple isolated virtual Ethernet networks across regions, clouds, and branch sites.

🤔 Why Choose OpenLAN?

If you need a flexible VPN solution for secure enterprise access, traffic proxying, or tunneling through public cloud instances, OpenLAN simplifies deployment and improves operational efficiency.

✨ Key Features

• 🔒 Multi-Network and Namespace Isolation: Support multiple network spaces, VRF/Namespace binding, cross-network isolation, scope-based SNAT, and in-network DHCP address allocation.
• 🔗 Central Switch Interconnect and Routing: Support TCP/UDP outputs, three-node forwarding, static routes, FindHop active-backup/load balancing, and External BGP prefix filters.
• 🖥️ OpenVPN Access: Support OpenVPN onboarding, static client addresses, client-to-client reachability, route redirect, TCP reset handling, and remote VIP access through SNAT.
• 🛡️ Tunnels and Overlays: Support TCP/UDP transports, router GRE/IPIP L3 tunnels, WireGuard hub/P2P peers, VxLAN/GRE outputs, and IPSec tunnels, with reload persistence plus connectivity and performance sampling.
• 🔑 Authentication and Layered Crypt: Support username/password auth, same-user mutex, concurrent admin logins, global and per-network pre-shared crypt, plus AES/SM4 OpenVPN cipher negotiation.
• 🧭 Policy Control Plane: Built-in ACL default actions, persisted fine-grained rules, zero-trust Guest/Knock controls, DNAT service publishing, and client QoS rules.
• ⚙️ Operational Traffic Governance: Dynamic rate-limit updates, observable Linux tc/iptables state, reload persistence, and ping/RTT/iperf3 performance sampling.
• 🔄 Ceci Proxy and Service Forwarding: HTTP/TCP/DNS Proxy, domain-matched multi-backend routing, and TCP/HTTP Service forwarding with route/global backends and restart recovery.

🗺️ Use Cases

🏢 Branch-to-Center Access

         Central Switch (Enterprise Center) - 10.16.1.10/24
                               ^
                               |
                            Wifi(DNAT)
                               |
                               |
         --------------------Internet-------------------
         ^                     ^                       ^
         |                     |                       |
      Branch1                Branch2                 Branch3
         |                     |                       |
      OpenLAN               OpenLAN                 OpenLAN
   10.16.1.11/24          10.16.1.12/24           10.16.1.13/24

OpenLAN can use a central switch as the enterprise access hub. Branch devices or edge gateways authenticate to the center over public networks and join the same virtual LAN with assigned addresses. This keeps branch-to-center and branch-to-branch traffic on a managed overlay, while the central switch can apply user authentication, shared crypt settings, ACLs, SNAT, DNAT, DHCP, and rate-limit policies from one control point.

🌍 Multi-Region Interconnection

192.168.1.20/24                                      192.168.1.21/24
     |                                                    |
OpenLAN -- Hotel Wifi --> Central Switch(NanJing) <--- Other Wifi --- OpenLAN
                                |
                                |
                              Internet
                                |
                                |
                  Central Switch(Shanghai) - 192.168.1.10/24
                                |
                                |
      --------------------------------------------------------
      ^                         ^                            ^
      |                         |                            |
   Office Wifi               Home Wifi                    Hotel Wifi
      |                         |                            |
   OpenLAN                    OpenLAN                     OpenLAN
192.168.1.11/24            192.168.1.12/24             192.168.1.13/24

OpenLAN can connect switches across cities, clouds, and temporary networks such as hotel or home Wi-Fi. Each region can keep its local OpenLAN switch while outputs build authenticated TCP/UDP tunnels between regions. Static routes or FindHop routes then make remote subnets and VIPs reachable through the proper nexthop, so applications can move across sites without exposing every backend directly to the Internet.

🔐 Zero-Trust Access Control

       Guest Endpoint            Staff Endpoint            Ops Endpoint
             |                        |                        |
          OpenVPN                  OpenVPN                  OpenVPN
             \                        |                        /
              \                       |                       /
               ---------------------Internet-------------------
                                      |
                                      |
                         Central Switch (Policy Hub)
                        ZTrust + ACL + Knock + Auth
                        /                         \
                       /                           \
      Guest Network (restricted)      Trusted Network (policy access)
            172.16.100.0/24                 10.16.1.0/24

OpenLAN Zero Trust turns a virtual network into a default-deny access plane for new traffic while keeping established flows intact. Remote users can connect through OpenVPN, but protected services stay unreachable until the user is registered as a ZTrust guest and creates a temporary knock rule for a specific protocol and socket, such as tcp/192.59.0.1:8081. This makes it useful for contractor access, emergency operations, and service-by-service approvals where network reachability, identity, and time-limited permission must be controlled together.

🛡️ Router GRE/IPIP/WireGuard Tunnels

        Site A Router/Switch                         Site B Router/Switch
        100.100.0.241                                100.100.0.242
              |                                            |
              +=========== GRE / IPIP tunnel ==============+
              |        10.253.1.1/30 <-> 10.253.1.2/30     |
              |        10.253.2.1/30 <-> 10.253.2.2/30     |
              |
              +=========== WireGuard tunnel ===============+
                       hub peers or explicit P2P endpoints

OpenLAN can also build router-level tunnels directly, without relying only on network output links. GRE and IPIP are useful for lightweight L3 site-to-site connectivity when both sides can reach each other by underlay addresses. WireGuard adds key-based encryption and supports both hub-style peers that dial one public endpoint and P2P peers with explicit remote endpoints. These modes fit migration, lab interconnect, cloud VPC bridging, and emergency routing where operators need simple tunnel interfaces, reload persistence, and clear remove/recreate behavior.

🔀 HTTP Route Forwarding

        Client request              Client request              Client request
        Host: group.test            Host: single.test           Host: unknown.test
              |                           |                           |
              +---------------------------+---------------------------+
                                          |
                                          v
                                  Ceci HTTP Service
                              listen: 192.168.1.10:13083
                                          |
                       +------------------+-----------------+
                       /                  |                  \
                      / group route       | single route      \ global backend
                     /                    |                    \
        sw2 group backends        sw2 single backend      sw3 fallback backend
         192.56.0.2:18084          192.56.0.2:18086         192.56.0.3:18088
         192.56.0.2:18085
         192.56.0.2:18087

OpenLAN can publish one local HTTP service endpoint and route requests to different backends by the HTTP Host header. A hostname such as single.test can map to one backend, while group.test can map to multiple backends with round-robin balancing. Requests without a matched hostname can fall back to a global backend. The backends may live behind other OpenLAN switches, so the service endpoint stays stable while applications are distributed across sites.

📚 Documentation

• 📦 Software Installation
• 🏢 Branch Access
• 🌍 Multi-Region Interconnection
• 🔐 Zero Trust Network
• 🔀 Ceci Proxy Examples
• 🐳 Docker Compose

🧪 Scenario Tests

OpenLAN provides 52 executable scenario scripts under tests/cases, organized into 80+ validation functions with 1000+ assertions in total. The unified entrypoint is tests/start.sh.

Common commands:

# List all scenarios
bash tests/start.sh --list

# Run all scenarios
bash tests/start.sh

# Run selected scenarios
bash tests/start.sh switch_tcp access_success

# Generate test reports (md/html)
bash tests/start.sh --report

Report: run.md

Capability coverage by test scenario:

• Access authentication and sessions
  • access_success: verifies two-client login, reachability, and reconnect after global crypt update.
  • access_fail: verifies wrong-password rejection.
  • access_admin_multi_login: verifies concurrent admin logins.
  • access_same_user_mutex: verifies same-user mutex for regular users.
• Access crypt, SNAT, and QoS
  • access_pre_network_crypt: verifies per-network pre-shared crypt and client behavior after key updates.
  • access_snat_scope_matrix: covers the SNAT scope matrix for OpenVPN, Network A, and Network B.
  • access_client_qos: verifies client QoS rule add, update, list, save, and remove flows.
• OpenVPN access paths
  • access_openvpn: covers OpenVPN add/remove, CCD files, invalid cipher rejection, and AES/SM4 data-channel negotiation.
  • access_openvpn_acl: verifies OpenVPN ACL uses iptables while bridge ACL uses ebtables.
  • access_openvpn_client_ping: verifies static-address client-to-client ping.
  • access_openvpn_redirect: verifies source-route redirect to a second switch for VIP access.
  • access_openvpn_tcp_reset: verifies server-side TCP reset handling.
  • access_openvpn_snat_vip: verifies OpenVPN client access to a remote VIP through SNAT.
  • access_openvpn_multi_route: verifies a sw1 network-a OpenVPN client cannot reach sw2 network a/b before sw2 return routing is added, then can reach both after the route is added.
  • access_openvpn_multi_snat: verifies a sw1 network-a OpenVPN client can reach sw2 network a/b through OpenVPN-scoped SNAT without a sw2 return route.
• OpenVPN performance sampling
  • access_openvpn_perf: covers TCP/UDP OpenVPN connectivity, 0% packet-loss RTT summaries, iperf3 bandwidth sampling, and reload persistence.
• Ceci Proxy and Service
  • proxy_http, proxy_tcp, proxy_name, and proxy_name_backends: cover HTTP/TCP/DNS proxying, domain-matched multi-backend routing, and reload recovery.
  • service_tcp and service_http: cover Ceci Service TCP/HTTP forwarding, route/global backends, and restart recovery.
• Switch baseline output links
  • switch_tcp and switch_udp: cover TCP/UDP output authentication, reachability, reload behavior, and isolation after output removal.
• Router tunnels and WireGuard
  • switch_router_gre and switch_router_ipip: verify router GRE/IPIP tunnel creation, generated Linux tunnel links, bidirectional tunnel-address ping, reload persistence, and removal.
  • switch_gre_output_mix, switch_ipip_output_mix, and switch_wireguard_output_mix: verify router tunnels mixed with network outputs across two service networks, including kernel routes, disabled SNAT forwarding, bidirectional reachability, and reload persistence.
  • switch_gre_perf, switch_ipip_perf, and switch_wireguard_perf: sample router tunnel ping RTT plus iperf3 TCP/UDP bandwidth, and verify reload persistence.
  • switch_wireguard: verifies a WireGuard hub where two no-public-address peers dial one public endpoint, including multi-peer merge, hidden private keys, Linux interface state, reload, and cross-peer reachability.
  • switch_wireguard_p2p: verifies two WireGuard peers with explicit remote endpoints, public-key exchange, hidden private keys, reload, and bidirectional reachability.
• Switch IPSec and overlays
  • switch_ipsec_vxlan and switch_ipsec_gre: cover VxLAN/GRE outputs with IPSec tunnel establishment, reload, and removal.
  • switch_ipsec_vxlan_perf: compares ping, RTT, and TCP/UDP iperf3 samples before and after IPSec is enabled.
• Switch ACL and zero trust
  • switch_acl: verifies ACL add/list/save/reload/remove with VIP TCP/80 and ICMP.
  • switch_acl_default: verifies ACL default action switching between drop and accept.
  • switch_acl_network: verifies ACL ebtables hook is bridge ingress only.
  • switch_ztrust: verifies ZTrust enable/disable, Guest add, no-address client error output, token-derived Guest/Knock add/list, other-user knock rejection, and reload persistence.
• Switch routing and forwarding control
  • switch_bgp: verifies BGP peering, prefix advertise/receive filters, and reload.
  • switch_route3: verifies three-node forwarding and static-route reachability.
  • switch_findhop: verifies FindHop route binding, remove guards, active-backup, and load balancing.
• Switch NAT, DHCP, rate limit, and namespace isolation
  • switch_dnat: verifies DNAT add, reachability, reload, and remove.
  • switch_dhcp: verifies DHCP enable/disable APIs, independent dhcpConfig, dnsmasq start/stop, namespace and access client lease allocation, ping reachability, and reload persistence.
  • switch_ratelimit: verifies bridge/OpenVPN device rate-limit updates and Linux tc state.
  • switch_setaddress: verifies bridge address updates refresh address assignment, SNAT source ranges, and OpenVPN pushed routes.
  • switch_namespace, switch_namespace_snat, and switch_namespace_openvpn: cover VRF binding, SNAT source rewriting, OpenVPN device VRF membership, cross-network isolation, and reload persistence.
• Switch output performance
  • switch_output_perf: covers one center switch with mixed UDP/TCP outputs, authentication, connectivity, 0% packet-loss RTT summaries, bandwidth sampling, and reload recovery.