Skip to main content

Configuration Guide

hlquery uses hlquery.conf as the primary runtime configuration file. Its location depends on the install layout chosen during ./configure.

llm.conf is deprecated. Keep runtime settings in hlquery.conf.

Configuration Files Overview​

The configuration files below are the ones you will use most often:

FilePurposeLocation
hlquery.confMain server configuration (including auth/users/links/search)run/conf/hlquery.conf (dev) or /etc/hlquery/hlquery.conf (system/debian/rpm)
IP FilteringIP allow-listing, DNS resolution behavior, and connection filteringConfigured inside hlquery.conf via <allow ...>
database.confRocksDB storage engine configuration (optional split file)run/conf/database.conf (dev) or /etc/hlquery/database.conf
search.confSearch tuning reference / optional split filerun/conf/search.conf (dev) or /etc/hlquery/search.conf
users.confLegacy auth layout referencerun/conf/users.conf (dev) or /etc/hlquery/users.conf

Typical locations:

run/conf/
/etc/hlquery/

hlquery.conf is the source of truth for runtime behavior. Split files remain available for legacy layouts.

Quick Start​

For most deployments, defaults are a good starting point. You will usually customize:

  • Logging: log levels and output destinations
  • Network: ports, bind addresses, and HTTPS
  • Authentication: access control and user setup
  • Performance: thread and cache-related settings

Configuration Format​

hlquery uses an XML-like format:

<log method="file" type="*" level="debug" target="/path/to/logfile.log">
<server name="hlquery.local" id="001">
<bind address="0.0.0.0" port="9200" type="http">

Detailed Configuration Pages​

Main Server Configuration​

hlquery.conf - Main server configuration:

  • Logging configuration (levels, types, methods)
  • Server identity
  • Network bindings (HTTP/HTTPS)
  • Performance settings (thread limits)
  • Configuration includes
  • IP filtering

Search Algorithm Configuration​

search.conf - Search algorithm configuration:

  • Algorithm selection (BM25, BM25+, TF-IDF, Hybrid)
  • Ranking parameters (k1, b, delta)
  • Advanced search improvements (adaptive k1, temporal BM25++, etc.)
  • Performance settings (caching, timeouts)
  • Query processing settings

RocksDB Storage Engine Configuration​

database.conf - RocksDB storage engine configuration:

  • MemTable settings (size, count)
  • SSTable settings (size, levels)
  • Compression settings
  • Background operations (compaction, flushing)
  • Bloom filters and block cache
  • WAL (Write-Ahead Log) options

User Authentication Configuration​

hlquery.conf - Authentication and users:

  • Enable/disable authentication (<auth enabled="...">)
  • Define user tokens or passwords (<user ...>)
  • Control user/admin flags
  • API-level auth behavior (Authorization: Bearer, X-API-Key, and HTTP Basic)

Common Configuration Tasks​

Change Server Port​

Edit hlquery.conf in your active config directory:

<bind address="0.0.0.0" port="9200" type="http">

Change port="9200" to your desired port.

Enable Authentication​

Edit hlquery.conf in your active config directory:

<auth enabled="true">

Adjust Logging​

Edit hlquery.conf in your active config directory:

<log method="file" type="*" level="normal" target="/var/log/hlquery/hlquery.log" />

Tune Performance​

Edit hlquery.conf in your active config directory:

<threads max="8" search="4" io="2">

Important Notes​

Note: Some changes (like port numbers) may require a server restart.

Security Note: Use strong, unique tokens in production.

Next Steps​