You are viewing a potentially older version of this package. View all versions.
RavenIronStudios-DwarvenDefender-0.1.0 icon

DwarvenDefender

Simple and effective mod enforcement for Valheim servers. Players must have every Whitelist mod, may have Greylist mods, and anything else is refused or kicked with the exact reason. Lists hot-reload, no restart.

Date uploaded 2 days ago
Version 0.1.0
Download link RavenIronStudios-DwarvenDefender-0.1.0.zip
Downloads 20
Dependency string RavenIronStudios-DwarvenDefender-0.1.0

This mod requires the following mods to function

denikson-BepInExPack_Valheim-5.4.2360 icon
denikson-BepInExPack_Valheim

BepInEx pack for Valheim. Preconfigured with the correct entry point for mods and preferred defaults for the community.

Preferred version: 5.4.2360

README

πŸ›‘οΈ DwarvenDefender

DWARVENDEFENDER VERSION BOTH SIDES

The dwarf at the gate does not care what you call your axe. He weighs it, he smells it, he counts the runes on the haft, and if it is not the axe written in his ledger you are not coming in. You may argue. He has been at this gate for three hundred years, and the ledger has never once been wrong.

Every player runs exactly your modpack. Anyone who does not is turned away, and told why.

Two folders on your server decide it. Whitelist: every player must have these. Greylist: players may have these. Anything else, and the player is refused at the door, or kicked on the spot if they are already inside.

Mods are matched by their contents, not their names, so renaming a DLL gets nobody past the gate. Change the folders while the server runs and the new rules apply within seconds. No restart.


NEW IN 0.1.0

Your modpack becomes the only way in.

A player… DwarvenDefender
has every Whitelist mod and nothing unlisted lets them in
is missing a Whitelist mod refuses them, naming the package they need
has a mod on neither list (renamed or not) refuses them, naming the file to remove
adds an unlisted patcher refuses that too
has no DwarvenDefender at all refuses them, as an incompatible version
is already playing when you tighten the lists gets 30 seconds' grace, then is kicked with the reason

πŸ”„ Hot reload: edit the folders live Β· 🧾 Reports: every player's full mod list, saved, so building your lists takes minutes Β· πŸ‘‘ Admins exempt, so you can test a new build before your players get it.


BEFORE YOU INSTALL

If… Then…
πŸ›‘ you put DwarvenDefender only on the server every player is refused. It goes in the modpack too: players need it to report their mods.
πŸ›‘ you put a server-only mod on the Whitelist every player is refused, because no player has it. Server-only mods go on no list.
⚠️ your pack has patchers add their DLLs to the package's entry too: DwarvenDefender checks patchers (or set Check patchers = false). Native DLLs are fine here.
🀝 you update DwarvenDefender update the server and the modpack together: players must run the server's exact build.
β›” another mod on the server also enforces a mod list keep one set of lists. Two gatekeepers with two ledgers refuse twice as many people.
πŸ” you need anti-cheat against a determined cheater this is not it. It enforces your mod list. A client built specifically to lie about its files can pass.

I

Two folders, one rule each.

Folder Means
πŸ“œ Whitelist/ every player must have every DLL in here
πŸ“ƒ Greylist/ a player may have these (optional mods, a second version during an update)
πŸ—‚οΈ One folder per package Owner-Name-version/ with the package's DLLs inside: the name is what players see in their refusal
πŸ” Matched by contents a SHA-256 of every file's bytes; the file and folder names are only labels
🧩 Patchers count DLLs under a player's BepInEx/patchers are held to the lists like plugins
πŸ—‘οΈ Gale's disabled mods don't count .dll.old files are ignored, exactly as BepInEx ignores them
πŸ“– Read the saga β€” why contents, and why nothing on a list is ever loaded

A name proves nothing: anyone can call a file Jotunn.dll. So every DLL a player runs is hashed on their machine, and the server compares those hashes with the hashes of the files in your folders. Two different builds of the same mod are two different files; one rebuild of a mod means a new file in its entry.

The server only ever reads the files on your lists. It never loads them. That matters because packs ship native DLLs (graphics layers, upscalers) next to their .NET ones: a list that tried to load those would fall over at the first one. Here they are just bytes to hash.

DwarvenDefender's own DLL needs no entry: the server allows its own build automatically, and the build is deterministic, so the same source always gives the same file.


II

Edit the folders while the server runs. No restart.

You It
Add, remove or replace an entry noticed within ~2 seconds, applied once the files stop changing
Copy a big pack in slowly waits for the copy to finish; a half-copied file is never used
Tighten the lists with players on 30 seconds' grace, then anyone still not matching is kicked, with the reason
Make a change in steps (remove the old entry, then copy the new one in) the grace re-checks against the lists as they stand then, so nobody is kicked by the gap
Delete a whole list folder by accident refused; the old lists stay. To clear a list, empty it
Type dd_reload rescans now
πŸ“– Read the saga β€” how it decides a change is finished

