ipam/README.md

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 types (Server, VM, Switch, Firewall, WiFi AP, Printer, Other)
• 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 Organization: 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
• REST API: Full-featured REST API with API key authentication for programmatic access
• CSV Export: Export subnet and rack data to CSV files
• Device Statistics: View device counts by type
• Web Interface: Modern, responsive web GUI built with Tailwind CSS and dark mode support

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 Organization" \
  -e LOGO_PNG="https://example.com/logo.png" \
  ghcr.io/jdb-net/ipam:latest

Docker Compose

version: '3.8'

services:
  ipam:
    image: ghcr.io/jdb-net/ipam:latest
    container_name: ipam
    restart: unless-stopped
    ports:
      - "5000:5000"  # Web interface
    environment:
      - MYSQL_HOST=10.10.2.27
      - MYSQL_USER=ipam
      - MYSQL_PASSWORD=your_password
      - MYSQL_DATABASE=ipam
      - SECRET_KEY=your_secret_key
      - NAME=Your Organization
      - 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: Organization name displayed in header (default: JDB-NET)
• LOGO_PNG: URL or path to organization 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;

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 "Admin" from the main menu
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 select device type
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 view
2. Click "Configure DHCP Pool"
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)

Audit Log

View all changes and actions in the "Audit Log" section, with filtering by user, subnet, action type, or device name.

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

The application includes a comprehensive REST API for programmatic access:

1. Authentication: All API requests require an API key, which can be provided via:

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

2. Base URL: All API endpoints are prefixed with /api/v1

3. Available Endpoints:

   • Devices: GET, POST, PUT, DELETE /api/v1/devices
   • Subnets: GET, POST, PUT, DELETE /api/v1/subnets
   • Racks: GET, POST, DELETE /api/v1/racks
   • Device Types: GET /api/v1/device-types
   • DHCP: GET, POST /api/v1/subnets/{id}/dhcp
   • Audit Log: GET /api/v1/audit
   • Users & Roles: GET /api/v1/users, GET /api/v1/roles (admin only)

4. API Keys: Each user has a unique API key that can be viewed and regenerated from the Users page. API keys respect the same role-based permissions as the web interface.

5. Documentation: Full API documentation is available in the Help page of the web interface.

Example API Request:

curl -H "X-API-Key: your_api_key" \
     https://your-server:5000/api/v1/devices

Kubernetes Deployment

The project includes a Kubernetes deployment manifest. See deployment.yml for details.

Example Kubernetes deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ipam
  namespace: ipam
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: ipam
        image: ghcr.io/jdb-net/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 (view in Admin 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.