Basic Configuration¶

Poweradmin v4.x uses an array-based configuration format in config/settings.php.

Note: Upgrading from v3.x? The old flat $variable format was removed in 4.1.0. See Legacy Configuration to map the old names onto the keys below.

Configuration File¶

Create config/settings.php with your custom settings. The file config/settings.defaults.php contains all defaults - do not edit it directly as changes will be overwritten during upgrades.

<?php
return [
    'database' => [
        'host' => 'localhost',
        'name' => 'powerdns-db',
        'user' => 'poweradmin-db-user',
        'password' => 'poweradmin-db-user-password',
        'type' => 'mysql',
    ],

    'security' => [
        'session_key' => 'change_this_key',
    ],

    'dns' => [
        'hostmaster' => 'hostmaster.example.com',
        'ns1' => 'ns1.example.com',
        'ns2' => 'ns2.example.com',
    ],
];

Configuration Precedence¶

When using Docker, configuration is loaded in this order (later overrides earlier):

config/settings.defaults.php - Default values
config/settings.php - Your custom settings file
Environment variables (PA_*) - Docker/container settings
Docker secrets (PA_*__FILE) - Sensitive values from files

Note: A secret and its plain environment variable are mutually exclusive, not layered. If both PA_FOO and PA_FOO__FILE are set, the container logs an error and exits rather than preferring one over the other.

Protecting Credentials Outside Docker¶

config/settings.php holds the database password and the session key in plain text, so on a non-container install the file permissions are the protection.

Make the file readable by the web server user and nobody else. With Apache or php-fpm running as www-data, that is chown root:www-data config/settings.php and chmod 640 config/settings.php.
Keep it out of version control and out of any backup that is world-readable.
Rotate security.session_key if the file is ever exposed; it signs session data.

Two things that work in Docker do not apply here:

The __FILE secrets convention is a container feature. It is implemented in docker-entrypoint.sh, which translates PA_FOO__FILE into PA_FOO before PHP starts. Nothing in the application reads it, so PA_DB_PASS__FILE has no effect on a bare-metal install. See Docker Secrets for what it does cover.
PA_* environment variables are also entrypoint-driven. They are turned into settings while the container starts, not read at runtime.

The one environment variable the application itself reads is PA_CONFIG_PATH, which points at an alternative settings file:

PA_CONFIG_PATH=/etc/poweradmin/settings.php

That lets you keep configuration outside the document root - on a read-only deployment, or where the application directory is replaced wholesale on upgrade. When it is unset, Poweradmin falls back to config/settings.php.

Configuration Sections¶

The configuration is organized into logical sections:

Section	Description
`database`	Database connection settings
`security`	Password policies, session management, MFA
`dns`	Nameserver details, SOA defaults, TLD checks
`interface`	UI preferences, themes, display options
`logging`	Logging configuration (file, syslog, database)
`pdns_api`	PowerDNS API integration
`mail`	Email configuration for notifications
`dnssec`	DNSSEC functionality
`ldap`	LDAP/Active Directory authentication
`oidc`	OpenID Connect authentication
`saml`	SAML authentication
`modules`	Optional modules: CSV export (`modules.csv_export`), zone import/export (`modules.zone_import_export`), secondary zone import over AXFR (`modules.secondary_zone_import`), WHOIS (`modules.whois`), RDAP (`modules.rdap`), DNS wizards (`modules.dns_wizards`), mail template previews (`modules.email_previews`)
`notifications`	Notification toggles: `notifications.zone_access_enabled` (default `false`) for zone access change emails, `notifications.change_request_enabled` (default `false`, v4.6.0+) for change request emails, `notifications.change_request_soa_contact` (default `false`, v4.6.0+) to include the zone's SOA contact
`approval`	Change approval workflow: `approval.enabled` and `approval.require_review_for_all` (v4.6.0+) - see Change Requests
`api`	REST API configuration
`user_agreement`	User agreement system
`misc`	Timezone, conflict handling, etc.

Database Settings¶

Setting	Default	Description
`database.host`	-	Database server hostname
`database.port`	-	Database port (optional)
`database.user`	-	Database username
`database.password`	-	Database password
`database.name`	-	Database name
`database.type`	-	Database type: mysql, mysqli, pgsql, sqlite
`database.charset`	-	Connection charset (e.g., utf8)
`database.file`	-	SQLite database file path
`database.debug`	false	Log SQL queries
`database.pdns_db_name`	(empty)	Separate PowerDNS database, MySQL/MariaDB only (v3.8.0+)

Security Settings¶

Setting	Default	Description
`security.session_key`	change_this_key	Session encryption key (change this!)
`security.password_encryption`	bcrypt	Hash algorithm: bcrypt, argon2i, argon2id
`security.password_cost`	12	Bcrypt cost parameter
`security.login_token_validation`	true	CSRF protection for login
`security.global_token_validation`	true	CSRF protection globally

For password policies and MFA settings, see Security Policies.

Interface Settings¶