Every couple of seconds (and instantly when the file system says something moved) the server takes a quick fingerprint of both folders: every file's path, size and time. When the fingerprint changes it waits until it has held still for three seconds, hashes everything, and fingerprints again. Only if nothing moved while it was hashing do the new lists go live. New joins are judged by them from that moment.

A file that cannot be read (wrong permissions, say) keeps the old lists in force, warns once, and is retried every 30 seconds. A folder that vanishes, from a bad unmount or a slip of the delete key, is never taken to mean "allow nothing".


III

A refused player knows exactly what to fix.

The player sees
Missing (required) each Whitelist package they do not have, by its folder name and file
Not allowed (remove) each DLL on neither list, by its path in their BepInEx folder
Kicked + the same lists when your lists changed while they were playing
Incompatible version when they do not have DwarvenDefender at all
You see
🧾 reports/<steamid>.txt that player's every DLL, marked WHITE · GREY · SELF · NONE, with its hash and path
πŸ“’ rejections.log one line per refusal or kick: when, who, what was missing, what was extra
πŸ–₯️ dd_status the lists right now, and every connected player's state

THE TOOLBOX

First ten minutes: install on the server and in the modpack β†’ start the server once (it makes the two folders) β†’ fill Whitelist/ from your pack β†’ join with your pack β†’ check reports/ and the log.

Command Where
dd_status lists + every player's state in-game console (F5), as an admin runs on the server, answers you
dd_reload rescan the folders now in-game console (F5), as an admin runs on the server
πŸ› οΈ Building the lists from your modpack
  1. Take the pack's packages exactly as players download them (not an admin's profile: it carries admin-only and server-only extras).
  2. For each package, make BepInEx/config/DwarvenDefender/Whitelist/<Owner>-<Name>-<version>/ and copy in every .dll from the package's plugins/ and patchers/ folders.
  3. Optional mods go the same way into Greylist/.
  4. Server-only and admin-only mods go on no list.
  5. Join with the pack, then open reports/<your id>.txt: every line should say WHITE or GREY. Any NONE line is a file you missed. (As an admin you are let in regardless, so read the report rather than trusting the join.)
πŸ› οΈ Updating a mod without kicking everyone
  1. Put the new version's entry on the Greylist next to the old one, and move the old one from the Whitelist to the Greylist too. Both versions now get in.
  2. Update the modpack.
  3. Once players have updated, move the new entry to the Whitelist and delete the old one.

Admins can try the new version at any point: they are exempt.

πŸ› οΈ Already have Whitelist / Greylist folders?
  1. Lists laid out a folder per package, DLLs inside, drop straight in: copy them into BepInEx/config/DwarvenDefender/Whitelist/ and Greylist/, or point List folder at the folder that holds them.
  2. Add each package's patcher DLLs to its entry, or set Check patchers = false.
  3. Join with the pack and read your reports/ file: every line should say WHITE or GREY.

MULTIPLAYER

On the dedicated server In every player's game Single player / hosting from the menu
the lists, the checks, the kicks, the logs reports the player's mods; shows the refusal reason does nothing (unless you switch on Enforce when hosting)

⚠️ Builds must match. Players need the server's own DwarvenDefender build. Update the server and the pack together, or put the other build on the Greylist while you switch over.


COMPATIBILITY

Mod
β›” Other mod-list enforcers Keep one set of lists. Two enforcers refuse on two different ledgers.
ServerSync mods (most config-synced mods) No conflict: their version checks and DwarvenDefender's check run side by side.
Jotunn mods No conflict.
Gale / r2modman profiles Disabled mods (.old) are ignored. Install the pack as players do and it just works.
Graphics packs with native DLLs Fine on a list: native DLLs are hashed, never loaded.
Server-only mods (world tools, admin tools) Belong on no list; DwarvenDefender never looks at the server's own mods.

SETTINGS

All safe to leave alone. BepInEx/config/wubarrk.dwarvendefender.cfg on the server.

πŸ”’ Server β€” set on the dedicated server
Section Setting What it does
1 - General Enabled off = log who would be refused, refuse nobody
1 - General List folder where Whitelist/ and Greylist/ live (default DwarvenDefender, under BepInEx/config)
1 - General Exempt admins adminlist.txt players join with any mods
1 - General Check patchers hold patcher DLLs to the lists too
1 - General Enforce when hosting also enforce in a game hosted from the main menu
2 - Hot reload Kick on list change re-check connected players when the lists change
2 - Hot reload Kick grace seconds wait before those kicks (0 = at once)
2 - Hot reload Poll seconds how often the folders are checked
2 - Hot reload Settle seconds how long the folders must be still before a change applies
3 - Logging Save reports write each player's report to reports/
πŸ–₯️ Local to your game β€” nothing to set
Section Settings
β€” A player's copy has nothing to configure: it reports, and it shows the server's verdict.

