Configuration

fastcached takes its settings from a YAML file, from command-line flags, or from both. fastcached --help prints the complete, always-current flag list; this page covers where the file lives, which source wins, and what happens when a setting cannot be applied.

Where the config file lives

You do not have to tell fastcached where its configuration is. Started with no --config, it reads the first of these that exists and it can read — which is exactly where each installer puts it:

Platform	Per-user	Machine-wide
Linux	$XDG_CONFIG_HOME/fastcached/fastcached.yaml, then ~/.config/fastcached/fastcached.yaml	/etc/fastcached/fastcached.yaml
macOS	$XDG_CONFIG_HOME/fastcached/fastcached.yaml, then ~/.config/fastcached/fastcached.yaml	/opt/fastcached/etc/fastcached.yaml
Windows	%APPDATA%\fastcached\fastcached.yaml	%ProgramData%\fastcached\fastcached.yaml

The per-user file wins, so you can shadow a machine-wide configuration without touching it and without root.

Which column applies depends on who you are. The machine-wide file describes the system service — its cache lives where only the service account can write — so only a process that could be that service reads it: root, or an elevated administrator, or LocalSystem. Run fastcached as yourself and the machine-wide row is passed over entirely, whatever its permissions; you get your own config, or the built-in defaults.

That is deliberate, and it is why systemctl --user start fastcached works out of the box on a host whose /etc/fastcached/fastcached.yaml points the system daemon at /var/lib/fastcached/cache: your instance never sees that file, so it never tries to open a directory it has no access to. Name it with --config if you genuinely want it.

then, not else: setting $XDG_CONFIG_HOME does not take ~/.config out of the search, it only puts another location ahead of it. The basedir specification treats ~/.config as what $XDG_CONFIG_HOME means when unset, so under a strict reading it would drop out entirely; fastcached probes both, on the grounds that a half-migrated setup is better served by finding the file than by ignoring it. If you have moved your config and left the old copy behind, the banner below is where you will notice.

The startup banner reports which file was chosen:

[INFO] fastcached 0.0.1 starting; bind=127.0.0.1:6674 ... config=/etc/fastcached/fastcached.yaml ...

config=<none> there means no file was found and the built-in defaults are in effect — which is a perfectly good way to run fastcached.

The compile worker has its own file, with its own name

fastcache-compile-node reads fastcache-compile-node.yaml from the same locations under its own name, by the same rule: named is strict, discovered is skipped when absent, unreadable or untrusted. Everything on this page about where applies to it unchanged.

What differs is the mapping. Every key there is one flag of fastcache-compile-node --help, spelled with underscores instead of dashes, and the file and the command line reach each setting through the same applier — so precedence is simply that the command line is applied second. The daemon's keys below are a mapping rather than a rule (--storage is storage_path), which is why they are listed out. The worker's are on its own page.

Named files are strict, discovered ones are not

--config=<path> overrides the search entirely, and the file must exist — you asserted it was there, so a typo is an error rather than a silent fallback to different settings.

A default location that does not exist, or that this account may not read, is skipped and the next one tried. That is what lets a per-user daemon start normally alongside a machine-wide config it has no access to. A default file that exists and is readable but does not parse is still a startup error: at that point it is plainly meant to be used.

A privileged daemon only obeys a config an administrator could have written

When fastcached runs as root or LocalSystem, storage_path: decides where a fully privileged process creates directories and writes files. So a privileged run uses a discovered config only when its directory is one no ordinary account can add or replace a file in — owned by Administrators/SYSTEM (or root), and not writable by anyone else.

This applies to every discovered location, per-user ones included. $HOME and $XDG_CONFIG_HOME are inputs an unprivileged account often controls, and sudo -E fastcached would otherwise take root's configuration from a file that account wrote. An unprivileged run is offered only its own files, so there is nothing there to vouch for and no check is applied.

It matters most on Windows, where C:\ProgramData lets every standard account create files in a new subdirectory. The installer creates C:\ProgramData\fastcached with an access list of its own, so a packaged install already satisfies this; a directory somebody else made first does not. When a config is skipped for this reason fastcached says so — on stderr, and in the log once the daemon has one — with the exact command that repairs it:

fastcached: C:\ProgramData\fastcached\fastcached.yaml: ignored: C:\ProgramData\fastcached
can be written by accounts other than the administrative ones, ...
Secure it with `icacls "C:\ProgramData\fastcached" /setowner *S-1-5-32-544 /inheritance:r ...`,
or name a config explicitly with --config.

--config=<path> is never checked this way — you named that file, which is your call to make.

What the file looks like

Every installed copy ships fully commented, with each setting shown at its built-in default, so an untouched file behaves exactly like running fastcached with no flags. Uncomment only what you want to change:

# bind: 127.0.0.1
# port: 6674
max_memory: 4g
storage_path: /var/lib/fastcached/cache

