Landscape Router: Domain-Based Linux Routing with eBPF

Why Landscape Router Exists Beyond IP Routing

Landscape Router addresses a specific limitation of ordinary router rules: routing only by IP address does not express a policy based on the destination domain a client intended to reach. Landscape associates devices with policy groups called flows, then gives each flow an isolated Hickory DNS server. Answers from that resolver populate kernel maps associated with the flow, allowing later packets to be directed according to the domains observed during DNS resolution.

The intended users are Linux system administrators, network engineers and homelab operators who want router functions on an existing distribution rather than accepting a dedicated appliance. The README explicitly mentions Debian, Arch and openSUSE. Landscape also supports redirecting matching traffic into Docker containers and extending that behavior with a TProxy-compatible program, although Docker remains optional.

This design is most relevant when applications or services need different routes or upstream resolvers. A client group can have an independent DNS cache, upstream and rules without sharing resolver state with another group. That isolation is a concrete operational distinction. It is not a replacement for a general-purpose ingress firewall, and the documentation excerpt does not describe intrusion detection, packet capture or traffic filtering by arbitrary payload.

The project targets a fairly narrow operating environment. Its prerequisites require Linux kernel 6.9 or newer, BTF or BPF support, and root privileges. FreeBSD and macOS are explicitly unsupported. That makes host-kernel compatibility the first adoption constraint, before configuration model or management interface.

Landscape Router DNS-to-eBPF Packet Path

Landscape divides routing into a userspace DNS plane and a kernel data plane. This separation is the central architectural choice. DNS processing can use familiar server-side components, but packet enforcement does not depend on a userspace process handling every packet.

For each flow, Landscape starts a separate Hickory DNS server. Devices join the flow by IP address or MAC address. Each resolver has its own cache, upstream configuration and rules, with UDP, DNS over HTTPS, DNS over TLS, and DNS over QUIC listed as supported upstream modes. DNS answers are written into per-flow eBPF maps in the kernel.

The data plane reads those maps from XDP and TC hooks. According to the README, packets matching a flow are steered according to its policy, while unmatched traffic passes through directly. The documented path is therefore DNS results, eBPF flow maps, in-kernel TC or XDP steering, and then interface routing. A central rule is that the DNS plane decides while the kernel enforces it.

This arrangement can limit per-packet userspace context switching, but the documentation excerpt does not provide throughput figures, latency measurements or a supported packet-rate range. It would therefore be wrong to treat the architecture as a quantified performance claim. The useful design fact is narrower: routing decisions generated by DNS become data consumed by kernel hooks.

NAT is another part of the data-plane policy. The README describes a default policy stricter than symmetric NAT, with domain or IP exceptions that can use full-cone NAT. Administrators evaluating applications that depend on permissive inbound behavior need to review that policy rather than assume every destination uses the same mapping behavior.

Installing Landscape Router and Opening Its Web UI

The README documents release-based installation rather than a package-manager command. First create the default configuration directory:

mkdir -p /root/.landscape-router

Next, download `static.zip` and the `landscape-webserver` binary matching the machine architecture from the repository Releases page. Extract the frontend assets to `/root/.landscape-router/static`. The README says this is the default location and that it can be customized. It does not provide a single archive command, so the exact extraction procedure is left to the administrator.

Start the backend from its actual location as `root`:

./landscape-webserver

No pre-created configuration file is required. Landscape can initialize directly, although the documentation site also describes optional initialization through `landscape_init.toml`. The default configuration path is `/root/.landscape-router`, and the HTTPS service listens on port `6443`. The documented initial credentials are `root` and `root`, which should be changed before exposing the management interface beyond a trusted setup.

The management host resolves to `landscape.local`. Its HTTP entry point redirects to HTTPS:

http://landscape.local:6300

The Web UI and API documentation are then available through these documented HTTPS paths:

https://landscape.local:6443
https://landscape.local:6443/api/docs

The README also says `./landscape-webserver --help` lists additional options. The HTTP request on port `6300` should redirect, while port `6443` should serve the management interface and API documentation. The excerpt does not explain how `landscape.local` is provisioned, so existing DNS or name resolution must already support that hostname.

Operating Landscape Router Through systemd and the REST API

The README includes a systemd unit for operators who have already confirmed that the binary works interactively. Its `ExecStart` is `/root/landscape-webserver`, the service runs as `root`, memory locking is unlimited, and restart behavior is set to `always`. Administrators must replace the path with the actual binary location.

Running as root is consistent with the stated prerequisites, but it also raises the operational consequence. The webserver manages DNS and privileged routing components, so compromise of the management plane would have a substantial host-level scope. The repository documentation excerpt does not describe authentication hardening beyond the initial credentials, TLS certificate lifecycle, firewalling of port `6443`, or role-based access. Those points need verification against the linked documentation before deployment on an untrusted network.

