Advanced configuration

Nearly everything is in the app, and the app is the right place to change it. This page is for the handful of settings that are not, and for anyone managing machines from a configuration tool rather than by hand.

Where the file lives

There is also a per-user file for the command-line and terminal tools when they run outside the service, under ~/.config/nyxbackup/ on Linux and the equivalent on other systems. The service’s own file, above, is the one that drives scheduled backups.

Stop the service before editing

This matters more than it usually does.

The service never reloads this file while running, so an edit does nothing until a restart. And the service rewrites the whole file from what it holds in memory whenever anything changes it - saving a set from the app, and once at startup if it finds credentials that need moving into the OS keystore. A rewrite reflects what the service loaded when it started, so any edit you made after that is discarded silently.

So:

# Linux
sudo systemctl stop nyx-backup
sudo nano /etc/nyxbackup/config.toml
sudo systemctl start nyx-backup

# macOS
sudo launchctl bootout system/com.nyxbackup.daemon
sudo nano "/Library/Application Support/NyxBackup/config.toml"
sudo launchctl bootstrap system /Library/LaunchDaemons/com.nyxbackup.daemon.plist

# Windows (elevated)
net stop NyxBackupSvc
notepad C:\ProgramData\NyxBackup\config.toml
net start NyxBackupSvc

Keep a copy before you start. A file that does not parse will stop the service starting, and the quickest fix is putting the old one back.

Never put credentials in this file

Storage keys and passwords belong in the operating system’s credential store, and Nyx Backup puts them there. If it finds a plain access_key_id or secret_access_key in config.toml it moves them into the keystore on the next start and rewrites the file without them - which is one of the rewrites described above.

Add a destination through the app so its credentials go straight to the keystore. The file keeps only a reference.

Settings with no equivalent in the app

Most of what follows is per-set, inside a [[backup_set]] block.

exclude_extensions

Skip files by extension across an entire set. There is no screen for this in either interface, so the file is the only way to set it:

[[backup_set]]
name = "Documents"
exclude_extensions = ["iso", "vmdk", "tmp"]

Extensions only, without the dot, matched case-sensitively against the file’s final extension. For anything more expressive use a pattern - see Customising exclusions.

The service preserves this setting when the app or the terminal interface saves a set, precisely because neither can express it.

max_pack_bytes and cpu_sleep

max_pack_bytes sets how much data is bundled into each uploaded object. Leave it at 0, which means automatic: the engine picks a size at the start of every run from the memory and cores actually available, which is almost always better than a fixed value. Set it only to work around a provider with an unusual object-size limit.

cpu_sleep inserts a pause between files. It exists for the background priority setting and slows small-file workloads considerably - three to five times is normal. Use the priority setting in the app instead.

Global settings worth knowing

These sit at the top of the file, outside any [[backup_set]] block. All are in the app’s Settings screen too; they are listed here for anyone deploying machines from a script.

machine_id, format_version, owner_identity and kdf_params are managed by Nyx Backup. Changing machine_id in particular will orphan the backups already stored under it - every object is namespaced by that identifier.

Deploying to several machines

Install, let the service start once so it writes a valid file with its own machine_id, then push your settings in with the service stopped. Do not copy one machine’s config.toml wholesale onto another: they would share a machine_id and write into the same namespace at the destination.

Exclusions are the exception, and the better route - a drop-in file under exclusions.d is designed for exactly this and survives upgrades. See Customising exclusions.