LogZilla

LogZilla stores its server configuration in YAML files, one per settings group. Most groups on this page can also be edited in the web interface under Settings > System Settings, where each group is listed under its title. Fields marked "(advanced)" in the tables below appear there only when the Show Advanced Settings option in the Generic group is enabled. The Query Settings group (querymodule.yaml) and the forwarder, InfluxDB, license, and secrets files have no web interface page; they are managed through the files and, except for secrets.yaml, the logzilla settings command. These backend settings control core system behavior, performance parameters, and security features.

Warning: Changing these settings may cause system instability or data loss. Exercise extreme caution and test changes in a non-production environment first.

Modern Configuration System

LogZilla stores configuration in YAML files located in /etc/logzilla/settings/. Each file corresponds to a specific configuration group (e.g., smtp.yaml, ldap.yaml, generic.yaml).

Configure with the command line

Administrators use the logzilla settings command to manage configuration:

bash
# List all available settings
logzilla settings list

# List settings for a specific group
logzilla settings list ldap

# Update a setting value
logzilla settings update SETTING_NAME=new_value

# Update multiple settings at once
logzilla settings update SMTP_SERVER=mail.company.com SMTP_PORT=587

# Manage multiple instances (e.g., secondary LDAP server)
logzilla settings update --id 1 LDAP_ENABLED=true

Edit the configuration file directly

Advanced users with root access can edit YAML files directly:

bash
# Navigate to settings directory
cd /etc/logzilla/settings/

# Edit a configuration file
vim smtp.yaml

After direct edits, see Applying Changes to reload the affected configuration group.

Applying Changes

After making configuration changes, apply them using one of these methods:

Method 1: Automatic Application (Recommended)

The logzilla settings update command automatically applies changes to compatible modules.

Method 2: Manual Reload (After Direct Edits)

If editing YAML files directly, notify the system of changes:

bash
# Reload a specific configuration group
logzilla settings reload smtp
logzilla settings reload ldap

Method 3: Container Restart (When Required)

The parser module reads parser.yaml, the storage module storage.yaml and sphinx.yaml, and the query module querymodule.yaml when their container starts. After changing one of those files, restart the module that reads it:

bash
# Restart the module container that reads the changed file
logzilla restart -c parsermodule     # parser.yaml
logzilla restart -c storagemodule-1  # storage.yaml, sphinx.yaml
logzilla restart -c querymodule      # querymodule.yaml

# Or restart all LogZilla services
logzilla restart

Note: Most settings files need no manual restart: the watcher reloads or restarts the containers that read them. Live Reloading vs Container Restart lists which files the watcher applies and which ones are restarted by hand.

These are the modules used by LogZilla, which can be restarted with logzilla restart -c <module>:

Module	Description
celerybeat	Schedules periodic background tasks for the platform.
gunicorn	API server for the LogZilla backend.
celeryworker	Executes background jobs and module orchestration tasks.
parsermodule	Parses, normalizes, and enriches incoming events using rules/apps.
querymodule	Runs searches/analytics, evaluates triggers, and publishes live results.
storagemodule-1	Event storage and indexing service (dedup, archiving, aggregates).
ai	LogZilla AI backend; powers AI features when enabled.
watcher	Orchestrates, monitors, and restarts LogZilla containers.
snmptrapd	Receives SNMP traps (UDP 162) and injects them as events.
httpreceiver	HTTP/HTTPS event ingest API (token-protected) into LogZilla.
sec	Simple Event Correlator for stateful, multi-event correlation.
scriptserver	Runs user-defined scripts for trigger actions/correlation.
front	Web frontend serving UI and proxying API/ingest endpoints.
syslog	Syslog-ng receiver for BSD/RFC5424, JSON, RAW, and TLS inputs.
logcollector	Collects and consolidates internal container logs for diagnostics.
mailer	Outbound SMTP service for alerts and test emails.
telegraf	Collects internal metrics and ships them to time-series storage.
qdrant	Vector database backing AI features (embeddings/search).
influxdb	Time-series database for metrics and aggregates.
postgres	Primary relational store for users, dashboards, triggers, settings.
redis	In-memory caching and queues for ephemeral data.

