Netweft
Deterministic network planning and configuration generation for portable infrastructure.
Netweft turns a small, typed TOML inventory into validated network plans and generated host artifacts. It is designed for homelabs and portable infrastructure that must survive location changes, ISP prefix changes, and host migrations without scattering deployment-specific addresses through source code.
Netweft 0.1.0 can:
- model hosts, logical networks, services, locations, DNS zones, and Tailscale routing;
- derive stable IPv6 ULA subnets and interface addresses;
- derive DNS recursion ACLs from the active location;
- build authoritative forward and reverse DNS plans;
- render a complete BIND configuration tree;
- render per-host environment files for Docker Compose, POSIX shells, Fish, and PowerShell;
- validate cross-file references, address ranges, duplicate ports, routing policies, and schema versions;
- keep generated runtime artifacts outside the source configuration tree.
Netweft plans and renders configuration. It does not deploy containers, alter router settings, approve Tailscale routes, or mutate host firewall rules.
Installation
Install the latest published release:
cargo install netweft
Install from a local checkout:
cargo install --path . --force
Verify the installation:
netweft --version
netweft --help
Netweft 0.1.0 is built with Rust 1.94 and edition 2024.
Filesystem layout
By default Netweft follows XDG-style paths:
~/.config/netweft/ source configuration
~/.local/share/netweft/generated/ rendered artifacts
~/.local/state/netweft/ persistent state
~/.cache/netweft/ cache data
Inspect the resolved paths:
netweft paths
Override the configuration directory with either:
netweft --config-dir /path/to/config validate
or:
export NETWEFT_CONFIG_DIR=/path/to/config
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, and XDG_CACHE_HOME are respected when present.
Configuration layout
A configuration directory contains:
~/.config/netweft/
├── netweft.toml
├── inventory.toml
├── networks.toml
├── services.toml
├── dns.toml
├── allocations.toml
└── locations/
├── home.toml
└── travel.toml
All files in schema version 1 begin with:
= 1
Unknown fields are rejected. This catches misspellings and stale configuration instead of silently ignoring them.
Minimal configuration walkthrough
The examples below use reserved documentation domains and addresses. Replace them with values appropriate for your network.
1. Select the active location
netweft.toml:
= 1
= "home"
[]
= true
= true
= true
[]
= true
= true
= true
= false
The active location determines which router, LAN segments, host addresses, and ISP IPv6 conditions are in effect.
Validate another location without changing the file:
netweft validate --location travel
2. Define stable inventory
inventory.toml:
= 1
[]
= "example.net"
= ["example.org"]
[]
= "physical"
= ["dns", "reverse-proxy", "subnet-router"]
= "/var/lib/example/services/gateway"
= "operator"
= true
[]
= "nas"
= ["storage"]
= "operator"
= true
[]
= "laptop"
= ["client"]
= true
Supported host kinds are:
physical
vm
laptop
workstation
nas
Inventory describes what a host is. Location files describe where it is attached and which addresses it currently uses.
3. Define logical networks
networks.toml:
= 1
[]
= "docker"
= "gateway"
= "services"
= "10.40.0.0/16"
= "10.40.0.1"
= "gateway-containers"
= 121
= true
= true
= true
[]
= "gateway"
= "via-host"
= "gateway"
Supported network kinds are lan and docker.
Routing modes are:
direct: the network is directly reachable;via-host: the network is routed through a named host;host-private: the network must not be advertised externally.
allocation_key connects a logical network to its stable ULA subnet allocation.
Netweft 0.1.0 does not create Docker networks. Deployment tooling must create the external network from the rendered values. When a Docker bridge should accept routed container traffic from Tailscale, create it with a trusted interface, for example:
docker network create \
--driver bridge \
--opt com.docker.network.bridge.trusted_host_interfaces=tailscale0 \
--ipv6 \
--subnet "$SERVICES_IPV4_SUBNET" \
--gateway "$SERVICES_IPV4_GATEWAY" \
--subnet "$SERVICES_IPV6_SUBNET" \
--gateway "$SERVICES_IPV6_GATEWAY" \
services
The interface name is deployment configuration; it is not hard-coded by Netweft.
4. Allocate a stable ULA
allocations.toml:
= 1
[]
= "fd12:3456:789a::/48"
[]
= 256
[]
= 289
The numeric values become the fourth IPv6 hextet:
segment 256 -> fd12:3456:789a:100::/64
network 289 -> fd12:3456:789a:121::/64
Use one randomly generated ULA /48 for the deployment and keep it stable. Do not copy the example prefix into a real network.
5. Describe a location
locations/home.toml:
= 1
= "home"
= "Primary home network"
[]
= "isp-gateway"
= false
= false
[]
= "router-advertised"
= "2001:db8:100:200::/64"
= 64
= "dynamic"
= false
[]
= "lan"
= "192.0.2.0/24"
= "192.0.2.1"
= true
= true
[]
= "lan"
= "192.0.2.10"
= "static"
= "10"
[]
= "lan"
= "192.0.2.20"
= "static"
= "20"
[]
= true
= "subnet-router"
= "gateway"
[]
= true
= true
= false
= false
= [
"segment:lan",
"network:gateway-containers",
]
IPv6 location modes are:
disabled;router-advertised, for a directly advertised/64such as an ISP gateway LAN;delegated, for a prefix Netweft may subdivide into/64networks.
A dynamic router-advertised prefix may be admitted to DNS recursion, but Netweft will not treat it as a durable allocation and will reject durable public AAAA publication from it.
6. Define services
services.toml:
= 1
[]
= "dns"
= "gateway"
= "gateway-containers"
= true
[]
= "10.40.20.20"
= "2020"
[]
= "host-port"
= "lan"
[[]]
= 53
= 53
= "tcp"
[[]]
= 53
= 53
= "udp"
[]
= "reverse-proxy"
= "gateway"
= "gateway-containers"
= true
[]
= "10.40.80.80"
= "8080"
[]
= "host-port"
= "lan"
[[]]
= 80
= 80
= "tcp"
[[]]
= 443
= 443
= "tcp"
Service kinds are:
dns
reverse-proxy
development-container
web
database
generic
A service may have:
- a stable container IPv4 address;
- a stable ULA interface ID;
- host-port ingress through one of the host’s location interfaces;
- published port mappings;
- optional SSH or web metadata.
7. Define DNS
dns.toml:
= 1
[]
= "bind9"
= "bind"
= 300
= 60
[]
= "ns1.example.net"
= "hostmaster.example.net"
= 3600
= 900
= 1209600
[]
= true
= true
= true
= true
= true
[]
= ["1.1.1.1", "1.0.0.1"]
= []
[[]]
= "example.net"
= "internal"
= true
[[]]
= "gateway.example.net"
= "host"
= "gateway"
= "lan"
= ["ipv4", "ipv6"]
= true
[[]]
= "bind.internal.example.net"
= "service"
= "bind"
= "container"
= ["ipv4", "ipv6"]
= true
[[]]
= "ns1.example.net"
= "service"
= "bind"
= "ingress"
= ["ipv4"]
= false
DNS record kinds are:
host: resolve a host interface;service: resolve a service container or ingress address;proxy: resolve the ingress address of a reverse-proxy service;cname: create a CNAME;segment-gateway: resolve a location segment gateway.
Address scopes for service records are container and ingress.
Validate and inspect
Validate the active configuration:
netweft validate
Validate another location:
netweft validate --location travel
Inspect typed configuration:
netweft show config
netweft show hosts
netweft show networks
netweft show services
Inspect derived plans:
netweft show dns-access
netweft show dns
netweft show env --host gateway
Validation checks include:
- schema-version agreement;
- references between hosts, services, networks, locations, and DNS records;
- IPv4 addresses and gateways inside their configured networks;
- duplicate service IPv4 addresses;
- duplicate host ports;
- routing-policy consistency;
- Tailscale advertisement references;
- ULA allocation consistency;
- unsafe durable AAAA publication from dynamic router-advertised prefixes.
Render artifacts
Render BIND:
netweft render bind
Render one host’s environment files:
netweft render env --host gateway
Render both:
netweft render all --host gateway
The generated tree is location-specific:
~/.local/share/netweft/generated/home/
├── bind/
│ ├── named.conf
│ ├── named.conf.options
│ ├── named.conf.local
│ ├── manifest.txt
│ └── zones/
│ └── db.*
└── hosts/
└── gateway/
├── compose.env
├── shell.sh
├── shell.fish
└── shell.ps1
Netweft also updates:
~/.local/share/netweft/current
to point at the currently rendered location.
Generated files begin with a warning that they must not be edited manually.
Docker Compose integration
Use the generated environment as the non-secret Compose environment:
docker compose \
--env-file "$HOME/.local/share/netweft/current/hosts/gateway/compose.env" \
--env-file .env \
config
Recommended split:
Netweft compose.env generated topology, addresses, routes, and paths
service .env local secrets and credentials
Do not store authentication keys, API tokens, passwords, or private keys in Netweft configuration.
A Compose wrapper can make the split repeatable:
#!/bin/sh
Shell and Apogee integration
POSIX shells can source the generated environment directly:
Fish:
source "$HOME/.local/share/netweft/current/hosts/gateway/shell.fish"
PowerShell:
. "$HOME/.local/share/netweft/current/hosts/gateway/shell.ps1"
An environment manager such as Apogee can source the host file dynamically. Keep secrets in the environment manager’s secret store, not in generated Netweft files.
Tailscale integration
For a host configured as a subnet router, Netweft renders:
TAILSCALE_HOSTNAME
TAILSCALE_STATE_DIR
TS_ADVERTISE_ROUTES
The route list is derived from location segments and logical networks referenced by the router’s advertise entries.
Netweft does not:
- authenticate a Tailscale node;
- approve advertised routes in the Tailscale admin console;
- change client route-acceptance settings;
- edit tailnet grants or ACLs.
For stable internal DNS over Tailscale, publish an owned ULA container address and configure split DNS for only the private zones that should use it.
BIND behavior
The generated BIND tree includes:
- authoritative forward zones;
- generated IPv4 and IPv6 reverse zones;
- recursion ACLs derived from the active location;
- configured forwarders;
- disabled dynamic updates and zone transfers;
- deterministic record ordering.
In 0.1.0, generated SOA serials are currently fixed at 1. A future release will add durable monotonic serial management.
Security model
Netweft deliberately separates topology from secrets.
Safe Netweft inputs include:
- host and service names;
- network CIDRs and stable addresses;
- ULA allocations;
- ports and routing policy;
- DNS zones and records;
- generated-output paths.
Keep these elsewhere:
- Tailscale auth keys;
- Cloudflare or DNS-provider API tokens;
- database passwords;
- TLS private keys;
- SSH private keys;
- application credentials.
Avoid committing real deployment configuration to the public Netweft source repository. The Rust source must not contain private hostnames, domains, addresses, interface names, or service names.
Current limitations
Netweft 0.1.0:
- renders configuration but does not deploy it;
- does not create Docker networks or containers;
- does not configure routers, DHCP, VLANs, or firewalls;
- does not mutate Tailscale control-plane settings;
- does not discover live infrastructure automatically;
- uses a fixed BIND SOA serial;
- supports only
/64subdivision from delegated IPv6 prefixes; - renders one active location at a time.
These boundaries are intentional: the first release focuses on a small, deterministic, reviewable planning core.
Development
cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
Inspect the package contents:
cargo package --list
cargo package
Test a local installation:
cargo install --path . --force
netweft --version
netweft --help
Release checklist
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
cargo package --list
cargo package
cargo publish --dry-run
Then commit, tag, push, and publish the same source revision.
License
Licensed under the MIT License.