Landscape provides a full REST API, and the README states that everything available in the UI is scriptable. That makes the API useful for configuration automation and integration with an existing administration system. The endpoint documentation is served at `/api/docs`, which should reveal the concrete request schemas and available resources.

The repository layout separates the major backend areas into crates such as `landscape-core`, `landscape-dns`, `landscape-ebpf`, `landscape-database`, `landscape-gateway` and `landscape-webserver`. It also contains `landscape-webui`, generated TypeScript bindings tooling and database migration code. This separation is consistent with the stated architecture, although the excerpt does not provide enough API examples to recommend a particular automation client.

Landscape Router Failure Boundaries and Operational Limits

The first failure boundary is host compatibility. Landscape requires Linux 6.9 or newer with BTF or BPF enabled, plus root access. A distribution label alone is insufficient because the kernel must provide the required features. Non-Linux systems are not supported.

The second boundary is dependency on DNS as the policy input. The documented mechanism routes traffic by domain through DNS answers placed in eBPF maps. The README does not explain how Landscape handles applications that bypass the configured resolver, encrypted DNS outside the managed path, cached mappings, changed DNS records, or destination IPs shared by unrelated domains. Consequently, the documentation excerpt is insufficient to establish exact behavior for those cases.

Per-flow isolation limits blast radius under some failures. The README states that a container going down affects only traffic routed through it. That is a specific architectural claim, but operators still need to understand what happens to existing eBPF map entries, DNS caches and interface state after a process or host restart. No rollback procedure or recovery-state description appears in the excerpt.

Landscape is also the wrong tool when a cloud router, managed firewall or simple static-route configuration already meets the requirement. Its root process, custom kernel datapath, DNS servers and policy maps add operational surfaces that a basic router utility does not need. It is better suited to hosts where domain-level policy and per-flow upstream control justify that extra control plane.

Comparing Landscape Router with OpenWrt and Static Linux Routing

Landscape takes a different approach: it runs on a selected Linux distribution and uses a Rust webserver, isolated DNS servers, eBPF maps, and XDP or TC hooks. Landscape instead emphasizes the host distribution and a two-plane split between DNS policy and kernel enforcement.

A static Linux routing configuration is simpler for networks that only need destination-based routes. It does not provide Landscape's documented per-flow Hickory DNS servers, domain-derived flow maps, independent resolver upstreams or Docker redirection. In return, it avoids a privileged management application and domain-driven control plane. Landscape adds value when the network policy must follow resolved destinations or client-defined flows; static routing is sufficient when ordinary IP prefixes express the requirement.

The comparison should not be framed as an automatic performance judgment. Landscape's repository does not publish comparative results against OpenWrt or standard routing tools in the available documentation. The architectural difference is verifiable, but the operational choice depends on kernel support, management scope, DNS control and whether dedicated router distribution features are required.

Landscape Router Releases, Upgrades and License Boundaries

The repository was not archived, and the last push was on 2026-10-15. The listed releases include v0.26.3 on 2026-10-12, v0.26.2 on 2026-10-10 and v0.26.0 on 2026-10-09. The workspace version in `Cargo.toml` is `0.26.3`, and it specifies Rust 1.98 with edition 2024. These are concrete build and release details rather than evidence of production suitability.

The README states that upgrades use a single directory and that replacing the binary also migrates the configuration. It further states that downgrades work. Those claims reduce deployment friction, but administrators should still preserve a copy of the configuration directory and the previous binary before replacement. The excerpt does not define migration failure recovery or compatibility guarantees across every release.

The repository declares GPL-3.0-only at the workspace level. The README gives a more specific split: `landscape-ebpf` is licensed under GNU GPL v2.0, while other parts are under GNU GPL v3.0. Source distribution, modification, and redistribution therefore need to account for the applicable component license. This identifies the stated terms and is not legal advice.

The repository also contains `build.sh`, Dockerfiles, `BUILD.md` and a Rust toolchain file for development. The README does not provide a complete release build recipe in the excerpt, so operators should use the published release assets unless their own build requirements call for the linked build guide.

Editorial conclusion

Landscape Router fits administrators who need domain-aware routing on a supported Linux host and can operate DNS infrastructure, privileged kernel features and container redirection. It is unsuitable for non-Linux systems, kernels older than 6.9, or deployments without root access. Before adoption, verify kernel BTF and BPF availability, interface placement, DNS interception and the privileges required by the intended routing policy.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. ThisSeanZhang/landscape on GitHub