How foobaroy/foomuuri works
Project Overview and Purpose
• Foomuuri is a firewall tool that leverages nftables to provide bidirectional (incoming, outgoing, and forwarding) firewall functionality.
• It supports advanced features such as zone-based filtering, macros, templates in its rule language, logging, rate limiting, dynamic IP list updates, geolocation, and multi-ISP monitoring.
• The project also includes integration points for systemd (via various service and timer unit configurations) and firewalld (for systems using NetworkManager’s zone support).
Analyzing the File Structure
• Core Sources: The firewall’s main logic is in the src/foomuuri folder. This is where the firewall engine – including parsing of the firewall rule language and interfacing with nftables – would reside.
• Configuration Files: The etc directory holds default and static configuration files (like “50-foomuuri.conf”) that likely determine runtime behavior.
• Integration with External Systems:
• The systemd directory contains service definitions (e.g., fi.foobar.Foomuuri1.conf, foomuuri.service, timers, etc.) used for service management and scheduled tasks.
• The firewalld directory has configuration files integrating with FirewallD, providing support for NetworkManager’s zone-based configurations.
• Documentation & Tests:
• The doc folder includes manuals, example scripts, and command-line examples.
• The test directory holds multiple configuration examples (organized by scenario such as “host”, “router”, “multi-isp”, etc.) along with “golden” output files for automated testing.
Guiding Principles
• Main components and their relationships:
a. Core Firewall Engine – Represented by the code in src/foomuuri. This is where firewall logic, rule parsing, and translation to nftables commands happens.
b. Configuration Management – Capturing both the static configuration files (in etc) and the dynamic rule language (macros/templates).
c. Integration Layers:
• systemd Integration – Represent service units and timers that start, monitor, and schedule firewall tasks.
• firewalld Integration – Represent the connection to FirewallD and its configuration for seamless integration with systems using NetworkManager.
d. API & External Interfaces – Highlight the D-Bus API provided by Foomuuri, which may interact with external programmatic clients.
e. Testing Suite – The test directory helps validate various firewall configurations and shows how multiple zones or special network scenarios are handled.
• Relationships and Interactions:
• From the engine, show output flows directed to nftables – indicating that rule synthesis is pushed to the underlying firewall system.
• A bidirectional link for the D-Bus API indicating both command input and event/notification output.
• Optionally, show test cases as validation flows, ensuring that the engine’s behavior under different configurations (each test scenario) results in defined “golden” outputs.
• Architectural Patterns and Technologies:
• Emphasis on modularity: separation between the rule parsing component, configuration loader, and firewall rule deployment.
• That the design leverages system integration patterns via systemd and firewalld.
• That integration with nftables leverages modern Linux kernel features, making the design “modern” and compatible with both IPv4 and IPv6.
Final Recommendations
• Since Foomuuri has both configuration complexity (with multiple test cases showing various network scenarios) and system integration complexities (systemd, firewalld, D-Bus, nftables), ensure that every component’s interaction is visualized.