Configuration Files and Settings

The following sections organize settings by their configuration files in /etc/logzilla/settings/:

Generic Settings (`generic.yaml`)

Setting	Description	Default	Range
`SEARCH_DEFAULT_LIMIT`	Default max results limit for search queries	`100`	Integer
`FREE_DISK_SPACE_SOFT_LIMIT_GB`	Warning threshold for free disk space	`10`	Integer (GB)
`FREE_DISK_SPACE_HARD_LIMIT_GB`	Critical threshold for free disk space	`1`	Integer (GB)
`EXTERNAL_BASE_URL`	External URL of the LogZilla instance	`null`	Valid URL
`TIME_ZONE`	Server timezone	`GMT`	Timezone string
`RBAC_ENABLED`	Enable Role Based Access Control	`true`	`true`, `false`
`TASKS_ENABLED`	Enable Tasks feature	`true`	`true`, `false`
`AIR_GAPPED`	Disable external service communication	`false`	`true`, `false`
`PRUNE_DOCKER_IMAGES`	Remove old Docker images during upgrades	`false`	`true`, `false`
`SHOW_ADVANCED_SETTINGS`	Show advanced settings in UI	`false`	`true`, `false`
`LICENSE_EXPIRATION_WARNING_DAYS`	Days before license expiration at which the UI shows the warning banner	`60`	Integer (days)
`API_WORKERS_NUM`	API worker processes (advanced)	`4`	Integer
`ASGI_THREADS_NUM`	Threads per API worker for synchronous code (advanced)	`10`	Integer (threads)
`API_DB_POOL_MAX_SIZE`	PostgreSQL connections one API worker may hold; requests beyond it wait up to 10 seconds for a free connection; `0` disables the pool (advanced)	`20`	Integer (connections)

Search Settings (`sphinx.yaml`)

Setting	Description	Default	Range
`SPHINX_MIN_WORD_LENGTH`	Minimum word length to index	-	Integer
`SPHINX_MIN_PREFIX_LENGTH`	Minimum prefix length to index	-	Integer
`SPHINX_MIN_INFIX_LENGTH`	Minimum infix length to index	-	Integer
`SPHINX_MAX_DOCUMENTS_PER_INDEX`	Max documents per index (advanced)	-	Integer
`SPHINX_MAX_INDEXING_TIME`	Max indexing time per chunk (seconds) (advanced)	-	Integer
`SPHINX_MIN_INDEX_LEN`	Min events per indexing batch (advanced)	-	Integer
`SPHINX_REINDEX_PROC_MAX`	Max concurrent indexing processes (advanced)	-	Integer
`SPHINX_MERGING_PROC_MAX`	Max concurrent merging processes (advanced)	-	Integer
`SPHINX_REINDEX_DELAY`	Delay between reindexing (seconds) (advanced)	-	Integer
`SPHINX_MAX_MATCHES`	Maximum matches per query (advanced)	-	Integer
`SPHINX_MYSQL_PORT`	Sphinx MySQL port (0 to disable) (advanced)	-	Integer
`SPHINX_HTTP_PORT`	Sphinx HTTP port (0 to disable) (advanced)	-	Integer
`SPHINX_REALTIME_MODE`	Enable realtime mode (experimental) (advanced)	-	`true`, `false`

Query Settings (`querymodule.yaml`)

Setting	Description	Default	Range
`MODULE_WORKERS`	Number of query worker threads	`10`	Integer (max 50)
`QUERY_POLL_TIMEOUT`	Timeout for query poll commands (meta/delta) sent to storage nodes (seconds)	`30`	Integer
`QUERY_LIFECYCLE_TIMEOUT`	Timeout for query lifecycle commands (register/stop/destroy) sent to storage nodes (seconds)	`30`	Integer

Trigger Settings (`triggers.yaml`)

Setting	Description	Default	Range
`TRIGGERS_ENABLED`	Enable or disable triggers	`true`	`true`, `false`
`SEND_MAIL_PERIOD`	Email resend interval (seconds)	`60`	Integer
`SEND_WEBHOOK_PERIOD`	Webhook resend interval (seconds)	`10`	Integer
`EXEC_SCRIPT_PERIOD`	Script rerun interval (seconds)	`1`	Integer
`SEND_SERVICENOW_PERIOD`	Interval between ServiceNow batches of one trigger (seconds)	`60`	Integer

