LogZilla

LogZilla uses a modern YAML-based configuration system that provides advanced settings not available through the web interface. 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).

Configuration Management

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

Direct File Editing

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

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)

Some settings require container restarts to take effect:

bash
# Restart specific containers
docker restart lz_gunicorn_1 lz_celeryworker_1 lz_celerybeat_1

# Or restart all LogZilla services
logzilla restart

Note: API and Celery containers typically require restart for changes to take effect, while core processing modules support live reloading for most settings.

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	`1000`	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	`2`	Integer (GB)
`EXTERNAL_BASE_URL`	External URL of the LogZilla instance	`null`	Valid URL
`TIME_ZONE`	Server timezone	`UTC`	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	`true`	`true`, `false`
`SHOW_ADVANCED_SETTINGS`	Show advanced settings in UI	`false`	`true`, `false`

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	-	Integer
`SPHINX_MAX_INDEXING_TIME`	Max indexing time per chunk (seconds)	-	Integer
`SPHINX_MIN_INDEX_LEN`	Min events per indexing batch	-	Integer
`SPHINX_REINDEX_PROC_MAX`	Max concurrent indexing processes	-	Integer
`SPHINX_MERGING_PROC_MAX`	Max concurrent merging processes	-	Integer
`SPHINX_REINDEX_DELAY`	Delay between reindexing (seconds)	-	Integer
`SPHINX_MAX_MATCHES`	Maximum matches per query	-	Integer
`SPHINX_MYSQL_PORT`	Sphinx MySQL port (0 to disable)	-	Integer
`SPHINX_HTTP_PORT`	Sphinx HTTP port (0 to disable)	-	Integer
`SPHINX_REALTIME_MODE`	Enable realtime mode (experimental)	-	`true`, `false`

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, 0=always)	`0`	Integer
`EXEC_SCRIPT_PERIOD`	Script rerun interval (seconds)	`60`	Integer

SMTP Settings (`smtp.yaml`)

Setting	Description	Default	Range
`MAIL_SENDER`	Email address used as sender	`logzilla@localhost`	Email address
`SMTP_SERVER`	SMTP server address	`localhost`	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)	`30`	Integer

Syslog 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_VMWARE_PORT`	TCP port for VMware events (0 to disable)	`1514`	Integer
`SYSLOG_VMWARE_UDP_PORT`	UDP port for VMware events (0 to disable)	`1514`	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	`500`	Integer
`SYSLOG_FLOW_CONTROL`	Enable flow control	`true`	`true`, `false`
`SYSLOG_DISK_BUFFER`	Enable disk buffer	`false`	`true`, `false`
`SYSLOG_BUFFER_RELIABLE`	Enable reliable disk buffer	`false`	`true`, `false`
`SYSLOG_MEMORY_BUFFER_SIZE_MB`	Memory buffer size (MB)	`4`	Integer
`SYSLOG_MEMORY_BUFFER_LENGTH`	Memory buffer length (messages)	`50000`	Integer
`SYSLOG_DISK_BUFFER_SIZE_MB`	Disk buffer size (MB)	`1`	Integer
`SYSLOG_DESTINATION_WORKERS`	Number of destination workers	`2`	Integer
`SYSLOG_DESTINATION_BATCH_LINES`	Lines per batch	`10000`	Integer
`SYSLOG_DESTINATION_BATCH_TIMEOUT`	Batch timeout (milliseconds)	`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`

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
parser.yaml: Message parsing engine configuration
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
django_login.yaml: Django authentication 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

Live Reloading: Core processing modules (parser, storage, query) support live reloading for most settings through the pub/sub mechanism.

Container Restart Required: API and Celery containers require restart for changes to take effect:

SMTP settings
LDAP configuration
Database connections
Security settings

SMTP Configuration

SMTP settings control outgoing email functionality for alerts and notifications. After changing SMTP settings, restart the API containers:

bash
docker restart lz_gunicorn_1 lz_celeryworker_1

Configuration File Access

To view the current settings in any configuration file:

bash
# View all settings in a specific file
logzilla settings list generic
logzilla settings list smtp

# View the raw YAML file
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.