discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens

ThisSeanZhang/landscape · source

Snapshot 0 · 2026-11-04T12:47:27Z · Rust · GPL-3.0

GitHub description at capture

The goal is to make it easier to configure your favorite Linux distribution as a router. Built with Rust and eBPF.

README at capture

<div align="center">

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-green.svg)](https://www.gnu.org/licenses/gpl-3.0)  

**Landscape routes traffic by domain—not just IP. Each flow gets its own DNS server.**

**DNS answers populate kernel eBPF maps. Packets are steered at XDP/TC.**

**No userspace datapath. No iptables.**

> Built with Rust / eBPF.

</div>

[简体中文](./README.zh.md) | [English](./README.md) | [Documentation](https://landscape.whileaway.dev/)

## Screenshot
![Landscape Web UI](./assets/main.png)

## Architecture

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./assets/arch-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="./assets/arch-light.svg">
  <img alt="Landscape architecture diagram" src="./assets/arch-light.svg">
</picture>

Landscape separates traffic steering into two planes:

**DNS plane (userspace).** A flow is a policy group that devices join by IP or MAC. Each flow gets its own isolated Hickory DNS server with independent cache, upstream (UDP/DoH/DoT/DoQ), and rules. DNS answers populate per-flow eBPF maps in the kernel.

**Data plane (kernel).** XDP and TC hooks read these maps to steer packets at wire speed. Packets matching a flow are steered according to its policy. Everything else passes through directly — no userspace context switch.

DNS results → eBPF flow maps → TC/XDP in-kernel steering → interface routing

DNS plane decides. Kernel enforces.

## Core Features
* DNS-driven traffic steering via eBPF — DNS answers populate per-flow kernel maps
* Fine-grained NAT — a stricter-than-symmetric NAT policy by default, with per-domain/IP full-cone NAT exceptions ([details](https://landscape.whileaway.dev/features/nat.html))
* Per-flow DNS isolation — independent cache and upstream per flow, no cross-flow leaks
* Redirect packets matching a flow into Docker containers — extend with any TProxy-compatible program
* Geo database management — DAT and TXT format support
* Full REST API — everything in the UI is scriptable

## Why Landscape

**Standard Linux, no lock-in.** Debian, Arch, openSUSE. Your distro, your rules.

**Upgrade without fear.** Single directory. Drop in a new binary, config auto-migrates. Downgrade works too.

**NAT that fits your LAN.** Full-cone NAT for BT/PT where needed, strict NAT everywhere else — domain/IP-level control, no blanket rules.

**One failure, one victim.** Per-flow DNS and traffic policies. A container goes down? Only the traffic routed through it is affected.

## Install with lkit

[Landscape Kit](https://github.com/landscape-router/landscape-kit) provides the `lkit` console and CLI for installing and managing Landscape — first-time deployment, updates, version switching, backup/restore, repair, and network takeover.

```bash
curl --proto '=https' --tlsv1.2 -fsSL https://github.com/landscape-router/landscape-kit/releases/latest/download/install.sh | sudo sh
# Or:
wget -qO- https://github.com/landscape-router/landscape-kit/releases/latest/download/install.sh | sudo sh
```

Then start the console:

```bash
sudo lkit
```

`sudo lkit` opens the interactive console. For automation, use an explicit subcommand, for example `sudo lkit --non-interactive install --password-file /root/lkit-password`. Release binaries support glibc-based Linux on `x86_64` and `aarch64`; musl distributions such as Alpine are not supported.

The manual steps below remain available if you prefer to install by hand.

## Quick Start

### Prerequisites

- Linux kernel ≥ 6.12 with BTF/BPF enabled, `root` privileges; non-Linux kernels (FreeBSD, macOS) are not supported
- Docker (optional, for container redirection)

### 1. Create the config directory

```bash
mkdir -p /root/.landscape-router
```

### 2. Download the release assets

- From [Releases](https://github.com/ThisSeanZhang/landscape/releases) (backend binary and frontend static assets are released separately)
  - Download `static.zip`
  - Download the `landscape-webserver` binary for your architecture
- Extract it to `/root/.landscape-router/static` (this is the default path, but it can be customized)

### 3. Start Landscape

Run as `root`:

```bash
./landscape-webserver
```

Defaults: config at `/root/.landscape-router`, HTTPS on port `6443`, user/pass `root` / `root`.

Landscape can start directly without any pre-created configuration file. If you want to initialize it through `landscape_init.toml`, see the configuration guide on the documentation site.

You can check more options with `./landscape-webserver --help`.

### 4. Open the management interface

- `http://landscape.local:6300` automatically redirects to HTTPS
- `https://landscape.local:6443` opens the Web UI
- `https://landscape.local:6443/api/docs` opens the REST API docs

## Run as a systemd Service

After confirming that the service is running correctly, you can configure it as a `systemd` service:

```ini
[Unit]
Description=Landscape Router

[Service]
ExecStart=/root/landscape-webserver
Restart=always
User=root
LimitMEMLOCK=infinity

[Install]
WantedBy=multi-user.target
```

Replace `ExecStart` with the actual path to your binary.

## Development

Build guide: [BUILD.md](./BUILD.md) | [BUILD.zh.md](./BUILD.zh.md)

## License

- `landscape-ebpf`: [GNU General Public License v2.0](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html)
- Other parts: [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html)

If you have suggestions or run into a problem, please open an [issue](https://github.com/ThisSeanZhang/landscape/issues).