IP Address Management

A Flask-based web application for comprehensive IP Address Management (IPAM). Manage subnets, IP addresses, devices, DHCP pools, and physical rack infrastructure with an intuitive web interface.

Features

• Subnet Management: Create and manage IP subnets with CIDR notation (supports /24 to /32)
• IP Address Tracking: Automatic IP address generation and tracking for each subnet
• Device Management: Track devices with names, descriptions, tags, and custom fields
• Device Tagging: Organize devices with customizable tags featuring colors and descriptions
• IP Assignment: Assign IP addresses to devices with automatic hostname updates
• DHCP Pool Configuration: Configure DHCP pools with start/end IP ranges and excluded IPs
• Rack Management: Physical infrastructure tracking with U positions and front/back sides
• Site Organisation: Organize subnets and devices by site/location
• Audit Logging: Complete audit trail of all changes with user, action, details, and timestamps
• User Management: Multi-user support with secure password authentication
• Role-Based Access Control (RBAC): Granular permission system with default roles (admin, user, view_only) and custom role creation
• Web Interface: Vue 3 SPA with automatic light/dark theme and mobile-first layout
• REST API v2: JSON API at /api/v2 (session cookies for browser, API keys for automation)

Local development

# Backend
pip install -r requirements.txt
./run.sh   # builds frontend if needed, starts Flask on :5000

# Frontend hot reload (optional)
cd frontend && npm install && npm run dev
# Vite proxies /api to http://127.0.0.1:5000

API reference: API.md

Quick Start with Docker

Docker Run

docker run -d \
  --name ipam \
  -p 5000:5000 \
  -e MYSQL_HOST=10.10.2.27 \
  -e MYSQL_USER=ipam \
  -e MYSQL_PASSWORD=your_password \
  -e MYSQL_DATABASE=ipam \
  -e SECRET_KEY=your_secret_key \
  -e NAME="Your Organisation" \
  -e LOGO_PNG="https://example.com/logo.png" \
  cr.jdbnet.co.uk/public/ipam:latest

Docker Compose

services:
  ipam:
    image: cr.jdbnet.co.uk/public/ipam:latest
    container_name: ipam
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - MYSQL_HOST=10.10.2.27
      - MYSQL_USER=ipam
      - MYSQL_PASSWORD=your_password
      - MYSQL_DATABASE=ipam
      - SECRET_KEY=your_secret_key
      - NAME=Your Organisation
      - LOGO_PNG=https://example.com/logo.png

Configuration

Environment Variables

• MYSQL_HOST: MySQL/MariaDB host (default: localhost)
• MYSQL_USER: Database user (default: user)
• MYSQL_PASSWORD: Database password (default: password)
• MYSQL_DATABASE: Database name (default: ipam)
• SECRET_KEY: Flask secret key for sessions (REQUIRED in production!)
• NAME: Organisation name displayed in header (default: JDB-NET)
• LOGO_PNG: URL or path to organisation logo (default: JDB-NET logo)

Database Setup

The application automatically initializes the database schema on first run. Ensure the database and user exist with appropriate permissions:

CREATE DATABASE ipam;
CREATE USER 'ipam'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON ipam.* TO 'ipam'@'%';
FLUSH PRIVILEGES;

Upgrading from v1.x

See v1-to-v2-breaking-changes.md for removed features, route changes, and automatic database migrations. Back up your database before upgrading.

Usage

First Login

1. Access the web interface at http://your-server:5000
2. Log in with the default credentials:
   • Email: admin@example.com
   • Password: password
3. Change the default password immediately via the Users page

Managing Subnets

1. Navigate to Subnet Management from the main menu (/subnets/manage)
2. Click Add Subnet and fill in:
   • Name: Friendly name for the subnet (e.g., "Office LAN")
   • CIDR: Subnet in CIDR notation (e.g., 192.168.1.0/24)
   • Site: Site/location identifier
3. The system automatically generates all IP addresses in the subnet

Adding Devices

1. Navigate to "Devices" from the main menu
2. Click "Add Device"
3. Enter device name (and optional description)
4. Click "Create Device"

Assigning IP Addresses to Devices

1. Open a device from the Devices page
2. Select a subnet and available IP address
3. Click "Assign IP" - the hostname is automatically updated

Configuring DHCP Pools

1. Open a subnet from the dashboard or subnet list
2. Click DHCP to open the DHCP pool modal
3. Set the start and end IP addresses
4. Optionally specify excluded IPs (comma-separated)
5. IPs within the pool range are automatically marked as "DHCP"

Managing Racks

