{"id":48824088,"url":"https://github.com/shift/nixos-gateway","last_synced_at":"2026-04-14T17:02:01.145Z","repository":{"id":346589429,"uuid":"1117095746","full_name":"shift/nixos-gateway","owner":"shift","description":"Modular, data-driven NixOS framework for building declarative routers, firewalls, and network infrastructure","archived":false,"fork":false,"pushed_at":"2026-04-13T17:09:05.000Z","size":1934,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T18:17:54.840Z","etag":null,"topics":["dhcp","dns","firewall","flake","gateway","networking","nix","nixos","router","wireguard"],"latest_commit_sha":null,"homepage":"https://github.com/shift/nixos-gateway","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shift.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["shift"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":["paypal.me/sectionme"]}},"created_at":"2025-12-15T20:33:25.000Z","updated_at":"2026-03-30T20:13:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shift/nixos-gateway","commit_stats":null,"previous_names":["shift/nixos-gateway"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shift/nixos-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shift%2Fnixos-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shift%2Fnixos-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shift%2Fnixos-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shift%2Fnixos-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shift","download_url":"https://codeload.github.com/shift/nixos-gateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shift%2Fnixos-gateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31806209,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dhcp","dns","firewall","flake","gateway","networking","nix","nixos","router","wireguard"],"created_at":"2026-04-14T17:02:00.342Z","updated_at":"2026-04-14T17:02:01.137Z","avatar_url":"https://github.com/shift.png","language":"Nix","funding_links":["https://github.com/sponsors/shift","paypal.me/sectionme"],"categories":[],"sub_categories":[],"readme":"# NixOS Gateway Configuration Framework\n\nA modular, data-driven NixOS gateway configuration framework for building enterprise-grade routers, firewalls, and network infrastructure.\n\n## Overview\n\nThis 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.\n\n## Architecture\n\n### Three-Layer Design\n1. **Data Layer**: Pure attribute sets defining network topology and configuration\n2. **Module Layer**: NixOS modules consuming data and implementing services\n3. **Integration Layer**: Combines modules with interface definitions\n\n### Key Principles\n- **Modular**: Each service is an independent module\n- **Data-Driven**: Configuration separated from implementation\n- **Type Safe**: Comprehensive validation and error handling\n- **Composable**: Modules combine in any configuration\n- **Tested**: Full test coverage for all functionality\n\n## Capabilities\n\n### Core Networking\n**IPv4/IPv6 Dual Stack Support**: Simultaneous IPv4 and IPv6 networking with automatic configuration.\n\n**Interface Management**: Multi-interface support with WAN failover, WiFi, WWAN, and LAN configurations.\n\n**Routing Configuration**: IP forwarding, static routes, and gateway management.\n\n**Network Address Translation**: Masquerade NAT for outbound traffic with port forwarding.\n\n*See: [Core Networking Spec](openspec/specs/core-networking/spec.md)*\n\n### DNS Management\n**Authoritative DNS Server**: Knot DNS for local domain zones with TSIG security.\n\n**DNS Resolution Service**: Knot Resolver for recursive DNS with caching and monitoring.\n\n**DNS Security**: TSIG authentication for DDNS updates and secure zone transfers.\n\n**DNS Monitoring**: Query logging and metrics collection with dnscollector.\n\n*See: [DNS Management Spec](openspec/specs/dns-management/spec.md)*\n\n### DHCP Management\n**DHCPv4 Server**: Kea DHCPv4 with dynamic allocation and static reservations.\n\n**DHCPv6 Server**: Kea DHCPv6 for IPv6 address assignment.\n\n**DDNS Integration**: Automatic DNS record updates during lease events.\n\n**DHCP Monitoring**: Lease tracking and service health monitoring.\n\n*See: [DHCP Management Spec](openspec/specs/dhcp-management/spec.md)*\n\n### Security\n**Firewall Management**: nftables-based zone policies with device type restrictions.\n\n**Intrusion Detection**: Suricata IDS with signature-based threat detection.\n\n**SSH Hardening**: Root login disabled, key-based authentication, rate limiting.\n\n**Threat Intelligence**: IP reputation blocking and domain filtering.\n\n**Zero Trust Architecture**: Network microsegmentation and continuous verification.\n\n*See: [Security Spec](openspec/specs/security/spec.md)*\n\n### Monitoring\n**Metrics Collection**: Prometheus exporters for system and service metrics.\n\n**Health Monitoring**: Service availability checks with automatic recovery.\n\n**Log Aggregation**: Centralized log collection from all services.\n\n**Distributed Tracing**: Request tracing across service boundaries.\n\n**Performance Baselining**: Normal performance establishment and anomaly detection.\n\n**Service Level Objectives**: SLO monitoring and compliance reporting.\n\n*See: [Monitoring Spec](openspec/specs/monitoring/spec.md)*\n\n### VPN\n**WireGuard VPN**: Secure VPN tunnels with peer management.\n\n**Tailscale Integration**: Mesh networking with automatic peer discovery.\n\n**VPN Security**: Encrypted communications with access controls.\n\n**Site-to-Site VPN**: Secure connectivity between multiple locations.\n\n*See: [VPN Spec](openspec/specs/vpn/spec.md)*\n\n### Quality of Service\n**Traffic Classification**: Application-aware and device-based traffic identification.\n\n**Bandwidth Management**: Rate limiting and priority queuing.\n\n**Traffic Shaping**: Buffer management and fair queuing.\n\n**DSCP Marking**: Packet marking for QoS treatment.\n\n*See: [QoS Spec](openspec/specs/qos/spec.md)*\n\n### Routing\n**Policy-Based Routing**: Routing decisions based on source and policies.\n\n**BGP Integration**: Border Gateway Protocol for internet routing.\n\n**OSPF Integration**: Open Shortest Path First for internal routing.\n\n**Static Routing**: Manual route configuration.\n\n**SD-WAN Traffic Engineering**: Multi-link optimization with quality monitoring.\n\n*See: [Routing Spec](openspec/specs/routing/spec.md)*\n\n### Load Balancing\n**Traffic Distribution**: Round-robin and health-based load distribution.\n\n**High Availability Clustering**: Multi-node active-active configurations.\n\n**State Synchronization**: Session persistence across cluster nodes.\n\n**Health Monitoring**: Backend server monitoring with automatic removal.\n\n*See: [Load Balancing Spec](openspec/specs/load-balancing/spec.md)*\n\n### Backup \u0026 Recovery\n**Configuration Backup**: Automated backup of gateway configurations.\n\n**Disaster Recovery**: Procedures for system restoration.\n\n**Configuration Drift Detection**: Monitoring for unauthorized changes.\n\n**Automated Recovery**: Service restart and configuration rollback.\n\n*See: [Backup \u0026 Recovery Spec](openspec/specs/backup-recovery/spec.md)*\n\n### Development Tools\n**Configuration Validation**: Schema validation and syntax checking.\n\n**Configuration Diff**: Before/after configuration comparison.\n\n**Topology Visualization**: Network diagram generation.\n\n**Interactive Tutorials**: Step-by-step learning guides.\n\n**Troubleshooting Tools**: Diagnostic decision trees and automated analysis.\n\n*See: [Dev Tools Spec](openspec/specs/dev-tools/spec.md)*\n\n### API Gateway\n**API Routing**: Request routing to backend services.\n\n**API Security**: Authentication and authorization controls.\n\n**API Monitoring**: Performance metrics and usage tracking.\n\n**Plugin System**: Extensible request processing pipeline.\n\n*See: [API Gateway Spec](openspec/specs/api-gateway/spec.md)*\n\n### Service Mesh\n**Service Discovery**: Automatic service registration and lookup.\n\n**Traffic Management**: Load balancing and circuit breaking.\n\n**Security Policies**: Mutual TLS and service-to-service authorization.\n\n**Observability**: Distributed tracing and metrics collection.\n\n*See: [Service Mesh Spec](openspec/specs/service-mesh/spec.md)*\n\n### Content Delivery\n**Content Caching**: Edge content caching for performance.\n\n**Geographic Distribution**: Content replication across locations.\n\n**Performance Optimization**: Compression and protocol optimization.\n\n*See: [Content Delivery Spec](openspec/specs/content-delivery/spec.md)*\n\n### Network Access Control\n**802.1X Authentication**: EAP-based network access control.\n\n**Time-Based Access**: Schedule-based access restrictions.\n\n**Device Posture Assessment**: Security evaluation of connecting devices.\n\n**Captive Portal**: Guest access with authentication.\n\n*See: [NAC Spec](openspec/specs/nac/spec.md)*\n\n### NAT \u0026 Translation\n**NAT Gateway**: Source and destination NAT functionality.\n\n**NAT64 Translation**: IPv4 to IPv6 address translation.\n\n**NAT Monitoring**: Connection tracking and performance metrics.\n\n*See: [NAT \u0026 Translation Spec](openspec/specs/nat-translation/spec.md)*\n\n### Cloud Integration\n**Direct Connect**: Dedicated cloud connectivity with BGP.\n\n**VPC Endpoints**: Private cloud service access.\n\n**BYOIP Integration**: Custom IP address advertisement.\n\n**Provider Peering**: Cloud provider network interconnection.\n\n*See: [Cloud Integration Spec](openspec/specs/cloud-integration/spec.md)*\n\n### Hardware \u0026 Infrastructure\n**Disk Configuration**: Btrfs and LUKS encryption setup.\n\n**Impermanence**: Ephemeral system with persistent paths.\n\n**Hardware Testing**: Component validation and benchmarking.\n\n*See: [Hardware \u0026 Infrastructure Spec](openspec/specs/hardware-infrastructure/spec.md)*\n\n### Secrets Management\n**Secret Storage**: Encrypted sensitive data storage.\n\n**Secret Rotation**: Automated secret lifecycle management.\n\n**Age Integration**: Modern encryption for secrets.\n\n*See: [Secrets Management Spec](openspec/specs/secrets-management/spec.md)*\n\n### CI/CD\n**Automated Testing**: Comprehensive test execution.\n\n**Build Automation**: Nix-based build and artifact generation.\n\n**Deployment Automation**: Configuration deployment with rollback.\n\n*See: [CI/CD Spec](openspec/specs/ci-cd/spec.md)*\n\n### Management UI\n**Web Interface**: Browser-based configuration and monitoring.\n\n**Configuration Management**: GUI-based settings modification.\n\n**Monitoring Dashboard**: Real-time metrics and alerting display.\n\n*See: [Management UI Spec](openspec/specs/management-ui/spec.md)*\n\n### Advanced Networking\n**XDP/eBPF Acceleration**: Kernel-level high-performance processing.\n\n**Container Networking**: Network policies for containerized applications.\n\n**Network Booting**: PXE boot services for devices.\n\n**NCPS Support**: Network Configuration Protocol Services.\n\n*See: [Advanced Networking Spec](openspec/specs/advanced-networking/spec.md)*\n\n## Quick Start\n\n### Basic Gateway Setup\n\n```nix\n{ config, pkgs, ... }:\n\n{\n  imports = [\n    (builtins.getFlake \"github:youruser/nixos-gateway\").nixosModules.gateway\n  ];\n\n  services.gateway = {\n    enable = true;\n\n    interfaces = {\n      lan = \"eth0\";\n      wan = \"eth1\";\n    };\n\n    domain = \"home.local\";\n\n    data = {\n      network = {\n        subnets = {\n          lan = {\n            ipv4 = {\n              subnet = \"192.168.1.0/24\";\n              gateway = \"192.168.1.1\";\n            };\n          };\n        };\n      };\n\n      hosts = {\n        staticDHCPv4Assignments = [\n          {\n            name = \"server1\";\n            macAddress = \"aa:bb:cc:dd:ee:01\";\n            ipAddress = \"192.168.1.10\";\n          }\n        ];\n      };\n    };\n  };\n}\n```\n\n### Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/youruser/nixos-gateway.git\ncd nixos-gateway\n\n# Enter development shell\nnix develop\n\n# Run tests\nnix flake check\n\n# Build specific outputs\nnix build .#checks.x86_64-linux.basic-gateway-test\n```\n\n## Testing\n\nThe framework includes comprehensive testing:\n\n```bash\n# Run all tests\nnix flake check\n\n# Run specific test\nnix build .#checks.x86_64-linux.dns-comprehensive-test\n\n# Run integration tests\nnix build .#checks.x86_64-linux.basic-gateway-test\n```\n\n## Contributing\n\n1. Review the [OpenSpec documentation](openspec/) for contribution guidelines\n2. Check existing [change proposals](openspec/changes/) for similar work\n3. Create a new change proposal for significant modifications\n4. Ensure all changes include comprehensive tests\n\n## License\n\nThis project is licensed under the **GNU General Public License v3.0 with Commons Clause**.\n\n- You are free to use, modify, and distribute this software under the terms of the [GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.html).\n- The **Commons Clause** addendum prohibits selling the software or offering it as a paid hosted/embedded product or service.\n- See the [LICENSE](LICENSE) file for full terms.\n\n## Support\n\nFor questions and support:\n- Review the detailed [specifications](openspec/specs/) for each capability\n- Check the [examples/](examples/) directory for configuration patterns\n- Run the interactive tutorials: `nix run .#tutorials`","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshift%2Fnixos-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshift%2Fnixos-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshift%2Fnixos-gateway/lists"}