Skip to content

Upgrading to Version 4.6.0

Warning: In development. 4.6.0 is the develop branch and has no tag yet. This guide is prepared in advance and the steps below will only work once v4.6.0 is tagged and published. The latest release is v4.4.1; 4.3.x remains the stable line recommended for production.

Overview

Version 4.6.0 adds an opt-in change approval workflow: users with a change request permission file their zone edits for review instead of writing them, and reviewers approve or reject from a new Change requests page or through the API. Alongside it, secondary zones can be retrieved from their primary on demand, the SOA serial bump on unchanged saves can be turned off, and every setting is reachable from a Docker environment variable.

Nothing changes unless you turn the workflow on. See What's New in 4.6.0 for the full list.

Database Schema Update

The 4.6.0 migration adds one table and four permissions:

Change Purpose
Table zone_change_requests Stores filed change requests: the zone, requester, reason, the JSON action list with before/after rows, the reviewer, decision, the error when applying failed, and the zone file kept before an approved deletion
Permissions zone_change_request_own, zone_change_request_others Request changes to owned zones, or to any zone
Permissions zone_change_approve_own, zone_change_approve_others Review change requests for owned zones, or for any zone

The permissions are not granted to any permission template automatically. Grant them in the template editor once approval.enabled is on - see Change Requests.

The migration scripts are:

  • sql/poweradmin-mysql-update-to-4.6.0.sql
  • sql/poweradmin-pgsql-update-to-4.6.0.sql
  • sql/poweradmin-sqlite-update-to-4.6.0.sql

Run the script even if you do not plan to use the workflow, so the schema matches the release.

Upgrade Instructions

Prerequisites

  • Poweradmin v4.5.x
  • PHP 8.2 or later
  • Database backup

If you are upgrading from an older release, run the intermediate migration scripts first (4.3.0, then 4.4.0, then 4.5.0, then 4.6.0). Do not skip versions.

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.6.0.tar.gz
tar -xzf v4.6.0.tar.gz
rsync -av poweradmin-4.6.0/ /var/www/poweradmin/ --exclude=config/settings.php

Step 3: Run Database Update

MySQL/MariaDB:

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

PostgreSQL:

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

SQLite:

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

Step 4: Clear Cache and Restart

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

New Features

Change Approval Workflow

Off by default. To turn it on:

return [
    'approval' => [
        'enabled' => true,
        'require_review_for_all' => false,
    ],
    'notifications' => [
        'change_request_enabled' => false, // mail reviewers and requesters; needs mail.enabled
    ],
];

Then grant zone_change_request_* to the users who should file requests and zone_change_approve_* to the reviewers. Reviewers also need the edit permission for the zone; superusers review everything. With require_review_for_all, every change goes through review, editors and administrators included.

In Docker the variables are PA_APPROVAL_ENABLED, PA_APPROVAL_REQUIRE_REVIEW_FOR_ALL and PA_NOTIFICATION_CHANGE_REQUEST.

Two things to check before enabling it on a live installation:

  • Dynamic DNS clients cannot file requests. An update from a user whose changes to the zone need review is refused (!yours from dynamic_update.php, 403 from the API endpoint). Keep an edit permission on DDNS accounts.
  • API clients whose changes need review get 403 on the record write endpoints and have to use the change request endpoints instead.

See Change Requests.

Other changes

  • dns.bump_serial_on_unchanged_save (default true) lets an installation stop bumping the SOA serial on saves that change nothing. See DNS Settings.
  • dnssec.debug and PA_DNSSEC_DEBUG are removed; they had no effect since the pdnsutil provider was dropped.

Rollback

To roll back to v4.5.0:

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

The zone_change_requests table and the four permissions are harmless in 4.5.0 - they are simply unused. Pending change requests are not applied by the older version; decide them before rolling back or file them again afterwards.