Upgrading to Version 4.2.0

Overview

Version 4.2.0 introduces group-based permissions, a module system for extensible functionality, zone file import/export, new API v2 endpoints, and numerous improvements to Docker deployments.

Key Changes

New Features

• Group-Based Permissions (Issue #480): User groups with permission templates, group-zone ownership, and audit logging
• Module System: Pluggable architecture for extending Poweradmin functionality with dynamic routing and capability checks
• Zone File Import/Export (Issue #986): Import and export zones in standard BIND zone file format, including import-into-existing-zone with conflict resolution strategies
• API v2 Zone Templates: Full CRUD endpoints for managing zone templates via API
• API v2 Zone Owners: Manage zone ownership including batch owner assignment
• PowerDNS Zone Metadata API: Access and manage zone metadata through the PowerDNS API
• Per-Record Comments (Issue #858): Individual record comments via linking table (previously comments were per-RRset)
• MFA Enforcement Permission: New user_enforce_mfa permission for requiring MFA on specific users/groups
• New Languages: Indonesian, Korean, Swedish, Ukrainian, Vietnamese
• Collapsible Sidebar: Sidebar sections can now be collapsed for a cleaner interface
• DNSSEC CSK Info: Informational alert when adding DNSSEC keys about Combined Signing Keys
• Deprecated Record Type Warnings (Issue #1009): Visual warnings for deprecated DNS record types

Docker Improvements

• Database SSL/TLS configuration support (Issue #978)
• DB_PORT environment variable (Issue #981)
• Immutable container deployments (Issue #939)
• Environment variables for security, logging, and module configuration
• TRUSTED_CA_FILE for custom CA certificates (Issue #1065)

Bug Fixes

• Group-only zone ownership support (Issue #1042)
• Group visibility filtered by user membership (Issue #1043)
• Auth method preserved for OIDC/SAML users on edit (Issue #1064)
• OIDC group extraction from ID token when userinfo lacks them (Issue #963)
• SQLite compatibility fixes for correlated subqueries in record comments
• Custom TLD whitelist for CNAME validation (Issue #946)
• Web server detection in installer requirements check

Database Schema Update

Version 4.2.0 includes significant schema changes for group-based permissions:

New Tables

Table	Purpose
user_groups	User groups with permission templates
user_group_members	User-group membership (many-to-many)
zones_groups	Zone-group ownership (many-to-many)
log_groups	Audit log for group operations
record_comment_links	Per-record comment associations

Modified Tables

Table	Change
zones	owner column now nullable (allows group-only zone ownership)
perm_templ	New template_type column (user or group)

New Data

• Permission template renames: "DNS Editor" to "Editor", "Read Only" to "Viewer", "No Access" to "Guest"
• Group permission templates: Administrators, Zone Managers, Editors, Viewers, Guests (with template_type='group')
• Default user groups: Matching groups pre-configured with the group permission templates
• New permission: user_enforce_mfa

Upgrade Instructions

Prerequisites

• Poweradmin v4.1.0 or later
• PHP 8.2 or later (PHP 8.1 support was dropped)
• Database backup

Step 1: Backup Your Data

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

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

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

Step 2: Download and Extract

cd /tmp
wget https://github.com/poweradmin/poweradmin/archive/refs/tags/v4.2.0.tar.gz
tar -xzf v4.2.0.tar.gz
rsync -av poweradmin-4.2.0/ /var/www/poweradmin/ --exclude=config/settings.php

Step 3: Run Database Updates

MySQL/MariaDB:

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

PostgreSQL:

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

SQLite:

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

Step 4: Clear Cache and Restart

sudo systemctl restart php-fpm
# or
sudo systemctl restart apache2

Step 5: Verify

1. Log in and check the new Groups menu item in the sidebar
2. Verify existing zones still display correctly
3. Test creating a group and assigning zones to it

Breaking Changes

PHP 8.1 No Longer Supported

The minimum PHP version is now 8.2. Upgrade your PHP installation before applying this update.

Permission Template Renames

The following default permission templates have been renamed:

Old Name	New Name
DNS Editor	Editor
Read Only	Viewer
No Access	Guest

If you reference these template names in scripts or automation, update the names accordingly. The rename only affects the default templates - custom templates are unchanged.

Post-Upgrade Notes

Group-Based Permissions

Groups provide a way to manage zone access for teams:

1. Create a group with a permission template (e.g., "Zone Managers")
2. Add users to the group
3. Assign zones to the group

Users inherit permissions from their group membership in addition to their individual permission template. Zone access is granted if the user owns the zone directly OR is a member of a group that owns the zone.

Module System

Modules extend Poweradmin with additional functionality. Built-in modules include:

• Zone Import/Export: Import and export BIND zone files
• CSV Export: Export zone data as CSV
• DNS Wizards: Interactive record creation wizards
• Email Previews: Preview notification emails

Module availability can be configured via Docker environment variables or config/settings.php.

Rollback

To rollback to v4.1.0:

1. Restore your database backup
2. Restore your file backup
3. Restart web server

The new tables (user_groups, user_group_members, zones_groups, log_groups, record_comment_links) and the template_type column on perm_templ will remain in the database but are harmless if not used by the older version.