CREDITS

Needs: BepInExPack Valheim

  • Wu'barrk: design, the server tooling and the live testing it was proven on.
  • Support Raven Iron. Every Raven Iron mod is free, and stays free: all of it, always. Nothing is held back for patrons, and nothing ever will be. To help cover server hosting and test hardware: the website Β· Patreon Β· Discord, a channel per mod and where the testing happens.

A Raven Iron mod. License: MIT. Use it, fork it, repackage it, ship it in a modpack; keep the copyright notice with it. The full text is in LICENSE.md.

CHANGELOG

Changelog

0.1.0

First release. A server-enforced mod-list check for Valheim 1.0.21 (network version 41). Runs on the dedicated server and on every client.

Added

  • Whitelist and Greylist folders under BepInEx/config/DwarvenDefender/ ([1 - General] List folder): every DLL in Whitelist/ is required, a DLL in Greylist/ is allowed, any other DLL refuses the player. One folder per package (<Owner>-<Name>-<version>/).
  • Content matching. Files are compared by SHA-256 of their bytes, never by name or folder. A list file is only hashed, never loaded, so native DLLs and patchers can sit on a list without breaking it.
  • What a client reports. Every *.dll under the client's BepInEx/plugins/ and BepInEx/patchers/ (any depth), plus any loaded plugin outside them. Gale's disabled *.dll.old files do not count; BepInEx core/ is not checked. The report is sent in ZNet.OnNewConnection, before PeerInfo, on the same ordered channel.
  • The join check, a Priority.First prefix on ZNet.RPC_PeerInfo on the server. Refusal is vanilla's: the reason goes to the client, then Error (ErrorVersion), and the connection is dropped after 3 s if the client keeps it open. A client without DwarvenDefender gets vanilla's "Incompatible version". A crash inside the check refuses the player instead of letting them in.
  • The reason on the player's screen: the connect-error (or kicked) dialog lists the missing Whitelist entries and the DLLs to remove, 12 of each at most.
  • Hot reload. The lists are polled every 2 s (Poll seconds), and a file watcher wakes the check early. A change applies once the folders have been unchanged for 3 s (Settle seconds), and only if they are still unchanged after hashing, so a half-copied DLL is never used. A list folder that disappears is refused (empty it to clear a list). A read error keeps the old lists, warns once and retries every 30 s. dd_reload forces a rescan.
  • Kick on list change ([2 - Hot reload] Kick on list change, on). After a change, connected players who no longer match are re-checked after Kick grace seconds (30) against the lists as they are then, and kicked with vanilla's kick and the reason. A change made in steps does not kick anyone by accident. New joins use the new lists at once.
  • Admins exempt (Exempt admins, on): adminlist.txt players join with any mods, and are not kicked on a reload.
  • Check patchers (on): patcher DLLs must be listed too. Off = patchers are reported and logged, never refused.
  • Dedicated servers only by default. A game hosted from the main menu enforces nothing unless Enforce when hosting is on.
  • DwarvenDefender's own DLL is allowed automatically by the server's own copy's hash. The build is deterministic, so the same source gives the same file. Clients must run the server's build; put another build on the Greylist to accept it too.
  • Logs. rejections.log (one line per refusal or kick, rotated to .1 at 5 MB) and reports/<id>.txt (each player's last report, every DLL marked WHITE / GREY / SELF / NONE with its hash and path; Save reports, on).
  • Admin console commands, run on the server from an admin's in-game console: dd_status (the lists and every connected player's state) and dd_reload.
  • Enabled (on): off = log what would be refused and refuse nobody.

Safety

  • Each connection is judged once; a client that sends PeerInfo again after a refusal is dropped at once, with no further logging. The report is capped at 4096 files; client-supplied paths and names are clipped and stripped of control characters and rich-text brackets before they reach a log or an admin's console.
  • Linux clients: paths are compared case-sensitively when building the report, so two folders differing only in case are both reported.

Tested

  • 36 unit tests on the list loader, watcher, report format and verifier.
  • A headless dedicated server (1.0.21, build 26266951) with hot reload exercised live: adding an entry, a slow copy (applied once, after it finished), deleting the Whitelist folder (refused) and restoring it.
  • The real 1.0.21 client against that server, driven unattended: compliant join, Greylist mod, Gale .old file, missing Whitelist mod, extra plugin, extra patcher, no DwarvenDefender, and a kick after a list change. All 8 pass.

Known limits

  • The client reports its own files: a client deliberately modified to send another pack's hashes can pass. This is a mod-list enforcer, not anti-cheat.
  • A same-size replacement that keeps the old file's modified time is not noticed until dd_reload.