A modular, data-driven NixOS gateway configuration framework for building enterprise-grade routers, firewalls, and network infrastructure.
This framework provides comprehensive networking, security, and monitoring capabilities through declarative NixOS configuration. All functionality is organized into independent modules that can be combined as needed.
- Data Layer: Pure attribute sets defining network topology and configuration
- Module Layer: NixOS modules consuming data and implementing services
- Integration Layer: Combines modules with interface definitions
- Modular: Each service is an independent module
- Data-Driven: Configuration separated from implementation
- Type Safe: Comprehensive validation and error handling
- Composable: Modules combine in any configuration
- Tested: Full test coverage for all functionality
IPv4/IPv6 Dual Stack Support: Simultaneous IPv4 and IPv6 networking with automatic configuration.
Interface Management: Multi-interface support with WAN failover, WiFi, WWAN, and LAN configurations.
Routing Configuration: IP forwarding, static routes, and gateway management.
Network Address Translation: Masquerade NAT for outbound traffic with port forwarding.
See: Core Networking Spec
Authoritative DNS Server: Knot DNS for local domain zones with TSIG security.
DNS Resolution Service: Knot Resolver for recursive DNS with caching and monitoring.
DNS Security: TSIG authentication for DDNS updates and secure zone transfers.
DNS Monitoring: Query logging and metrics collection with dnscollector.
See: DNS Management Spec
DHCPv4 Server: Kea DHCPv4 with dynamic allocation and static reservations.
DHCPv6 Server: Kea DHCPv6 for IPv6 address assignment.
DDNS Integration: Automatic DNS record updates during lease events.
DHCP Monitoring: Lease tracking and service health monitoring.
See: DHCP Management Spec
Firewall Management: nftables-based zone policies with device type restrictions.
Intrusion Detection: Suricata IDS with signature-based threat detection.
SSH Hardening: Root login disabled, key-based authentication, rate limiting.
Threat Intelligence: IP reputation blocking and domain filtering.
Zero Trust Architecture: Network microsegmentation and continuous verification.
See: Security Spec
Metrics Collection: Prometheus exporters for system and service metrics.
Health Monitoring: Service availability checks with automatic recovery.
Log Aggregation: Centralized log collection from all services.
Distributed Tracing: Request tracing across service boundaries.
Performance Baselining: Normal performance establishment and anomaly detection.
Service Level Objectives: SLO monitoring and compliance reporting.
See: Monitoring Spec
WireGuard VPN: Secure VPN tunnels with peer management.
Tailscale Integration: Mesh networking with automatic peer discovery.
VPN Security: Encrypted communications with access controls.
Site-to-Site VPN: Secure connectivity between multiple locations.
See: VPN Spec
Traffic Classification: Application-aware and device-based traffic identification.
Bandwidth Management: Rate limiting and priority queuing.
Traffic Shaping: Buffer management and fair queuing.
DSCP Marking: Packet marking for QoS treatment.
See: QoS Spec
Policy-Based Routing: Routing decisions based on source and policies.
BGP Integration: Border Gateway Protocol for internet routing.
OSPF Integration: Open Shortest Path First for internal routing.
Static Routing: Manual route configuration.
SD-WAN Traffic Engineering: Multi-link optimization with quality monitoring.
See: Routing Spec
Traffic Distribution: Round-robin and health-based load distribution.
High Availability Clustering: Multi-node active-active configurations.
State Synchronization: Session persistence across cluster nodes.
Health Monitoring: Backend server monitoring with automatic removal.
See: Load Balancing Spec
Configuration Backup: Automated backup of gateway configurations.
Disaster Recovery: Procedures for system restoration.
Configuration Drift Detection: Monitoring for unauthorized changes.
Automated Recovery: Service restart and configuration rollback.
Configuration Validation: Schema validation and syntax checking.
Configuration Diff: Before/after configuration comparison.
Topology Visualization: Network diagram generation.
Interactive Tutorials: Step-by-step learning guides.
Troubleshooting Tools: Diagnostic decision trees and automated analysis.
See: Dev Tools Spec
API Routing: Request routing to backend services.
API Security: Authentication and authorization controls.
API Monitoring: Performance metrics and usage tracking.
Plugin System: Extensible request processing pipeline.
See: API Gateway Spec
Service Discovery: Automatic service registration and lookup.
Traffic Management: Load balancing and circuit breaking.
Security Policies: Mutual TLS and service-to-service authorization.
Observability: Distributed tracing and metrics collection.
See: Service Mesh Spec
Content Caching: Edge content caching for performance.
Geographic Distribution: Content replication across locations.
Performance Optimization: Compression and protocol optimization.
802.1X Authentication: EAP-based network access control.
Time-Based Access: Schedule-based access restrictions.
Device Posture Assessment: Security evaluation of connecting devices.
Captive Portal: Guest access with authentication.
See: NAC Spec
NAT Gateway: Source and destination NAT functionality.
NAT64 Translation: IPv4 to IPv6 address translation.
NAT Monitoring: Connection tracking and performance metrics.
Direct Connect: Dedicated cloud connectivity with BGP.
VPC Endpoints: Private cloud service access.
BYOIP Integration: Custom IP address advertisement.
Provider Peering: Cloud provider network interconnection.
Disk Configuration: Btrfs and LUKS encryption setup.
Impermanence: Ephemeral system with persistent paths.
Hardware Testing: Component validation and benchmarking.
See: Hardware & Infrastructure Spec
Secret Storage: Encrypted sensitive data storage.
Secret Rotation: Automated secret lifecycle management.
Age Integration: Modern encryption for secrets.
Automated Testing: Comprehensive test execution.
Build Automation: Nix-based build and artifact generation.
Deployment Automation: Configuration deployment with rollback.
See: CI/CD Spec
Web Interface: Browser-based configuration and monitoring.
Configuration Management: GUI-based settings modification.
Monitoring Dashboard: Real-time metrics and alerting display.
See: Management UI Spec
XDP/eBPF Acceleration: Kernel-level high-performance processing.
Container Networking: Network policies for containerized applications.
Network Booting: PXE boot services for devices.
NCPS Support: Network Configuration Protocol Services.
{ config, pkgs, ... }:
{
imports = [
(builtins.getFlake "github:youruser/nixos-gateway").nixosModules.gateway
];
services.gateway = {
enable = true;
interfaces = {
lan = "eth0";
wan = "eth1";
};
domain = "home.local";
data = {
network = {
subnets = {
lan = {
ipv4 = {
subnet = "192.168.1.0/24";
gateway = "192.168.1.1";
};
};
};
};
hosts = {
staticDHCPv4Assignments = [
{
name = "server1";
macAddress = "aa:bb:cc:dd:ee:01";
ipAddress = "192.168.1.10";
}
];
};
};
};
}# Clone the repository
git clone https://github.com/youruser/nixos-gateway.git
cd nixos-gateway
# Enter development shell
nix develop
# Run tests
nix flake check
# Build specific outputs
nix build .#checks.x86_64-linux.basic-gateway-testThe framework includes comprehensive testing:
# Run all tests
nix flake check
# Run specific test
nix build .#checks.x86_64-linux.dns-comprehensive-test
# Run integration tests
nix build .#checks.x86_64-linux.basic-gateway-test- Review the OpenSpec documentation for contribution guidelines
- Check existing change proposals for similar work
- Create a new change proposal for significant modifications
- Ensure all changes include comprehensive tests
This project is licensed under the GNU General Public License v3.0 with Commons Clause.
- You are free to use, modify, and distribute this software under the terms of the GPL-3.0.
- The Commons Clause addendum prohibits selling the software or offering it as a paid hosted/embedded product or service.
- See the LICENSE file for full terms.
For questions and support:
- Review the detailed specifications for each capability
- Check the examples/ directory for configuration patterns
- Run the interactive tutorials:
nix run .#tutorials