This documentation covers Poweradmin 4.0.x and 4.1.x. Some sections are still being expanded.

Upgrading to Version 4.1.0

Overview

Version 4.1.0 is a major feature release that introduces federated authentication (OIDC/SAML), DNS record wizards, improved permission management, and custom theming capabilities. It also includes critical security fixes, numerous bug fixes, and improvements to existing features.

Key Changes

New Features

Federated Authentication: OpenID Connect (OIDC) and SAML 2.0 support with automatic user provisioning
DNS Wizards: Interactive wizards for creating DMARC, SPF, DKIM, CAA, TLSA, and SRV records
Zone Deletion Permissions: Separate permissions for zone deletion, independent from edit permissions
Permission Templates: Pre-configured templates (Zone Manager, DNS Editor, Read Only, No Access)
Custom CSS Theming: Support for custom stylesheets that survive application updates
Username Recovery: Self-service username recovery via email
API Key Management: New permission for users to manage their own API keys

Security & Bug Fixes

Critical Security Fixes: MFA bypass vulnerability patched (affects SQL, LDAP, OIDC, and SAML authentication)
Email System Improvements: Fixed SMTP TLS/STARTTLS handling and long line issues
DNS Validation Enhancements: Improved support for DKIM records, SRV records, LUA scripts, and NAPTR records
API Improvements: Better error handling, optional pagination, and Basic Auth support
Database Compatibility: Enhanced PostgreSQL and SQLite compatibility
UI/UX Fixes: Sorting improvements, form handling fixes, and dark mode visibility fixes

Security Updates

