9.1 KiB
BZOD Administrator Guide
Version: v0.6.0
Introduction
This guide is intended for BZOD administrators responsible for operating, maintaining, and managing a BZOD instance.
It covers:
- Administrator authentication
- User management
- Quotas
- Sessions
- Moderation
- Slug ownership
- Analytics
- Audit logs
- Backup and recovery
- Health monitoring
- Operational best practices
Administrator Role
Administrators have full platform control.
Administrative capabilities include:
- Create users
- Modify users
- Disable users
- Delete users
- Reset passwords
- Manage quotas
- Review analytics
- Moderate content
- Transfer slug ownership
- Manage backups
- Review audit logs
- Monitor system health
Administrators cannot bypass audit logging.
All administrative actions are recorded.
Login
Administrative login is available at:
/login
Successful login redirects to:
/admin
Authentication uses:
users.db
Sessions are stored in:
users.db.sessions
Cookie name:
bzod_session
Administrative Dashboard
Route:
/admin
The dashboard provides a high-level overview of platform activity.
Metrics include:
- Total Users
- Active Users
- Total URLs
- Total Landing Pages
- Active Sessions
- API Tokens
- Storage Usage
- Moderation Events
- Recent Audit Events
Quick actions include:
- Create User
- View Sessions
- View Audit Logs
- Create Backup
- Review Health Status
User Management
Users List
Route:
/admin/users
Displays:
- User ID
- Username
- Status
- Account Type
- Creation Date
Available actions:
- View
- Edit
- Disable
- Enable
- Reset Password
- Delete
Create User
Route:
/admin/users/new
Fields:
- Username
- Password
- Account Type
- Quota Limits
Supported account types:
admin
standard
Reserved usernames cannot be used.
Examples:
admin
legacy_admin
system
root
administrator
User Detail Page
Route:
/admin/users/{id}
Displays:
Profile
- User ID
- Username
- Status
- Account Type
- Created Date
Usage Statistics
- URL Count
- Landing Page Count
- Visit Count
- Storage Usage
- API Token Count
- Active Sessions
Quotas
- Maximum URLs
- Maximum Pages
- Maximum Storage
- Maximum Tokens
Sessions
List of active sessions.
API Tokens
List of active tokens.
Edit User
Route:
/admin/users/{id}/edit
Administrators may:
- Change status
- Change account type
- Modify quotas
Reset Password
Route:
/admin/users/{id}/password
Creates a new password hash and invalidates existing sessions.
Audit event generated:
password_reset
Disable User
Route:
/admin/users/{id}/disable
Effects:
- User login disabled
- Existing sessions revoked
- API access denied
Audit event generated:
user_disabled
Enable User
Route:
/admin/users/{id}/enable
Restores account access.
Audit event generated:
user_enabled
Delete User
Route:
/admin/users/{id}/delete
Deletion performs:
- Session revocation
- API token removal
- Content removal
- Analytics removal
- Slug release
- User database deletion
Audit event generated:
user_deleted
Session Management
Route:
/admin/sessions
Displays all active platform sessions.
Information displayed:
- User ID
- Username
- Session Identifier
- Created Time
- Expiry Time
- IP Address
- User Agent
Revoke Session
Individual sessions can be revoked.
Effects:
- Session removed immediately
- User forced to reauthenticate
Revoke All Sessions
Administrators may invalidate all active sessions.
Useful after:
- Password compromise
- Security incidents
- Large configuration changes
Quota Management
Route:
/admin/quotas
Quotas limit user resource consumption.
Available limits:
max_urls
max_pages
max_storage_mb
max_api_tokens
Quota Reconciliation
Administrators can execute:
quota_reconcile
Purpose:
- Detect counter drift
- Recount resources
- Repair quota usage
Common causes:
- Manual database modifications
- Failed migrations
- Interrupted operations
Moderation
Route:
/admin/moderation
Moderation allows administrators to manage abuse and policy violations.
Flag Content
Marks content for review.
Audit event:
content_flagged
Disable Content
Disabled content returns:
410 Gone
Affected endpoints:
/{slug}
/p/{slug}
/api/qr/{slug}.png
/api/qr/{slug}.svg
Audit event:
content_disabled
Enable Content
Restores functionality.
Audit event:
content_enabled
Delete Content
Permanently removes content.
Audit event:
content_deleted
Slug Management
Route:
/admin/slugs
Displays platform-wide slug ownership.
Information includes:
- Slug
- Owner
- Type
- Status
- Creation Date
Slug Types
Supported types:
url
page
Transfer Ownership
Administrators may transfer ownership.
Workflow:
- Validate recipient quota.
- Copy content.
- Update ownership.
- Update global slug registry.
- Write audit record.
Audit event:
slug_transfer
Analytics are preserved.
Analytics
Administrators can access analytics for any managed resource.
URL Analytics
Route:
/admin/analytics/url/{id}
Displays:
- Total Visits
- Unique Visitors
- Referrers
- Browsers
- Countries
- Visit Timeline
Page Analytics
Route:
/admin/analytics/page/{id}
Displays identical metrics for landing pages.
User Analytics
Administrators can review user-level analytics.
Route:
/analytics
Includes:
- Top Links
- Top Pages
- Referrers
- Browsers
- Countries
- Recent Visits
Audit Logs
Route:
/admin/audit
All administrative actions are recorded.
Searchable event types include:
login
logout
failed_login
user_created
user_deleted
user_disabled
user_enabled
password_reset
quota_updated
slug_transfer
content_flagged
content_disabled
backup_created
restore_executed
Audit logs should be reviewed regularly.
Backup Management
Route:
/admin/backups
Provides web-based backup operations.
Create Backup
Creates a platform snapshot.
Includes:
users.db
system.db
tenant databases
Audit event:
backup_created
Download Backup
Allows local storage of backup archives.
Recommended frequency:
Daily
Restore Backup
Restores a selected backup archive.
Audit event:
restore_executed
Always test restores before production use.
Delete Backup
Removes backup archives from storage.
Health Dashboard
Route:
/admin/health
Provides operational diagnostics.
Displays:
- Database Status
- WAL Status
- Storage Utilization
- Backup Status
- Health Check Results
- Quota Reconciliation Results
Database Health
Checks:
users.db
system.db
content.db
analytics.db
Reports:
healthy
warning
error
Storage Monitoring
Shows:
- Total Storage
- Free Storage
- Database Sizes
- Backup Sizes
Security Administration
Password Policies
Recommendations:
- Minimum 12 characters
- Unique passwords
- Password manager usage
Session Management
Recommended actions:
- Revoke old sessions
- Review active sessions
- Remove inactive users
CSRF Protection
All administrative forms require valid CSRF tokens.
Invalid requests return:
403 Forbidden
Audit Reviews
Recommended review schedule:
| Event Type | Frequency |
|---|---|
| Failed Logins | Daily |
| User Creation | Weekly |
| Slug Transfers | Weekly |
| Backup Events | Daily |
| Moderation Events | Weekly |
Disaster Recovery
Recommended workflow:
- Stop BZOD.
- Create backup copy.
- Restore archive.
- Verify databases.
- Run integrity checks.
- Restart service.
Operational Best Practices
Recommended:
- Enable HTTPS
- Run daily backups
- Monitor disk usage
- Review audit logs
- Keep binaries updated
- Test restore procedures regularly
Avoid:
- Manual database modifications
- Direct deletion of tenant databases
- Disabling audit logging
Troubleshooting
User Cannot Login
Check:
- User status
- Session validity
- Password reset history
Slug Already Exists
Check:
/admin/slugs
for ownership conflicts.
Analytics Missing
Verify:
- Analytics worker running
- Analytics database present
- Event queue processing
Backup Failure
Check:
- Free disk space
- File permissions
- Backup destination path
Summary
The BZOD administration system provides:
- Centralized user management
- Quotas and session controls
- Moderation and slug ownership management
- Analytics visibility
- Audit logging
- Backup and restore capabilities
- Health monitoring
while maintaining strong tenant isolation and a SQLite-native operational model.
End of Document.