Upgrading to Version 4.4.0¶

Overview¶

Version 4.4.0 focuses on adapting Poweradmin to the version of PowerDNS it is connected to. Poweradmin now detects the backend version and adjusts the UI accordingly - record types, metadata kinds, zone-kind labels, and entire features (Views & Networks, DNSSEC PEM key import/export, Producer/Consumer zones) light up or stay hidden based on what your PowerDNS instance actually supports.

This release also lands a long-requested default zone template, per-user display_hostname_only, a new zone_ownership_mode setting, configurable PowerDNS API timeout, audit log access for zone owners, and eight new locales.

Database Schema Update¶

The 4.4.0 migration adds one column to the zone_templ table:

Column	Type	Purpose
`is_default`	tinyint(1)	Marks a single template as the system-wide default on the add-zone form

Only one template should carry is_default=1 at a time. Uniqueness is enforced at the application layer.

The migration scripts are:

sql/poweradmin-mysql-update-to-4.4.0.sql
sql/poweradmin-pgsql-update-to-4.4.0.sql
sql/poweradmin-sqlite-update-to-4.4.0.sql

The change is small, additive, and safe for both SQL and API backend installs.

Upgrade Instructions¶

Prerequisites¶

Poweradmin v4.3.0 or later
PHP 8.2 or later
Database backup

If you are upgrading from 4.2.x, run the 4.3.0 migration script first, then the 4.4.0 migration script. Do not skip intermediate 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.4.0.tar.gz
tar -xzf v4.4.0.tar.gz
rsync -av poweradmin-4.4.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.4.0.sql

PostgreSQL:

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

SQLite:

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

Step 4: Clear Cache and Restart¶

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

New Features¶

PowerDNS Capability Detection¶

Poweradmin queries the connected PowerDNS server's version on first use and adapts the UI to match what that version supports.

What's gated by detected version:

Record types unsupported by your PowerDNS version are hidden from the add/edit/bulk-import forms.
Metadata kinds unsupported by your PowerDNS version show a "Requires X.Y+" hint instead of failing silently.
Last-modified record column appears on PowerDNS 5.0+, and only with the LMDB backend.
Master/Slave labels become Primary/Secondary on PowerDNS 4.5+.
Supermasters is renamed to Autoprimaries on PowerDNS 4.6+ (PowerDNS itself renamed the concept in 4.5.0; 4.6 added the API Poweradmin detects).
Producer/Consumer zone kinds become available on PowerDNS 4.7+.
Views & Networks management appears on PowerDNS 5.0+ (see below).
DNSSEC PEM key import/export is available on PowerDNS 4.7+ (see below).

The detected version is shown on the dashboard. The detection result is cached per user with a TTL so the capability gates refresh after PowerDNS upgrades without requiring a restart.

On DB-backed installs without API access, Poweradmin uses a permissive capability set so existing functionality keeps working when the API isn't reachable.

Views & Networks (PowerDNS 5.0)¶

PowerDNS 5.0 introduced views (named sets of zones) and networks (CIDR-to-view mappings). Both can now be managed from the Poweradmin UI on installations connected to PowerDNS 5.0+. The corresponding dashboard tiles are gated on the API backend; SQL-mode installs do not see them.

DNSSEC PEM Key Import / Export¶

On PowerDNS 4.7+, you can import existing PEM-encoded private keys into a zone and export the active keys back out. This makes it possible to migrate signed zones between PowerDNS instances or recover from key material kept outside Poweradmin.

The CSK guidance alert that was previously shown on the DNSSEC page is now scoped to legacy pre-PowerDNS-4.0 servers, where it actually applies.

DS and DNSKEY records can be copied to clipboard from the DNSSEC display.

Manual Sync from PowerDNS¶

A Sync from PowerDNS button is now available on the Forward Zones page. This triggers an immediate zone-sync against the PowerDNS API, useful after creating zones directly in PowerDNS (via pdnsutil or another tool) when you don't want to wait for the next scheduled sync.

The sync action requires a CSRF-protected POST. Sync runs are also recorded inside sync() itself, preventing double-reconciliation when multiple page loads race.

When the PowerDNS API is unreachable, the dashboard now surfaces the failure on every admin page with HTTP status and actionable guidance, instead of a stack trace. Cached zone counts are retained so the dashboard doesn't suddenly show zero zones during a transient outage.

Default Zone Template¶

You can now mark one zone template as the system-wide default on the add-zone form.

The default is stored in the new zone_templ.is_default column.
It can also be configured via dns.default_zone_template in config/settings.php (template id as int, or template name as string; null means no default).
Only one template can be the default at a time.

return [
    'dns' => [
        'default_zone_template' => 'default-internal', // or a numeric id, or null
    ],
];

Zone Audit Log for Owners¶

