Release ipfilter-v4.3

Release ipfilter-v4.3:
- add ipfilter.service and ipfilter.timer for system service setup (Linux with systemd only)
- add instructions for system service setup to README.md
- overhaul ipfilter.conf (comments only, no changes to configuration items)
- split SCREENSHOT.png into SCREENSHOT1.png and SCREENSHOT2.png (GitHub only)
- rename 'Windows Runtime Environments.md' to WINDOWS.md (KISS)
- apply other minor changes to README.md (URLs, wording, formatting)

Author: Fonic

CHANGELOG.md

@@ -1,3 +1,13 @@
+## Changelog for v4.3 release
+
+Changes:
+- added `ipfilter.service` and `ipfilter.timer` for system service setup (Linux with systemd only)
+- added instructions for system service setup to `README.md`
+- overhauled `ipfilter.conf` (comments only, no changes to configuration items)
+- split `SCREENSHOT.png` into `SCREENSHOT1.png` and `SCREENSHOT2.png` (GitHub only)
+- renamed `Windows Runtime Environments.md` to `WINDOWS.md` (KISS)
+- applied other minor changes to `README.md` (URLs, wording, formatting)
+
 ## Changelog for v4.2 release
 
 Changes:
@@ -70,4 +80,4 @@ Initial release
 
 ##
 
-_Last updated: 07/22/23_
+_Last updated: 08/25/23_

README.md