SMTP Settings (`smtp.yaml`)

Setting	Description	Default	Range
`MAIL_SENDER`	Email address used as sender	`[email protected]`	Email address
`SMTP_SERVER`	SMTP server address	`mailer`	Hostname/IP
`SMTP_PORT`	SMTP server port	`25`	Integer
`SMTP_AUTH_REQUIRED`	Enable SMTP authentication	`false`	`true`, `false`
`SMTP_USER`	SMTP username for authentication	(empty)	String
`SMTP_PASS`	SMTP password for authentication	(empty)	String
`SMTP_CRYPT`	Encryption method	`NONE`	`TLS`, `SSL`, `NONE`
`SMTP_TIMEOUT`	Connection timeout (seconds)	`5`	Integer

Auth and Sessions Settings (`django_login.yaml`)

Login session lifetime, the limits on repeated authentication failures, and how the client address is determined behind an additional proxy. A change saved in the web interface or with logzilla settings update is applied by a graceful reload of the API workers, with no container restart.

Setting	Description	Default	Range
`AUTOLOGIN_ENABLED`	Log every visitor in as `AUTOLOGIN_USER` without a password	`false`	`true`, `false`
`AUTOLOGIN_USER`	Account used when auto-login is enabled	`admin`	Username
`SESSION_COOKIE_AGE`	Lifetime of a login session (seconds)	`1209600`	Positive integer
`AUTH_FAILURE_USER_LIMIT`	Failed logins for one username from one client address after which that username is refused from that address for the rest of the window, even with the right password; `0` switches the lock off	`5`	Non-negative integer
`AUTH_FAILURE_ADDRESS_LIMIT`	Failed logins, unknown API tokens, and wrong password reset keys, each counted separately, from one client address after which further failures of that kind are answered with `429 Too Many Requests` until the failure window ends; a correct password, a valid token, or a valid reset key is never refused by this limit; `0` switches it off	`30`	Non-negative integer
`AUTH_FAILURE_WINDOW`	Length of the failure window, counted from the first failure (seconds)	`300`	Positive integer
`AUTH_TRUSTED_PROXY_HOPS`	Number of additional proxies or load balancers in front of LogZilla that append the client address to `X-Forwarded-For`; the failure limits and the login audit then charge the address that many entries before the one the LogZilla front proxy appends; set only when every request reaches LogZilla through those proxies	`0`	Non-negative integer

Executive Report Settings (`exec_report.yaml`)

Branding, link paths, and attention thresholds of the executive report. The Executive Report page describes the report itself and how the thresholds are applied.

Setting	Description	Default	Range
`EXEC_REPORT_BRAND_NAME`	Brand name shown in the report email and workbook; empty keeps the LogZilla branding	(empty)	String
`EXEC_REPORT_LOGO_URL`	Absolute URL of the logo shown in the report email in place of the brand name	(empty)	URL or empty
`EXEC_REPORT_VIEW_PATH`	Path of the interactive report linked from the email and workbook, appended to the instance URL; `{document_id}` is replaced; empty links the report file download	`/reports/executive/{document_id}`	Path starting with `/`, or empty
`EXEC_REPORT_SCHEDULE_PATH`	Path of the report schedule linked from the email, appended to the instance URL; `{schedule_id}` is replaced; empty removes the link	`/reports/schedules/{schedule_id}`	Path starting with `/`, or empty
`EXEC_REPORT_EPD_WARNING_PCT`	Licensed events per day used, in percent, from which the license is flagged as a warning	`80`	Positive integer, at most `EXEC_REPORT_EPD_CRITICAL_PCT`
`EXEC_REPORT_EPD_CRITICAL_PCT`	Licensed events per day used, in percent, from which the license is flagged as critical	`100`	Positive integer
`EXEC_REPORT_DISK_WARNING_DAYS`	Projected days until storage is full below which storage is flagged as a warning	`60`	Positive integer
`EXEC_REPORT_DISK_SERIOUS_DAYS`	Projected days until storage is full below which storage is flagged as serious	`14`	Positive integer, at most `EXEC_REPORT_DISK_WARNING_DAYS`
`EXEC_REPORT_THREAT_UP_PCT`	Increase of critical threats over the previous period, in percent, from which they are flagged	`50`	Positive integer
`EXEC_REPORT_THREAT_MIN_EVENTS`	Critical threat events in the period needed before the increase is flagged	`100`	Positive integer
`EXEC_REPORT_FAILED_AUTH_UP_PCT`	Increase of failed logins over the previous period, in percent, from which they are flagged; 100 means twice as many	`100`	Positive integer
`EXEC_REPORT_FAILED_AUTH_MIN_EVENTS`	Failed login events in the period needed before the increase is flagged	`1000`	Positive integer
`EXEC_REPORT_LINK_DOWN_MIN_EVENTS`	Link down events on one device in the period from which the device is flagged	`10`	Positive integer
`EXEC_REPORT_DEFAULT_SCHEDULE`	Create the Weekly Executive Report and its Monday 06:00 schedule for the admin account on a new installation and switch the schedule on once the SMTP server or the sender address is changed from its default and the admin account has an email address	`true`	`true`, `false`

