From 5fcb0d665585802a94fa4a462eac877439e45088 Mon Sep 17 00:00:00 2001
From: "pulse-triage[bot]"
 <249995291+pulse-triage[bot]@users.noreply.github.com>
Date: Wed, 26 Aug 2026 13:28:46 +0100
Subject: [PATCH] Document pfSense agent service recovery

Refs discussion #1781

Change-source: pulse-maintainer
---
 docs/UNIFIED_AGENT.md                        | 23 ++++++++++++++++++++
 frontend-modern/public/docs/UNIFIED_AGENT.md | 23 ++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md
index f33e7a8722..b67659f549 100644
--- a/docs/UNIFIED_AGENT.md
+++ b/docs/UNIFIED_AGENT.md
@@ -647,6 +647,29 @@ Set `--health-addr=""` or `PULSE_HEALTH_ADDR=off` to disable the health/metrics
 
 ## Troubleshooting
 
+### pfSense service disabled after a major upgrade
+
+Pulse installs two service files on pfSense: the FreeBSD rc.d service at
+`/usr/local/etc/rc.d/pulse-agent` and an executable
+`/usr/local/etc/rc.d/pulse_agent.sh` boot wrapper. pfSense only runs custom
+scripts from that directory at boot when their filename ends in `.sh`.
+
+If both files still exist after a pfSense upgrade, run the following as root to
+restore the enable flag, permissions and running service:
+
+```sh
+sysrc pulse_agent_enable=YES
+chmod 755 /usr/local/etc/rc.d/pulse-agent /usr/local/etc/rc.d/pulse_agent.sh
+service pulse-agent start
+service pulse-agent status
+```
+
+If either file is missing, copy the current command from **Settings →
+Infrastructure → Install on a host** and run it again on the same firewall. Do
+not uninstall the existing agent first. The installer repairs the rc.d service,
+enable flag and pfSense boot wrapper in place and reuses saved connection and
+agent identity state when it is still present.
+
 ### Installer Fails With "Not enough free disk space"
 
 The installer stages the agent binary (~34 MiB) in a temporary directory before
diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.md
index f33e7a8722..b67659f549 100644
--- a/frontend-modern/public/docs/UNIFIED_AGENT.md
+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md
@@ -647,6 +647,29 @@ Set `--health-addr=""` or `PULSE_HEALTH_ADDR=off` to disable the health/metrics
 
 ## Troubleshooting
 
+### pfSense service disabled after a major upgrade
+
+Pulse installs two service files on pfSense: the FreeBSD rc.d service at
+`/usr/local/etc/rc.d/pulse-agent` and an executable
+`/usr/local/etc/rc.d/pulse_agent.sh` boot wrapper. pfSense only runs custom
+scripts from that directory at boot when their filename ends in `.sh`.
+
+If both files still exist after a pfSense upgrade, run the following as root to
+restore the enable flag, permissions and running service:
+
+```sh
+sysrc pulse_agent_enable=YES
+chmod 755 /usr/local/etc/rc.d/pulse-agent /usr/local/etc/rc.d/pulse_agent.sh
+service pulse-agent start
+service pulse-agent status
+```
+
+If either file is missing, copy the current command from **Settings →
+Infrastructure → Install on a host** and run it again on the same firewall. Do
+not uninstall the existing agent first. The installer repairs the rc.d service,
+enable flag and pfSense boot wrapper in place and reuses saved connection and
+agent identity state when it is still present.
+
 ### Installer Fails With "Not enough free disk space"
 
 The installer stages the agent binary (~34 MiB) in a temporary directory before