Note: This documentation is still in progress, not reviewed properly, and might contain some errors or outdated images. It's intended for the upcoming 4.0.0 release, so configuration settings might be different from previous versions.

Upgrading to Version 4.0.0

Overview

Version 4.0.0 represents a major update to Poweradmin with significant architectural improvements, enhanced security features, and a new configuration system. This guide will help you migrate from older versions.

Key Changes

  • Configuration file format and location have changed
  • Database schema updates including 8 new tables for enhanced functionality
  • New theming system with light/dark mode support
  • Enhanced security with multi-factor authentication (MFA)
  • Advanced account lockout and password reset features
  • API key management system
  • User preferences and agreements system
  • Google reCAPTCHA integration
  • WHOIS and RDAP lookup functionality
  • Enhanced email system with multiple transport options
  • Improved object-oriented architecture with proper separation of concerns

Upgrade Instructions

  1. Download latest tarball from GitHub
  2. Backup your files and database before proceeding - this is especially important for a major version upgrade
  3. Replace all files with content from the downloaded archive
  4. Run the database migration (see Database Schema Updates section below)
  5. Migrate your configuration (see Configuration Changes section below)

Configuration Migration

If you're upgrading from an older version of Poweradmin (pre-4.0.0), use the automatic migration script:

php config/migrate-config.php

This will convert your old inc/config.inc.php settings to the new config/settings.php format.

Configuration Changes Overview

Aspect Old (pre-4.0.0) New (4.0.0+)
Location inc/config.inc.php config/settings.php
Format Direct variable assignments Structured array format

Configuration Format Examples

Old Format (pre-4.0.0):

$db_host = 'localhost';
$db_user = 'poweradmin';
$db_pass = 'password';
$db_name = 'powerdns';
$db_type = 'mysql';

New Format (4.0.0+):

return [
    'database' => [
        'host' => 'localhost',
        'user' => 'poweradmin',
        'password' => 'password',
        'name' => 'powerdns',
        'type' => 'mysql',
    ],
];

Manual Migration Steps

If the automatic migration script doesn't work for your setup:

  1. Create a new config/settings.php file
  2. Refer to config/settings.defaults.php for available options
  3. Map your old settings to the new format using the examples above
  4. Test the configuration thoroughly

Database Schema Updates

Version 4.0.0 introduces significant database schema changes including multiple new tables for enhanced security, API management, user preferences, and multi-factor authentication.

New Tables Added in v4.0.0

  • login_attempts - Login attempt tracking for security
  • migrations - Database migration tracking
  • api_keys - API access management
  • user_mfa - Multi-factor authentication support
  • user_preferences - User preferences and settings
  • zone_template_sync - Zone template synchronization
  • password_reset_tokens - Password reset functionality
  • user_agreements - User agreement tracking

Database Migration Files

Important: Instead of running individual SQL statements, use the dedicated migration files from the Poweradmin repository:

MySQL:

mysql -u [username] -p [database_name] < sql/poweradmin-mysql-update-to-4.0.0.sql

Download: poweradmin-mysql-update-to-4.0.0.sql

PostgreSQL:

psql -U [username] -d [database_name] -f sql/poweradmin-pgsql-update-to-4.0.0.sql

Download: poweradmin-pgsql-update-to-4.0.0.sql

SQLite:

sqlite3 [database_file] < sql/poweradmin-sqlite-update-to-4.0.0.sql

Download: poweradmin-sqlite-update-to-4.0.0.sql

Migration Prerequisites and Upgrading from Older Versions

Important: If you're upgrading from a version earlier than v3.9.0, you must upgrade incrementally:

  1. From v2.x.x: First upgrade to v3.0.0 (see v3.0.0 upgrade guide)
  2. From v3.0.x to v3.1.x: Upgrade to v3.2.0 (see v3.2.0 upgrade guide)
  3. From v3.2.x to v3.8.x: Upgrade to v3.9.0 (see v3.9.0 upgrade guide)
  4. From v3.9.x: Follow this guide to upgrade to v4.0.0

This incremental approach ensures all database migrations are applied correctly and configurations are properly migrated.

Verify Database Migration Completeness