Setting	Default	Description
`interface.language`	en_EN	Default language
`interface.enabled_languages`	multiple*	Available languages
`interface.theme`	default	Theme name (`default`, `modern`, or your own directory under `theme_base_path`)
`interface.style`	light	UI style: `light` or `dark`
`interface.rows_per_page`	10	Rows per page in lists
`interface.session_timeout`	1800	Session timeout in seconds. Must be a positive integer; from 4.5.0 a value of `0` is rejected with a configuration error instead of logging users out on their next request. The timeout cannot be disabled - use a large value
`interface.title`	Poweradmin	Application title
`interface.application_url`	(empty)	Public base URL of the install. Required for OIDC, SAML, password reset and emailed links
`interface.web_enabled`	true	Serve the web interface; `false` runs API-only - see the Headless Quickstart
`interface.display_serial_in_zone_list`	false	Show serial in zone list
`interface.display_template_in_zone_list`	false	Show template in zone list
`interface.show_zone_comments`	true	Enable zone comments
`interface.show_record_comments`	false	Enable record comments
`interface.add_reverse_record`	true	Show PTR record checkbox
`interface.add_domain_record`	true	Show A/AAAA checkbox in reverse view
`interface.show_record_id`	false	Show record ID in edit form
`interface.position_record_form_top`	true	Add record form at top
`interface.position_save_button_top`	false	Save button at top
`interface.show_forward_zone_associations`	true	Show associated forward zones in reverse zone list (v4.0.5+)
`interface.display_hostname_only`	false	Show only hostname part in zone edit form (strips zone suffix). Site-wide default; from v4.4.0 each user can override this in their account preferences.
`interface.wide_layout`	false	Use the full browser width instead of a fixed-width page. Site-wide default; from v4.5.0 each user can override this in their account preferences.

* Default languages: ar_SA, bg_BG, bs_BA, cs_CZ, da_DK, de_DE, el_GR, en_EN, es_ES, et_EE, fa_IR, fi_FI, fr_FR, ga_IE, he_IL, hi_IN, hr_HR, hu_HU, id_ID, it_IT, ja_JP, ko_KR, lt_LT, lv_LV, ms_MY, nb_NO, nl_NL, pl_PL, pt_BR, pt_PT, ro_RO, ru_RU, sk_SK, sl_SI, sq_AL, sr_RS, sv_SE, th_TH, tr_TR, uk_UA, vi_VN, zh_CN, zh_TW (et_EE, fi_FI, hr_HR, hu_HU, lv_LV, ro_RO, sk_SK, sr_RS added in v4.4.0)

Tip: If you experience slow loading or timeout errors on the reverse zones page, set show_forward_zone_associations to false. This disables the lookup of associated forward zones which can be slow with many PTR records.

For UI customization, see UI Customization.

DNS Settings¶

Setting	Default	Description
`dns.hostmaster`	-	Default hostmaster (e.g., hostmaster.example.net)
`dns.ns1`	-	Primary nameserver
`dns.ns2`	-	Secondary nameserver
`dns.ns3`	-	Third nameserver (optional)
`dns.ns4`	-	Fourth nameserver (optional)
`dns.ttl`	86400	Default TTL (seconds)
`dns.soa_refresh`	28800	SOA refresh (seconds)
`dns.soa_retry`	7200	SOA retry (seconds)
`dns.soa_expire`	604800	SOA expire (seconds)
`dns.soa_minimum`	86400	SOA minimum (seconds)
`dns.zone_type_default`	MASTER	Default zone type: `MASTER` or `NATIVE`
`dns.strict_tld_check`	false	Allow only official TLDs
`dns.top_level_tld_check`	false	Prevent top-level TLD creation
`dns.third_level_check`	false	Prevent third-level domain creation
`dns.txt_auto_quote`	false	Auto-quote TXT records

For more DNS options, see DNS Settings.

Change Approval Settings¶

Setting	Default	Description
`approval.enabled`	false	Route the zone changes of request-only users through review (v4.6.0+)
`approval.require_review_for_all`	false	Every zone change becomes a change request, even for editors and administrators (v4.6.0+)

Email for filed and decided requests is a separate switch, notifications.change_request_enabled, and needs mail.enabled. See Change Requests.

Miscellaneous Settings¶

Setting	Default	Description
`misc.timezone`	UTC	Application timezone, used for SOA serial generation (e.g. `Europe/Berlin`, `Asia/Shanghai`)
`misc.display_stats`	false	Show memory/execution stats
`misc.display_errors`	false	Show PHP errors (disable in production)
`misc.show_generated_passwords`	true	Display generated passwords
`misc.edit_conflict_resolution`	last_writer_wins	Conflict strategy*
`misc.record_comments_sync`	false	Sync A/PTR record comments
`misc.template_cache`	false	Cache compiled Twig templates on disk for faster rendering (v4.5.0+)
`misc.template_cache_path`	(empty)	Directory for compiled templates; empty uses `var/cache/twig` (v4.5.0+)

* Conflict resolution strategies:

last_writer_wins - Latest save overwrites previous
only_latest_version - Reject if record was modified

From 4.6.0 a rejected save keeps the submitted records and comment on the page, marks the rows that differ from what the zone holds, and lets you resubmit instead of retyping.

Template caching¶

Enabling misc.template_cache compiles Twig templates to PHP once and reuses them, which takes the compile step out of every request. The cache directory must be writable by the web server user. If it cannot be created or written, Poweradmin logs a warning and falls back to uncached rendering rather than failing the request.

Compiled templates are revalidated against their source files, so an upgrade that ships new templates takes effect without clearing the cache by hand.