WFORCE(1)
🌸 NAME 🌸
okay so bestie, meet wforce(1) — the daemon that sniffs out brute-force login attempts and enforces other policies for logins. it's literally the bouncer at the club door but for auth. 💅
✨ SYNOPSIS ✨
wforce [OPTION]...💖 DESCRIPTION 💖
wforce is a simple HTTP server that takes JSON formatted commands — you tell it about successful/unsuccessful logins, and you ask it whether a login should be allowed to proceed. that's the whole vibe check. 🫶
she can be both a client and a server, iconic behaviour honestly:
- as a server she typically runs under systemd control, but she can also run as a traditional daemon, or in 'interactive' mode.
- as a client, she connects to a
wforceserver and gives you the same interactive commands.
and the bestie is scriptable in Lua — check wforce.conf for a simple example, and wforce.conf.example for a more sophisticated one. in fact, all configuration is done using the Lua language, because wforce.conf is simply a Lua script. no cap. 🐍
🦋 SCOPE 🦋
wforce depends on the systems performing login authentication to integrate with it using the HTTP/JSON API. example clients of the API include Dovecot and OX AppSuite. 👑
she also provides a simple clustering mechanism by the process of configuring "siblings" in wforce.conf. all modifications to the blacklists or the string stats DB (either from Lua or the REST API) get replicated to all configured siblings. replication uses the UDP protocol, so if your siblings are not on a local subnet, you should ensure that any firewalls forward UDP on the configured ports. 🔥
💅 OPTIONS 💅
-c— act as a client, connecting to awforceinstance at the IP/Port specified in the'controlSocket'function inwforce.conf. a custom configuration file can be specified.-C,--config FILE— load configuration from FILE.-R,--regexes FILE— read device parsing regexes from FILE (usuallyregexes.yaml).-s— run in foreground, but do not spawn a console. use this switch to runwforceinside a supervisor (use with e.g. systemd and daemontools).-d,--daemon— operate as a daemon.-e,--execute CMD— connect towforceand execute CMD.-f,--facility FACILITY NAME— log using the specified facility name, e.g.local0-l,--loglevel <0-7>— logs sent to stdout will be filtered according to the specified log level, matching the equivalent syslog level (0- Emerg to7- Debug).-h,--help— display a helpful message and exit.
🎀 CONSOLE COMMANDS 🎀
these are the commands you can run from the console when wforce is started with the -c option. group chat energy only. 💬
makeKey()- returns a string to be used in thesetKey()function inwforce.confto authenticate sibling communications. all siblings must be configured with the same key.
> makeKey()
setKey("CRK+jKBpzXNLmM2A4C7OpFCBxiwpYlreCWgGEAIKAQI=")stats()- returns statistics about thewforceprocess. for example:
> stats()
40 reports, 8 allow-queries (% denies)siblings()- returns information about configured siblings. for example:
> siblings()
Address Send Successes Send Failures Rcv Successes Rcv Failures Note
127.0.0.1:4001 0 0 17 0
127.0.0.1:4002 0 0 0 0 SelfshowNamedReportSinks()- returns information about configured report sinks. for example:
> showNamedReportSinks()
Name Address Successes Failures
trackalert 192.168.1.79:4501 18 0
trackalert 192.168.1.30:4501 19 0
elasticsearch 10.22.2.15:4501 18 0
elasticsearch 10.22.2.16:4501 19 0showReportSinks()- deprecated — useshowNamedReportSinks()instead. returns information about configured report sinks. for example:
> showReportSinks()
Address Successes Failures
192.168.1.79:4501 18 7
192.168.1.30:4501 25 0showStringStatsDB()- returns information about configured stats databases. this includes the DB Name/number of shards, whether it is configured for replication, the size and number of windows, the maximum size, the current size, and finally all the configured fields and their types. for example:
> showStringStatsDB()
DB Name/Shards Repl? Win Size/No Max Size Cur Size Field Name Type
MyDB1/1 yes 1/15 524288 0 countLogins int
diffPasswords hll
MyDB2/10 no 600/6 5000 2093 diffIPs hllshowACL()- returns the configured ACLs for thewforceserver.
> showACL()
127.0.0.0/8
10.0.0.0/8
100.64.0.0/10
169.254.0.0/16
192.168.0.0/16
172.16.0.0/12
::1/128
fc00::/7
fe80::/10showWebHooks()- returns information about configured webhooks. for example:
> showWebHooks()
ID Successes Failures URL Events
1 5 2 http://localhost:8080/webhook/ report allowshowCustomWebHooks()- returns information about configured custom webhooks. for example:
> showCustomWebHooks()
ID Name Successes Failures URL
1 mycustomhook 10 0 http://localhost:8080/webhook/regressionshowCustomEndpoints()- returns information about configured custom endpoints. for example:
> showCustomEndpoints()
Custom Endpoint Send to Report Sink?
custom1 true
custom2 falseshowPerfStats()- (deprecated in favour of prometheus metrics — will be removed in a future version). returns information about performance statistics. stats beginning withWTWrefer to the time that worker threads waited in a queue before running. stats beginning withWTRrefer to the time that worker threads took to run. each stat is in a bucket, where each bucket represents a time range in ms, e.g.0-1. a server that is not overloaded will have most stats in the0-1buckets. stats are for the previous 5 minutes. for example:
> showPerfStats()
WTW_0_1=2939287
WTW_1_10=9722
WTW_10_100=4
WTW_100_1000=0
WTW_Slow=0
WTR_0_1=2939229
WTR_1_10=2837
WTR_10_100=131
WTR_100_1000=0
WTR_Slow=0showCommandStats()- (deprecated in favour of prometheus metrics — will be removed in a future version). returns information about the number of REST API commands that have been called, including custom endpoints. stats are for the previous 5 mins, and due to the counting method, may be approximate when the numbers get very large. for example:
> showCommandStats()
addBLEntry=0
allow=23942
delBLEntry=0
getBL=0
getDBStats=0
ping=300
report=19232
reset=24
stats=92
customEndpoint=2821showCustomStats()- (deprecated in favour of prometheus metrics — will be removed in a future version). returns information about custom stats that are incremented from Lua. stats are for the previous 5 mins, and due to the counting method, may be approximate when the numbers get very large. for example:
> showCustomStats()
custom1=0
custom2=8405reloadGeoIPDBs()- reload all GeoIP DBs that have been initialized. for example:
> reloadGeoIPDBs
reloadGeoIPDBs() successfulshowVersion()- returns the current version of thewforceserver. for example:
> showVersion()
wforce 1.2.0💀 BUGS 💀
ngl the replication function of clustering means that as more servers are added to a cluster, incremental performance gains may be less each time — eventually possibly leading to performance degradation. 😭 why? because each server keeps a full copy of the stats DBs and the blacklists, and changes to those are replicated to all siblings. you can mitigate this by partitioning siblings into smaller clusters that do not share information... but that comes at the expense of missing potential abuse activity. pick your struggle, bestie. 🙈
fr fr, read this one twice before you go scaling your cluster to the moon. 🚀
🔥 SEE ALSO 🔥
wforce.conf(5) wforce_webhook(5) wforce_api(7)
🫶 AUTHOR 🫶
Open-Xchange 2018
okay that's the whole page, go be iconic with it. 💜
this was the WFORCE(1) manual, dated 2026-07-28, and the source/version line up top says WFORCE — so yeah, that's the ✨ lore ✨. slay, periodt. 💅✨🎀
📦 where this page comes from
- ubuntu stonking: weakforced 3.0.0-5build2 · GPL-3.0-only
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms