appa-net

Central repository for managing, orchestrating, and storing configuration for local network infrastructure and servers.

Overview

This repository serves as the single source of truth for your home network's server and infrastructure configurations. By versioning your network infrastructure as code, you gain:

• Version control — track all configuration changes, revert if needed
• Documentation — configurations serve as living documentation
• Reproducibility — easily redeploy or migrate services
• Auditability — understand who changed what and when

Repository Structure

Each folder represents a network-accessible device or server, named using the .home.arpa suffix (RFC 6762 — local network discovery):

appa-net/
├── pfsense.home.arpa/          # pfSense router/firewall (DHCP, DNS, NAT, etc.)
├── zet.home.arpa/              # General compute/services (Squid proxy, etc.)
└── README.md                    # This file

Directory Naming Convention

• Domain format: Use hostname.home.arpa to follow RFC 6762 conventions for local-only names
• Lowercase: Keep hostnames lowercase for consistency
• Self-contained: Each folder contains all configs and documentation specific to that device

Device Inventory

pfsense.home.arpa

Your primary router/firewall running pfSense. Handles:

• DHCP and static IP assignment
• DNS resolution
• WAN/LAN routing
• NAT and port forwarding
• Firewall rules

Configurations to track:

• System configuration backups (XML exports)
• Firewall rules and aliases
• Static routes
• NAT rules and port forwards
• DHCP scopes and reservations
• DNS configuration
• VPN settings (if applicable)

zet.home.arpa

General-purpose compute server. Currently running:

• Squid transparent proxy for HTTP traffic interception and caching

Configurations to track:

• Squid configuration and rules
• iptables/firewall rules for traffic redirection
• Service startup and monitoring scripts
• Application-specific settings

Adding a New Device

To add a new server or device to this repository:

1. Create a new folder: mkdir hostname.home.arpa
2. Add relevant configuration files:
   • Configuration files (YAML, JSON, or text formats for readability)
   • README.md explaining the device's purpose and key configurations
   • Any orchestration scripts (Ansible playbooks, Terraform configs, etc.)
3. Commit with a clear message: Add hostname.home.arpa configuration

Example structure for a new device:

myserver.home.arpa/
├── README.md                # Purpose, role, and setup notes
├── config/
│   ├── app.conf
│   └── network.conf
├── scripts/
│   └── deploy.sh
└── orchestration/
    └── playbook.yml         # (if using Ansible)

Management Approaches

Orchestration Tools (Recommended for Future)

Consider these tools for managing configurations at scale:

• Ansible — agentless configuration management, great for heterogeneous infrastructure
• Terraform — infrastructure-as-code, useful for reproducible deployments
• Docker/Compose — containerize services for consistency across hosts
• Custom scripts — shell scripts for simple one-off configurations

Backup Strategy

• Export pfSense configs regularly (Diagnostics → Backup/Restore)
• Archive configuration snapshots in this repo with timestamps
• Keep sensitive data (keys, credentials) in a secure vault outside this repo

Best Practices

1. Documentation First — Each device folder should have a README explaining:

   • Device purpose and role in the network
   • IP address and hostname
   • Key services running
   • How to access and modify configurations

2. Configuration as Code — Store configs in text-based formats (YAML, JSON, conf) when possible

   • Avoid binary formats; prefer exports you can diff
   • Use comments to explain non-obvious settings

3. Secrets Management — Never commit passwords, API keys, or tokens:

   • Store sensitive values in .env files or a secrets manager
   • Use {% raw %}{{ variables }}{% endraw %} placeholders in configs
   • Document where secrets come from (e.g., "stored in Bitwarden")

4. Change Control — Use git commits to document infrastructure changes:

   git commit -m "pfsense: Add NAT rule for Squid traffic interception"
   

5. Testing Changes — When possible, test config changes in a staging environment first

Feedback on Your Current Setup

✅ Strengths:

• Using .home.arpa naming is correct per RFC 6762
• Clear device-based organization scales well
• Git-based versioning from the start is a great practice
• Already documenting configuration workflows (PROXY-SETUP.md)

💡 Suggestions:

1. Add a README to pfsense.home.arpa/ documenting:

   • Current network topology and IP ranges
   • Important firewall rules
   • How to export/restore backups

2. Consider a docs/ folder at the root for:

   • Network topology diagrams (Mermaid, draw.io)
   • IP addressing scheme and VLAN assignments
   • Service dependencies and network flows

3. For pfSense backups:

   • Export XML configs to pfsense.home.arpa/backups/ with dates
   • Document critical custom configurations as markdown files

4. As you add more devices, consider an inventory file (YAML/JSON) at the root:

   # inventory.yml
   devices:
     pfsense.home.arpa:
       ip: 172.27.0.1
       role: router/firewall
     zet.home.arpa:
       ip: 172.27.0.35
       role: compute/proxy
   

5. Add GitHub Actions or a CI workflow to:

   • Validate configuration syntax
   • Generate documentation from configs
   • Alert on uncommitted changes (for critical devices)

Quick Start

1. Navigate to a device folder:

   cd pfsense.home.arpa
   

2. Review current configuration:

   cat README.md
   

3. Make changes and commit:

   git add .
   git commit -m "Description of change"
   git push
   

Contributing & Maintenance

• Regular backups: Schedule automated exports of device configs to this repo
• Documentation updates: Keep READMEs in sync with actual configurations
• Change log: Use commit messages to maintain a history of infrastructure decisions
• Review: Before major changes, review existing configs to understand dependencies

---

Last Updated: 2026-04-22