After running the migration, verify your database contains all 8 new tables:

Verification Query (MySQL):

SELECT TABLE_NAME FROM information_schema.TABLES 
WHERE TABLE_SCHEMA = 'your_database_name' 
AND TABLE_NAME IN ('migrations', 'login_attempts', 'api_keys', 'user_mfa', 'user_preferences', 'zone_template_sync', 'password_reset_tokens', 'user_agreements');

Expected Result: You should see all 8 tables listed in the "New Tables Added in v4.0.0" section above.

If any tables are missing, the migration may have failed. Check the migration logs for errors.

New Feature: DNS Record Type Customization

Version 4.0.0 introduces the ability to customize which DNS record types are available in the interface. This feature helps simplify the user interface by showing only the record types that are relevant to your specific DNS needs.

To configure this feature, add the following to your config/settings.php file:

'dns' => [
    // Other DNS settings...

    // Record Type Settings
    'domain_record_types' => ['A', 'AAAA', 'CNAME', 'MX', 'NS', 'SOA', 'TXT'], // For forward zones
    'reverse_record_types' => ['PTR', 'NS', 'SOA'],                            // For reverse zones
]

For full documentation on this feature, see Record Type Customization.

New Features in v4.0.0

Enhanced Security Features

  • Multi-Factor Authentication (MFA)

    • Support for authenticator apps (TOTP)
    • Email-based verification
    • Recovery codes for account recovery
    • Configurable recovery code generation

  • Advanced Account Lockout

    • Login attempt tracking with database support
    • Configurable lockout attempts and duration
    • IP address-based tracking and lockouts
    • Whitelist and blacklist support (supports IPs, CIDRs, wildcards)

  • Password Reset System

    • Secure password reset via email
    • Configurable token lifetime and rate limiting
    • Protection against brute force attacks

  • Google reCAPTCHA Integration

    • Support for reCAPTCHA v2 and v3
    • Configurable score thresholds for v3
    • Login form protection

  • Enhanced Password Policies

    • Configurable minimum length requirements
    • Character type requirements (uppercase, lowercase, numbers, special)
    • Custom special character sets

API Management

  • API Key System
    • Generate and manage API keys for external integrations
    • Key-based authentication for API endpoints
    • Request logging and monitoring
    • API documentation endpoints

User Experience Improvements

  • Theming System

    • Light and dark mode support
    • Customizable theme base paths
    • Theme selection per user preference

  • User Preferences

    • Personalized user settings storage
    • Individual user customization options

  • Enhanced Interface Options

    • Display full names instead of usernames in zone lists
    • Improved reverse zone sorting (natural or hierarchical)
    • PowerDNS server status integration
    • Database consistency checks page
    • Email template previews
    • Display hostname only in zone edit forms (strips zone suffix)
    • Prevent duplicate PTR records in batch operations
    • Configurable display of generated passwords
    • PHP error display control for development/production

  • Advanced Workflow Configuration

    • Edit Conflict Resolution: Three strategies for handling concurrent edits:
      • last_writer_wins (default): Latest changes override previous ones
      • only_latest_version: Prevent editing of outdated versions
      • 3_way_merge: Attempt to merge conflicting changes

Lookup and Integration Features

  • WHOIS Lookup

    • Built-in WHOIS query functionality
    • Configurable WHOIS servers
    • Socket timeout controls
    • Admin-only access controls

  • RDAP Lookup

    • Registration Data Access Protocol support
    • HTTP-based domain information queries
    • Configurable RDAP servers
    • Request timeout controls

Email System Enhancements

  • Multiple Transport Options
    • SMTP with authentication and encryption
    • Sendmail binary support
    • PHP mail() function
    • Configurable return paths

