certyiknofetch/netops repository overview

⁠🍃 Netops

⁠Netops — IPAM Subnet Control Engine

A production-ready IP Address Management (IPAM) tool with a FastAPI backend, SQLite persistence, and a dark-themed TailwindCSS dashboard. Automatically allocates subnets, detects gaps, avoids reserved ranges, and supports multiple independent network pools.

⁠Features

• Multi-Pool Orchestration — Register and switch between independent network blocks (e.g. 10.0.0.0/8, 172.19.0.0/16, 192.168.0.0/16) from the UI.
• Auto CIDR Calculation — Input the number of hosts needed; the engine picks the correct prefix (/30 through /24).
• Gap Detection — Released subnets are automatically reused by the first-fit allocation algorithm. No wasted space.
• Reserved Block Skipping — Per-pool reserved CIDRs (e.g. your physical LAN) are skipped during allocation.
• Docker Compose Generator — Click any row in the ledger to get a ready-to-use docker-compose network snippet.
• Fragmentation Monitoring — Real-time utilization %, gap count, and allocated subnet count in the dashboard header.
• API Key Authentication — Mutating endpoints (POST /api/pools, POST /api/subnets/allocate, DELETE /api/subnets/{id}) are protected by X-API-Key header. Read-only endpoints (GET /api/subnets, GET /api/pools, GET /api/subnets/fragmentation) are open.
• WAL Mode SQLite — Concurrent read/write support with zero configuration.
• Fully Offline — TailwindCSS bundled locally. No CDN dependencies.

⁠Quick Start

⁠Prerequisites

• Docker & Docker Compose

⁠Run with Docker

docker run -d \
  -p 8000:8000 \
  -v ipam_data:/app \
  --name ipam \
  your-dockerhub-username/ipam-engine

Open http://localhost:8000 in your browser.

⁠Run with Docker Compose

# clone or copy the project files
cd ipam-app
docker compose up -d

⁠Run without Docker

pip install fastapi uvicorn sqlalchemy aiosqlite
python -m uvicorn main:app --host 0.0.0.0 --port 8000

⁠First-Time Setup

1. Open the dashboard at http://localhost:8000.
2. Get your API key — on first run, a random 256-bit key is generated and printed to the server log. It's also saved to .ipam_key in the app directory.

   cat /path/to/app/.ipam_key
   

   Copy
3. Paste the key into the Security Token field on the dashboard.
4. Click "+ New Pool" to register your first network block (e.g. 10.0.0.0/8).
5. Select the pool from the Target Workspace dropdown in the form.
6. Enter a project name, choose the number of hosts, and click "Calculate & Register Blocks".

⁠API Reference

⁠Authentication

Mutating endpoints require an X-API-Key header. The key is auto-generated on first run (see .ipam_key file or server logs) or set via the IPAM_ADMIN_KEY environment variable.

⁠Endpoints

⁠Example: Create a Pool

curl -X POST http://localhost:8000/api/pools \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $(cat .ipam_key)" \
  -d '{"pool_name":"Production","base_cidr":"10.0.0.0/8","reserved_blocks":"10.0.0.0/24,10.0.1.0/24"}'

⁠Example: Allocate a Subnet

curl -X POST http://localhost:8000/api/subnets/allocate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $(cat .ipam_key)" \
  -d '{"pool_id":1,"project_name":"Web Stack","required_hosts":6}'

⁠Example: Release a Subnet

curl -X DELETE http://localhost:8000/api/subnets/1 \
  -H "X-API-Key: $(cat .ipam_key)"

⁠Environment Variables

If neither variable is set, a random key is generated on first run and persisted to .ipam_key.

⁠Docker Build & Push

⁠Build the image

docker build -t ipam-engine .

⁠Tag & push to Docker Hub

docker tag ipam-engine your-dockerhub-username/ipam-engine:latest
docker login
docker push your-dockerhub-username/ipam-engine:latest

⁠Pull & run on any server

docker pull your-dockerhub-username/ipam-engine:latest
docker run -d \
  -p 8000:8000 \
  -v /path/on/host:/app \
  -e IPAM_ADMIN_KEY=my-secret-key \
  --name ipam \
  your-dockerhub-username/ipam-engine

⁠Data Persistence

The SQLite database (ipam_prod.db) and API key file (.ipam_key) are stored in the application directory. To persist data across container restarts, mount a host directory to /app:

docker run -d -p 8000:8000 -v /my/data/dir:/app ipam-engine

With docker-compose, the ipam_data named volume is used by default. You can switch to a bind mount by editing docker-compose.yml:

volumes:
  - /my/data/dir:/app

⁠Project Structure

ipam-app/
├── main.py              # FastAPI application
├── index.html           # Dashboard UI (TailwindCSS, offline)
├── Dockerfile           # Production Docker build
├── docker-compose.yml   # Docker Compose configuration
├── requirements.txt     # Python dependencies
├── README.md            # This file
└── static/
    └── tailwind.js      # TailwindCSS (local, no CDN)

⁠Architecture

Browser (index.html)
     │
     ▼
FastAPI (main.py)
     │
     ├── GET  /api/pools                   → List pools
     ├── POST /api/pools          [auth]   → Create pool
     ├── GET  /api/subnets                  → List subnets
     ├── POST /api/subnets/allocate [auth]  → Allocate subnet
     ├── DELETE /api/subnets/{id}  [auth]   → Release subnet
     └── GET  /api/subnets/fragmentation    → Pool utilization
              │
              ▼
         SQLite (ipam_prod.db)
         ├── network_pools — Pool definitions
         └── subnets       — Allocated subnets linked to pools via pool_id

The allocation engine uses Python's built-in ipaddress module. When a subnet is requested:

1. The engine determines the required CIDR prefix from the host count.
2. It scans the pool's existing subnets and reserved blocks sorted by network address.
3. It places the new subnet in the first gap large enough to fit — reusing freed space from released subnets.
4. The result is saved with correct infrastructure IP offsets: hosts[0] = gateway, hosts[1] = first usable container IP.

⁠License

MIT