Provided by: weakforced_2.10.2-1build1_amd64 
NAME
wforce - daemon to detect brute-force login attempts and enforce other policies for logins
SYNOPSIS
wforce [OPTION]...
DESCRIPTION
wforce implements a simple HTTP server that accepts JSON formatted commands that report
successful/unsuccessful logins and query whether a login should be allowed to proceed.
wforce can act as both a client and server. As a server it typically runs under systemd control,
although it can also be run as a traditional daemon or in `interactive' mode. As a client, it connects
to a wforce server and provides the same interactive commands.
wforce is scriptable in Lua, see the wforce.conf file for a simple example, and wforce.conf.example for a
more sophisticated example. In fact all configuration is done using the Lua language, as wforce.conf is
simply a Lua script.
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.
wforce provides a simple clustering mechanism through 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) will be replicated to all configured siblings. Replication uses the UDP protocol, so if 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 a wforce instance at the IP/Port specified in the `controlSocket'
function in wforce.conf. A custom configuration file can be specified.
-C,–config FILE
Load configuration from FILE.
-R,–regexes FILE
Read device parsing regexes from FILE (usually regexes.yaml).
-s Run in foreground, but do not spawn a console. Use this switch to run wforce inside a supervisor
(use with e.g. systemd and daemontools).
-d,–daemon
Operate as a daemon.
-e,–execute CMD
Connect to wforce and 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 to 7 - Debug).
-h,–help
Display a helpful message and exit.
CONSOLE COMMANDS
The following commands can be run from the console when wforce is started with the -c option.
• makeKey() - Returns a string to be used in the setKey() function in wforce.conf to authenticate sibling
communications. All siblings must be configured with the same key.
> makeKey()
setKey("CRK+jKBpzXNLmM2A4C7OpFCBxiwpYlreCWgGEAIKAQI=")
• stats() - Returns statistics about the wforce process. 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 Self
• showNamedReportSinks() - 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 0
• showReportSinks() - Deprecated - use showNamedReportSinks() 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 0
• showStringStatsDB() - 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 hll
• showACL() - Returns the configured ACLs for the wforce server.
> 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::/10
• showWebHooks() - Returns information about configured webhooks. For example:
> showWebHooks()
ID Successes Failures URL Events
1 5 2 http://localhost:8080/webhook/ report allow
• showCustomWebHooks() - Returns information about configured custom webhooks. For example:
> showCustomWebHooks()
ID Name Successes Failures URL
1 mycustomhook 10 0 http://localhost:8080/webhook/regression
• showCustomEndpoints() - Returns information about configured custom endpoints. For example:
> showCustomEndpoints()
Custom Endpoint Send to Report Sink?
custom1 true
custom2 false
• showPerfStats() - (Deprecated in favour of prometheus metrics - will be removed in a future version).
Returns information about performance statistics. Stats beginning with WTW refer to the time that
worker threads waited in a queue before running. Stats beginning with WTR refer 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 the 0-1 buckets. 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=0
• showCommandStats() - (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=2821
• showCustomStats() - (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=8405
• reloadGeoIPDBs() - Reload all GeoIP DBs that have been initialized. For example:
> reloadGeoIPDBs
reloadGeoIPDBs() successful
• showVersion() - Returns the current version of the wforce server. For example:
> showVersion()
wforce 1.2.0
BUGS
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. This is
because each server keeps a full copy of the stats DBs and the blacklists, and changes to those are
replicated to all siblings. This can be mitigated by partitioning siblings into smaller clusters that do
not share information, at the expense of missing potential abuse activity.
SEE ALSO
wforce.conf(5) wforce_webhook(5) wforce_api(7)
AUTHORS
Open-Xchange.
2018 WFORCE(1)