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 new login_attempts table
• New theming system
• Updated permission system
• Enhanced security with account lockout features
• Customizable DNS record types
• 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

Migrating from Legacy Configuration

If you're upgrading from an older version of Poweradmin (pre-4.0.0), you need to migrate your legacy configuration:

php scripts/migrate-config.php

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

Configuration Changes

Old Configuration Location

inc/config.inc.php

New Configuration Location

config/settings.php

Configuration Format

The configuration format has changed from direct variable assignments to a structured array format:

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, follow these steps:

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
4. Test the configuration

Database Schema Updates

Version 4.0.0 requires database schema updates. Run the following SQL statements for your database type:

MySQL

CREATE TABLE `login_attempts` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `user_id` int(11) NULL,
    `ip_address` varchar(45) NOT NULL,
    `timestamp` int(11) NOT NULL,
    `successful` tinyint(1) NOT NULL,
    PRIMARY KEY (`id`),
    KEY `idx_user_id` (`user_id`),
    KEY `idx_ip_address` (`ip_address`),
    KEY `idx_timestamp` (`timestamp`),
    CONSTRAINT `fk_login_attempts_users`
        FOREIGN KEY (`user_id`) REFERENCES `users` (`id`)
        ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

PostgreSQL

CREATE TABLE login_attempts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NULL,
    ip_address VARCHAR(45) NOT NULL,
    "timestamp" INTEGER NOT NULL,
    successful BOOLEAN NOT NULL,
    CONSTRAINT fk_login_attempts_users
        FOREIGN KEY (user_id) REFERENCES users(id)
        ON DELETE SET NULL
);

CREATE INDEX idx_login_attempts_user_id ON login_attempts(user_id);
CREATE INDEX idx_login_attempts_ip_address ON login_attempts(ip_address);
CREATE INDEX idx_login_attempts_timestamp ON login_attempts("timestamp");

SQLite

CREATE TABLE login_attempts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NULL,
    ip_address VARCHAR(45) NOT NULL,
    timestamp INTEGER NOT NULL,
    successful BOOLEAN NOT NULL,
    FOREIGN KEY (user_id) REFERENCES users(id)
        ON DELETE SET NULL
);

CREATE INDEX idx_login_attempts_user_id ON login_attempts(user_id);
CREATE INDEX idx_login_attempts_ip_address ON login_attempts(ip_address);
CREATE INDEX idx_login_attempts_timestamp ON login_attempts(timestamp);

Post-Upgrade Tasks

1. Check for any new required settings
2. Test functionality thoroughly
3. Update custom scripts that might reference the old configuration format

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.

Enhanced Security with Account Lockout

Version 4.0.0 includes a new security feature to protect against brute force attacks:

• Login attempt tracking system with database support (using the new login_attempts table)
• Configurable account lockout after failed login attempts
• IP address-based tracking and lockouts
• Whitelist and blacklist support for IP addresses (includes CIDR support)

To configure these security features, add the following to your config/settings.php file:

'security' => [
    // Maximum number of failed attempts before lockout
    'max_login_attempts' => 5,

    // Time window in minutes for counting failed attempts
    'login_attempt_timeframe' => 30,

    // Lockout duration in minutes after max failed attempts
    'lockout_duration' => 30,

    // IP address whitelist (never locked out)
    'ip_whitelist' => ['127.0.0.1', '192.168.1.0/24'],

    // IP address blacklist (always blocked)
    'ip_blacklist' => [],
],

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

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