You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

95 lines
5.4 KiB

  1. # banIP - ban incoming and/or outgoing ip adresses via ipsets
  2. ## Description
  3. IP address blocking is commonly used to protect against brute force attacks, prevent disruptive or unautherized address(es) from access or it can be used to restrict access to or from a particular geographic area — for example.
  4. ## Main Features
  5. * support many IP blocklist sources (free for private usage, for commercial use please check their individual licenses):
  6. * zero-conf like automatic installation & setup, usually no manual changes needed
  7. * supports four different download utilities: uclient-fetch, wget, curl, aria2c
  8. * Really fast downloads & list processing as they are handled in parallel as background jobs in a configurable 'Download Queue'
  9. * full IPv4 and IPv6 support
  10. * ipsets (one per source) are used to ban a large number of IP addresses
  11. * supports blocking by ASN numbers
  12. * supports blocking by iso country codes
  13. * supports local white & blacklist (IPv4, IPv6 & CIDR notation), located by default in /etc/banip/banip.whitelist and /etc/banip/banip.blacklist
  14. * auto-add unsuccessful ssh login attempts to 'dropbear' or 'sshd' to local blacklist (see 'ban_autoblacklist' option)
  15. * auto-add the uplink subnet to local whitelist (see 'ban_autowhitelist' option)
  16. * per source configuration of SRC (incoming) and DST (outgoing)
  17. * integrated IPSet-Lookup
  18. * integrated RIPE-Lookup
  19. * blocklist source parsing by fast & flexible regex rulesets
  20. * minimal status & error logging to syslog, enable debug logging to receive more output
  21. * procd based init system support (start/stop/restart/reload/refresh/status)
  22. * procd network interface trigger support
  23. * automatic blocklist backup & restore, they will be used in case of download errors or during startup
  24. * output comprehensive runtime information via LuCI or via 'status' init command
  25. * strong LuCI support
  26. * optional: add new banIP sources on your own
  27. ## Prerequisites
  28. * [OpenWrt](https://openwrt.org), tested with the stable release series (19.07) and with the latest snapshot
  29. * a download utility:
  30. * to support all blocklist sources a full version with ssl support of 'wget', 'uclient-fetch' with one of the 'libustream-*' ssl libraries, 'aria2c' or 'curl' is required
  31. ## Installation & Usage
  32. * install 'banip' (_opkg install banip_)
  33. * at minimum configure the needed IP blocklist sources, the download utility and enable the banIP service in _/etc/config/banip_
  34. * control the banip service manually with _/etc/init.d/banip_ start/stop/restart/reload/refresh/status or use the LuCI frontend
  35. ## LuCI banIP companion package
  36. * it's recommended to use the provided LuCI frontend to control all aspects of banIP
  37. * install 'luci-app-banip' (_opkg install luci-app-banip_)
  38. * the application is located in LuCI under 'Services' menu
  39. ## banIP config options
  40. * usually the pre-configured banIP setup works quite well and no manual overrides are needed
  41. * the following options apply to the 'global' config section:
  42. * ban\_enabled => main switch to enable/disable banIP service (bool/default: '0', disabled)
  43. * ban\_automatic => determine the L2/L3 WAN network device automatically (bool/default: '1', enabled)
  44. * ban\_fetchutil => name of the used download utility: 'uclient-fetch', 'wget', 'curl', 'aria2c', 'wget-nossl'. 'busybox' (default: 'uclient-fetch')
  45. * ban\_iface => space separated list of WAN network interface(s)/device(s) used by banIP (default: automatically set by banIP ('ban_automatic'))
  46. * the following options apply to the 'extra' config section:
  47. * ban\_debug => enable/disable banIP debug output (bool/default: '0', disabled)
  48. * ban\_nice => set the nice level of the banIP process and all sub-processes (int/default: '0', standard priority)
  49. * ban\_triggerdelay => additional trigger delay in seconds before banIP processing begins (int/default: '2')
  50. * ban\_backupdir => target directory for banIP backups (default: '/tmp')
  51. * ban\_sshdaemon => select the SSH daemon for logfile parsing, 'dropbear' or 'sshd' (default: 'dropbear')
  52. * ban\_starttype => select the used start type during boot, 'start' or 'reload' (default: 'start')
  53. * ban\_maxqueue => size of the download queue to handle downloads & IPSet processing in parallel (int/default: '4')
  54. * ban\_fetchparm => special config options for the download utility (default: not set)
  55. * ban\_autoblacklist => store auto-addons temporary in ipset and permanently in local blacklist as well (bool/default: '1', enabled)
  56. * ban\_autowhitelist => store auto-addons temporary in ipset and permanently in local whitelist as well (bool/default: '1', enabled)
  57. ## Examples
  58. **receive banIP runtime information:**
  59. <pre><code>
  60. /etc/init.d/banip status
  61. ::: banIP runtime information
  62. + status : enabled
  63. + version : 0.2.0
  64. + fetch_info : /bin/uclient-fetch (libustream-ssl)
  65. + ipset_info : 11 IPSets with overall 118359 IPs/Prefixes
  66. + backup_dir : /tmp
  67. + last_run : 09.09.2019 16:49:40
  68. + system : UBNT-ERX, OpenWrt SNAPSHOT r10962-c19b9f9a26
  69. </code></pre>
  70. **cronjob for a regular IPSet blocklist update (/etc/crontabs/root):**
  71. <pre><code>
  72. 0 06 * * * /etc/init.d/banip reload
  73. </code></pre>
  74. ## Support
  75. Please join the banIP discussion in this [forum thread](https://forum.openwrt.org/t/banip-support-thread/16985) or contact me by mail <dev@brenken.org>
  76. ## Removal
  77. * stop all banIP related services with _/etc/init.d/banip stop_
  78. * optional: remove the banip package (_opkg remove banip_)
  79. Have fun!
  80. Dirk