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

Upgrading to Version 4.3.0

Overview

Version 4.3.0 introduces full PowerDNS REST API backend support. Poweradmin can now operate without direct access to the PowerDNS database, communicating entirely through the PowerDNS API. This enables deployments where the PowerDNS database is inaccessible (cloud-hosted PowerDNS, restricted network environments, or API-first architectures).

Key Changes

PowerDNS API Backend Mode (Issue #658)

Previously, Poweradmin required direct database access to both the Poweradmin database and the PowerDNS database. With API backend mode, Poweradmin only needs its own database and a network connection to the PowerDNS API.

How it works:

  • Zone and record operations are performed via the PowerDNS REST API instead of SQL queries
  • Zone metadata (name, type, master) is cached in the local zones table for fast lookups
  • A background sync service keeps the local cache in sync with zones created outside Poweradmin
  • All existing features (ownership, groups, permissions, templates) work the same way

When to use API backend mode:

  • PowerDNS database is not accessible from the Poweradmin server
  • Running PowerDNS as a managed service or in a separate network
  • Prefer not to give Poweradmin direct database access to PowerDNS
  • Multi-server setups where the API is the standard integration point

Database Schema Update

The 4.3.0 migration adds columns to the zones table for caching zone metadata locally:

Column Type Purpose
zone_name VARCHAR(255) Zone name (cached from PowerDNS API)
zone_type VARCHAR(8) Zone type: Master, Slave, Native (cached)
zone_master VARCHAR(255) Master server address for slave zones (cached)

The domain_id column is also made nullable, since API-mode zones don't require a PowerDNS domain ID.

A unique index idx_zones_zone_name is created on zone_name for fast lookups.

These schema changes are safe for existing SQL-mode installations - the new columns are nullable and unused when running in SQL backend mode.

Separate API Logs Table

API key events (create, edit, delete, regenerate, toggle) are now logged to a dedicated log_api table instead of log_users. The migration automatically moves existing API key log entries to the new table.

A new API Logs page is available under Tools in the navigation menu.

Login events now also include auth_method (sql, ldap, oidc, saml) for audit visibility.

The record_comment_links.record_id column has been widened from INT to VARCHAR(3072) (MySQL) / VARCHAR(4096) (PostgreSQL) / TEXT (SQLite). This supports API-mode encoded string record IDs (base64url-encoded name+type+content composites).

Migration scripts handle this automatically. No manual action needed for existing installations.

Upgrade Instructions

Prerequisites

  • Poweradmin v4.2.0 or later
  • PHP 8.2 or later
  • 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.3.0.tar.gz
tar -xzf v4.3.0.tar.gz
rsync -av poweradmin-4.3.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.3.0.sql

PostgreSQL:

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

SQLite:

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

Step 4: Clear Cache and Restart

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

Switching to API Backend Mode

If you want to switch from SQL backend to API backend mode:

Prerequisites

  1. PowerDNS API must be enabled in your PowerDNS configuration:
api=yes
api-key=YOUR_API_KEY
webserver=yes
webserver-port=8081
webserver-address=127.0.0.1
  1. Verify the API is reachable:
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:8081/api/v1/servers/localhost

Configuration

New Installation

The installer (Step 4) now offers a choice between "Database" and "API" backend. Selecting API will prompt for the PowerDNS API URL and key, and will skip PowerDNS database configuration.

Existing Installation

Update your config/settings.php:

return [
    'dns' => [
        'backend' => 'api',   // Change from 'sql' to 'api'
        // ... existing dns settings (hostmaster, ns1, ns2, etc.)
    ],

    // PowerDNS API settings (required for API mode)
    'pdns_api' => [
        'url' => 'http://localhost:8081',
        'key' => 'YOUR_API_KEY',
        'server_name' => 'localhost',
    ],

    // PowerDNS database settings are no longer needed in API mode
    // You can remove pdns_db_host, pdns_db_port, pdns_db_user, pdns_db_pass, pdns_db_name
    // Keep the Poweradmin database settings (db_host, db_port, etc.)
];

Both pdns_api.url and pdns_api.key are required when dns.backend is api. Missing values cause Poweradmin to error out on the first DNS operation. There is no silent fallback to SQL.

What Happens After Switching

  1. First page load: The zone sync service automatically populates zone_name, zone_type, and zone_master for all existing zones in your local zones table
  2. Ongoing: The sync runs at most once every 5 minutes per user session to pick up zones created directly in PowerDNS
  3. Zone operations: Create, edit, delete operations go through the PowerDNS API instead of direct SQL
  4. Permissions: All ownership, group, and permission checks work unchanged - they only use the local Poweradmin database

Switching Back to SQL Mode

Change dns.backend back to 'sql' and restore your PowerDNS database settings. The cached columns (zone_name, zone_type, zone_master) are ignored in SQL mode.

Zone Sync Service

The zone sync service reconciles the local zones table with zones in PowerDNS:

Action When
Add Zone exists in PowerDNS but not locally - creates a local entry (no owner, available for admin assignment)
Remove Zone exists locally but was deleted from PowerDNS - removes local entry and group associations
Update Zone type or master changed in PowerDNS - updates cached metadata

The sync is triggered automatically on zone list page loads and is throttled to run at most once every 5 minutes per session. The sync makes a single API call to fetch all zone metadata and performs minimal database operations.

Newly Synced Zones

Zones discovered during sync have no owner assigned. An administrator must assign ownership (user or group) for other users to access them. Superusers can see all zones regardless of ownership.

Performance Notes

  • Sync overhead: One HTTP request to PowerDNS API every 5 minutes per session. The response contains only zone metadata (not records), so it is lightweight even with thousands of zones.
  • Zone lookups: The zone_name column has a unique index, making name-based queries fast.
  • Record operations: Each record list/edit operation makes an API call to PowerDNS. This adds network latency compared to direct SQL, but the API response times are typically under 50ms for local deployments.

Zone Metadata Editor (Issue #16)

A new zone metadata editor allows managing PowerDNS domainmetadata entries per zone. Access it from the zone edit page via the Metadata button.

Features:

  • Edit all known PowerDNS metadata kinds (ALLOW-AXFR-FROM, ALSO-NOTIFY, TSIG-ALLOW-AXFR, etc.)
  • Custom metadata kind support
  • Multi-value metadata (one row per value)
  • Inline help and version badges for each metadata kind
  • Works in both SQL and API backend modes

SOA-EDIT-API (Issue #622) is editable through the metadata editor. In API mode, it writes via the zone properties endpoint. Options: DEFAULT, INCREASE, EPOCH, SOA-EDIT, SOA-EDIT-INCREASE, OFF.

Permissions: Requires zone_meta_edit_own (own zones) or zone_meta_edit_others (all zones).

Security Changes

Password Hashing

  • md5 and md5salt password hashing methods have been removed. Only bcrypt, argon2i, and argon2id are supported for new passwords.
  • Existing md5/md5salt hashes are still verified on login and automatically upgraded to the configured algorithm.
  • Default bcrypt cost aligned to 12 across all code paths.

Update your config/settings.php if you were using md5 or md5salt:

'security' => [
    'password_encryption' => 'bcrypt',  // Options: bcrypt, argon2i, argon2id
    'password_cost' => 12,
],

Breaking Changes

None. API backend mode is opt-in. Existing SQL-mode installations continue to work without any configuration changes. Password hashing changes are backward-compatible - legacy hashes are auto-upgraded on login.

Rollback

To rollback to v4.2.0:

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

The new columns (zone_name, zone_type, zone_master) on the zones table are harmless in older versions.