Skip to content

ARCHITECTURE

github-actions[bot] edited this page Nov 17, 2026 · 5 revisions

Languages: English | العربية | Čeština | Deutsch | Español | فارسی | Français | हिन्दी | Bahasa Indonesia | Italiano | 日本語 | 한국어 | Nederlands | Polski | Português | Русский | Svenska | ไทย | Türkçe | Українська | Tiếng Việt | 中文


Architecture

VD Dropbear is a KernelSU / APatch / Magisk module that runs exactly one Dropbear SSH daemon, driven entirely by configuration. Nothing about the SSH server is hard-coded to one device; everything specific is runtime config or a secret.

Pieces

  • module/common/vddropbear.sh is the core library: load config (with safe built-in defaults), resolve the secret store, ensure a host key, build the Dropbear argument vector, and manage a single daemon instance (start / stop / status / restart).
  • module/service.sh: boot entry. Honours the BFU/AFU start policy; in AFU mode it waits for credential-encrypted storage to unlock without stalling boot.
  • module/action.sh is the manager's Action button: (re)launch the daemon. It never reads stdin and detaches the daemon into its own session, so the manager does not hang.
  • module/common/vddb-webui.sh + module/webroot/index.html: the WebUI backend and page.
  • patches/: small, auditable patches applied to upstream Dropbear at build time.
  • scripts/build.sh, scripts/build-bundles.sh, .github/workflows/build.yml: the build.

Daemon lifecycle (single instance)

vddb_start loads the config, stops any running instance, ensures a host key exists, then spawns one daemon. The binary is shipped as vddropbear, so its process name matches pgrep -x exactly (Android mksh has no exec -a). It is launched with setsid so it detaches from the caller's process group, which is what keeps the manager's Action from blocking.

The secret store (CE vs DE, BFU vs AFU)

Settings are not secret and live on device-encrypted storage (/data/adb/vddropbear), readable at boot. Secrets (host key, authorized_keys, password hashes) default to credential-encrypted storage (/data/misc_ce/0/vddropbear), which only unlocks after the user authenticates. Turning on START_IN_BFU moves the secrets to device-encrypted storage so the daemon can run before first unlock, at the cost of those secrets being readable earlier. The module computes which store to use at each boot stage.

The patch set

The SSH server stays upstream Dropbear; our changes are a few reviewable patches (see patches/README.md):

  • a neutral, runtime-configurable identity banner;
  • authorized_keys read from an environment-set path (so keys live in the secret store);
  • password auth against a PBKDF2 hash file instead of the system crypt()/shadow, which Android lacks (see BUILDING.md).

The WebUI

A static page in the manager's WebUI (KernelSU / APatch / WebUI-X). It drives module/common/vddb-webui.sh through the ksu.exec bridge: status, start/stop/restart, config read/write, and management of keys and password accounts. All data crosses the bridge base64-encoded, so the shell never interprets it; password hashes are computed in the browser with WebCrypto, so the clear-text password never leaves the page.


This documentation was generated with Claude (Anthropic) and is maintained by VD171. Corrections and improvements are welcome; see CONTRIBUTING.md.

Clone this wiki locally