This documentation covers Poweradmin 4.x. Some sections are still being expanded.

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 4.9+.
  • Master/Slave labels become Primary/Secondary on PowerDNS 4.5+.
  • Supermasters is renamed to Autoprimaries on PowerDNS 4.6+.
  • 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.
  • 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

None. All new features 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.2:

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

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