Skip to content

Latest commit

 

History

History
238 lines (184 loc) · 8.04 KB

wforce.1.md

File metadata and controls

238 lines (184 loc) · 8.04 KB
Raw

% WFORCE(1) % Open-Xchange % 2018

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)