pgl-Usage

How to use pgl

This page is the more general documentation for end-users. The internal working of pgl, intended for developers and advanced users, is decribed here.

pgl consists of three components: pgld, pglcmd and pglgui. Users control pgl

• either with the command line interface pglcmd and by editing pgl's or system configuration files
• or with the graphical user interface pglgui, which is an addon for these tasks. So pglgui is just an easy way to access the features of pglcmd and save your settings to pgl's or the system configuration files. This means, pgl works independently of pglgui: e.g. stopping pglgui does not stop pgl - but of course you can use pglgui to stop pgl.

pglcmd features

Most of these features can be accessed with pglgui or happen automatically.

• Start and stop pgl. Or let init do this automatically.
• Blocklist management:
  • Update your blocklists from online sources. Or let cron do this automatically on a regular basis.
  • Use local blocklists.
  • Remove lines by keyword from the blocklists.
  • Merge all these single blocklists into one master blocklist. This optimized master blocklist is the one really used by pgl.
• Handle your iptables rules:
  • use a default setup to get pgl working
  • easily allow all traffic on specific ports and use an allow list
  • add your own sophisticated iptables rules.
  • automatically allow all LAN traffic and the DNS server. If you are on a public LAN, you probably want to disable this feature.
• Check the status of and test pgl.
• A watchdog monitors pgl and restarts if necessary.
• Detects if kernel modules are needed and loads them if necessary.
• Set verbosity and logging options.
• Provides LSB 3.1 compatible init script.
• Daily rotation of the logfiles.

pglcmd usage

You need root privileges to manipulate pgl.

Command	Description
pglcmd start	inserts iptables rules and starts pgld. If the blocklist configuration changed, rebuild the master blocklist.
pglcmd stop	deletes iptables rules and stops pgld.
pglcmd restart	restarts pgl.
pglcmd reload	rebuilds the master blocklist and reload pgld if it is running.
pglcmd update	updates the blocklists, rebuilds the master blocklist and reloads pgld.
pglcmd status	gives the iptables settings and the status of pgld.
pglcmd test	does a simple test to check if pgl is working (pings a random IP in the blocklist and checks if this IP was logged in the pgld logfile and if it answered).
pglcmd search PATTERN	outputs the occurences of a keyword PATTERN and the names of the single blocklists. Use this to find out which blocklist caused an IP to be blocked.
pglcmd stats	reports pgld's statistics
pglcmd reset_stats	resets pgld's statistics
show_config	shows the current configuration settings.

Note for blocklist operations: When the master blocklist is built, missing single blocklists are downloaded. If any blocklist fails to download, and if there is no old version available, the operation aborts. If a downloaded blocklist fails to extract, it is deleted and the operation aborts.

pgl configuration

• Blocklists
  • Remote blocklists are configured in blocklists.list (/etc/pgl/blocklists.list).
  • Local blocklists are saved in the folder /etc/pgl/blocklists.local/.
  • The allowlist for IP ranges is allow.p2p (/etc/pgl/allow.p2p). Per default, the allowlist is used for incoming and outgoing connections. If desired different allow lists for incoming, outgoing and forward connections may be used.
• The rest is done in pglcmd.conf (/etc/pgl/pglcmd.conf). Refer to pglcmd.defaults (/usr/lib/[YOUR_ARCHITECTURE]/pgl/pglcmd.defaults) for the complete set of possible configuration variables with comments.
• Further the init, cron, logrotate and NetworkManager systems are used.