Please disclose if any significant portion of your mod was created using AI tools by adding the 'AI Generated' category. Failing to do so may result in the mod being removed from Thunderstore.
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
BepInEx pack for Valheim. Preconfigured with the correct entry point for mods and preferred defaults for the community.
Preferred version: 5.4.2360README
π‘οΈ DwarvenDefender
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.
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.
| 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. |
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.
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".
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 |
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
- Take the pack's packages exactly as players download them (not an admin's profile: it carries admin-only and server-only extras).
- For each package, make
BepInEx/config/DwarvenDefender/Whitelist/<Owner>-<Name>-<version>/and copy in every.dllfrom the package'splugins/andpatchers/folders. - Optional mods go the same way into
Greylist/. - Server-only and admin-only mods go on no list.
- Join with the pack, then open
reports/<your id>.txt: every line should sayWHITEorGREY. AnyNONEline 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
- 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.
- Update the modpack.
- 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?
- Lists laid out a folder per package, DLLs inside, drop straight in: copy them into
BepInEx/config/DwarvenDefender/Whitelist/andGreylist/, or pointList folderat the folder that holds them. - Add each package's patcher DLLs to its entry, or set
Check patchers = false. - Join with the pack and read your
reports/file: every line should sayWHITEorGREY.
| 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.
| 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. |
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. |
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 inWhitelist/is required, a DLL inGreylist/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
*.dllunder the client'sBepInEx/plugins/andBepInEx/patchers/(any depth), plus any loaded plugin outside them. Gale's disabled*.dll.oldfiles do not count; BepInExcore/is not checked. The report is sent inZNet.OnNewConnection, beforePeerInfo, on the same ordered channel. - The join check, a
Priority.Firstprefix onZNet.RPC_PeerInfoon the server. Refusal is vanilla's: the reason goes to the client, thenError(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_reloadforces 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 afterKick 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.txtplayers 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 hostingis 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.1at 5 MB) andreports/<id>.txt(each player's last report, every DLL markedWHITE/GREY/SELF/NONEwith 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) anddd_reload. Enabled(on): off = log what would be refused and refuse nobody.
Safety
- Each connection is judged once; a client that sends
PeerInfoagain 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
.oldfile, 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.