Every key is a command-line flag spelled with underscores, and it takes exactly the value the flag does: port: 0x50 is refused because --port=0x50 is, and listen: takes host:port like --listen. A flag that takes no value is true or false in the file — true passes the flag, false passes nothing — and no other word; yes and on are refused rather than guessed at. A key the daemon does not know, or a key written twice, stops it at startup naming the key and the line, so a typo is never a setting that silently fails to apply.

A release that changes the on-disk record layout refuses an older store at startup rather than mis-reading it. It is not damaged, and it does not have to be thrown away — see Upgrading a store.

Path-valued settings (storage_path, tls_cert, tls_key) understand $VAR and ${VAR} environment references in the file; write $$ for a literal dollar. On the command line your shell has already expanded them, so fastcached does not expand them again. A reference to a variable that is not set is an error rather than an empty string, so a typo fails loudly instead of quietly relocating the cache. Windows %VAR% is not expanded — a bare % is valid in a path.

Precedence

From strongest to weakest:

1. Command-line flags — --port=7000 beats everything.
2. The config file — whether named with --config or discovered.
3. Environment — only FASTCACHED_METRICS_PORT, so a container's daemon and its --healthcheck probe can agree on a port with one -e.
4. Built-in defaults.

Because a flag outranks the file for as long as it is on the command line, a service registered with a setting baked into its launch arguments will ignore that key in the file forever. This is why --install-service registers only what you typed, and why editing the config file is the way to change a running installation.

Reloading

systemctl reload fastcached (or SIGHUP directly, or the service manager's PARAMCHANGE on Windows) re-reads the file in place, without dropping connections. Only part of the configuration is reloadable:

Reloadable	Requires a restart
log_level, max_memory, requirepass, auth_username, notify_keyspace_events	bind, port, listen, listen_tls, storage_path, storage_shards, storage_durability, storage_max_value, threads, active_expiry_interval, active_expiry_scan

The right-hand column is live-wired at startup — listeners are bound and the storage backend is constructed once — so a reload that changes any of it is rejected in full, the previous configuration is kept, and the reason is logged. A reload therefore either applies everything or nothing.

Secrets

Keep requirepass in the config file, not on the command line: launch arguments are world-readable through the process table and through the service registration. --install-service refuses --requirepass outright for that reason.

On Linux and macOS, give the file mode 0640 and make it readable by the account the service runs as — which is what the macOS installer does to /opt/fastcached/etc/fastcached.yaml.

On Windows the installer does it for you, and the directory and the file are deliberately different. C:\ProgramData\fastcached is locked so that only SYSTEM and Administrators can write it — which is what the daemon's own trust check requires — while Users may still read it, the convention for %ProgramData%. The file does not inherit that: seeding gives fastcached.yaml an access list of its own, granting SYSTEM and Administrators full control and NT AUTHORITY\SERVICE read, and nothing else. The service reads it through that last entry.

Upgrading from a version that did not do this repairs the file, but only if it is still readable by every local account — a narrower grant you added yourself is left alone. Your edits are never touched either way. To check, or to repair a file you have re-created by hand:

icacls C:\ProgramData\fastcached\fastcached.yaml
icacls C:\ProgramData\fastcached\fastcached.yaml /inheritance:r `
       /grant *S-1-5-18:F /grant *S-1-5-32-544:F /grant *S-1-5-6:R

Raw SIDs rather than account names, because names are localised: S-1-5-18 is SYSTEM, S-1-5-32-544 is Administrators, and S-1-5-6 is NT AUTHORITY\SERVICE. Dropping that last grant leaves a file the service cannot read, and a daemon that cannot read its configuration starts on built-in defaults rather than failing.

Editing the installed file

LinuxmacOSWindows

sudoedit /etc/fastcached/fastcached.yaml
sudo systemctl reload fastcached     # or restart, for the non-reloadable keys

The file is a package config file (dpkg conffile / rpm %config(noreplace)), so your edits survive upgrades.

sudo vi /opt/fastcached/etc/fastcached.yaml
sudo launchctl kickstart -k system/software.lastrada.fastcached

Only the fastcached.yaml.default beside it is package payload; the live file is seeded from it once, when absent, and never replaced.

notepad C:\ProgramData\fastcached\fastcached.yaml   # elevated
sc.exe stop FastCached; sc.exe start FastCached

The MSI installs a fastcached.yaml.default template under the install directory and seeds %ProgramData% from it only when nothing is there yet, so a later upgrade does not discard your edits. The live file is deliberately not part of the installer payload, and uninstalling leaves it behind.

Per-user daemons

A personal cache needs no root and no packaged file at all — drop one in your own config directory and fastcached will find it:

mkdir -p ~/.config/fastcached
cp /etc/fastcached/fastcached.yaml ~/.config/fastcached/fastcached.yaml
systemctl --user restart fastcached