ServiceNow Settings (`servicenow.yaml`)

Destination of the Send to ServiceNow trigger action. The ServiceNow Event Management page under Alerts covers the record layout and the ServiceNow-side setup.

Setting	Description	Default	Range
`SERVICENOW_ENABLED`	Enable the Send to ServiceNow trigger action	`false`	`true`, `false`
`SERVICENOW_INSTANCE_URL`	Instance URL; `/api/global/em/jsonv2` is added when the URL has no path	(empty)	URL
`SERVICENOW_USERNAME`	Service account for basic authentication	(empty)	String
`SERVICENOW_PASSWORD`	Service account password	(empty)	String (secret)
`SERVICENOW_SOURCE`	ServiceNow `source` field	`LogZilla`	String
`SERVICENOW_DEFAULT_EVENT_TYPE`	ServiceNow `type` for events without a program	`syslog`	String
`SERVICENOW_EVENT_CLASS`	ServiceNow `event_class` field	(empty)	String
`SERVICENOW_VERIFY_TLS`	Verify the instance certificate	`true`	`true`, `false`
`SERVICENOW_TIMEOUT`	Request timeout (seconds)	`10`	Integer
`SERVICENOW_MAX_ATTEMPTS`	Attempts per batch	`3`	1 to 10
`SERVICENOW_BACKOFF`	Retry delay base (seconds) (advanced)	`2`	Integer
`SERVICENOW_BATCH_SIZE`	Records per request (advanced)	`100`	1 to 500
`SERVICENOW_SEVERITY_<LEVEL>`	ServiceNow severity per syslog level, `EMERGENCY` to `DEBUG` (advanced)	see the alerts page	`0` to `5`

Syslog Daemon Settings (`syslogng.yaml`)