Zone owners can now read the audit log for their own zones. Previously this was restricted to administrators. Owners see only entries for zones they own (directly or via group ownership).

Zone Ownership Mode¶

A new dns.zone_ownership_mode setting controls which ownership models are exposed:

return [
    'dns' => [
        'zone_ownership_mode' => 'both', // 'both', 'users_only', or 'groups_only'
    ],
];

both (default) - users and groups can both own zones, matching prior behavior.
users_only - only direct user ownership is shown. Group-ownership UI is hidden.
groups_only - only group ownership is shown. Direct-user ownership UI is hidden.

This is a UI gating setting, not a destructive switch. Existing ownership records are preserved; the modes just hide one model or the other from the forms.

Per-User `display_hostname_only`¶

The display_hostname_only setting, which strips the zone suffix from record names in the zone edit form, is now also a per-user preference. Users can flip it independently of the site-wide default in their account preferences.

The site-wide dns.display_hostname_only continues to act as the default for users who haven't set a personal preference.

Configurable PowerDNS API Timeout¶

The PowerDNS API request timeout is now configurable:

return [
    'pdns_api' => [
        'timeout' => 10, // seconds; default 10
    ],
];

GET requests are retried once on transient PowerDNS API failures (network errors, 5xx responses). Write requests are not retried.

New Locales¶

Eight new locales were added: Serbian, Hungarian, Slovak, Romanian, Croatian, Latvian, Estonian, and Finnish. They are available in the installer language picker and the runtime locale selector.

OIDC and Web Proxies¶

OIDC endpoint discovery now honors the HTTPS_PROXY and http_proxy environment variables. Deployments behind a web proxy can reach external OIDC providers without additional configuration.

Security and Audit¶

Forwarded-IP headers (X-Forwarded-For, X-Real-IP, Client-IP) are only honored when the upstream peer is on a private or loopback address. Direct-internet deployments stop trusting client-supplied headers. This was also shipped in 4.2.3 and 4.3.2.
Emailed URLs no longer auto-detect from the request host. Password reset and username recovery emails are built from interface.application_url instead of Host/X-Forwarded-*. This closes a host-header injection path where a forged Host could redirect the reset link to an attacker-controlled domain. See Breaking Changes below for the operator-facing impact.
DNSSEC sign events are now logged in the zone activity feed alongside unsign events.
DNSSEC authorization for sign/unsign requires both full edit and ownership.

Breaking Changes¶

`interface.application_url` is now required for password reset emails¶

If security.password_reset.enabled = true and interface.application_url is empty, the forgot-password endpoint accepts the request but stops short of sending mail and logs Password reset email NOT sent: interface.application_url must be configured to build a trustworthy reset link. Set application_url to the full public URL of the install before upgrading:

return [
    'interface' => [
        'application_url' => 'https://dns.example.com/poweradmin',
    ],
];

Username recovery continues to send emails when application_url is empty; the email omits the login link but still includes the username. See Security Policies and Username Recovery for the full details.

Warning: Later 4.2.x, 4.3.x, 4.4.x and 4.5.0 releases extend this requirement to OIDC, SAML and OIDC logout, which now refuse to build IdP-bound URLs rather than deriving a host from the request. See Upgrading to 4.5.0.

API and client-facing changes¶

HTTP status codes on existing user and zone endpoints are now accurate: missing templates or transfer targets return 404, conflicts (duplicate template names, deleting the last super admin) return 409, and internal failures return 500 where a blanket 400 was returned before. Error message strings are unchanged. Clients that branch on status codes should be reviewed.
PUT /permission_templates/{id} without a permissions field now leaves the template's permissions untouched. Send an explicit empty array to clear them.
Removing a zone's last owner (user or group) through the API returns 400 instead of leaving the zone unowned. Reassign with add-then-remove.
Dynamic DNS responses follow the dyndns2 convention: unchanged updates return nochg (was good) and authentication failures return badauth (was badauth2). Standard clients such as ddclient handle both; custom scripts matching the old literals need updating.
API user creation without an explicit perm_templ assigns a minimal template instead of falling back to the Administrator template, and supplying perm_templ requires the template-edit permission.

Custom themes¶

Themes that fork edit.html must re-sync it from this release. Zone saves depend on the hidden form_complete and per-row _complete marker fields; a fork without them saves no records and shows a misleading max_input_vars warning.

Other changes¶

All other new features in 4.4.0 are additive or opt-in:

The schema migration adds one nullable-friendly column.
New settings (zone_ownership_mode, default_zone_template, pdns_api.timeout) have safe defaults that match prior behavior.
Capability-gated UI changes only show or hide elements based on the connected PowerDNS version.

Rollback¶

To roll back to v4.3.4:

Restore your database backup.
Restore your file backup.
Restart the web server.

The new zone_templ.is_default column is harmless in earlier versions - it's simply unused.