Basic Logging Configuration¶

Poweradmin has two independent logging systems. This guide covers the basic configuration options. For advanced settings and best practices, see the Advanced Logging Configuration guide.

Two Logging Systems¶

Poweradmin uses two separate logging systems that serve different purposes:

1. Audit Logging (who did what)¶

Controlled by database_enabled and syslog_enabled. Tracks user, zone, and group changes - create/edit/delete operations, login/logout, group membership changes.

database_enabled: writes audit events to the log_users, log_zones, log_groups, log_api, log_changesets and log_record_changes tables
syslog_enabled: writes audit events to syslog

2. Diagnostic Logging (application errors and debug info)¶

Controlled by type and level. Used for troubleshooting application issues such as password reset flows, MFA, OIDC/SAML errors. Writes to PHP's error_log. Not related to audit logging.

Configuration Options¶

Legacy variable	Modern equivalent	Default value	Description	Added in version
$logger_type	logging.type	null	Diagnostic logger type: null (disabled), native (PHP error_log)	3.9.0
$logger_level	logging.level	info	Diagnostic logging level (debug, info, notice, warning, error, critical, alert, emergency)	3.9.0
$dblog_use	logging.database_enabled	false	Enable audit logging to database (log_users, log_zones, log_groups, log_api, log_changesets, log_record_changes tables)	3.2.0
N/A	logging.api_request_logging	false	Log every public API request to log_api (requires database_enabled); permission violations logged regardless	4.5.0
N/A	logging.api_log_retention_days	0	Days to keep log_api rows; 0 = keep forever	4.5.0
$syslog_use	logging.syslog_enabled	false	Enable audit logging to syslog	2.1.6
$syslog_ident	logging.syslog_identity	poweradmin	Specifies program name which is added to syslog message	2.1.6
$syslog_facility	logging.syslog_facility	LOG_USER	Specifies what type of program is logging the message	2.1.6

Diagnostic Log Levels¶

Available logging levels for the diagnostic logger (type/level), in order of increasing severity:

DEBUG: Detailed debug information
INFO: Interesting events
NOTICE: Normal but significant events
WARNING: Exceptional occurrences that are not errors
ERROR: Runtime errors that do not require immediate action
CRITICAL: Critical conditions
ALERT: Action must be taken immediately
EMERGENCY: System is unusable

When you set a specific log level, you will receive logs of that level and all higher severity levels. For example, setting level to warning will log warnings, errors, critical issues, alerts, and emergencies, but not info or debug messages.

Level values are lowercase in the configuration file. From 4.5.0 an unrecognised value, such as warn in place of warning, falls back to info and the logger records a warning naming the value it rejected. Earlier versions suppressed every message below emergency instead.

Configuration Example¶

return [
    'logging' => [
        'type' => 'native',
        'level' => 'warning',
        'database_enabled' => true,
        'syslog_enabled' => true,
        'syslog_identity' => 'poweradmin',
        'syslog_facility' => LOG_USER,
    ],
];

syslog_facility takes the PHP constant itself, not its name as a string. A quoted value such as 'LOG_USER', often carried over from an old config.inc.php, is rejected by the configuration check; on versions without that check it produced a blank page after login with an openlog() type error.

Upgrading from v3.x? The equivalent flat variables were $logger_type, $logger_level, $syslog_use, $syslog_ident, $syslog_facility and $dblog_use. That format was removed in 4.1.0 - see Legacy Configuration.

Docker Configuration¶

In the Docker image each setting has an environment variable, so logging can be turned on without a configuration file or a volume:

Variable	Setting	Default
`PA_LOGGING_TYPE`	`logging.type`	`null`
`PA_LOGGING_LEVEL`	`logging.level`	`info`
`PA_LOGGING_DATABASE_ENABLED`	`logging.database_enabled`	`false`
`PA_LOGGING_API_REQUEST_LOGGING`	`logging.api_request_logging`	`false`
`PA_LOGGING_API_LOG_RETENTION_DAYS`	`logging.api_log_retention_days`	`0`
`PA_LOGGING_SYSLOG_ENABLED`	`logging.syslog_enabled`	`false`
`PA_LOGGING_SYSLOG_IDENTITY`	`logging.syslog_identity`	`poweradmin`
`PA_LOGGING_SYSLOG_FACILITY`	`logging.syslog_facility`	`LOG_USER`

environment:
  PA_LOGGING_TYPE: "native"
  PA_LOGGING_LEVEL: "warning"
  PA_LOGGING_DATABASE_ENABLED: "true"

With PA_LOGGING_TYPE=native the diagnostic messages go to the container output, so docker logs or podman logs shows them.

If you mount your own directory over /app/config to supply a settings.php, the container copies settings.defaults.php back into that directory at startup. A settings.php that holds only a logging block is enough; everything else keeps its default.

The full variable list is in DOCKER.md.

For more advanced logging configuration, environment-specific examples, and best practices, see:

Advanced Logging Configuration