Setting	Description	Default	Range
`SYSLOG_BSD_TCP_PORT`	TCP port for BSD syslog (0 to disable)	`514`	Integer
`SYSLOG_BSD_UDP_PORT`	UDP port for BSD syslog (0 to disable)	`514`	Integer
`SYSLOG_RFC5424_PORT`	Port for RFC5424 syslog (0 to disable)	`601`	Integer
`SYSLOG_JSON_PORT`	Port for JSON syslog (0 to disable)	`515`	Integer
`SYSLOG_RAW_PORT`	Port for RAW TCP events (0 to disable)	`516`	Integer
`SYSLOG_RAW_UDP_PORT`	Port for RAW UDP events (0 to disable)	`516`	Integer
`SYSLOG_TLS_PORT`	Port for TLS syslog (0 to disable)	`6514`	Integer
`SYSLOG_TLS_CERT_FILE`	Path to TLS certificate file	`/etc/logzilla/nginx/server.crt`	File path
`SYSLOG_TLS_KEY_FILE`	Path to TLS key file	`/etc/logzilla/nginx/server.key`	File path
`SYSLOG_MAX_CONNECTIONS`	Maximum concurrent TCP connections (advanced)	`500`	Integer
`SYSLOG_FLOW_CONTROL`	Enable flow control (advanced)	`true`	`true`, `false`
`SYSLOG_DISK_BUFFER`	Enable disk buffer	`false`	`true`, `false`
`SYSLOG_BUFFER_RELIABLE`	Enable reliable disk buffer (advanced)	`false`	`true`, `false`
`SYSLOG_MEMORY_BUFFER_SIZE_MB`	Memory buffer size (MB) (advanced)	`4`	Integer
`SYSLOG_MEMORY_BUFFER_LENGTH`	Memory buffer length (messages)	`50000`	Integer
`SYSLOG_DISK_BUFFER_SIZE_MB`	Disk buffer size (MB) (advanced)	`1`	Integer
`SYSLOG_DESTINATION_WORKERS`	Number of destination workers (advanced)	`2`	Integer
`SYSLOG_DESTINATION_BATCH_LINES`	Lines per batch (advanced)	`10000`	Integer
`SYSLOG_DESTINATION_BATCH_TIMEOUT`	Batch timeout (milliseconds) (advanced)	`500`	Integer
`SYSLOG_DEBUG`	Enable debug logging (TSV format)	`false`	`true`, `false`
`SYSLOG_DEBUG_JSON`	Enable debug logging (JSON format)	`false`	`true`, `false`
`PCI_COMPLIANT_LOGS`	Enable PCI compliant logging	`false`	`true`, `false`

Application Ports (`application_ports.yaml`)

Dedicated syslog ports for vendors whose log format requires separate handling. Events received on these ports are automatically tagged for processing by the corresponding application rules. Each port listens on both TCP and UDP.

Setting	Description	Default	Range
`SYSLOG_ARISTA_EOS_PORT`	Arista EOS syslog port (0 to disable)	`0`	Integer
`SYSLOG_CHECKPOINT_PORT`	Check Point syslog port (0 to disable)	`0`	Integer
`SYSLOG_DATAPOWER_PORT`	IBM DataPower syslog port (0 to disable)	`0`	Integer
`SYSLOG_DELL_N_SERIES_PORT`	Dell N-Series switch syslog port (0 to disable)	`0`	Integer
`SYSLOG_FIREEYE_PORT`	FireEye syslog port (0 to disable)	`0`	Integer
`SYSLOG_INFOBLOX_PORT`	Infoblox NIOS syslog port (0 to disable)	`0`	Integer
`SYSLOG_MERAKI_PORT`	Cisco Meraki syslog port (0 to disable)	`0`	Integer
`SYSLOG_PALOALTO_PORT`	Palo Alto syslog port (0 to disable)	`0`	Integer
`SYSLOG_PALOALTO_SDWAN_ION_PORT`	Palo Alto Prisma SD-WAN ION syslog port (0 to disable)	`0`	Integer
`SYSLOG_SYMANTEC_PORT`	Symantec Endpoint Protection syslog port (0 to disable)	`0`	Integer
`SYSLOG_UNIFI_PORT`	Ubiquiti UniFi syslog port (0 to disable)	`0`	Integer
`SYSLOG_VMWARE_PORT`	VMware syslog port (0 to disable)	`0`	Integer

Parser Settings (`parser.yaml`)

Message parsing engine settings. RULE_ERROR_LIMIT controls when a parser rule that keeps raising runtime errors is disabled automatically; see Lua Rules for the behavior and recovery steps.

Setting	Description	Default	Range
`PARSER_WORKERS`	Number of worker threads used to parse messages	Half the CPU count, between 2 and 10	Integer (max 50)
`RULE_ERROR_LIMIT`	Processing errors in the last hour that disable a rule	`5`	Positive integer
`MAX_PROCESSING_PACKS`	Maximum number of event packs processed simultaneously (advanced)	`5`	Positive integer
`USE_HYPERSCAN`	Use Hyperscan for regex matching (advanced)	`true`	`true`, `false`

SNMP Trap Settings (`snmptrapd.yaml`)