Critical Security Fix: MFA Bypass (Issue #813)

Severity: High Affected Versions: 4.0.0 through 4.0.3 Fixed in: 4.0.4+

A critical vulnerability was discovered that allowed bypassing multi-factor authentication in certain scenarios:

SQL and LDAP Authentication: MFA verification could be bypassed (commit 534198bb9)
OIDC and SAML Authentication: Similar MFA bypass issue (commit 4cbc1b1ed)

Action Required: If you're running v4.0.0 through v4.0.3 with MFA enabled, upgrade immediately to v4.0.4 or later.

Other Security Improvements

Permission Enforcement: Non-superusers can no longer modify superuser accounts (commit 627e10bb7)
Docker Image Security: Base packages updated to resolve security vulnerabilities
Boolean Type Safety: Fixed boolean type handling in PostgreSQL for MFA comparisons

New Features in Detail

Federated Authentication (OIDC & SAML)

Version 4.1.0 introduces support for enterprise Single Sign-On (SSO) through OpenID Connect and SAML 2.0 protocols.

OpenID Connect (OIDC) supports:

Google, Microsoft Azure AD, Okta, Keycloak, Auth0, Authentik
Automatic user provisioning on first login
Group-based permission template mapping
Account linking for existing users

SAML 2.0 supports:

Microsoft Azure AD, Okta, Auth0, Keycloak
Service Provider (SP) initiated SSO
Automatic user provisioning with attribute mapping
Group-based permission assignment

See the OIDC Configuration and SAML Configuration guides for setup instructions.

DNS Record Wizards

Interactive wizards help create complex DNS records with validation and best-practice defaults:

Wizard	Purpose
DMARC	Email authentication policy records
SPF	Sender Policy Framework records
DKIM	DomainKeys Identified Mail selector records
CAA	Certificate Authority Authorization records
TLSA	DANE/TLSA records for TLS certificate pinning
SRV	Service location records

Access wizards from the zone edit page or the DNS Wizards menu. See DNS Wizards for details.

Zone Deletion Permissions

Zone deletion is now controlled by separate permissions, allowing finer-grained access control:

Permission	Description
`zone_delete_own`	Delete zones the user owns
`zone_delete_others`	Delete zones owned by other users

Migration note: Users with existing zone_content_edit_own or zone_content_edit_others permissions are automatically granted the corresponding delete permissions during upgrade.

Permission Templates

Four new pre-configured permission templates are included:

Template	Use Case
Zone Manager	Full self-service zone management (create, edit, delete, templates)
DNS Editor	Edit records but not SOA/NS (suitable for delegated management)
Read Only	View-only access with search capability (auditors, viewers)
No Access	No permissions (inactive accounts, pending assignment)

Custom CSS Theming

Customize the Poweradmin interface with CSS files that persist across upgrades:

Copy example files in templates/default/style/
Edit the CSS files with your customizations
Changes are automatically loaded for the corresponding theme

cp custom_light.css.example custom_light.css
cp custom_dark.css.example custom_dark.css

See Custom CSS for details.

Username Recovery

Users can recover forgotten usernames via email:

Click "Forgot Username?" on the login page
Enter the email address associated with the account
Receive an email with the username(s) linked to that address

Requires email configuration. See Mail Configuration.

Breaking Changes

URL Rewriting Now Required

Version 4.1.0 switched from query-parameter URLs (e.g., index.php?page=login) to clean URLs (e.g., /login). This means URL rewriting is now required for your web server.

Apache users must ensure:

mod_rewrite is enabled: a2enmod rewrite && systemctl restart apache2
AllowOverride All is set in the VirtualHost configuration
The .htaccess file from the v4.1.0 release is present in the Poweradmin root directory

Nginx users must ensure:

The try_files directive routes requests to index.php — use the nginx.conf.example from master

Caddy users must ensure:

The try_files directive is configured — use the caddy.conf.example from master

Warning: If you see a 404 error when Poweradmin redirects to /login, your web server is not rewriting URLs to index.php. This is the most common issue when upgrading from v4.0.x to v4.1.0. See the troubleshooting section below.

No Configuration Breaking Changes

Version 4.1.0 is fully backward compatible with v4.0.0 configuration format. No config/settings.php changes are required.

Database Schema Update

Version 4.1.0 includes significant database schema changes:

Primary key added to records_zone_templ table (MySQL InnoDB Cluster compatibility)
New tables: oidc_user_links, saml_user_links, username_recovery_requests
New column: auth_method on users table
New permissions: api_manage_keys (65), zone_delete_own (67), zone_delete_others (68)
Performance indexes added to multiple tables
Permission templates: Zone Manager, DNS Editor, Read Only, No Access

Upgrade Instructions

Prerequisites

You must be running Poweradmin v4.0.0 or later
If upgrading from v3.x, first upgrade to v4.0.0
Ensure you have database backup before proceeding

Step 1: Backup Your Data

Always backup your database and files before upgrading.

# Example MySQL backup
mysqldump -u username -p poweradmin_db > poweradmin_backup_$(date +%Y%m%d).sql

# Example PostgreSQL backup
pg_dump -h localhost -U username poweradmin_db > poweradmin_backup_$(date +%Y%m%d).sql

# Example SQLite backup
cp /path/to/poweradmin.db /path/to/poweradmin_backup_$(date +%Y%m%d).db

Step 2: Download and Extract

Download the latest v4.1.0 release from GitHub
Extract the archive to a temporary location
Replace files in your Poweradmin installation directory

# Example upgrade process
cd /tmp
wget https://github.com/poweradmin/poweradmin/archive/refs/tags/v4.1.0.tar.gz
tar -xzf v4.1.0.tar.gz
rsync -av poweradmin-4.1.0/ /var/www/poweradmin/ --exclude=config/settings.php

Step 3: Run Database Updates

Version 4.1.0 includes significant database schema changes:

Primary key added to records_zone_templ table
New tables for OIDC/SAML authentication
New auth_method column on users table
New permissions for API key management and zone deletion
Performance indexes on multiple tables
Username recovery request tracking table

Apply the 4.1.0 migration:

For MySQL/MariaDB:

mysql -u username -p poweradmin_db < sql/poweradmin-mysql-update-to-4.1.0.sql

For PostgreSQL:

psql -h localhost -U username -d poweradmin_db -f sql/poweradmin-pgsql-update-to-4.1.0.sql

For SQLite:

sqlite3 /path/to/poweradmin.db < sql/poweradmin-sqlite-update-to-4.1.0.sql

Note: If you're upgrading from v4.0.0-4.0.3, you may also need to apply the v4.0.2 migration if not already applied. Check if the password_reset_tokens table has a default value for the used field:

-- MySQL/MariaDB
SHOW CREATE TABLE password_reset_tokens;

-- PostgreSQL
\d password_reset_tokens

-- SQLite
.schema password_reset_tokens

If the used field doesn't have DEFAULT 0, apply the 4.0.2 migration first:

# MySQL/MariaDB
mysql -u username -p poweradmin_db < sql/poweradmin-mysql-update-to-4.0.2.sql

# PostgreSQL
psql -h localhost -U username -d poweradmin_db -f sql/poweradmin-pgsql-update-to-4.0.2.sql

# SQLite
sqlite3 /path/to/poweradmin.db < sql/poweradmin-sqlite-update-to-4.0.2.sql

Step 4: Clear Cache and Restart Services

# Clear PHP opcache (if applicable)
sudo systemctl restart php-fpm
# or
sudo systemctl restart apache2

# Clear any application cache
rm -rf cache/* tmp/*

Step 5: Verify the Upgrade

Check the web interface: Ensure Poweradmin loads without errors
Test authentication: Verify login works, especially if using MFA
Test core functionality: Try creating/editing a DNS zone
Review logs: Check web server and PHP error logs for any issues

Detailed Changelog

Security Fixes (v4.0.1 - v4.0.4)

[Critical] Fix MFA bypass in SQL and LDAP authentication (#813)
[Critical] Fix MFA bypass in OIDC and SAML authentication (#813)
Fix non-superusers ability to modify superuser accounts
Enhanced boolean type safety in PostgreSQL MFA comparisons
Docker image security updates

Email System (v4.0.1 - v4.0.4)

v4.0.3: Fix email rejection due to long lines, closes #798 Added proper line wrapping for email content to comply with RFC 5322
v4.0.3: Ensure logger is always initialized (commit 056b3f921)
v4.0.3: Add comprehensive debug and operational logging
v4.0.3: Fix SMTP authentication and response parsing issues
v4.0.2: Remove invalid SMTP headers causing server rejections, closes #774
v4.1.0: Fix TLS/STARTTLS connection handling, closes #861 Properly handle TLS encryption modes in SMTP connections

DNS Record Validation (v4.0.1 - v4.0.4)

v4.0.1: Remove 255-byte TXT record validation to support long DKIM records, closes #809 DKIM records can now exceed 255 characters as per PowerDNS specifications
v4.0.1: Use consistent FQDN handling across record creation flows, closes #814
v4.0.2: Allow multiple instances of SPF mechanisms (commit 372764f92)
v4.0.2: Correct SRV record validation to match PowerDNS format requirements, closes #755
v4.0.2: Support record type prefixes in LUA validator, closes #770
v4.0.2: Improve IP address validation, closes #794
v4.0.4: NAPTR Record compatibility with ETSI TS 123 003 (#811)

API Improvements (v4.0.1 - v4.0.4)

v4.0.1: Update SOA serial on all record operations, closes #804
v4.0.1: Make pagination optional for zones and users endpoints, closes #803
v4.0.2: Resolve routing and method validation issues, related to #767
v4.0.2: Handle missing optional fields gracefully, closes #818
v4.0.3: Add Basic Auth support for PowerDNS metrics endpoint, closes #800
v4.0.4: Resolve Basic Auth TypeError when LDAP authentication is enabled, closes #799

UI/UX Fixes (v4.0.1 - v4.0.4)

v4.0.1: Correct checkbox handling in multi-record add form, closes #807
v4.0.2: Enable sorting by owner, id, and disabled status, closes #781
v4.0.2: Clear form data and errors when switching between zones, closes #769
v4.0.2: Disable browser autofill for user creation, closes #782
v4.0.2: Improve error handling for validation failures, closes #764
v4.0.3: Remove color classes preventing dark mode visibility, closes #801
v4.0.4: Reload page instead of submitting empty search form, closes #815
v4.1.0: Display latency metrics in microseconds (μs), closes #915
v4.1.0: Gracefully handle removed legacy themes with fallback, closes #899

Database & Zone Management (v4.0.1 - v4.1.0)

v4.1.0: Add primary key to records_zone_templ table for MySQL InnoDB Cluster compatibility, closes #906
v4.0.1: Exclude reverse zones from forward zone listings (commit a21f35f03)
v4.0.1: Allow slave zone creation with delegation NS records, closes #802
v4.0.2: Exclude invalid database entries from queries, closes #758
v4.0.2: Bind LIMIT and OFFSET as integers in filtered record queries, closes #810
v4.0.2: Enforce integer binding for pagination parameters in all queries
v4.0.2: Standardize boolean parameter binding for MySQL strict mode compatibility
v4.0.2: Move reverse zone filtering from PHP to database level, closes #751
v4.0.2: Correct pagination calculation when filters are applied, closes #748
v4.0.2: Fix password reset token default value (4.0.2 migration)
v4.0.2: Include used field in password reset token creation

Authentication & User Management (v4.0.1 - v4.0.4)

v4.0.2: Correct recovery code input validation length, closes #784
v4.0.2: Add missing LDAP section in Add User form, closes #750
v4.0.2: Resolve user preference persistence and loading issues
v4.0.2: Resolve config summary display when using custom config files
v4.0.2: Fix configuration validation errors in migration from v3.9.2 to v4.0.0, resolves #754

Docker Support (v4.0.1 - v4.0.4)

v4.0.2: Resolve container startup validation logic, closes #766
v4.0.3: Add MySQL separate PowerDNS database configuration support
v4.0.4: Add LDAP extension for LDAP authentication support
v4.1.0: Fix config generation from environment variables (#876)
v4.1.0: Capture admin user insert result correctly

Bug Fixes & Stability (v4.0.1 - v4.0.4)

v4.0.2: Handle null ptrZoneId in RecordCommentSyncService PTR record updates, closes #760
v4.0.2: Resolve test failures and improve type conversion handling
v4.0.4: Cast uid to int in DeleteUserController

Configuration Changes

No Breaking Configuration Changes

Version 4.1.0 maintains full compatibility with v4.0.0 configuration format. No configuration file changes are required.

Recommended Configuration Reviews

If you use any of the following features, review your configuration:

Email Configuration

With the improved SMTP handling, verify your email transport settings in config/settings.php:

'mail' => [
    'transport' => 'smtp',  // or 'sendmail', 'mail'
    'smtp' => [
        'host' => 'smtp.example.com',
        'port' => 587,
        'encryption' => 'tls',  // Options: 'tls', 'ssl', null
        'auth' => true,
        'username' => 'user@example.com',
        'password' => 'your-password',
    ],
    'debug' => false,  // Set to true to enable detailed logging
],

Note: The TLS/STARTTLS handling has been fixed in v4.1.0. If you experienced email issues in earlier versions, they should now be resolved.

PowerDNS API Configuration

If you use PowerDNS metrics or API features, you can now use Basic Auth:

'pdns' => [
    'api_url' => 'http://localhost:8081/api/v1',
    'api_key' => 'your-api-key',
    'server_id' => 'localhost',
    'metrics' => [
        'enabled' => true,
        'basic_auth' => [
            'username' => 'admin',
            'password' => 'your-password',
        ],
    ],
],

Enhanced DNS Record Validation

DKIM and long TXT records are now properly supported. No configuration changes needed, but you can now add DKIM records without worrying about the 255-character limit.

Post-Upgrade Verification

1. Test MFA (If Enabled)

If you have MFA enabled, test the authentication flow:

Log out of Poweradmin
Log in with username and password
Verify MFA prompt appears
Complete MFA verification
Ensure you're successfully logged in

2. Test Email Functionality

If you use email features (password reset, MFA codes):

Test password reset flow
Verify emails are delivered
Check email formatting is correct
Review SMTP logs if using external mail server

3. Test DNS Record Operations

Create a test zone and verify:

Create various record types (A, AAAA, MX, TXT, SRV, NAPTR)
Test long TXT records (DKIM records with 500+ characters)
Verify SRV record formatting
Test record sorting functionality

4. Test API (If Enabled)

If you use the Poweradmin API:

Test authentication with API keys
Verify pagination works (both with and without limit parameters)
Test Basic Auth for PowerDNS metrics endpoint
Check zone and record CRUD operations

Troubleshooting

MFA Still Not Working After Upgrade

If MFA verification fails after upgrading:

Clear browser cache and cookies
Clear PHP session files: rm -rf /var/lib/php/sessions/*
Restart PHP-FPM: sudo systemctl restart php-fpm
Check database permissions on user_mfa table

Email Sending Fails

If emails aren't being sent:

Enable email debugging in config/settings.php: 'mail' => ['debug' => true]
Check PHP error logs for SMTP errors
Verify SMTP credentials and server settings
Test SMTP connection: telnet smtp.example.com 587
Ensure your server's IP is not blacklisted

Database Performance Issues

If you experience slow queries:

Check database indexes are present:

-- MySQL
SHOW INDEX FROM zones;
SHOW INDEX FROM records;

-- PostgreSQL
\di

Analyze query performance: Enable slow query log
Consider adding indexes for frequently filtered columns

Theme Not Found Error

If you see "Theme not found" errors after upgrade:

This likely means you had a custom theme in inc/config.inc.php that no longer exists
The fallback mechanism in v4.1.0 should handle this automatically
Check config/settings.php and ensure theme is set to a valid theme: 'ignite' or 'spark'

If you see a 404 error when accessing Poweradmin after upgrading to v4.1.0:

Apache: Verify mod_rewrite is enabled:

apache2ctl -M | grep rewrite
# If not listed, enable it:
a2enmod rewrite
systemctl restart apache2

Apache: Verify AllowOverride All is set in your VirtualHost:

<Directory /path/to/poweradmin>
    AllowOverride All
</Directory>

Apache: Verify the .htaccess file is present in the Poweradmin root directory and is the version from v4.1.0 (not v4.0.x)
Nginx: Verify your configuration includes the try_files directive:

location / {
    try_files $uri $uri/ /index.php$is_args$args;
}

All servers: Check error logs for more details:

# Apache
tail -f /var/log/apache2/error.log

# Nginx
tail -f /var/log/nginx/error.log

Permission Issues After Upgrade

If you see permission denied errors:

# Fix file permissions
sudo chown -R www-data:www-data /var/www/poweradmin
sudo chmod -R 755 /var/www/poweradmin
sudo chmod -R 775 /var/www/poweradmin/cache
sudo chmod -R 775 /var/www/poweradmin/tmp

Rollback Instructions

If you need to rollback to your previous version:

Restore your database backup
Restore your file backup
Clear PHP session files and restart web server

Note: If you need to rollback to v4.0.x, the records_zone_templ table will have an extra id column from the 4.1.0 migration. This is harmless and doesn't affect functionality. If you applied the 4.0.2 migration, you can keep it applied as it's a minor fix.

Upgrading from Older Versions

From v3.x

You must first upgrade to v4.0.0 before upgrading to v4.1.0.

From v4.0.0 through v4.0.3

Follow the standard upgrade process in this document. Pay special attention to:

The MFA security fix (critical if you use MFA)
Email configuration if you experienced delivery issues
Database migration to 4.0.2 if you haven't applied it

From v4.0.4 or v4.0.5

Upgrading from v4.0.4 or v4.0.5 requires replacing the files and running the 4.1.0 database migration, which adds new tables and permissions for OIDC/SAML authentication and zone deletion.

Known Issues

Users upgrading from v4.0.x may encounter a 404 error when Poweradmin redirects to /login. This happens because v4.1.0 uses clean URLs that require URL rewriting to be properly configured on the web server. See the Breaking Changes section above for the fix.

If you encounter any other issues, please report them on GitHub Issues.

Additional Resources

Support

If you encounter issues during the upgrade:

Check the GitHub Issues page
Review the error logs for specific error messages
Ensure all prerequisites are met for v4.1.0
Join the community discussion on GitHub Discussions

Summary of Version History

v4.0.0 (July 2025): Major release with MFA, API keys, user agreements, new config system
v4.0.1 (August 2025): Bug fixes for DNS validation, zones, API pagination
v4.0.2 (October 2025): Database compatibility fixes, validation improvements
v4.0.3 (October 2025): Email system fixes, PowerDNS metrics, dark mode fixes
v4.0.4 (November 2025): Critical MFA security fix, LDAP support in Docker
v4.0.5 (January 2026): PTR duplicate warnings, per-record comments refactor, minor fixes
v4.1.0 (Current): OIDC/SAML authentication, DNS wizards, zone deletion permissions, custom CSS theming, username recovery

PHP Version Notice

Poweradmin 4.1.x is the last version to support PHP 8.1. Starting with version 4.2.x, the minimum required PHP version will be 8.2. If you are running PHP 8.1, plan your PHP upgrade before moving to 4.2.x.

For a detailed history of all changes, see the GitHub commit history.