Update Log Configuration#
TheHive uses logback for logging. You can adjust log levels to control the amount of information recorded for troubleshooting and monitoring purposes. By default, logs are stored in /var/log/thehive/
, with the current log in application.log
and older logs compressed as application.%i.log.zip
.
Maintenance window required
This procedure involves changing configuration files and restarting services. Schedule a maintenance window to prevent service disruption.
Adjust log levels#
Control the detail of logged information by modifying log levels in the logback configuration. Higher log levels capture more detailed information for troubleshooting.
Docker deployment
Docker containers write logs to both stdout and /var/log/thehive/application.log
by default. To use custom logging settings, mount your logback configuration file to /etc/thehive/logback.xml
.
-
Stop TheHive service.
Service commands
For stop/restart commands depending on your installation method, refer back to the relevant installation guide.
-
Open the
logback.xml
file using a text editor. -
Modify the log level based on your needs.
- To set a global log level:
<!-- ... --> <root level="<log_level>"> <!-- ... --> </root>
- To set a specific logger level:
<logger name="<logger_name>" level="log_level"/>
-
Choose the appropriate log level from least to most verbose.
- OFF: No logging
- ERROR: Only errors
- WARN: Warnings and errors
- INFO: General information (default)
- DEBUG: Detailed debugging information
- TRACE: Very detailed trace information
Performance impact
Setting log levels to
DEBUG
orTRACE
significantly increases log volume and may impact performance. Use these levels only for troubleshooting, then return toINFO
for normal operation. -
Save your modifications in the
logback.xml
file. -
Restart TheHive service to apply the new configuration.
Debug logback configuration#
Enable logback debug mode to troubleshoot logging configuration issues. This displays logback internal status messages in the console during TheHive startup.
-
Stop TheHive service.
Service commands
For stop/restart commands depending on your installation method, refer back to the relevant installation guide.
-
Open the
logback.xml
file using a text editor. -
Set the debug attribute to
true
.<?xml version="1.0" encoding="UTF-8"?> <configuration debug="true">
-
Save your modifications in the
logback.xml
file. -
Restart TheHive service to apply the new configuration.
-
Check the console output for logback configuration details during startup.
Create an access log#
Separate access logs from application logs by configuring dedicated log appenders. This allows you to track API requests and user access patterns independently from system logs.
-
Stop TheHive service.
Service commands
For stop/restart commands depending on your installation method, refer back to the relevant installation guide.
-
Open the
logback.xml
file using a text editor. -
Add an appender for access logs after the existing appenders:
<!-- ... other appenders and settings --> <appender name="ACCESSFILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>/var/log/thehive/access.log</file> <rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy"> <fileNamePattern>/var/log/thehive/access.%i.log.zip</fileNamePattern> <minIndex>1</minIndex> <maxIndex>10</maxIndex> </rollingPolicy> <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy"> <maxFileSize>10MB</maxFileSize> </triggeringPolicy> <encoder> <pattern>%date [%level] from %logger [%traceID] %message%n%xException</pattern> </encoder> </appender> <appender name="ASYNCACCESSFILE" class="ch.qos.logback.classic.AsyncAppender"> <appender-ref ref="ACCESSFILE"/> </appender> <root level="INFO"> <!-- other appender-refs ... --> </root>
-
Configure the loggers to use the access appender.
<logger name="org.thp.scalligraph.AccessLogFilter"> <appender-ref ref="ASYNCACCESSFILE" /> </logger> <logger name="org.thp.scalligraph.controllers.Entrypoint"> <appender-ref ref="ASYNCACCESSFILE" /> </logger>
-
Adjust the
maxFileSize
andmaxIndex
parameters as needed. -
Save your modifications in the
logback.xml
file. -
Restart TheHive service to apply the new configuration.
-
Verify access logs are being written to
/var/log/thehive/access.log
.
Send logs to syslog#
Forward TheHive logs to a centralized syslog server for aggregation and monitoring.
-
Stop TheHive service.
Service commands
For stop/restart commands depending on your installation method, refer back to the relevant installation guide.
-
Open the
logback.xml
file using a text editor. -
Add a syslog appender after the existing appenders.
<!-- ... other appenders and settings --> <appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender"> <syslogHost><remote_host></syslogHost> <facility>AUTH</facility> <suffixPattern>[%thread] %logger %msg</suffixPattern> </appender>
-
Replace
<remote_host>
with your syslog server's host name or IP address. -
Add the syslog appender to the root logger.
<root level="INFO"> <appender-ref ref="SYSLOG" /> <!-- other appender-refs ... --> </root>
-
Save your modifications in the
logback.xml
file. -
Restart TheHive service to apply the new configuration.
Limitations
The logback syslog appender only supports UDP protocol. For TCP or TLS connections, use a third-party appender or forward logs through a local syslog daemon. See the logback documentation for alternatives.