From ec75ca07c08d85225d9b1e8f8466f5fda8372a11 Mon Sep 17 00:00:00 2001
From: Jonathan David Lee <111817527+JonathanDLee24@users.noreply.github.com>
Date: Mon, 12 Jan 2026 15:03:07 -0800
Subject: [PATCH 1/2] Add pfSense NVMe cache overlay documentation
This document provides a script for creating a filesystem overlay using nullfs to mount an alternate NVMe-backed directory as the Squid cache location on pfSense systems. It includes usage instructions and a cron job setup.
---
.../Caching/pfSensenvmecacheuse.md | 76 +++++++++++++++++++
1 file changed, 76 insertions(+)
create mode 100644 docs/ConfigExamples/Caching/pfSensenvmecacheuse.md
diff --git a/docs/ConfigExamples/Caching/pfSensenvmecacheuse.md b/docs/ConfigExamples/Caching/pfSensenvmecacheuse.md
new file mode 100644
index 00000000..2967e96a
--- /dev/null
+++ b/docs/ConfigExamples/Caching/pfSensenvmecacheuse.md
@@ -0,0 +1,76 @@
+---
+categories: [ConfigExample]
+FaqSection: operation
+---
+## Dscription
+This script creates a filesystem overlay using nullfs to mount an alternate NVMe-backed directory as the Squid cache location. On pfSense systems, the standard cache path (/var/squid/cache) is transparently redirected to a user-defined path on a different drive.
+The overlay itself functions correctly: Squid writes to and utilizes the new cache location as intended. However, the Clear Cache button in the pfSense GUI does not currently work with this setup. While this was the original goal of the project, this implementation is an important first step—it enables cache relocation without modifying Squid’s configured path, even though cache clearing still requires manual intervention.
+—
+J. Lee
+## Usage
+This script is intended for Netgate pfSense systems where Squid’s cache is normally located at:
+ /var/squid/cache
+When an alternate drive or filesystem (such as NVMe storage) is used for caching, management becomes more complex. In particular, the pfSense Clear Cache function does not operate correctly, requiring manual deletion of cache files.
+This script was created to simplify cache relocation by overlaying the default Squid cache path with a different storage location, while maintaining compatibility with pfSense’s expected directory structure.
+
+## add cron file
+ @reboot /root/mount_squid_nullfs.sh
+
+## Script .sh file used for cron job
+
+ #!/bin/sh
+
+ TAG="squid-nullfs"
+ NVME_DEV="/dev/nda0p2"
+ NVME_MNT="/nvme/LOGS_Optane"
+ CACHE_SRC="${NVME_MNT}/Squid_Cache"
+ CACHE_DST="/var/squid/cache"
+
+ # --- Helper function to log safely to system.log using pfSense PHP ---
+ log_sys() {
+ MESSAGE="$1"
+ logger -t "$TAG" "$MESSAGE"
+ }
+
+ log_sys "Starting Squid nullfs mount sequence"
+
+ # 1. Ensure NVMe filesystem is mounted
+ if ! mount | grep -q "on ${NVME_MNT} "; then
+ log_sys "Mounting NVMe filesystem"
+ mount_msdosfs "${NVME_DEV}" "${NVME_MNT}" || {
+ log_sys "ERROR: NVMe mount failed"
+ exit 1
+ }
+ else
+ log_sys "NVMe already mounted"
+ fi
+
+ # 2. Stop squid if running
+ if pgrep -x squid >/dev/null; then
+ log_sys "Stopping squid"
+ /usr/local/sbin/pfSsh.php playback svc stop squid
+ sleep 2
+ fi
+
+ # 3. Ensure directories exist
+ mkdir -p "${CACHE_SRC}" "${CACHE_DST}"
+
+ # 4. Mount nullfs if not already mounted
+ if ! mount | grep -q "on ${CACHE_DST} "; then
+ log_sys "Mounting nullfs cache"
+ mount -t nullfs "${CACHE_SRC}" "${CACHE_DST}" || {
+ log_sys "ERROR: nullfs mount failed"
+ exit 1
+ }
+ else
+ log_sys "nullfs already mounted"
+ fi
+
+ # 5. Start squid
+ log_sys "Starting squid"
+ /usr/local/sbin/pfSsh.php playback svc start squid
+
+ log_sys "Squid nullfs mount completed"
+
+## Testing should show a valid mount on reboot in logs
+
From ce32a1598bae4e61376882da3379dd1ed55437c5 Mon Sep 17 00:00:00 2001
From: Jonathan David Lee <111817527+JonathanDLee24@users.noreply.github.com>
Date: Tue, 13 Jan 2026 07:39:01 -0800
Subject: [PATCH 2/2] Clarify testing log messages for nullfs mount
Updated the testing section to text based expected log messages. removed image
---
docs/ConfigExamples/Caching/pfSensenvmecacheuse.md | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/docs/ConfigExamples/Caching/pfSensenvmecacheuse.md b/docs/ConfigExamples/Caching/pfSensenvmecacheuse.md
index 2967e96a..7a7984de 100644
--- a/docs/ConfigExamples/Caching/pfSensenvmecacheuse.md
+++ b/docs/ConfigExamples/Caching/pfSensenvmecacheuse.md
@@ -72,5 +72,9 @@ This script was created to simplify cache relocation by overlaying the default S
log_sys "Squid nullfs mount completed"
-## Testing should show a valid mount on reboot in logs
-
+## Testing should show a valid mount on reboot in standard system logs
+ Squid nullfs mount completed
+ Starting squid
+ Mounting nullfs cache
+ Mounting NVMe filesystem
+ Starting Squid nullfs mount sequence