241 lines
8.7 KiB
Markdown
241 lines
8.7 KiB
Markdown
## 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 |