@@ -81,4 +81,4 @@ Refer to [Microsoft Learn](https://learn.microsoft.com/en-us/) articles _[Instal
 
 ##
 
-_Last updated: 08/13/23_
+_Last updated: 08/25/23_

SCREENSHOT.png

@@ -2,10 +2,10 @@
 
 # ------------------------------------------------------------------------------
 #                                                                              -
-#  IP Filter Updater & Generator                                               -
+#  IP Filter Updater & Generator (ipfilter)                                    -
 #                                                                              -
 #  Created by Fonic (https://github.com/fonic)                                 -
-#  Date: 04/15/19 - 08/10/23                                                   -
+#  Date: 04/15/19 - 08/25/23                                                   -
 #                                                                              -
 # ------------------------------------------------------------------------------
 
@@ -16,7 +16,7 @@
 VERBOSE_OUTPUT="false"
 
 # Path of file to log output to (folder + filename)
-# NOTE:    ${SCRIPT_DIR}: directory of 'ipfilter.sh' script, ${SCRIPT_NAME}: filename of 'ipfilter.sh' script without extension
+# NOTE:    ${SCRIPT_DIR}: directory where 'ipfilter.sh' is stored, ${SCRIPT_NAME}: name of file 'ipfilter.sh' without extension
 # Format:  String
 # Example: LOG_FILE="/var/log/ipfilter.log"
 # Default: LOG_FILE="${SCRIPT_DIR}/${SCRIPT_NAME}.log"
@@ -37,58 +37,59 @@ LOG_COLORS="false"
 
 # Options to pass to curl when downloading files
 # NOTE:    To debug download issues, temporarily remove option '--fail' and check contents of downloaded files for server messages
-# Format:  Bash array of strings
+# Format:  Array of strings
 # Example: CURL_OPTS=("--fail" "--location" "--silent" "--show-error" "--retry" "8" "--connect-timeout" "120" "--proxy" "<protocol>://<host>:<port>")
 # Default: CURL_OPTS=("--fail" "--location" "--silent" "--show-error" "--retry" "2" "--connect-timeout" "60")
 CURL_OPTS=("--fail" "--location" "--silent" "--show-error" "--retry" "2" "--connect-timeout" "60")
 
 # Options to pass to wget when downloading files
 # NOTE:    wget is used only if curl is not available; do not add option '--quiet' here as this will also suppress error messages
-# Format:  Bash array of strings
+# Format:  Array of strings
 # Example: WGET_OPTS=("--no-verbose" "--tries=9" "--timeout=120" "--execute" "use_proxy=yes" "--execute" "http_proxy=<host>:<port>")
 # Default: WGET_OPTS=("--no-verbose" "--tries=3" "--timeout=60")
 WGET_OPTS=("--no-verbose" "--tries=3" "--timeout=60")
 
-# List of blocklists to download from I-Blocklist (https://www.iblocklist.com/lists)
-# NOTE:    For possible ids, inspect link targets on page 'https://www.iblocklist.com/lists', e.g.
-#          'level1' -> 'https://www.iblocklist.com/list?list=ydxerpxkpcfqjaybcssw' -> id is 'ydxerpxkpcfqjaybcssw'
-# Format:  Bash dictionary of name-id-pairs (string-string-pairs)
+# List of blocklists to download from I-Blocklist (https://www.iblocklist.com)
+# NOTE:    To identify valid ids, inspect hyperlink targets or column 'Update URL' on this web page: https://www.iblocklist.com/lists
+#          e.g. 'level1' -> 'https://www.iblocklist.com/list?list=ydxerpxkpcfqjaybcssw' -> id is 'ydxerpxkpcfqjaybcssw' -> ["level1"]="ydxerpxkpcfqjaybcssw"
+# Format:  Array of name-id-pairs (i.e. string-string-pairs)
 # Example: IBL_LISTS=(["badpeers"]="cwworuawihqvocglcoss" ["adservers"]="zhogegszwduurnvsyhdf")
 # Default: IBL_LISTS=(["level1"]="ydxerpxkpcfqjaybcssw" ["level2"]="gyisgnzbhppbvsphucsw" ["level3"]="uwnukjqktoggdknzrhgh")
 IBL_LISTS=(["level1"]="ydxerpxkpcfqjaybcssw" ["level2"]="gyisgnzbhppbvsphucsw" ["level3"]="uwnukjqktoggdknzrhgh")
 
-# License key to use to download GeoLite2 country blocks database
-# NOTE:    See 'https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases/' for details
-#          License key is required in order to use the GeoLite2 feature
+# License key to use to download GeoLite2 country blocks database (https://dev.maxmind.com/geoip)
+# NOTE:    A valid license key is required to use the GeoLite2 feature, see URL below for details:
+#          https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases/
 # Format:  String
 # Example: GL2_LICENSE="1a2b3c4d5e6f7g8h"
 # Default: GL2_LICENSE=""
 GL2_LICENSE=""
 
-# List of countries to block using GeoLite2 country blocks
-# NOTE:    For a list of country names, download ZIP archive from URL below and inspect file 'geolite2-country-locations-en.csv':
-#          'https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country-CSV&license_key=<your-gl2-license-key>&suffix=zip'
-# Format:  Bash array of strings
-# Example: GL2_COUNTRIES=("Tomorrowland" "Middle-earth")
+# List of countries to block using GeoLite2 country blocks (https://dev.maxmind.com/geoip)
+# NOTE:    For a list of valid country names, download ZIP archive from URL below and inspect file 'geolite2-country-locations-en.csv':
+#          https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-Country-CSV&license_key=<your-gl2-license-key>&suffix=zip
+# Format:  Array of strings
+# Example: GL2_COUNTRIES=("Tomorrowland" "Soldier Island" "Wonderland")
 # Default: GL2_COUNTRIES=()
 GL2_COUNTRIES=()
 
-# IP protocol versions to process for GeoLite2 country blocks
-# Format:  Bash array of strings
+# IP protocol versions to process for GeoLite2 country blocks (https://dev.maxmind.com/geoip)
+# NOTE:    Only few applications actually support and recognize IPv6 ranges in .p2p files
+# Format:  Array of strings
 # Example: GL2_IPVERS=("IPv4") | GL2_IPVERS=("IPv6") | GL2_IPVERS=("IPv4" "IPv6")
 # Default: GL2_IPVERS=("IPv4")
 GL2_IPVERS=("IPv4")
 
 # Path to install final output file to (folder + filename)
-# NOTE:    ${SCRIPT_DIR}: directory of 'ipfilter.sh' script, ${SCRIPT_NAME}: filename of 'ipfilter.sh' script without extension
-#          Correct file extension will be determined automatically, there is no need to modify this when changing COMP_TYPE
+# NOTE:    ${SCRIPT_DIR}: directory where 'ipfilter.sh' is stored, ${SCRIPT_NAME}: name of file 'ipfilter.sh' without extension
+#          Correct file extension will be determined automatically, there is no need to modify this when changing 'COMP_TYPE'
 # Format:  String
 # Example: INSTALL_DST="/tmp/blocklist.p2p"
 # Default: INSTALL_DST="${SCRIPT_DIR}/${SCRIPT_NAME}.p2p"
 INSTALL_DST="${SCRIPT_DIR}/${SCRIPT_NAME}.p2p"
 
 # Type of compression to apply to final output file (in-place)
-# NOTE:    Correct file extension will be determined automatically, there is no need to modify INSTALL_DST when changing this
+# NOTE:    Correct file extension will be determined automatically, there is no need to modify 'INSTALL_DST' when changing this
 # Format:  String
 # Example: COMP_TYPE="none" | COMP_TYPE="gzip" | COMP_TYPE="bzip2" | COMP_TYPE="xz" | COMP_TYPE="zip"
 # Default: COMP_TYPE="none"

SCREENSHOT1.png

@@ -0,0 +1,63 @@
+# /etc/systemd/system/ipfilter.service
+
+# ------------------------------------------------------------------------------
+#                                                                              -
+#  IP Filter Updater & Generator (ipfilter)                                    -
+#                                                                              -
+#  Created by Fonic (https://github.com/fonic)                                 -
+#  Date: 04/15/19 - 08/25/23                                                   -
+#                                                                              -
+#  For detailed information regarding systemd units, see:                      -
+#  man systemd.exec, man systemd.unit, man systemd.service                     -
+#                                                                              -
+#  Run the following command after applying changes to this file:              -
+#  $ systemctl daemon-reload                                                   -
+#                                                                              -
+# ------------------------------------------------------------------------------
+
+# NOTE:
+#
+# - Replace all '%{...}' tokens with appropriate values, then copy or move this
+#   file to folder '/etc/systemd/system' and run the following command to make
+#   systemd recognize the newly added service (mandatory):
+#   $ systemctl daemon-reload
+#
+# - To have IP Filter send desktop notifications informing about success/failure
+#   of update runs, enable the 'ExecStart=...' line containing '--notify' and
+#   disable the other one (optional, recommended for use on desktop machines)
+#
+# - To restart applications that use the generated '.p2p' file after it has been
+#   successfully generated/updated by IP Filter, edit and enable one or more of
+#   the 'ExecStartPost=[+]...' lines (optional)
+
+[Unit]
+Description=IP Filter Updater & Generator
+Wants=network-online.target
+After=local-fs.target network-online.target nss-lookup.target
+
+[Service]
+Type=oneshot
+
+User=%{USER}
+Group=%{GROUP}
+
+WorkingDirectory=%{HOME}
+#ExecStart=%{HOME}/ipfilter.sh --notify
+ExecStart=%{HOME}/ipfilter.sh
+StandardOutput=file:%{HOME}/ipfilter.stdout.log
+StandardError=file:%{HOME}/ipfilter.stderr.log
+
+# Restart applications that use the generated '.p2p' after it has been success-
+# fully updated by IP Filter (add a '+' after 'ExecStartPost=' if the specified
+# command requires root privileges)
+#ExecStartPost=+/usr/bin/systemctl restart appname.service
+#ExecStartPost=+/path/to/root/app/executable --restart
+#ExecStartPost=/path/to/user/app/executable --restart
+
+# Allow up to 15min for an IP Filter run to complete (this prevents the job from
+# hanging indefinitely if something goes wrong; when the timeout is exceeded, IP
+# Filter receives SIGTERM and should shut down gracefully)
+TimeoutStartSec=900
+
+[Install]
+WantedBy=multi-user.target

SCREENSHOT2.png

@@ -2,10 +2,10 @@
 
 # ------------------------------------------------------------------------------
 #                                                                              -
-#  IP Filter Updater & Generator                                               -
+#  IP Filter Updater & Generator (ipfilter)                                    -
 #                                                                              -
 #  Created by Fonic (https://github.com/fonic)                                 -
-#  Date: 04/15/19 - 08/10/23                                                   -
+#  Date: 04/15/19 - 08/25/23                                                   -
 #                                                                              -
 # ------------------------------------------------------------------------------
 

Windows Runtime Environments.md renamed to WINDOWS.md

@@ -0,0 +1,42 @@
+# /etc/systemd/system/ipfilter.timer
+
+# ------------------------------------------------------------------------------
+#                                                                              -
+#  IP Filter Updater & Generator (ipfilter)                                    -
+#                                                                              -
+#  Created by Fonic (https://github.com/fonic)                                 -
+#  Date: 04/15/19 - 08/25/23                                                   -
+#                                                                              -
+#  For detailed information regarding systemd units, see:                      -
+#  man systemd.exec, man systemd.unit, man systemd.service, man systemd.timer  -
+#                                                                              -
+#  Run the following command after applying changes to this file:              -
+#  $ systemctl daemon-reload                                                   -
+#                                                                              -
+# ------------------------------------------------------------------------------
+
+# NOTE:
+#
+# - Copy or move this file to folder '/etc/systemd/system' and run the following
+#   command to make systemd recognize the newly added timer (mandatory):
+#   $ systemctl daemon-reload
+#
+# - Items 'OnCalendar', 'RandomizedDelaySec' and 'Persistent' may be customized
+#   to fit the specific use case (optional)
+
+[Unit]
+Description=Timer for IP Filter Updater & Generator
+
+[Timer]
+# Run IP Filter on every day of every month of every year at 03:00am within a
+# 30min window (i.e. run at a randomly chosen time between 03:00am and 03:30am)
+OnCalendar=*-*-* 03:00:00
+RandomizedDelaySec=1800
+
+# Save last time timer was triggered and trigger immediately if a run has been
+# missed (e.g. due to system being offline during the time when the timer would
+# have normally been triggered)
+Persistent=true
+
+[Install]
+WantedBy=timers.target