Configuration

Configuration

HS5 can be configured either via config file, environment variables or command line arguments. The configuration file can be specified via -c command line argument pointing at the configuration file.

Options available in the configuration file:

Use KEY=VALUE format (one option per line). Lines starting with # are treated as comments.

Example:

1
2
3
4
5
HTTP_PORT=8085
SERVER_IP=0.0.0.0
DATA_STORAGE_PATH=/var/lib/hs5/data
METADATA_STORAGE_PATH=/var/lib/hs5/meta
LOGLEVEL=info
OptionTypeDefaultDescription
HTTP_PORTinteger80HTTP port HS5 listens on.
SERVER_URLstringemptyPublic/base URL of this server.
DATA_STORAGE_PATHpath.Path for HS5 data files.
METADATA_STORAGE_PATHpath.Path for HS5 metadata/index files.
SERVER_IPstring0.0.0.0Address/hostname HS5 binds to.
INIT_ROOT_ACCESS_KEYstringrootInitial root access key name on first startup.
INIT_ROOT_PASSWORDstringauto-generated if unsetInitial root password on first startup.
INIT_CREATE_BUCKETstringemptyComma-separated list of buckets to create at startup.
MANUAL_COMMITbooleanfalseEnable manual commit mode. Accepted true values: true, yes, on, 1.
MANUAL_COMMIT_LIST_CONSISTENTbooleantrueKeep list operations fully consistent in manual commit mode (higher latency).
COMMIT_AFTER_MSinteger (ms)30000In manual commit mode, automatically commit after this delay. Use 0 to disable auto-commit.
WORKER_THREADSinteger2 x CPU coresNumber of global worker threads.
HTTP_WORKER_THREADSintegerCPU core countNumber of HTTP worker threads.
GET_IN_WORKER_THRESHOLDinteger (bytes)0Serve GET/HEAD requests in the HTTP worker thread and read objects smaller than this via mmap there. Lowers latency for small objects; 0 disables.
LOGLEVELenuminfoLog level. Allowed values: debug, info, warn, error.
STOP_ON_ERRORbooleanfalseStop HS5 on write/read errors instead of continuing.
DISABLE_MD5_ETAGbooleanfalseUse a unique random value as ETag instead of the MD5 of the object data. Saves CPU on uploads, but ETags are no longer content MD5s (not S3 compatible for clients that verify them).
PREALLOCATE_DATAbooleantruePreallocate space in the data file to improve write performance and reduce fragmentation. Automatically disabled on Btrfs.
TRIM_FREESPACE_SIZEinteger (bytes)1048576If contiguous free space in the data file exceeds this size, HS5 can punch holes to free disk space. Set to -1 to disable.
DB_MAX_DIRTY_MBinteger (MiB)50Maximum LMDB dirty page budget before flush.
WAL_MODEenumdisabledPerformance WAL mode. Allowed values: disabled, metadata-only, data-only, all-data-only, full, full-all-data.
WAL_PATHpathmetadata pathPath where WAL files are written.
WAL_SMALL_OBJECT_LIMITinteger (bytes)6000In full or data-only WAL mode, object size threshold for writing object data to WAL.
WAL_SIZE_MBinteger (MiB)1000WAL file size threshold before reset/rollover.
WAL_ITEMSinteger10000WAL item count threshold before reset/rollover.

HS5 can also read these options from environment variables using the HS5_ prefix (for example, HS5_HTTP_PORT). Option precedence is: config file values first, then environment variables, then command line arguments.

Tuning for best performance

  • Enable MANUAL_COMMIT for write-heavy workloads when you can tolerate delayed visibility/durability. This reduces commit overhead, but recent writes are not fully durable until commit (or COMMIT_AFTER_MS) runs.
  • Set MANUAL_COMMIT_LIST_CONSISTENT=false to reduce list latency in manual commit mode. Trade-off: list results may temporarily miss uncommitted objects (eventual consistency until commit).
  • Enable WAL_MODE only when MANUAL_COMMIT is disabled, and prefer placing WAL_PATH on storage that is at least as fast as METADATA_STORAGE_PATH.
  • Set TRIM_FREESPACE_SIZE=-1 to disable hole-punch trimming when optimizing for throughput over disk-space reclamation.
  • Increase DB_MAX_DIRTY_MB if you have available RAM and want fewer flushes under sustained writes in MANUAL_COMMIT mode.
  • Increase WORKER_THREADS above the default when storage is fast and CPU is not saturated; raise gradually while monitoring throughput and p95/p99 latency, since too many threads can increase contention and hurt performance.
  • Set DISABLE_MD5_ETAG=true to skip computing the MD5 of uploaded data. This only saves CPU (roughly 1–1.5 ms of CPU per MiB uploaded) and does not improve throughput unless HS5 is CPU-bound on uploads. Trade-off: ETags are no longer the MD5 of the object data, which breaks clients that verify ETags against content.