1. Navigate to "Racks" from the main menu
2. Click "Add Rack" and specify:
   • Name: Rack identifier
   • Site: Site location
   • Height: Rack height in U units
3. Open a rack to assign devices to specific U positions (front or back)

Device Tagging

1. Managing Tags (requires add_tag / edit_tag / delete_tag permissions):

   • Navigate to Tags from the main menu
   • Create tags with custom colours and descriptions
   • Edit or delete existing tags as permitted by your role

2. Assigning Tags to Devices:

   • Open any device from the Devices page
   • Use the tag assignment dropdown to add multiple tags
   • Remove tags by clicking the × button next to the tag name

3. Filtering by Tags:

   • Use the tag filter dropdown on the Devices page to view devices with specific tags
   • Tags appear as colored badges throughout the interface for easy identification

Audit Log

View changes in Audit Log. Filter by user name, action type, and date range. Export filtered results to CSV.

Exporting Data

• Subnet CSV: Click "Export CSV" on any subnet page to download IP addresses with hostnames
• Rack CSV: Click "Export CSV" on any rack page to download rack layout information

Role-Based Access Control

The system uses a granular role-based access control (RBAC) system to manage user permissions:

1. Default Roles:

   • Admin: Full access to all features including user and role management
   • User: Can view and manage most features (devices, subnets, racks, etc.) but cannot manage users or roles
   • View Only: Read-only access to view pages but cannot make any changes

2. Custom Roles: Administrators can create custom roles with specific permission sets from the Users page

3. Permission Granularity: Permissions are organized into categories:

   • View permissions (access to pages)
   • Device Management (add, edit, delete devices)
   • Network Management (subnet operations)
   • Rack Management (rack operations)
   • DHCP Configuration
   • Administration (user and role management)

4. User Management: Navigate to the Users page to:

   • Create and manage users
   • Assign roles to users
   • Create custom roles with specific permissions
   • View and regenerate API keys

REST API

Programmatic access uses /api/v2. The browser SPA uses session cookies; automation uses API keys via:

• X-API-Key header
• Authorization: Bearer <api_key> header
• ?api_key=<api_key> query parameter

Each user has an API key (view/regenerate on the Users page). Keys respect the same RBAC permissions as the web UI.

Full endpoint reference: API.md

# List devices
curl -H "X-API-Key: YOUR_KEY" https://your-server:5000/api/v2/devices

# Session login (browser-style)
curl -c cookies.txt -X POST -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"password"}' \
  https://your-server:5000/api/v2/auth/login

Kubernetes Deployment

Example deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ipam
  namespace: ipam
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: ipam
        image: cr.jdbnet.co.uk/public/ipam:latest
        ports:
        - containerPort: 5000
        env:
        - name: SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: ipam-secrets
              key: secret-key
        - name: MYSQL_HOST
          value: "mysql-service"
        - name: MYSQL_USER
          value: "ipam"
        - name: MYSQL_PASSWORD
          valueFrom:
            secretKeyRef:
              name: ipam-secrets
              key: mysql-password
        - name: MYSQL_DATABASE
          value: "ipam"

Security Notes

• CHANGE THE DEFAULT ADMIN PASSWORD immediately after first login
• CHANGE THE SECRET_KEY in production - use a strong random string (e.g., openssl rand -hex 32)
• Use strong passwords for database access
• Ensure database connections are secured (consider SSL/TLS for MySQL connections)
• Review audit logs regularly for unauthorized changes
• Limit database user permissions if possible (though CREATE/ALTER may be needed for schema initialization)
• API Keys: Keep API keys secure and never share them publicly. Regenerate keys if they may have been compromised
• Role-Based Access: Use the RBAC system to grant users only the permissions they need (principle of least privilege)
• HTTPS: Use HTTPS in production to protect API keys and session data in transit

Troubleshooting

Database Connection Issues

• Ensure MySQL/MariaDB is running and accessible from the container
• Check database credentials in environment variables
• Verify database and user exist with proper permissions
• Check network connectivity between container and database
• Ensure the database name matches exactly (case-sensitive on some systems)

Application Not Starting

• Check container logs: docker logs ipam
• Verify all required environment variables are set
• Ensure port 5000 is not already in use
• Check that MySQL/MariaDB is reachable

Subnet or IP Not Appearing

• Verify CIDR notation is correct (supports /24 to /32)
• Check subnet was created successfully (Subnet Management page)
• Ensure you're logged in with appropriate permissions
• Check application logs for errors

Device IP Assignment Issues

• Verify the IP address is available (not already assigned)
• Check that the IP is not in a DHCP pool range
• Ensure the device exists and is visible in the Devices list

License

This project is provided as-is for IP Address Management.