# pfelk: turning pfSense and OPNsense firewall logs into an Elastic Stack deployment > pfelk is an Apache-2.0 collection of Logstash, Elasticsearch and Kibana configuration that ingests and enriches pfSense or OPNsense firewall traffic and serves it up as dashboards, with four installation routes and a broad set of parsers. The judgement is that its value is the log-shape knowledge rather than the tooling, and that the four install paths are four different maintenance commitments rather than four equivalent conveniences. **pfelk/pfelk** — pfSense/OPNsense + Elastic Stack - Repository: https://github.com/pfelk/pfelk - Website: https://pfelk.github.io/pfelk/ - Stars: 1,222 · Forks: 198 - Language: Shell - License: NOASSERTION - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/pfelk-pfelk ## It ingests firewall logs, then enriches and visualises them pfelk is described as a highly customizable open-source tool for ingesting and visualizing your firewall traffic with the full power of Elasticsearch, Logstash and Kibana. The repository is `pfelk/pfelk` and the primary language is Shell, which tells you something about its shape: this is a set of configuration, templates and installation scripts rather than an application with a codebase. The three capabilities map onto the three Elastic components. Ingest and enrich your pfSense or OPNsense firewall traffic logs by leveraging Logstash. Search your indexed data in near-real-time with the full power of Elasticsearch. Visualize your network traffic with interactive dashboards, Maps and graphs in Kibana. The goal is stated directly: pfelk aims to replace the vanilla pfSense or OPNsense web UI with extended search and visualization features. That is a specific and defensible ambition. A firewall's own UI gives you live log viewing and a few charts; an Elastic Stack gives you search over months of data, dashboards built from the data, and the ability to correlate firewall events with everything else you collect. What you deploy is the Elastic Stack itself with pfelk's configuration inside it. The `docker-compose.yml` at the repository root is the reference deployment, and it starts Elasticsearch, Logstash, Kibana and a certificate container. The version badge in the README header reads ELK-9.0.0, and the compose file pins the Elastic images to `${STACK_VERSION}` from the environment, so the stack version is a variable you set rather than a constant in the file. The homepage is `pfelk.github.io/pfelk/`, and the project also links the Elastic integration documentation for pfSense, which is the upstream guide for getting the firewall to ship its logs somewhere useful in the first place. ## The parser list is where the real work is The supported entries list is longer than a firewall-log tool usually is, and it is the clearest statement of what the project actually knows about. The base is pfSense and OPNsense setups, covering the TCP, UDP and ICMP protocols. Then there is IPv4 and IPv6 mapping, and pfSense CARP data, which is the cluster failover protocol, and those two are the ones a network engineer would immediately want and cannot easily reconstruct. The service-specific parsers are the bulk of the list, and most of them come with a dashboard and, in several cases, Kibana SIEM compliance. Unbound DNS Resolver has a dashboard and Kibana SIEM compliance. Suricata IDS has a dashboard and Kibana SIEM compliance. Snort IDS has a dashboard and Kibana SIEM compliance. Squid has a dashboard and Kibana SIEM compliance. openVPN has a dashboard. HAProxy has a dashboard. The Captive Portal has a dashboard. NGINX has a dashboard. Two entries carry status warnings, and they are the ones to read carefully. KEA-DHCP, for v4 and v6 message types, has a dashboard and is marked in development. DHCP, for v4 and v6 message types, has a dashboard and is marked depreciated, which is the README's own spelling. The SIEM compliance mention is the most interesting phrase in the list, because it means these parsers are not only producing charts. They are producing events shaped so that a SIEM rule set can consume them, which is a higher bar than a dashboard with a pie chart of source addresses. A rule that fires on a Suricata alert is only useful if the alert lands in a field the rule engine looks at. The comparison to similar solutions is acknowledged in the README with a link to a wiki page, and the roadmap is described as an experimental public roadmap, hosted as a GitHub project board for the organisation. ## Four install routes, and they are not equivalent pfelk can be deployed via ansible-playbook, docker-compose, bash script, or manually, and the four routes carry quite different costs. The Docker Compose route is the shortest. The `docker-compose.yml` is in the repository and the command is `docker-compose up`. There is a manual Docker method with its own documentation page, and the scripted Docker method is marked as coming soon. Note also that the repository root contains a file literally named `docker-compose.(single cluster unstable)`, which is a second compose variant for a single cluster, labelled unstable. The script route is a four-step shell sequence: ```bash $ wget https://raw.githubusercontent.com/pfelk/pfelk/main/etc/pfelk/scripts/pfelk-installer.sh $ chmod +x pfelk-installer.sh $ sudo ./pfelk-installer.sh ``` After the installer runs you are pointed at three separate documentation pages: security configuration, templates, and finishing configuration. The fact that there are three pages after the script runs is a reasonable signal of how much configuration remains after an install. The manual route is a set of preparation documents, one for Ubuntu 20.04 to 22.04, one for Debian 11 to 12, one for Docker, and a video guide. What is worth noticing is the asymmetry. Docker is one command but assumes you can work with a compose file. The script assumes root on the host and installs system services. The manual route assumes you will read several pages and assemble the pieces yourself. The ansible-playbook option is listed in the overview sentence but is not given its own installation section, which suggests it is available but less documented. The prerequisites are stated for all of them: Ubuntu Server 20.04 or later or Debian Server 11 or later, with stretch and buster tested, pfSense 2.5.0 or later or OPNsense 23.0 or later, a minimum of 8GB of RAM with 32GB recommended and Docker requiring more, and setting up remote logging, which is a prerequisite step the project links to rather than performs. ## The compose file shows TLS being handled properly The `docker-compose.yml` is worth reading even if you never deploy it, because the certificate handling is the part of an Elastic Stack setup that is most often done badly. The compose file defines a `certs` service that runs the Elasticsearch certificate tooling before anything else starts. It creates a certificate authority if one does not exist, using `bin/elasticsearch-certutil ca --silent --pem`, then unzips it into the config directory. Next it writes an `instances.yml` describing a node named es01 with DNS names for es01 and localhost and the IP 127.0.0.1, and issues the node certificate with `bin/elasticsearch-certutil cert`, passing the CA certificate and CA key. Both archives are unzipped, and the permissions are then set, directories to 750 and files to 640, with ownership to 0:0. The Elasticsearch service declares `depends_on` with `condition: service_completed_successfully` for the certs service, which means the node waits for the certificates to exist rather than racing it. That is the kind of ordering that turns a flaky first start into a reliable one. The node itself is configured with a single-node discovery type, memory lock enabled, and xpack security enabled with HTTP SSL turned on and the key and certificate paths pointing into the certs volume. The `ELASTIC_PASSWORD` and `CLUSTER_NAME` come from the environment, and the `STACK_VERSION` variable selects the image tag across the services. The security posture is worth noting against the pfelk premise. This is a deployment that ingests firewall logs, which is exactly the kind of data that reveals internal topology, so having the Elastic HTTP layer on TLS with a generated CA from the start is the right default, and the separate `install/security.md` page exists to configure the rest of it. ## Where the appliance side of the work lands on you The gap between this project and a working deployment is the firewall configuration, and the documentation is honest that it is a prerequisite you handle yourself. Setting up remote logging is listed among the prerequisites, with a wiki page on it, and the Elastic integration documentation for pfSense is linked at the top of the README. In practice that means configuring the firewall to write its logs somewhere other than its own local log, which for pfSense means a syslog destination and for OPNsense the equivalent, and that configuration is per-firewall and per-site. That has consequences for the shape of a deployment. pfelk assumes one Elastic Stack receiving from whatever firewalls point at it, and a network with several sites, each with its own pfSense or OPNsense box, needs each box pointed at the same Logstash and needs the source address preserved so the dashboards can tell sites apart. The IPv4 and IPv6 mapping support and the per-firewall data in the parsers are what make that work, and they are also where the effort goes. The second thing to plan for is scale, and the documentation addresses it with a memory floor and a performance wiki page. A minimum of 8GB of RAM, 32GB recommended, and more required for Docker. A firewall on a busy network produces a lot of log lines, and the Elastic Stack is what absorbs them, so the firewall is rarely the sizing constraint. There is also a note about Elastic's own integration. The README links the Elastic integration documentation for pfSense, which suggests the pfSense community and Elastic cooperate on the log format. If you are starting a new deployment, reading that document alongside the pfelk templates is the way to find out whether the parsers here match the current log layout. ## Project state, and a licence the badge does not describe Two things about the repository's current condition are worth stating plainly. The first is the release history. The listed tags are v23.08 from 2023-08-14, v24.06 from 2024-06-19 and 25.01 from 2025-01-20, so the versioning follows a year and month pattern. The last push was on 2026-10-02 and the repository is not archived, so the code is being worked on, and the Elastic stack version in the header badge, ELK-9.0.0, is current relative to that activity. The second is the licence, and there is a mismatch worth flagging. The README's License section says the project is licensed under the terms of the Apache 2.0 open source license, and points to a `license` file for the full terms. The repository's licence is reported as a custom one that GitHub cannot classify, and the root entry is named `license` in lowercase with no extension rather than `LICENSE`. The `docker-compose.yml` at the root also has a name with a parenthetical in it, `docker-compose.(single cluster unstable)`, which is a further sign that the repository is maintained by hand rather than by a release process that normalises file naming. That is not a criticism of the project so much as a caution: confirm the licence text in the `license` file yourself before redistributing pfelk's configuration in a commercial context. This is a licensing observation rather than legal advice. The community infrastructure is a Discord server and a YouTube channel, the documentation site is on GitHub Pages, and the repository has a `CODE_OF_CONDUCT.md`, a `PULL_REQUEST_TEMPLATE.md` and a `CONTRIBUTING.md`, so the project has the process scaffolding of a mature community project even where the release cadence is annual. ## Conclusion pfelk fits a network administrator who already runs pfSense or OPNsense and wants searchable, visualised firewall traffic without building Logstash pipelines, Kibana dashboards and Elasticsearch index templates by hand. It does not fit a team that wants a single software package to install, since the Elastic Stack is a large multi-service deployment, and it does not fit someone who needs only live firewall log viewing, which both firewalls already provide. Verify first that the firewall writes the log format you intend to parse, since remote logging setup on the appliance is a prerequisite the project does not do for you, that the machine has the memory the documentation asks for, at least 8GB and more for Docker with 32GB recommended, and that the parsers you need are in the supported list, since the DHCP and KEA-DHCP entries are marked as in development and deprecated respectively. ## FAQ ### What is pfelk and what does it do? pfelk is a highly customizable open-source tool for ingesting and visualizing firewall traffic with the Elastic Stack. It uses Logstash to ingest and enrich pfSense or OPNsense logs, Elasticsearch to search the indexed data in near-real-time, and Kibana for interactive dashboards, Maps and graphs. ### How do I install pfelk? There are several routes. Docker Compose is the shortest with `docker-compose up` using the file in the repository. The script route downloads `pfelk-installer.sh`, makes it executable and runs it with sudo, followed by separate security, templates and configuration steps. There is also a manual route with preparation documents for Ubuntu 20.04-22.04, Debian 11-12 and Docker. ### What are the system requirements for pfelk? Ubuntu Server 20.04 or later or Debian Server 11 or later, pfSense 2.5.0 or later or OPNsense 23.0 or later, a minimum of 8GB of RAM with 32GB recommended and more required for Docker, and remote logging configured on the firewall. ### Which log sources does pfelk parse besides the base firewall log? The supported list includes KEA-DHCP, which is marked in development, DHCP, which is marked depreciated, IPv4 and IPv6 mapping, pfSense CARP data, openVPN, Unbound DNS Resolver, Suricata IDS, Snort IDS, Squid, HAProxy, the Captive Portal and NGINX, most with a Kibana dashboard, and several with Kibana SIEM compliance. ### Does pfelk replace the pfSense or OPNsense web interface? That is the stated aim: pfelk aims to replace the vanilla pfSense or OPNsense web UI with extended search and visualization features. It is a separate Elastic Stack deployment receiving logs from the firewall, not a modification to the firewall software itself, so the appliance configuration is a prerequisite you set up yourself. ## Sources - [Issues](https://github.com/pfelk/pfelk/issues) - [pfelk/pfelk on GitHub](https://github.com/pfelk/pfelk) - [Project website](https://pfelk.github.io/pfelk/) - [README](https://github.com/pfelk/pfelk/blob/main/README.md) - [Releases](https://github.com/pfelk/pfelk/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pfelk-pfelk