Skip to content

[pfsense] update pfsense docs #15969

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+377 −221
Open

[pfsense] update pfsense docs #15969

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
25015a1
update pfsense docs
vinit-chauhan Nov 13, 2025
8268223
Update link in the changelog
vinit-chauhan Nov 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 84 additions & 40 deletions packages/pfsense/_dev/build/docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,47 +1,91 @@
# pfSense Integration

This is an integration to parse certain logs from [pfSense and OPNsense firewalls](https://docs.netgate.com/pfsense/en/latest/). It parses logs received over the network via syslog (UDP/TCP/TLS). pfSense natively only supports UDP. OPNsense supports all 3 transports.

Currently the integration supports parsing the Firewall, Unbound, DHCP Daemon, OpenVPN, IPsec, HAProxy, Squid, and PHP-FPM (Authentication) logs.
All other events will be dropped.
The HAProxy logs are setup to be compatible with the dashboards from the HAProxy integration. Install the HAProxy integration assets to use them.

## pfSense Setup
1. Navigate to _Status -> System Logs_, then click on _Settings_
2. At the bottom check _Enable Remote Logging_
3. (Optional) Select a specific interface to use for forwarding
4. Input the agent IP address and port as set via the integration config into the field _Remote log servers_ (e.g. 192.168.100.50:5140)
5. Under _Remote Syslog Contents_ select what logs to forward to the agent
* Select _Everything_ to forward all logs to the agent or select the individual services to forward. Any log entry not in the list above will be dropped. This will cause additional data to be sent to the agent and Elasticsearch. The firewall, VPN, DHCP, DNS, and Authentication (PHP-FPM) logs are able to be individually selected. In order to collect HAProxy and Squid or other "package" logs, the _Everything_ option must be selected.

## OPNsense Setup
1. Navigate to _System -> Settings -> Logging/Targets_
2. Add a new _Logging/Target_ (Click the plus icon)
- Transport = UDP or TCP or TLS
- Applications = Select a list of applications to send to remote syslog. Leave empty for all.
- Levels = Nothing Selected
- Facilities = Nothing Selected
- Hostname = IP of Elastic agent as configured in the integration config
- Port = Port of Elastic agent as configured in the integration config
- Certificate = Client certificate to use (when selecting a tls transport type)
- Description = Syslog to Elasticsearch
- Click Save

The module is by default configured to run with the `udp` input on port `9001`.

**Important**
The pfSense integration supports both the BSD logging format (used by pfSense by default and OPNsense) and the Syslog format (optional for pfSense).
However the syslog format is recommended. It will provide the firewall hostname and timestamps with timezone information.
When using the BSD format, the `Timezone Offset` config must be set when deploying the agent or else the timezone will default to the timezone of the agent. See `https://<pfsense url>/status_logs_settings.php` and https://docs.netgate.com/pfsense/en/latest/monitoring/logs/settings.html for more information.
# pfSense Integration for Elastic

## Overview
The pfSense integration for Elastic enables the collection of logs from pfSense and OPNsense firewalls. It parses logs received over the network via syslog (UDP, TCP, or TLS), providing visibility into network traffic, security events, and system health.
Copy link
Contributor

@mjwolf mjwolf Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(UDP, TCP, or TLS) - TLS isn't a transport, this should probably change to (UDP or TCP) or UDP or TCP, using TLS


This integration facilitates real-time monitoring and analysis of firewall activity, helping with threat detection and network troubleshooting.

### How it works
The integration works by receiving syslog data streams from pfSense or OPNsense devices. Elastic Agent listens on a configured network port (UDP, TCP, or TLS), receives the logs, processes them through its ingest pipelines to parse and structure the data, and then securely sends the data to Elasticsearch for indexing and analysis.

## What data does this integration collect?
The pfSense integration collects and parses the following types of logs:
* Firewall
* Unbound (DNS)
* DHCP Daemon
* OpenVPN
* IPsec
* HAProxy
* Squid (Web Proxy)
* PHP-FPM (Authentication events)

**Note:** The HAProxy dashboards are compatible with the official HAProxy integration. For the best experience, it is recommended to also install the HAProxy integration assets. All other log types not listed above will be dropped.

## What do I need to use this integration?
You need an installed Elastic Agent to act as the collection point for the syslog data.

## How do I deploy this integration?

### Agent-based deployment

Elastic Agent must be installed to stream data from the syslog receiver and ship it to Elastic. For more details, check the Elastic Agent [installation instructions](https://www.elastic.co/guide/en/fleet/current/install-elastic-agents.html).

### Onboard / configure

Follow the steps below to configure your pfSense or OPNsense device to send logs to the Elastic Agent.

#### pfSense Setup

1. In the pfSense web interface, navigate to **Status > System Logs**, and then click on the **Settings** tab.
2. Scroll to the bottom and check the **Enable Remote Logging** box.
3. (Optional) Select a specific source interface to use for log forwarding under **Source Address**.
4. In the **Remote log servers** field, enter the IP address and port of your Elastic Agent (e.g., `192.168.100.50:9001`).
5. Under **Remote Syslog Contents**, select the logs you wish to forward.
* To collect logs from packages like HAProxy or Squid, you must select **Everything**.
* For standard logs, you can select individual services like Firewall, DHCP, OpenVPN, etc.

#### OPNsense Setup

1. In the OPNsense web interface, navigate to **System > Settings > Logging / Targets**.
2. Click the **Add** button (plus icon) to create a new logging target.
3. Configure the target with the following settings:
* **Transport**: UDP, TCP, or TLS, matching your Elastic Agent input configuration.
* **Applications**: Leave empty to forward all logs, or select specific applications.
* **Levels & Facilities**: Leave with "Nothing Selected".
* **Hostname**: The IP address of your Elastic Agent.
* **Port**: The port your Elastic Agent is listening on.
* **Certificate**: (For TLS only) Select the appropriate client certificate.
* **Description**: A descriptive name, e.g., "Syslog to Elastic".
4. Click **Save**.

**Important Configuration Note:**

The pfSense integration supports both the BSD logging format (default on pfSense) and the standard Syslog format (RFC 5424, an option on pfSense).

The **Syslog format is highly recommended** as it provides the firewall's hostname and includes proper timezone information in the timestamps.

If you must use the BSD format, you **must** configure the `Timezone Offset` setting in the integration policy. If you do not, timestamps will default to the timezone of the Elastic Agent, which may be incorrect. For more details, see the pfSense [log settings documentation](https://docs.netgate.com/pfsense/en/latest/monitoring/logs/settings.html).

### Validation

1. On a host connected to the pfSense network, generate traffic that will trigger a firewall log event. For example, attempt a connection that you know will be blocked by a firewall rule.
2. Check the pfSense system logs to confirm that new event data is being written. In the pfSense web interface, navigate to **Status > System Logs > Firewall**.
3. In Kibana, navigate to the **Discover** tab or open the pre-built **Firewall - Dashboard [pfSense]** dashboard.
4. Filter for pfSense data by using the KQL query `event.dataset : "pfsense.log"`.
Copy link
Contributor

@mjwolf mjwolf Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could be a bit confusing, you don't need to filter, if you choose to open the dashboard

Copy link
Contributor Author

@vinit-chauhan vinit-chauhan Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In step 3 it says Navigate to discover or Open dashboard. If user opens discover then they have to add the query. And for dashboards, I think the query would most likely be there or adding it won't change anything.

5. Verify that new log events from the pfSense host are appearing. You should see logs corresponding to the traffic you generated.

A huge thanks to [a3ilson](https://github.com/a3ilson) for the https://github.com/pfelk/pfelk repo, which is the foundation for the majority of the grok patterns and dashboards in this integration.

## Logs
## Reference

### pfSense log
### log
The `log` data stream contains all log types collected from the pfSense or OPNsense device.

This is the pfSense `log` dataset.
#### log fields
{{ fields "log" }}

{{event "log"}}
#### log sample event
{{ event "log" }}

{{fields "log"}}
### Inputs used
{{ inputDocs }}
5 changes: 5 additions & 0 deletions packages/pfsense/changelog.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
# newer versions go on top
- version: "1.25.0"
changes:
- description: Update the documentation.
type: enhancement
link: https://github.com/elastic/integrations/pull/15969
- version: "1.24.0"
changes:
- description: Preserve event.original on pipeline error.
Expand Down
Loading