## 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)

### Optional external sign-in (Logto)

External sign-in is **disabled and hidden** unless all three variables below are set. Self-hosted deployments should leave these unset so users cannot use the operator's identity provider.

- `LOGTO_OIDC_ENDPOINT`: Logto instance URL (e.g. `https://sso.jdbnet.co.uk`)
- `LOGTO_APP_ID`: Traditional web application client ID (OIDC login flow)
- `LOGTO_APP_SECRET`: Traditional web application client secret

When configured, enable external sign-in per deployment from **Users → SSO** (admin only). Pre-provisioned users are redirected to Logto after entering their email, where they can sign in with **Microsoft 365** or **Discord**. Local password and TOTP authentication remain available when external sign-in is disabled or the user is not pre-provisioned.

**Operator setup (managed deployments only):** Configure Microsoft (multi-tenant) and Discord connectors once in Logto Console. Register each IPAM instance redirect URI on the Logto application: `https://{host}/api/v2/auth/sso/callback`. Ensure the **email** scope is enabled on the Logto application.

### Database Setup

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

```sql
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](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](API.md)

```bash
# 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:

```yaml
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