Zone Management Features

  • Zone Template Enhancements

    • Template Ownership Tracking: New created_by field tracks who created each template
    • Enhanced Permissions: New granular permissions system with two new permissions:
      • zone_templ_add: "User is allowed to add new zone templates"
      • zone_templ_edit: "User is allowed to edit existing zone templates"
    • Template-Zone Synchronization: New zone_template_sync table tracks sync status between templates and zones
    • Change Detection: System detects when templates need to be re-synchronized with zones
    • Template Unlinking: Ability to unlink zones from templates when needed
    • Batch Operations: Support for bulk template operations and zone updates

  • Bulk Operations Suite

    • Bulk Record Addition: Add multiple DNS records at once to existing zones
    • Bulk Zone Registration: Register multiple zones simultaneously with templates
    • Batch PTR Record Creation: Automated batch creation of reverse DNS records
    • Bulk Zone Management: Streamlined operations for managing large numbers of zones

User Management Features

  • User Agreements System
    • Version-controlled user agreements with database tracking
    • IP address and user agent logging for compliance
    • Automatic re-acceptance requirement on version changes
    • Custom agreement content per theme
    • Admin-controlled versioning and enforcement
    • Graceful handling when disabled (users bypass agreement screen)

Administrative Features

  • Advanced Administrative Tools

    • Database Consistency Checker: Automated database integrity checks and repair tools
    • Migrations Management Interface: Web-based database migration management
    • Email Template Preview System: Administrators can preview email templates before sending
    • PowerDNS Status Integration: Real-time server monitoring and status display

  • Enhanced Logging

    • Improved logging levels and types
    • Database activity logging
    • API request logging
    • Syslog integration

  • Improved PowerDNS Integration

    • Enhanced API connectivity
    • Server status monitoring
    • Better error handling

Configuration Examples

Enable MFA:

'security' => [
    'mfa' => [
        'enabled' => true,
        'app_enabled' => true,
        'email_enabled' => true,
        'recovery_codes' => 8,
    ],
],

Configure Account Lockout:

'security' => [
    'account_lockout' => [
        'enable_lockout' => true,
        'lockout_attempts' => 5,
        'lockout_duration' => 15,
        'whitelist_ip_addresses' => ['127.0.0.1', '192.168.1.0/24'],
    ],
],

Enable API with reCAPTCHA:

'api' => [
    'enabled' => true,
    'docs_enabled' => true,
],
'security' => [
    'recaptcha' => [
        'enabled' => true,
        'site_key' => 'your_site_key',
        'secret_key' => 'your_secret_key',
        'version' => 'v3',
    ],
],

Configure User Agreement System:

'user_agreement' => [
    'enabled' => true,                           // Enable user agreement system
    'current_version' => '2.0',                  // Current agreement version
    'require_on_version_change' => true,         // Force re-acceptance on version updates
],

Enable Administrative Tools:

'interface' => [
    'enable_consistency_checks' => true,        // Enable database consistency checker
    'show_pdns_status' => true,                 // Show PowerDNS server status page
],
'misc' => [
    'email_previews_enabled' => true,           // Enable email template previews
    'edit_conflict_resolution' => 'only_latest_version', // Prevent concurrent edit conflicts
],

Configure Enhanced Interface Options:

'interface' => [
    'display_hostname_only' => true,            // Strip zone suffix in edit forms
    'display_fullname_in_zone_list' => true,    // Show full names instead of usernames
    'reverse_zone_sort' => 'hierarchical',      // Use hierarchical reverse zone sorting
],
'dns' => [
    'prevent_duplicate_ptr' => true,            // Prevent duplicate PTR records in batch ops
],
'misc' => [
    'show_generated_passwords' => false,        // Hide generated passwords for security
    'display_errors' => false,                  // Disable PHP error display for production
],

Notes

  • Legacy configuration format (inc/config.inc.php) is still supported but will be removed in a future version
  • You can have both configuration files during the transition period
  • The new configuration system offers more flexibility and better organization
  • Review security settings after upgrade to take advantage of new account lockout features
  • This is a significant update that lays groundwork for future improvements
  • Consider testing in a staging environment before applying to production

Post-Upgrade Configuration

Many of the new v4.0.0 features require additional configuration to enable. Here are the key areas to configure after upgrading:

Security Features Configuration

User Management Features

  • User Agreement System: Complete setup guide in User Agreements
  • User Preferences System: Individual user customization options (automatically available once upgraded)

Communication Features

External Services Integration

API and Development Features

For detailed information about all new settings and options, refer to config/settings.defaults.php which contains comprehensive documentation in comments.