SFSCHUNKSERVER.CFG(5)

📦
version 5.8.0 · 4 versions
, in ubuntu stonking

💖 SFSCHUNKSERVER.CFG(5) 💖

okay bestie, so this is the glow-up guide for sfschunkserver.cfg(5) — yes, that's the section 5 of the manual, we're in file-formats territory, very chic, very technical girlie. pull up a chair, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

sfschunkserver.cfg — the main configuration file for sfschunkserver 👑

like, THE config file. the one that matters. the main character. everything else is a side plot fr fr.

🌸 DESCRIPTION 🌸

so the file sfschunkserver.cfg contains the configuration of the SaunaFS chunkserver process. that's it, that's the whole vibe — this file is where you tell your chunkserver how to live its life. 💅

🎀 SYNTAX 🎀

the syntax is, and I quote, so simple:

OPTION = VALUE

that's the whole thing. OPTION, equals sign, VALUE. no cap, that's iconic.

also, super important bestie: lines that start with the # character are ignored. so go ahead and leave yourself little love notes in there, the chunkserver will just scroll right past them 🙈

tl;dr — # at the start of the line = ignored. that's your comment escape hatch.

✨ OPTIONS ✨

Okay bestie, this is the big one — the full config menu for your chunkserver. Every knob, every default, every little "please don't touch unless you know what you're doing" warning. Configuration options, let's go. 💅

  • DATA_PATH — the spot where files with usage statistics and the daemon lock file live. 🗂️
  • LABEL — the label of this chunkserver. It's for tiering, bestie. 🏷️
  • WORKING_USER — the user to run the daemon as. 👤
  • WORKING_GROUP — group to run daemon as. It's optional — if it's empty, then the default user group gets used. 🫶
  • SYSLOG_IDENT — the name of the process that goes into syslog messages. Default is sfschunkserver. 📝
  • LOCK_MEMORY — whether to perform mlockall() to avoid swapping out the sfschunkserver process. Default is 0, i.e. no. 🔒
  • LIMIT_GLIBC_MALLOC_ARENAS — Linux only, bestie: limit glibc malloc arenas to the given value. It prevents using a huge amount of virtual memory. This can influence performance by reducing memory fragmentation and improving cache locality, but it may also lead to contention and reduced parallelism in multi-threaded applications. Use it in constrained memory environments; recommended values are 4 or 8. Default is 0: disabled or let glibc decide. 🧠
  • MALLOC_TRIM_INTERVAL — interval in seconds at which the chunkserver will attempt to release unused memory back to the OS using malloc_trim(). This can help reduce the process's memory footprint by returning free memory to the system more frequently. Set to 0 to disable memory trimming entirely. Default is 0, 0 = disabled. 🧹
  • NICE_LEVEL — nice level to run the daemon with. Default is -19 if possible. Note: process must be started as root to increase priority. ⚡
  • MASTER_HOST — address of the SaunaFS master host to connect with. Default is sfsmaster. 🏠
  • MASTER_PORT — number of the SaunaFS master port to connect with. Default is 9420. 🔌
  • CLUSTER_ID — only connect to metadata servers with this CLUSTER_ID. Prevents accidental connections to the wrong metadata servers. Default is default. 🚫
  • MASTER_RECONNECTION_DELAY — delay in seconds before trying to reconnect to the master server after disconnection. Default is 5. ⏳
  • MASTER_TIMEOUT — timeout (in seconds) for the master server connection. Default is 60, minimum is 0.01. ⌛
  • MASTER_NR_OF_WORKERS — number of threads that the connection to master may use to process operations on chunks, like create, duplicate, replicate and truncate. Default is 10, minimum is 2. 🧵
  • MASTER_REPLICATION_NR_OF_WORKERS — number of threads that the connection to master may use to process replications operations on chunks. Default is 5, minimum in 1. 🧵✨
  • BIND_HOST — local address to use for connecting with the master server. Default is *, i.e. default local address. 🌐
  • CSSERV_LISTEN_HOST — IP address to listen on for client (mount) connections. * means any. 👂
  • CSSERV_LISTEN_PORT — port to listen on for client (mount) connections. Default is 9422. 🚪
  • HDD_CONF_FILENAME — alternative name of the sfshdd.cfg file. 📄
  • HDD_LEAVE_SPACE_DEFAULT — free space threshold to set volume as 100% utisaued when there is less than the given amount of free space left. Default is "4GiB". This number is always added to the used disk space reported by chunkserver. 💾
  • HDD_TEST_FREQ — chunk test period in seconds. Default is 10. 🧪
  • HDD_CHECK_CRC_WHEN_READING — whether to check the CRC on every read operation. Default is 1. 🔍
  • HDD_CHECK_CRC_WHEN_WRITING — whether to check the CRC on every write operation. The safest and recommended value is 1; disable it only to test maximum throughput. Default is 1. ✍️
  • HDD_ADVISE_NO_CACHE — whether to remove each chunk from page when closing it to reduce cache pressure generated by chunkserver. Default is 0, i.e. no. 🧊
  • HDD_PUNCH_HOLES — if enabled, then chunkserver detects zero values in chunk data and frees corresponding file blocks (decreasing file system usage). This option works only on Linux with file systems supporting punching holes (XFS, ext4, Btrfs, tmpfs). 🕳️
  • ENABLE_LOAD_FACTOR — if enabled, chunkserver will send periodical reports of its I/O load to master, which will be taken into consideration when picking chunkservers for I/O operations. 📊
  • REPLICATION_BANDWIDTH_LIMIT_KBPS — limit how many kilobytes can be replicated from other chunkservers to this chunkserver in every second. By default undefined, i.e. no limits. 🚦
  • NR_OF_NETWORK_WORKERS — number of threads which handle (in a round-robin manner) connections with clients. Default is 4; these threads are responsible for reading from sockets and coping data from internal buffers to sockets. 🔄
  • NR_OF_HDD_WORKERS_PER_NETWORK_WORKER — number of threads that each network worker may use to do disk operations like opening chunks, reading or writing them. Default is 16. 💽
  • BGJOBSCNT_PER_NETWORK_WORKER — maximum number of jobs that each network worker may use for disk operations. Default is 4000. 📋
  • POLL_TIMEOUT_MS — maximum amount of time in milliseconds that the polling operation will wait for events. In the chunkservers, the same value is applied for the events loop and for the network worker threads. Smaller values could reduce latency at the cost of CPU usage. Default: 50. ⏱️
  • MAX_BLOCKS_PER_HDD_WRITE_JOB — maximum number of blocks written to the device in a single write job. If possible, will try to make a single pwrite call. Default is 16, minimum is 1, maximum is 64. 📦
  • MAX_BLOCKS_PER_HDD_READ_JOB — maximum number of blocks read from the device in a single read job. If possible, will try to make a single pread call. Default is 16, minimum is 1. 📥
  • MAX_PARALLEL_HDD_READ_JOBS_PER_CS_ENTRY — maximum number of read jobs processed in parallel per client connection. Default is 1. 🧮
  • MAX_BUFFERS_POOL_SIZE_MB — maximum size of the buffers pool used for read, write and replicate operations, in megabytes. Consider decreasing it if the system is running out of memory, or increasing it to improve performance if there is enough memory available. Unused buffers are regularly freed. Default is 512. 🧺
  • READ_AHEAD_KB — additional number of kilobytes which should be passed to posix_fadvise(POSIX_FADV_WILLNEED) before reading data from a chunk. Default is 0, i.e. use posix_fadvise only with the amount of data that is really needed; the value is aligned down to 64 KiB. 🔮
  • MAX_READ_BEHIND_KB — try to fix out-of-order read requests; the value tells how much of skipped data to read if an offset of some read operation is greater than the offset where the previous operation finished. Default is 0, i.e. don't read any skipped data; the value is aligned down to 64 KiB. 🔙
  • PERFORM_FSYNC — call fsync() after a chunk is modified. Default is 1, i.e. enabled. 💾
  • STAT_CHUNKS_AT_DISK_SCAN — verify that chunk metadata and data parts exists at scan time. If set to 1, the data part is also checked to be multiple of SFSBLOCKSIZE. Disabling this option accelerates the scan process, but does not check the chunk files. Warning: use it with caution, only in scenarios where a fast chunkserver restart is needed. Default is 1, i.e. enabled. ⚠️
  • REPLICATION_TOTAL_TIMEOUT_MS — total timeout for single replication operation. Replications that take longer than that are considered failed and are immediately aborted. Default: 60000. ⏰
  • REPLICATION_CONNECTION_TIMEOUT_MS — connection for single replication operation. If connecting to another chunkserver takes longer than this timeout, the operation is considered failed and is immediately aborted. Default: 1000. 📞
  • REPLICATION_WAVE_TIMEOUT_MS — ADVANCED:: timeout for single wave in replication. After this timeout, next wave of read requests is sent to other chunkservers. Default: 500. 🌊
  • PLUGINS_DIR — directory to search for Chunkserver plugins (absolute path). When set, the plugin manager will search this directory first. If not set, then it will search in usual plugin locations, like PLUGINS_PATH/chunkserver (PLUGINS_PATH is defined at build time), /usr/local/lib/saunafs/plugins/chunkserver, and /usr/lib/saunafs/plugins/chunkserver. Default is empty string, i.e. disabled. 🔌
  • CHUNK_TRASH_ENABLED (EXPERIMENTAL) — enables or disables the chunk trash feature. When enabled, deleted chunks are moved to a trash directory instead of being immediately removed. Default: 0. 🗑️
  • CHUNK_TRASH_EXPIRATION_SECONDS (EXPERIMENTAL) — specifies the timeout in seconds for chunks to remain in the trash before being permanently deleted. Default: 259200. ⏳
  • CHUNK_TRASH_FREE_SPACE_THRESHOLD_GB (EXPERIMENTAL) — sets the available space threshold in gigabytes. If the available space on the disk falls below this threshold, the system will start deleting older chunks from the trash to free up space. A suggested value is about the 15% of the capacity of the smaller configured disk. Default: 0. 💽
  • CHUNK_TRASH_GC_BATCH_SIZE (EXPERIMENTAL) — defines the bulk size for the garbage collector when processing chunks in the trash. This determines how many files are processed in each garbage collection cycle. Default: 1000. 🧹
  • CHUNK_TRASH_GC_SPACE_RECOVERY_BATCH_SIZE (EXPERIMENTAL) — [ADVANCED] The number of files to remove from the trash in a single GC cycle, in case the disk is full and space needs to be recovered. Default: 100. 🚨
  • LOG_LEVEL — setup logging. Uses the environment variable SAUNAFS_LOG_LEVEL or config value LOG_LEVEL to determine logging level. Valid log levels are:
    • trace
    • debug
    • info
    • warn or warning
    • err or error
    • crit or critical
    • off 📝
  • IO_PRIORITY_MODE (EXPERIMENTAL) — define IO jobs, i.e reads and writes from drives, prioritization scheme. The available modes are:
    • FIFO: prioritizes the IO jobs first enqueued.
    • SWITCH: alternates read and write jobs (interleaving) to prevent one class of IO from starving the other. Not reloadable. Default: FIFO. ⚖️
  • TLS_CERT_FILE (EXPERIMENTAL) — path to the TLS certificate file the chunk server will use for TLS connections. There is no default value. 🔐
  • TLS_KEY_FILE (EXPERIMENTAL) — path to the TLS private key file the chunk server will use for TLS connections. There is no default value. 🔑
  • TLS_CA_CERT_FILE (EXPERIMENTAL) — path to the trusted CA certificate which is used to authenticate through TLS to the master server. There is no default value. 📜

🐛 REPORTING BUGS 🐛

Report bugs to the GitHub repository https://github.com/leil-io/saunafs as an issue. 🫶

okay bestie, legal era incoming, but it's actually kinda wholesome so stay with me 🫶

  • Copyright 2008-2009 Gemius SA
  • Copyright 2013-2019 Skytechnology sp. z o.o.
  • Copyright 2023-2024 Leil Storage OÜ

SaunaFS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation</>, version 3. slay, freedom, periodt. 💅

SaunaFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. (not me being legally required to yell this at you but also like… it's true, so 👀)

You should have received a copy of the GNU General Public License along with SaunaFS. If not, see http://www.gnu.org/licenses/. no gatekeeping here, the license link is right there for you babe 💖

🌸 SEE ALSO 🌸

the way that these two are literally the main characters of this whole saga, iykyk 👑

and that's a wrap on the whole SFSCHUNKSERVER.CFG(5) bestie 🎀 that was section 5 of the manual, dropped on 2026-07-29 ✨ go forth and configure your chunkserver like the icon you are, no cap 🦋💜

📦 where this page comes from