diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..936591b --- /dev/null +++ b/readme.md @@ -0,0 +1,163 @@ +################################################################### +# Fresh Installation Guide +################################################################### + +1) Create a new user (we'll call ours "_pfbadhost"): + The user should be created with a default shell of "nologin", home folder + set to /var/empty/ with no password specified (disables password logins) + # useradd -s /sbin/nologin -d /var/empty _pfbadhost + +2) Download script: + $ ftp https://geoghegan.ca/pub/pf-badhost/0.5/pf-badhost.sh + +3) Install script with appropriate permissions: + # install -m 755 -o root -g bin pf-badhost.sh /usr/local/bin/pf-badhost + +4) Create required files: + # install -m 640 -o _pfbadhost -g wheel /dev/null /etc/pf-badhost.txt + # install -d -m 755 -o root -g wheel /var/log/pf-badhost + # install -m 640 -o _pfbadhost -g wheel /dev/null /var/log/pf-badhost/pf-badhost.log + # install -m 640 -o _pfbadhost -g wheel /dev/null /var/log/pf-badhost/pf-badhost.log.0.gz + +5) OPTIONAL: Install RipGrep and mawk for greatly improved performance: + Note: RipGrep is not available on all CPU architectures, use 'ggrep' if affected. + # pkg_add ripgrep mawk + +6) Give user "_pfbadhost" strict doas permission for the exact commands the + script needs run as superuser. NOTE: Unlike "sudo", _ALL_ users must be + explicitly granted permission to use doas, even the root user. + + $ cat /etc/doas.conf + ... + permit root + permit nopass _pfbadhost cmd /sbin/pfctl args -nf /etc/pf.conf + permit nopass _pfbadhost cmd /sbin/pfctl args -t pfbadhost -T replace -f /etc/pf-badhost.txt + # Optional rule for authlog scanning + permit nopass _pfbadhost cmd /usr/bin/zcat args -f /var/log/authlog /var/log/authlog.0.gz + ... + +7) Add the following lines to your pf.conf: + (Putting it higher-up/earlier in the ruleset is recommended) + ... + table persist file "/etc/pf-badhost.txt" + block in quick on egress from + block out quick on egress to + ... + +8) To enable additional features such as IPv6, Subnet Aggregation, Geo-Blocking, + Bogon Filtering or Authlog Scanning open "/usr/local/bin/pf-badhost" with + your text editor of choice and find the "User Configuration Area" near the top + of the file where you can enable features by setting their value to "1" + --- + Most options can also be configured via command line flags. See man page for more details. + --- + See the "Notes" section below for more info on installing optional utilities. + +9) Run pfbadhost as user "_pfbadhost" using the "-O openbsd" argument: + # doas -u _pfbadhost pf-badhost -O openbsd + +10) Reload your pf rule set: + # pfctl -f /etc/pf.conf + +11) For good measure, we'll run pf-badhost once more: + # doas -u _pfbadhost pf-badhost -O openbsd + +12) Edit _pfbadhost users crontab to run pf-badhost every night: + # crontab -u _pfbadhost -e + ... + ~ 0~1 * * * -s pf-badhost -O openbsd + ... + +Note: + If you're running an OpenBSD release older than 6.7 you'll have to use a workaround: + ... + @daily sleep $(echo $((RANDOM\%7200+1))) ; pf-badhost -O openbsd + ... + Please see the crontab(5) man page for further info + + +Yay! pf-badhost is now installed! + +With the nightly cron job, the list will be regularly updated with +the latest known bad hosts. + +Please read the man page for information on how to configure pf-badhost. +The manpage can be found here: https://www.geoghegan.ca/pub/pf-badhost/0.5/man/man.txt + +To receive notification of new pf-badhost releases and updates please send an email +to 'announce@geoghegan.ca' with a subject line and body of "subscribe pf-badhost" + + +################################################################### +# Post Install Notes: +################################################################### + +X) To add custom rules or enable features, or add alternate blocklists, + See the "User Configuration Area" located at the top of the script. + This area serves as a built in config file, so please feel free to + edit it and experiment with all the features available within. + --- + Note: Most options can also be configured from the command line + +X) Regarding Cron Jobs: + Over the past year I've noticed a number of list host servers + going down at midnight in populated timezones (ie West Coast, + East Coast and Western Europe). To be respectful (and to avoid + overloading list providers servers) we have cron jobs + scheduled to run at a random time within a defined interval. + --- + With the new default cron job, pf-badhost will be run every + night at some point between midnight and 2AM, and thus + distributing the load of thousands of queries from numerous + users over a 2 hour period rather than a matter of seconds. + + +1) The script is able to detect which (if any) subnet aggregation utilities are + installed and will try to "Do The Right Thing(tm)" and fallback to the best + available option. If no subnet aggregation utility is found, the script + will fallback to using a pure Perl IPv4 aggregator if Perl is installed. + Despite its name, "aggregate6" supports both IPv4 and IPv6 addresses and is + written in Python, whereas the "aggregate" utility supports only IPv4 + addresses and is written in C and uses significantly less memory but runs much + slower. For greatly improved performance, aggregate6 can be run with Pypy. + If both utilities are installed, the C based "aggregate" utility will be + preferred for IPv4 aggregation, but the script will happily function if only + one or the other is installed (or neither). + --- + Note: Subnet aggregation can be enabled with the '-A' switch on the commandline. + + * "aggregate" can be installed via: # pkg_add aggregate + * "aggregate6" can be installed via: # pkg_add aggregate6 + + * For greatly improved aggregation performance, run aggregate6 with Pypy: + # pkg_add pypy + # pypy -m pip install wheel aggregate6 + # ln -s /usr/local/pypy/bin/aggregate6 /usr/local/bin/aggregate6 + + * The experimental aggregator "aggy" can be installed like so: + ... + # pkg_add go + $ ftp https://geoghegan.ca/pub/aggy/0.1/aggy.go + $ go build aggy.go + # install -m 755 -o root -g bin aggy /usr/local/bin/aggy + ... + + +2) If you would like to update pf-badhost blocklists at a more frequent interval + you can use a modified cron job: + --- + It is essential that you make use of the crontab randomization feature to + ensure use of pf-badhost remains respecful of blocklist provider resources. + --- + The following example runs pf-badhost every 3 hours at a random minute + (this avoids flooding the server with traffic at exactly XX:00) + --- + Run pf-badhost every 3 hours Example: (you can change '/3' to '/4' to run every 4 hours) + Note: Use of the '-s' switch prevents 2 instances of pf-badhost from being run + at the same time - which is a good thing. + + # crontab -u _pfbadhost -e + ... + ~ */3 * * * -s pf-badhost -O openbsd + ... +