Setting	Description	Default	Range
`SNMPTRAPD_ENABLED`	Enable SNMP trap daemon module	`False`	`True`, `False`
`SNMPTRAPD_FORMAT`	Message field format (see snmptrapd(8))	See below	-
`SNMPTRAPD_PROGRAM`	Program field value for SNMP trap events	`SNMPTrap`	-
`SNMPTRAPD_FACILITY`	Facility field value for SNMP trap events	`LOCAL0`	-
`SNMPTRAPD_SEVERITY`	Severity field value for SNMP trap events	`INFO`	-
`SNMPTRAPD_PORT`	SNMP trap daemon port	`162`	-

Additional Configuration Files

Other important configuration files include:

storage.yaml: Event storage, deduplication, and archiving settings
logger.yaml: Logging levels for different components
forwarder.yaml: Event forwarding to external systems
sec.yaml: Simple Event Correlator (SEC) integration
front.yaml: Nginx frontend proxy configuration (HTTP/HTTPS ports)
ldap.yaml: LDAP/Active Directory integration (supports multiple instances)
ai.yaml: AI/ML feature settings
httpreceiver.yaml: HTTP event receiver configuration
influxdb.yaml: InfluxDB integration settings
license.yaml: License configuration
secrets.yaml: Sensitive configuration data

Configuration Management Best Practices

Multi-Instance Configuration

LogZilla supports multiple instances of certain configurations. For example, to configure a secondary LDAP server:

bash
# Configure primary LDAP server
logzilla settings update LDAP_ENABLED=true LDAP_SERVER=ldap1.company.com

# Configure secondary LDAP server
logzilla settings update --id 1 LDAP_ENABLED=true LDAP_SERVER=ldap2.company.com

This creates ldap.yaml and ldap__1.yaml files respectively.

Configuration Validation

The logzilla settings command validates all changes against predefined schemas before saving, preventing invalid configurations:

bash
# This will fail with validation error if port is invalid
logzilla settings update SMTP_PORT=invalid_port

Backup and Recovery

Before making significant configuration changes, backup the settings directory:

bash
# Create backup
cp -r /etc/logzilla/settings /etc/logzilla/settings.backup.$(date +%Y%m%d)

# Restore from backup if needed
cp -r /etc/logzilla/settings.backup.20241201 /etc/logzilla/settings
logzilla settings reload generic  # Reload as needed

Important Notes

Live Reloading vs Container Restart

A change saved in the web interface or with logzilla settings update, or announced with logzilla settings reload <group> after a direct file edit, is published to the watcher, which applies it by settings file:

Settings file	Applied by the watcher
`generic.yaml`, `smtp.yaml`, `script_server.yaml`, `sec.yaml`	Graceful reload of the API workers and a restart of the Celery worker; `sec.yaml` also reloads the SEC instances
`django_login.yaml`, `ldap.yaml`	Graceful reload of the API workers
`syslogng.yaml`, `application_ports.yaml`	Reload of the syslog-ng configuration; the current dedicated ports are also handed to the running parser module
`front.yaml`	Restart of the front proxy, which briefly interrupts the web interface, and reload of the syslog-ng configuration
`httpreceiver.yaml`	Graceful reload of the HTTP receiver

The parser, storage, and query modules read parser.yaml, storage.yaml, sphinx.yaml, and querymodule.yaml when their container starts, so a change to those files takes effect after logzilla restart -c <module> (Method 3 under Applying Changes). Logging levels (logger.yaml) are read when a container starts as well and take effect after logzilla restart; SNMP trap settings (snmptrapd.yaml) take effect after logzilla restart -c snmptrapd.

Configuration File Access

Inspect settings with the command line

The logzilla settings list command prints the current values for a specific configuration group:

bash
logzilla settings list generic
logzilla settings list smtp

Inspect the configuration file directly

Administrators with root access can read the raw YAML file on disk:

bash
cat /etc/logzilla/settings/generic.yaml

SNMP Trap Format Default

The default SNMPTRAPD_FORMAT setting is:

text
Enterprise OID: %N, Trap Type: %W, Trap Sub-Type: %q,
Uptime: %T, Description: %W,
PDU Attribute/Value Pair Array: %v

Legacy Configuration Command

Deprecated: The logzilla config command is deprecated and should not be used. It lacks support for multi-instance configurations and validation. Use logzilla settings instead.