MediawikiCIT - User contributions [en]

Organizing Coder Terminals

2026-05-02T08:13:26Z

Justinaquino: Added RCA: tmux send-keys broke launchers, fixed with direct exec; ce-char-gen troubleshooting

== Problem ==

When running multiple AI coding agents (Claude, Kimi, Qwen, OpenCode) in separate GNOME Terminal windows, every tab looks identical — usually titled by the running process name (e.g., "Kimi Code"). After opening 3–4 terminals, it becomes impossible to tell at a glance which terminal belongs to which project without clicking into each one.

GNOME Terminal 3.44+ removed the "Set Title" option from the tab right-click menu, eliminating the old manual workaround.

== Solution ==

Use '''tmux''' inside every terminal:
* One named tmux session per project (e.g., <code>claude</code>, <code>kimi</code>, <code>qwen</code>)
* A <code>title</code> bash command that renames both the tmux window and the terminal title
* Persistent panes — if an AI agent crashes, the pane stays alive and can be respawned

== Quick Start ==

=== Launch All Agents at Once ===

Run on the Ubuntu desktop:
<pre>
~/start_dev_env.sh
</pre>

This opens 5 GNOME Terminal windows:
{| class="wikitable"
! # !! Window Title !! Tmux Session !! Purpose
|-
| 1 || Claude Code — tmux || claude || Claude Code AI agent
|-
| 2 || OpenCode Claude — tmux || opencode-claude || OpenCode (Claude provider)
|-
| 3 || OpenCode Kimi — tmux || kimi || OpenCode (Kimi provider)
|-
| 4 || OpenCode Qwen — tmux || qwen || OpenCode (Qwen provider)
|-
| 5 || Tmux — General || general || Plain bash for git, docker, file ops
|}

Each session survives even if the GNOME Terminal window is closed.

=== Launch Individual Agents ===

Double-click any desktop launcher:
* <code>~/Desktop/claude.sh</code>
* <code>~/Desktop/kimi.sh</code>
* <code>~/Desktop/opencode.sh</code>
* <code>~/Desktop/Qwen.sh</code>

Each launcher auto-creates or reattaches to its tmux session.

== How to Title Your Session ==

=== The Default Title Is the Command Itself ===

Every new terminal opens with the title:
<pre>
title "project"
</pre>

This is intentional — the '''default title is the command reminder'''. You never forget the syntax because it's staring at you from the tab.

=== Change It ===

Inside any terminal, type:
<pre>
title "ce char gen"
</pre>

This does two things:
# Renames the tmux window (visible in the green status bar at the bottom)
# Sets the GNOME Terminal tab/window title

Change it anytime:
<pre>
title "mneme shipgen"
title "IT-knowledge docs"
title "$(hostname)" # reset to hostname
</pre>

The title auto-resets after every shell prompt, so AI agents cannot overwrite it.

=== Tmux-Only Renaming ===
<pre>
tmux rename-window "my project" # rename current window
tmux rename-session "newname" # rename entire session
</pre>

=== Key Shortcuts ===
{| class="wikitable"
! Key !! Action
|-
| Ctrl+b , || Rename current window (interactive prompt)
|-
| Ctrl+b r || Respawn pane (restart AI agent if it crashed)
|-
| Ctrl+b d || Detach session (keeps it running in background)
|-
| Ctrl+b | || Split pane horizontally
|-
| Ctrl+b - || Split pane vertically
|-
| Alt+Arrow || Switch panes
|-
| Ctrl+b R || Reload tmux config
|}

== Reattaching to Sessions ==

If a terminal window is closed, the tmux session keeps running:
<pre>
tmux list-sessions
tmux attach-session -t claude
tmux attach-session -t kimi
</pre>

Aliases added to <code>~/.bashrc</code>:
<pre>
tls # list sessions
tas claude # attach to claude session
</pre>

== Configuration Files ==

{| class="wikitable"
! File !! Purpose
|-
| <code>~/.tmux.conf</code> || Tmux settings (status bar, mouse, key bindings)
|-
| <code>~/.bashrc</code> || <code>title()</code> function + auto-reset + tmux aliases
|-
| <code>~/.config/tmux-launcher.sh</code> || Helper script for desktop launchers
|}

== Troubleshooting ==

{| class="wikitable"
! Symptom !! Cause !! Fix
|-
| Title shows "Kimi Code" instead of custom || AI resets it via escape sequences || <code>PROMPT_COMMAND</code> auto-resets after every prompt
|-
| Tab right-click has no "Set Title" || GNOME Terminal 3.44+ removed it || Use <code>title</code> bash command or <code>Ctrl+b ,</code>
|-
| <code>title</code> command not found || <code>.bashrc</code> not loaded || Start an interactive shell, or run <code>source ~/.bashrc</code>
|-
| Default title shows <code>title "project"</code> || Working as designed — syntax reminder || Type <code>title "your real project"</code> to replace it
|-
| Tmux status bar shows <b>"ce char gen"</b> || Old <code>~/.tmux.conf</code> on host hardcoded the title || Replace host <code>~/.tmux.conf</code> with container's clean version
|-
| AI agent crashed and pane is dead || Process exited || Press <code>Ctrl+b r</code> to respawn
|-
| Session already exists || Previous session still running || <code>tmux attach -t <name></code> or <code>tmux kill-session -t <name></code>
|}

== RCA: Why Tmux Broke the Original Launch Scripts ==

=== What Worked Before (No Tmux) ===
<pre>
distrobox enter agent260411 -- bash -c 'cd /home/justin/opencode260220 && ./csb.sh; exec bash'
</pre>
<code>./csb.sh</code> does <code>exec claude</code>, which replaces the shell with the interactive AI agent. Claude owns the TTY and runs until the user exits.

=== What Broke (First Tmux Attempt) ===
The initial <code>tmux-launcher.sh</code> used <code>tmux send-keys</code> to type commands into a detached session:
<pre>
tmux new-session -s "$SESSION" -n "$WINDOW" -d
tmux send-keys -t "$SESSION:$WINDOW" "./csb.sh" C-m
tmux attach-session -t "$SESSION"
</pre>

=== Why This Failed ===
# '''Race condition''': <code>send-keys</code> types faster than the shell initializes. The command often arrived before bash was ready, causing "command not found" or silent failure.
# '''No TTY guarantee''': Interactive apps (Claude, Kimi) need a controlling terminal. <code>send-keys</code> provides a pane but doesn't guarantee the app receives proper TTY initialization before the keystrokes land.
# '''Exit timing''': If the app started before attach, the user attached to a pane that was already dead or mid-execution.

=== The Fix ===
Replace <code>send-keys</code> with direct command execution via a wrapper script. This gives tmux the full command upfront, so it initializes the TTY properly before the app starts — exactly like the original scripts, just wrapped in tmux.

== See Also ==

* [[IT Knowledge Base]]
* [[Forgejo]]
* [[Docker Stacks]]

[[Category:System Administration]]
[[Category:Development Environment]]
[[Category:AI Agents]]

Main Page

2026-05-02T07:31:02Z

Justinaquino: Added Organizing Coder Terminals to IT index

__NOTOC__
<div style="background:#f8f9fa; border:1px solid #ddd; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
Welcome to the '''Comfac IT Knowledge Base'''. Use the sections below to find guides, SOPs, and references organized by topic.
</div>

== ERPNext / Frappe ==
<div style="column-count:2; column-gap:2em;">
* [[Frappe HRMS]] — '''HR & Payroll''' (with Philippine Localization)
* [[Frappe ERPNext/Webshop]] — '''E-Commerce Webshop''' (setup, architecture, chapters)
* [[Manufacturing v16 260125]]
* [[ERpnext Asset Management Procedure 260113]]
* [[ERPNext HR Module Outline]]
* [[ERPNEXT Payroll POC 251212]]
* [[Comfac ERPNext Strategy Canvas (Expanded)]]
* [[PAD-Driven ERPNext Strategy 260303]] — PAD/AI-agentic implementation strategy for Frappe ERPNext
* [[ERPNext v15 Docker Setup Guide]] — Local Docker setup for evaluation, testing, and student use
* [[Frappe Links and References]]
* [[Using Frappe Wiki]]
* [https://docs.frappe.io/cloud/guidelines-for-contributing-regional-compliance-app Guidelines for Contributing Regional Compliance App]
* [https://docs.frappe.io/cloud/what-are-benches-and-bench-groups What are Benches?]
</div>

== System Administration & Self-Hosting ==
<div style="column-count:2; column-gap:2em;">
* [[Networking PfSense Index]] — Consolidated index of all networking, pfSense, DNS, and infrastructure guides
* [[System Hardening Strategy: Win2Lin Migration & Infrastructure 251129]]
* [[Controller Systems 251213-01]]
* [[Power Distribution Tree 251213]]
* [[Introduction: Why Self-Host Your Email?]]
* [[Mailcow + Thunderbird Setup Guide (Email + Calendar)]]
* [[Mailcow SOGo: Creating Filters for Events, Approvals, and Organizational Emails]]
* [[Spoof Timezone Extension – Setup Guide for Comfac Staff]]
* [[Viber Focus-Stealing]]
* [[🌐 WordPress Website — *You Own Everything, Learn Everything*]]
* [[Portainer to Docker Compose Migration Guide]]
* [[Organizing Coder Terminals]] — Tmux + dynamic titles for managing multiple AI agent terminals
* [[Editing Mastodon Docker Deployment Guide 260402]]
</div>

== Storage & Hardware ==
<div style="column-count:2; column-gap:2em;">
* [[TrueNAS Configuration Options & Scale Options 251130]]
* [[TrueNAS Business Plan: Project 251212]]
* [[Comparison: TrueNAS Mini X+ vs Dell Precision 3680 Tower (2025)]]
* [[Backblaze Drive Stats for Server and Storage Qualification]]
* [[Industrial Controllers and Water Utilities 251011]]
</div>

== AI & Machine Learning ==
<div style="column-count:2; column-gap:2em;">
* [[OpenWebUI - 251128-justin]]
* [[Comfac GPU Scaling and AI Research Goals]]
* [[🧠 Process: Selecting and Installing the Right Ollama Model for Your Hardware]]
* [[Ollama GNOME System Tray Panel 260401]] — GNOME system tray toggle to start/stop Ollama and reclaim VRAM
* [[Proceedural Agentic Development Methodology 260304]] — Methodology for systematic agent use
* [[Project OpenCoder: AI Independence Initiative]] — Strategic roadmap for manufacturing intelligence
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 Modelfile fix for tool calling in OpenCode; thinking mode suppression; HDD vs SSD findings
* [[OpenCode Multi-Provider Configuration Guide 260401]] — Dual-mode AI coding setup with Kimi cloud + Ollama local models via Distrobox
* [[PAD-Driven ERPNext Strategy 260303]] — Procedural Agentic Development for Frappe/ERPNext configuration and deployment
</div>

== Job Descriptions ==
<div style="column-count:2; column-gap:2em;">
* [[Job Descriptions]] — Index of all official job descriptions (IT, Engineering, Sales)
* [[JD IT Project Staff]] — IT Project Staff
* [[JD Security Compliance Assistant 260224]] — Security and Compliance Assistant (SCA)
* [[JD Engineering Designer 260108]] — Engineering Designer
* [[JD Engineering Supervisor 260109]] — Engineering Supervisor
* [[JD Technical Sales 260112]] — Technical Sales Engineer
* [[JD Marketing Assistant 251119]] — Marketing Assistant
</div>

== IT Operations & SOPs ==
<div style="column-count:2; column-gap:2em;">
* [[SCA Program Plan 260320]] — Security & Compliance Assistant Program Plan v3 (ISO 9001/27001, PDCA, distributed audit model)
* [[SOP: Inter-Company Ordering and Production Process 260203]] — Ordering and production workflow between Sister Companies and the Cabuyao Plant
* [[Memo: Team Roles & Reporting Process Clarification 260320]] — Role boundaries, data ownership, and the new ERPNext-driven reporting paradigm
* [[Standard Operating Procedure: Distributed Minute Taking & Task Ownership 251208]]
* [[Business Continuity]]
* [[Procedure: CC-Blast Data Breach Prevention]]
* [[8D (Eight Discipline) Problem Solving Procedure]]
* [[Offline Malware Remediation & Data Recovery]]
* [[Troubleshooting: Access & Permission Issues]]
* [[Steps to Repair and OCR a Scanned or Corrupted PDF in Ubuntu]]
* [[IT IMPORTS PROCESSES]]
* [[IT Purchase Requests 241126]]
* [[IT REQUEST (OP-ERP-ITR) - EDITED 250801]]
</div>

== Sales & Business ==
<div style="column-count:2; column-gap:2em;">
* [[Comfac Sales Knowledge Base]]
* [[Comfac CRM – Customer Qualification & Conversion Process]]
* [[Partner Reseller Pricing 251109]]
* [[Biz Analysis Methodology 251109]]
* [[2026 MIS IT KRA KPI Biz Plan]]
* [[SALES INVOICE TAX OUTPUT 250829]]
* [[Projects in Process Report 251023]]
</div>

== Tools & Productivity ==
<div style="column-count:2; column-gap:2em;">
* [[Excel Description Filler Tool 📝]]
* [https://github.com/Comfac-Global-Group/comfac-studies Comfac Studies - Spaced Repetiton Active Recall]
* [[LibreOffice / Nextcloud Office – "Due Tasks" Conditional Formatting]]
* [[Google Drive and Shared Drive Training]]
* [[260108 CGG- GitHub Administration Guide]]
</div>

== Wiki & Documentation ==
<div style="column-count:2; column-gap:2em;">
* [[Mediawiki Setting Up Guide]]
* [[Contributing to Only Office 260307]]
* [[Mediawiki Additional Configuration]]
* [[Mediawiki Docker Migration Guide]]
* [[Home]]
</div>

== Tutorials ==
<div style="column-count:2; column-gap:2em;">
* [[Claude Code Isolation and Burner Workflow 260211]] — Secure AI development environment setup
* [[Opencode isolation and burner workflow 260216]] — OpenCode CLI isolation procedures
* [[LibreOffice Calc NumToWords Extension Complete Guide]] — Extension development
* [[ERPNext v15 Docker Setup Guide]] — ERPNext v15 local Docker setup (students, evaluators, thin-client demos)
* [[Erpnextv15-SSH-setup-241111]] — ERPNext v15 SSH/Portainer production setup
* [[Git-Mediawiki Local Editing 260223]] — Wiki editing with Git
* [[Understanding & Fixing Kernel Panics 260212]] — System debugging
* [[OpenCode in Android Termux 260303]] — OpenCode in Android
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 agentic setup: Modelfile, tool calling fix, storage impact
* [[Lora Basics 260304]] — LORA research
* [https://github.com/anomalyco/opencode/issues/4283#issuecomment-4083399210 Opencode Copy-paste Clipboard doesnt Work - Solution] https://github.com/anomalyco/opencode/issues/4283#issuecomment-4083399210
</div>

== Research ==
<div style="column-count:2; column-gap:2em;">
* [[Ladybird Browser]] — Browser engine development
* [[Computing Architecture]] — System design principles
* [[Backblaze Drive Stats for Server and Storage Qualification 260219]] — Drive reliability analysis
</div>

----

== For Users Only ==
* [[Private:Private Ngani]]
* [[Private:Private Nganipart2]]

== CIT-OJT Project Documentations ==
* [[OJTDocs: For OJTs only]]

== Need Help? ==
<div style="column-count:2; column-gap:2em;">
* [[Troubleshooting: Access & Permission Issues]]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents MediaWiki User's Guide]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
</div>

Organizing Coder Terminals

2026-05-02T07:27:04Z

Justinaquino: Updated: default title is now the command reminder 'title "project"' (2026-05-02)

== Problem ==

When running multiple AI coding agents (Claude, Kimi, Qwen, OpenCode) in separate GNOME Terminal windows, every tab looks identical — usually titled by the running process name (e.g., "Kimi Code"). After opening 3–4 terminals, it becomes impossible to tell at a glance which terminal belongs to which project without clicking into each one.

GNOME Terminal 3.44+ removed the "Set Title" option from the tab right-click menu, eliminating the old manual workaround.

== Solution ==

Use '''tmux''' inside every terminal:
* One named tmux session per project (e.g., <code>claude</code>, <code>kimi</code>, <code>qwen</code>)
* A <code>title</code> bash command that renames both the tmux window and the terminal title
* Persistent panes — if an AI agent crashes, the pane stays alive and can be respawned

== Quick Start ==

=== Launch All Agents at Once ===

Run on the Ubuntu desktop:
<pre>
~/start_dev_env.sh
</pre>

This opens 5 GNOME Terminal windows:
{| class="wikitable"
! # !! Window Title !! Tmux Session !! Purpose
|-
| 1 || Claude Code — tmux || claude || Claude Code AI agent
|-
| 2 || OpenCode Claude — tmux || opencode-claude || OpenCode (Claude provider)
|-
| 3 || OpenCode Kimi — tmux || kimi || OpenCode (Kimi provider)
|-
| 4 || OpenCode Qwen — tmux || qwen || OpenCode (Qwen provider)
|-
| 5 || Tmux — General || general || Plain bash for git, docker, file ops
|}

Each session survives even if the GNOME Terminal window is closed.

=== Launch Individual Agents ===

Double-click any desktop launcher:
* <code>~/Desktop/claude.sh</code>
* <code>~/Desktop/kimi.sh</code>
* <code>~/Desktop/opencode.sh</code>
* <code>~/Desktop/Qwen.sh</code>

Each launcher auto-creates or reattaches to its tmux session.

== How to Title Your Session ==

=== The Default Title Is the Command Itself ===

Every new terminal opens with the title:
<pre>
title "project"
</pre>

This is intentional — the '''default title is the command reminder'''. You never forget the syntax because it's staring at you from the tab.

=== Change It ===

Inside any terminal, type:
<pre>
title "ce char gen"
</pre>

This does two things:
# Renames the tmux window (visible in the green status bar at the bottom)
# Sets the GNOME Terminal tab/window title

Change it anytime:
<pre>
title "mneme shipgen"
title "IT-knowledge docs"
title "$(hostname)" # reset to hostname
</pre>

The title auto-resets after every shell prompt, so AI agents cannot overwrite it.

=== Tmux-Only Renaming ===
<pre>
tmux rename-window "my project" # rename current window
tmux rename-session "newname" # rename entire session
</pre>

=== Key Shortcuts ===
{| class="wikitable"
! Key !! Action
|-
| Ctrl+b , || Rename current window (interactive prompt)
|-
| Ctrl+b r || Respawn pane (restart AI agent if it crashed)
|-
| Ctrl+b d || Detach session (keeps it running in background)
|-
| Ctrl+b | || Split pane horizontally
|-
| Ctrl+b - || Split pane vertically
|-
| Alt+Arrow || Switch panes
|-
| Ctrl+b R || Reload tmux config
|}

== Reattaching to Sessions ==

If a terminal window is closed, the tmux session keeps running:
<pre>
tmux list-sessions
tmux attach-session -t claude
tmux attach-session -t kimi
</pre>

Aliases added to <code>~/.bashrc</code>:
<pre>
tls # list sessions
tas claude # attach to claude session
</pre>

== Configuration Files ==

{| class="wikitable"
! File !! Purpose
|-
| <code>~/.tmux.conf</code> || Tmux settings (status bar, mouse, key bindings)
|-
| <code>~/.bashrc</code> || <code>title()</code> function + auto-reset + tmux aliases
|-
| <code>~/.config/tmux-launcher.sh</code> || Helper script for desktop launchers
|}

== Troubleshooting ==

{| class="wikitable"
! Symptom !! Cause !! Fix
|-
| Title shows "Kimi Code" instead of custom || AI resets it via escape sequences || <code>PROMPT_COMMAND</code> auto-resets after every prompt
|-
| Tab right-click has no "Set Title" || GNOME Terminal 3.44+ removed it || Use <code>title</code> bash command or <code>Ctrl+b ,</code>
|-
| <code>title</code> command not found || <code>.bashrc</code> not loaded || Start an interactive shell, or run <code>source ~/.bashrc</code>
|-
| Default title shows <code>title "project"</code> || Working as designed — it's the syntax reminder || Type <code>title "your real project"</code> to replace it
|-
| AI agent crashed and pane is dead || Process exited || Press <code>Ctrl+b r</code> to respawn
|-
| Session already exists || Previous session still running || <code>tmux attach -t <name></code> or <code>tmux kill-session -t <name></code>
|}

== See Also ==

* [[IT Knowledge Base]]
* [[Forgejo]]
* [[Docker Stacks]]

[[Category:System Administration]]
[[Category:Development Environment]]
[[Category:AI Agents]]

Organizing Coder Terminals

2026-05-02T07:09:30Z

Justinaquino: Created article on organizing coder terminals with tmux (2026-05-02)

Forgejo Pages

2026-04-28T13:24:36Z

Justinaquino: Added Forgejo Pages setup guide

= Forgejo Pages — Complete Setup Guide =

<blockquote>**Wiki:** wiki.gi7b.org | **Last updated:** 2026-04-28</blockquote>
<blockquote>**Status:** Production — `pages.gi7b.org` live on PC03</blockquote>

----

== Overview ==

Forgejo does '''not''' have a built-in static site server. To serve Pages, you run a
separate <code>ronmi/forgejo-pages</code> container alongside Forgejo. It reads files from a
special branch in each repo via the Forgejo API and serves them over HTTP.

<syntaxhighlight>
Browser → Cloudflare DNS → NPM (SSL) → forgejo-pages:8080 → Forgejo API → repo branch
</syntaxhighlight>

* **Forgejo:** `https://git.gi7b.org` (container: `forgejo`, internal port 3000)
* **Pages server:** `https://pages.gi7b.org` (container: `forgejo-pages`, internal port 8080)
* **Routing:** path-based — `https://pages.gi7b.org/{owner}/{repo}/`
* **Branch name:** `static-pages` (exact, hardcoded default in this image)

----

== Gotchas — Read This First ==

=== 1. There is no built-in Pages in Forgejo ===
<code>ENABLE_FORGEJO_PAGES = true</code> in <code>app.ini</code> does nothing. It is not a real setting.
You need the external <code>ronmi/forgejo-pages</code> container.

=== 2. Branch must be named exactly `static-pages` ===
Not <code>gh-pages</code>, not <code>pages</code>, not <code>static_pages</code>. The image default is <code>static-pages</code>.
If the branch doesn't exist in the repo, the server returns 404.

=== 3. Use two separate tokens ===
{| class="wikitable"
! Token !! Scope !! Used by
|-
| `forgejo-pages` service token | `repository: read` | Docker container reads repo files via API
|-
| `git-push` personal token | `repository: read+write` + `user: read` | You/AI push code via git CLI
|}

Never use your account password for git CLI over HTTPS — it will be rejected.

=== 4. NPM forward port is the internal container port ===
When NPM uses the container DNS name (<code>forgejo-pages</code>), forward to port <code>8080</code> (internal).
If using the host IP (<code>192.168.196.76</code>), forward to port <code>8585</code> (exposed host port).
Mixing these up causes 502 Bad Gateway.

=== 5. Remove NPM Access List from git.gi7b.org ===
HTTP Basic Auth at the NPM layer blocks git CLI, API calls, and webhooks.
Forgejo's own auth (tokens, SSH keys, 2FA) is the correct security layer for a git host.

=== 6. SSH is more reliable than HTTPS for git push ===
HTTPS git auth has multiple failure modes (token scopes, credential helpers, NPM layers).
SSH just works. Set it up once per machine and never deal with tokens for pushing again.

----

== Docker Compose Setup ==

'''File:''' <code>/home/user/forgejo/compose.yml</code>

<syntaxhighlight lang="yaml">
services:
server:
image: codeberg.org/forgejo/forgejo:13
container_name: forgejo
restart: unless-stopped
environment:
- USER_UID=1000
- USER_GID=1000
volumes:
- ./data:/data
- /etc/localtime:/etc/localtime:ro
ports:
- "3001:3000"
- "223:22"
networks:
- internal
- proxy

pages:
image: ronmi/forgejo-pages
container_name: forgejo-pages
restart: unless-stopped
command: serve --server http://forgejo:3000 --token ${FORGEJO_PAGES_TOKEN} --bind :8080
ports:
- "8585:8080"
networks:
- internal
- proxy
depends_on:
- server

networks:
internal:
driver: bridge
proxy:
external: true
name: npm_proxy
</syntaxhighlight>

'''File:''' <code>/home/user/forgejo/.env</code>

<syntaxhighlight>
FORGEJO_PAGES_TOKEN=your_read_only_repository_token_here
</syntaxhighlight>

----

== Tokens ==

=== Service Token (for forgejo-pages container) ===
Generated in Forgejo → Settings → Applications:
* **Name:** `forgejo-pages-service`
* **Repository and Organization Access:** All
* **Permissions:** `repository: Read` only, everything else No access
* Goes in `/home/user/forgejo/.env` as `FORGEJO_PAGES_TOKEN`

=== Personal Push Token (for git CLI / AI agents) ===
Generated in Forgejo → Settings → Applications:
* **Name:** `git-push-{machinename}`
* **Repository and Organization Access:** All
* **Permissions:** `repository: Read and Write`, `user: Read`, everything else No access
* Used as the **password** when git prompts, or embedded in SSH-less workflows

----

== NPM Proxy Host — pages.gi7b.org ==

'''Details tab:'''
{| class="wikitable"
! Field !! Value
|-
| Domain Names | `pages.gi7b.org`
|-
| Scheme | `http`
|-
| Forward Hostname / IP | `forgejo-pages` (container name) OR `192.168.196.76` (host IP)
|-
| Forward Port | `8080` if using container name / `8585` if using host IP
|-
| Cache Assets | ✅ On
|-
| Block Common Exploits | ✅ On
|-
| Websockets Support | Off
|-
| Access List | **Publicly Accessible** (no HTTP Basic Auth)
|}

'''SSL tab:'''
{| class="wikitable"
! Field !! Value
|-
| SSL Certificate | `pages.gi7b.org` (Let's Encrypt)
|-
| Force SSL | ✅ On
|-
| HTTP/2 Support | ✅ On
|}

----

== SSH Setup for Git Push (per machine) ==

Run once on each machine that needs to push to Forgejo:

<syntaxhighlight lang="bash">
# Generate key
ssh-keygen -t ed25519 -C "{machinename}-git" -f ~/.ssh/id_ed25519 -N ""

# Show public key to add to Forgejo
cat ~/.ssh/id_ed25519.pub
</syntaxhighlight>

Add the public key in Forgejo → Settings → SSH / GPG Keys → Add Key.

Set remote URL to SSH (note custom port 223):

<syntaxhighlight lang="bash">
git remote set-url origin ssh://git@192.168.196.76:223/{owner}/{repo}.git
</syntaxhighlight>

<blockquote>Use the ZeroTier IP `192.168.196.76` directly — port 223 is not forwarded through</blockquote>
<blockquote>the public relay (PC06). SSH over ZeroTier is reliable for internal machines.</blockquote>
<blockquote>For external machines, either forward port 223 through PC06 or use HTTPS with a token.</blockquote>

----

== Publishing a Page (Repeatable Workflow) ==

=== New repo — first time ===

<syntaxhighlight lang="bash">
git clone ssh://git@192.168.196.76:223/{owner}/{repo}.git
cd {repo}

# Create orphan branch (no shared history with main)
git checkout --orphan static-pages
git rm -rf . 2>/dev/null || true

# Create your site
mkdir -p .
cat > index.html <<'EOF'
<!DOCTYPE html>
<html lang="en">
<head><meta charset="UTF-8"><title>My Page</title></head>
<body>
<h1>Hello from Forgejo Pages</h1>
</body>
</html>
EOF

git add .
git commit -m "Initial pages content"
git push -u origin static-pages
</syntaxhighlight>

Live immediately at: <code>https://pages.gi7b.org/{owner}/{repo}/</code>

=== Update existing pages ===

<syntaxhighlight lang="bash">
git checkout static-pages
# edit files
git add .
git commit -m "Update pages"
git push
</syntaxhighlight>

=== Via Forgejo Web UI (no git needed) ===

1. Open repo → click '''New File'''
2. Filename: <code>index.html</code>, add content
3. In commit section: select '''"Create a new branch"'''
4. Branch name: <code>static-pages</code>
5. Commit

----

== Verification ==

<syntaxhighlight lang="bash">
# Local test (on PC03)
curl -i http://localhost:8585/{owner}/{repo}/

# Expected: HTTP/1.1 200 OK + your HTML

# Check pages server logs
docker logs forgejo-pages --tail 20
</syntaxhighlight>

Browser: <code>https://pages.gi7b.org/{owner}/{repo}/</code> (trailing slash matters)

----

== Troubleshooting ==

{| class="wikitable"
! Symptom !! Cause !! Fix
|-
| 400 Bad Request | No valid owner/repo path in URL | URL must be `/{owner}/{repo}/`
|-
| 404 Not Found | `static-pages` branch missing or no `index.html` at root | Create branch, push `index.html` to root
|-
| 502 Bad Gateway | NPM port mismatch or container not on `npm_proxy` network | Check forward port (8080 internal / 8585 host). Verify: `docker network inspect npm_proxy \ | grep forgejo`
|-
| Auth failed (git push) | Wrong token scope or using account password | Use personal push token with `repository: write`. Use SSH instead.
|-
| SSH connection refused | Port 223 not reachable from external machine | Use ZeroTier IP for internal machines. Forward port via PC06 for external.
|-
| Pages container crash-looping | Missing `serve` command or bad token | Check `docker logs forgejo-pages`. Verify `.env` token is correct.
|-
| Stale content | Browser cache | Hard refresh (Ctrl+Shift+R) or test with `curl`
|}

Buzz Transcription

2026-04-24T18:43:50Z

Justinaquino: Add Buzz meeting transcription guide + Vulkan GPU & OOM investigation (2026-04-25)

Buzz is an open-source, offline-capable audio/meeting transcription tool powered by OpenAI Whisper (via whisper.cpp). On this system it is installed as a Flatpak and runs with Vulkan GPU acceleration on the AMD RX 7600.

== How to Transcribe a Meeting ==

=== Prerequisites ===
* Buzz installed (Flatpak: <code>io.github.chidiwilliams.Buzz</code>)
* A model downloaded — recommended: <code>ggml-large-v3-turbo</code> for quality, <code>ggml-tiny</code> for speed
* Models are stored at <code>~/.var/app/io.github.chidiwilliams.Buzz/cache/Buzz/models/</code>

=== File Transcription (Meeting Recording) ===
# Launch Buzz from the application menu or run: <code>flatpak run io.github.chidiwilliams.Buzz</code>
# Go to '''File → Import Media''' and select your meeting recording (MP3, WAV, M4A, etc.)
# In the transcription dialog:
#* '''Model''': Select <code>large-v3-turbo</code> (best quality for meetings)
#* '''Task''': Transcribe
#* '''Language''': Select your language or leave on Auto
#* '''Extract Speech''': '''Leave unchecked''' for files longer than ~30 minutes (see [[#OOM Crash with Large Files|OOM Crash]] below)
#* '''Output''': SRT, VTT, or TXT depending on your need
# Click '''Transcribe'''
# When complete, the transcript appears in the main window and is saved alongside the source file

=== Live Transcription (Real-Time) ===
# Go to '''File → Record and Transcribe'''
# Select your microphone input
# Choose model and language
# Click '''Record''' — transcription appears live on screen
# Stop recording when done; export via '''File → Export'''

=== Recommended Settings for Meetings ===
{| class="wikitable"
|-
! Setting !! Value !! Reason
|-
| Model || large-v3-turbo || Best accuracy; 1.6 GB VRAM, runs on RX 7600
|-
| Extract Speech || '''Off''' for files >30 min || Demucs uses 8–15 GB RAM for long files (OOM risk)
|-
| Language || Set explicitly || Faster than auto-detect
|-
| Task || Transcribe || Use Translate only if you need English output from another language
|}

=== Before Each Session: Clear Swap ===
Prior transcription sessions can leave stale pages in swap. Run this before starting a long transcription:
<pre>sudo swapoff -a && sudo swapon -a</pre>
This is safe when free RAM exceeds swap used (typical on this system: 15+ GB free, 8 GB swap).

== GPU Acceleration ==

Buzz's Flatpak installation includes a Vulkan-enabled <code>whisper-cli</code>. On this system, GPU inference is automatically active — no configuration needed.

* GPU in use: '''AMD RX 7600 (RDNA3, RADV NAVI33)'''
* Confirmed by: <code>whisper_backend_init_gpu: using Vulkan0 backend</code> in runtime output
* Buzz checks for Vulkan at startup (<code>IS_VULKAN_SUPPORTED</code>) and omits the <code>--no-gpu</code> flag when found

To force CPU inference (for debugging):
<pre>flatpak override --user io.github.chidiwilliams.Buzz --env=BUZZ_FORCE_CPU=true</pre>

To revert:
<pre>flatpak override --user --reset io.github.chidiwilliams.Buzz</pre>

== OOM Crash with Large Files ==

=== Symptom ===
When selecting <code>ggml-large-v3-turbo</code> in Buzz and starting a transcription on a long file, the application crashes. VRAM usage never visibly climbs before the crash.

=== Root Cause ===
The crash is caused by the '''Extract Speech (Demucs)''' pre-processing step, not the large model.

Demucs is a PyTorch-based music source separation model that strips background noise from audio before passing it to the transcription engine. It processes raw PCM audio at full float32 precision entirely in RAM:

{| class="wikitable"
|-
! Audio Duration !! Compressed Size !! RAM Required (Demucs)
|-
| 1 hour MP3 || ~60 MB || 500 MB – 1 GB
|-
| 3–4 hour session || ~220 MB || 8–15 GB peak
|}

The combination that caused the crash:
# Swap already exhausted from previous sessions
# Extract Speech (Demucs) triggered on a ~220 MB MP3 (~3–4 hours of audio)
# Python RAM usage exceeded available RAM + swap ceiling
# OOM killer terminated the process at 22 GB RSS
# <code>whisper-cli</code> was never launched → no VRAM activity observed

=== Why VRAM Never Climbed ===
<code>whisper-cli</code> runs as a subprocess of the Python GUI. The OOM kill happened during Demucs pre-processing — <code>whisper-cli</code> was never started, so no VRAM allocation occurred.

From the Buzz log at crash time:
<pre>~/.var/app/io.github.chidiwilliams.Buzz/.local/state/Buzz/log/logs.txt</pre>
The last entry was <code>Will extract speech</code> — the log never reached <code>Starting whisper file transcription</code>.

=== Fix ===
'''Uncheck "Extract Speech"''' in the Buzz transcription dialog for any file longer than ~30 minutes. The <code>large-v3-turbo</code> model has built-in noise tolerance that makes Demucs pre-processing unnecessary in most cases.

Optionally, grow the swapfile if you need Extract Speech for shorter files:
<pre>sudo swapoff /swap.img
sudo fallocate -l 16G /swap.img
sudo mkswap /swap.img
sudo swapon /swap.img</pre>

== Environment Variables ==

{| class="wikitable"
|-
! Variable !! Default !! Effect
|-
| <code>BUZZ_FORCE_CPU</code> || false || Set to <code>true</code> to disable GPU inference
|-
| <code>BUZZ_WHISPERCPP_N_THREADS</code> || cpu_count / 2 || Override thread count for whisper-cli
|}

Set via: <code>flatpak override --user io.github.chidiwilliams.Buzz --env=VAR=value</code>

== Key File Paths ==

{| class="wikitable"
|-
! Path !! Description
|-
| <code>/var/lib/flatpak/app/io.github.chidiwilliams.Buzz/.../buzz/whisper_cpp/whisper-cli</code> || Bundled Vulkan whisper-cli (libwhisper 1.8.3)
|-
| <code>~/.var/app/io.github.chidiwilliams.Buzz/cache/Buzz/models/</code> || Buzz model cache (ggml binaries)
|-
| <code>~/.var/app/io.github.chidiwilliams.Buzz/.local/state/Buzz/log/logs.txt</code> || Buzz application log
|-
| <code>~/.var/app/io.github.chidiwilliams.Buzz/config/Buzz.conf</code> || Buzz settings
|-
| <code>~/whisper.cpp/build/bin/whisper-cli</code> || Custom Vulkan-enabled whisper.cpp build
|-
| <code>~/bin/whisper-cli-vulkan</code> || Wrapper script for custom build (sets <code>LD_LIBRARY_PATH</code>)
|-
| <code>~/.local/share/pipx/venvs/buzz-captions/lib/python3.12/site-packages/buzz/whisper_cpp/</code> || pipx install whisper_cpp directory (directly modifiable)
|}

== Investigation Summary ==

{| class="wikitable"
|-
! Question !! Finding
|-
| Is Buzz using the RX 7600? || '''Yes.''' <code>using Vulkan0 backend</code> confirmed inside the Flatpak sandbox.
|-
| Was <code>--no-gpu</code> being added? || '''No.''' <code>IS_VULKAN_SUPPORTED = True</code> in the sandbox; flag is never appended.
|-
| Does the large model load correctly? || '''Yes.''' 1.6 GB to VRAM, transcribes in ~1.25s on a short clip.
|-
| What caused the crash? || '''Extract Speech (Demucs) OOM.''' Python killed at 22 GB RSS before whisper-cli launched.
|-
| Why was VRAM not climbing? || <code>whisper-cli</code> was never started — process died during Demucs pre-processing.
|-
| Fix? || '''Uncheck Extract Speech''' for long files. Clear swap before sessions.
|}

''Investigation date: 2026-04-25. System: Ubuntu 24.04, AMD RX 7600, Buzz 1.4.4 (Flatpak).''

PfSense Sales Training Material

2026-04-23T11:59:49Z

Justinaquino: Restructure: client-friendly networking table, expand myths section, add 5-Pillar Scoping Framework

= pfSense Sales Training Material =

'''Reference:''' [https://chatgpt.com/share/67c82515-7074-800e-b29c-0df75f5492f3 Full Session Log]

----

== 1. Introduction ==

; Objective
: Provide a clear, layman-friendly explanation of what a firewall is, why pfSense is a powerful solution, and how its key features protect networks.

; Audience
: Sales teams, marketing, and non-technical staff who need to explain the technology to potential customers — non-technical decision-makers, IT managers, and SMB owners.

----

== 2. Network Basics ==

; Definition
: Networking is the ability to connect computers and systems together. It occurs when more than one device communicates with another device or group of devices.

=== Networking Disciplines ===

==== ECE (Electronics and Communication Engineering) ====
* Focuses on how electronic devices work and on designing/building network hardware from basic components.
* In the Philippines, a PRC ECE license is required to sign off plans for CCTV installations — the only legally mandated network designs (CCTV and phone lines).
* '''Sales Note:''' Clients needing custom electronic solutions (for automation or high-security requirements) will require ECE expertise.

==== IT (Information Technology) ====
* Specializes in deploying and integrating off-the-shelf networking equipment.
* Advanced configurations improve reliability, scalability (hundreds to thousands of users), and automation for convenience.
* '''Sales Note:''' Larger-scale deployments and convenience features command higher-level IT skills and corresponding investment.

=== Networking Functions ===

{| class="wikitable"
|-
! Function
! What This Means for Your Business
! Technical Role
|-
| '''Connecting to the Internet'''<br/>(WAN — Wide Area Network)
| Your business's door to the outside world — controls what comes in and what goes out.
| Connects the facility to external networks (Internet or other sites).
|-
| '''Connecting Your Devices Together'''<br/>(LAN — Local Area Network)
| Lets computers, printers, servers, and phones talk to each other inside your office.
| Connects devices within the facility for internal communications.
|-
| '''Staying Online Even When Hardware Fails'''<br/>(High Availability)
| Prevents downtime — if one device fails, another takes over automatically.
| Builds redundancy and resilience so services stay online despite failures.
|-
| '''Controlling Who Can Access What'''<br/>(User Management)
| Staff, guests, and contractors each see only what they're supposed to see.
| Implements captive portals, LDAP, RADIUS to organize users by roles and privileges.
|-
| '''Protecting Against Attacks and Breaches'''<br/>(Security)
| Keeps threats out and sensitive data in — separates risky zones from critical systems.
| Establishes hardened systems using DMZs (buffer zones) and proxy servers.
|-
| '''Wireless Connectivity'''<br/>(Wi-Fi)
| Lets staff and devices connect without cables — can be segmented by department or role.
| Deploys mesh or enterprise Wi-Fi for convenient, flexible connectivity.
|-
| '''Wired Connectivity'''<br/>(Ethernet/LAN Cabling)
| High-speed, reliable connections for servers, workstations, and critical equipment.
| Provides high-bandwidth, low-latency connections for critical systems.
|}

----

== 3. Key Myths & Objections ==

Understanding and countering these objections is critical in every sales conversation.

=== Myth 1: "We're too small — we don't need a firewall" ===
; Reality
: Small and medium businesses are the most targeted precisely because attackers know they have weak defenses. Anyone hosting a web server, NAS, ERP system, or remote workers needs a firewall. Size is not protection.

=== Myth 2: "Our ISP router/modem is enough" ===
; Reality
: ISP-provided routers are consumer-grade equipment with no intrusion detection, no network segmentation, no VPN capability, and no traffic monitoring. They are designed for convenience, not security.

=== Myth 3: "Firewalls only block traffic" ===
; Reality
: Modern firewalls do far more — they segment your network into zones, prioritize critical traffic (e.g., video calls over casual browsing), detect intrusions in real time, and enable secure VPN access for remote workers.

=== Myth 4: "A VPN is all the security I need" ===
; Reality
: A VPN only encrypts traffic between two points. It does nothing to protect your internal network from threats already inside, compromised devices, or unauthorized users on-site.

=== Myth 5: "The cloud handles our security" ===
; Reality
: Cloud providers secure their own infrastructure. Your office network, on-site devices, servers, and traffic between locations remain entirely your responsibility.

=== Myth 6: "Hardware firewalls are different from software firewalls" ===
; Reality
: All firewalls are computers running software. A "hardware firewall" is simply dedicated hardware optimized to run firewall software. Performance scales by upgrading network interface cards: 100 Mbps → 1 Gbps → 10 Gbps → 100 Gbps.

=== Myth 7: "Competitor products are better out-of-the-box" ===
; Reality
: Competitors like Fortinet and Cisco lock key features behind annual licenses that expire. When you stop paying, features stop working. pfSense delivers enterprise-grade features permanently — only updates and support require payment.

----

== 4. Why pfSense? ==

* '''Open Source:''' No recurring feature licenses; you pay only for support and updates. When support lapses, pfSense continues to work — only security updates stop.
* '''Enterprise Features:'''
** LAN/WAN routing and segmentation
** VPN (remote access and site-to-site)
** IDS/IPS (intrusion detection and prevention)
** High Availability & Load Balancing
** DHCP, DNS, and user Authentication
* '''No License Lock-in:''' Other vendors "rent" features that expire with licenses. pfSense features remain available indefinitely.

----

== 5. Core Functions & Features ==

=== Primary Functions ===

{| class="wikitable"
|-
! Function
! Explanation
|-
| '''LAN'''
| Segments and protects internal network traffic to enforce security zones.
|-
| '''WAN'''
| Controls access to the Internet; filters inbound/outbound traffic.
|-
| '''VPN'''
| Creates encrypted tunnels for secure remote access or site-to-site links.
|-
| '''IDS/IPS'''
| Monitors traffic for threats and automatically blocks or alerts on intrusions.
|}

=== Secondary Features ===

* '''Authentication:''' Integrates with Active Directory, LDAP, RADIUS for user-based firewall policies.
* '''DHCP:''' Assigns IP addresses automatically to devices on the network.
* '''DNS:''' Acts as resolver or forwarder to improve name lookup speed and security.
* '''Load Balancer / HA:''' Distributes traffic across multiple WAN links or appliances and provides failover.

----

== 6. The 5-Pillar Scoping Framework ==

Use this framework on every prospect conversation. Work through each pillar in order — each answer builds context for the next. The goal is to understand the client's situation before recommending any hardware or solution.

=== Pillar 1: Stakes ===

''Budget equals stakes. Before pricing anything, establish what is at risk.''

; Key Questions
: "What happens to your business if the network goes down for a full day?"
: "What data do you store or process — customer records, financial data, health information?"
: "Have you experienced a breach or outage before? What did it cost you?"

; What It Tells You
: The client's tolerance for risk and the true value of the protection being sold. A business that loses 50,000 PHP per hour of downtime has very different stakes than one running a small shared drive.

; How It Maps to pfSense
: '''High stakes''' → High Availability setup, IDS/IPS, VLAN segmentation, full TAC support.
: '''Lower stakes''' → Single appliance, basic firewall rules, standard support.

; Sales Note
: This pillar justifies the budget. Never skip it — without establishing stakes, you are selling on price alone and will always lose to the cheapest option.

=== Pillar 2: Devices & Users ===

''Knowing the scale determines the hardware tier.''

; Key Questions
: "How many staff members use the network daily?"
: "What devices are connected — computers, phones, tablets, IP cameras, printers, servers, POS terminals?"
: "Do you have remote workers or multiple office locations?"

; What It Tells You
: Scale of deployment, number of network interfaces needed, and whether user management features (captive portal, RADIUS) are required.

; How It Maps to pfSense
: <10 users → Entry-level appliance.
: 10–100 users → Mid-range (Netgate 4200 series).
: 100–500 users → HA pair (2× Netgate 4200 MAX, ~120k PHP one-time).
: 500+ users or ISP → Netgate 6100 series or higher.

=== Pillar 3: Bandwidth & Traffic ===

''Traffic type matters as much as raw speed.''

; Key Questions
: "What is your current internet plan speed (download/upload)?"
: "What do people do on the network — video calls, large file transfers, cloud apps, IP cameras streaming 24/7?"
: "Do you have peak hours where the network slows down noticeably?"

; What It Tells You
: WAN capacity requirements, whether QoS (Quality of Service) is needed to prioritize traffic types, and the processing load for IDS/IPS inspection.

; How It Maps to pfSense
: Heavy video/VoIP usage → QoS rules to prioritize real-time traffic.
: Heavy cloud usage → WAN load balancing for redundancy and speed.
: Many IP cameras → Dedicated VLAN and allocated bandwidth.

=== Pillar 4: Hardware Compatibility ===

''Existing infrastructure must integrate — not be replaced.''

; Key Questions
: "What servers do you have on-site — web servers, NAS, ERP, database?"
: "Do you have CCTV systems, POS terminals, VoIP phones, or other specialty devices?"
: "What network switches and access points are currently deployed?"

; What It Tells You
: VLAN design requirements, potential conflicts with existing devices, number of network interfaces needed, and whether any equipment requires a DMZ or special firewall rules.

; How It Maps to pfSense
: '''NAS or web server''' → DMZ or isolated VLAN with strict inbound rules.
: '''CCTV system''' → Isolated VLAN with no internet access (security best practice).
: '''POS terminals''' → Segmented from general office traffic (PCI-DSS compliance).
: '''VoIP phones''' → Dedicated VLAN with QoS priority to prevent call drops.

=== Pillar 5: Features & Functions Needed ===

''Match the pfSense feature set to the client's actual workflow.''

; Key Questions
: "Do staff work remotely and need secure access to office systems?"
: "Do you have a second office location that needs to connect to the main office?"
: "Do guests or contractors need network access, separate from staff?"
: "Are there compliance requirements — PCI, HIPAA, data privacy laws?"

; What It Tells You
: Which pfSense features to highlight in the proposal and configure in the deployment.

; How It Maps to pfSense
: Remote workers → VPN (OpenVPN or WireGuard).
: Multiple sites → Site-to-site VPN.
: Guest or contractor access → Captive portal with time or bandwidth limits.
: Compliance requirements → IDS/IPS, logging, VLAN segmentation, audit trails.

----

== 7. Sizing & Total Cost of Ownership (TCO) ==

=== Sizing Guidelines ===

{| class="wikitable"
|-
! Company Size / Bandwidth
! Recommended Model
! Notes
|-
| Under 1 Gbps Internet
| Netgate 6100 Series
| Fits most small-to-medium offices
|-
| Up to 500 Users
| 2× Netgate 4200 MAX (HA setup)
| ~120k PHP one-time cost for both appliances
|-
| Large Networks / ISPs (>1 Gbps)
| Netgate 6100+ or higher
| Only ISPs or large enterprises need these models
|}

=== Example: Makati Office (200 Users) ===

* '''Hardware Cost:''' 2×4200 MAX for HA → '''120,000 PHP''' (one-time)
* '''Annual Costs:'''
** License Renewal: 7,500 PHP × 2 = '''15,000 PHP/year'''
** TAC Support: '''45,000 PHP/year''' (one needed in HA)
** Snort Subscription: 24,000 PHP × 2 = '''48,000 PHP/year'''
** '''Total Annual: ~84,000 PHP/year'''

{{Note|'''Competitor Comparison:''' Fortinet equivalent: 150k PHP hardware + 200k PHP/year support → pfSense is more cost-effective.}}

----

== 8. Next Steps for Sales ==

# Work through the [[#The 5-Pillar Scoping Framework|5-Pillar Scoping Framework]] with the client before recommending any hardware.
# Select the right appliance based on scoping output (6100 vs 4200 MAX vs higher models).
# Prepare TCO comparison (pfSense vs competitor).
# Send proposal template and service brochure.

----

== Resources & References ==

* [https://www.comfac-it.com/services/netgate-pfsense-setup Setup Services]
* [https://www.comfac-it.com/blog-post/making-sense-of-unified-threat-management-utm UTM Deep Dive]
* [https://www.pfsense.org/products/ Netgate Product Info]

PfSense Training Project Tracker

2026-04-23T10:43:07Z

Justinaquino: Update Phase 1: Decision made to use dedicated training machine instead of 200-core server; add hardware selection tasks

__NOTOC__
<div style="background:#fff8e1; border:1px solid #ffcc80; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
'''Project Tracker''' for Comfac's pfSense Practical Training System implementation. This page tracks all tasks from material conversion to infrastructure deployment and course delivery.
</div>

== Phase 0: Material Conversion (FUND001 → Wiki) ==
Convert all Netgate FUND001 training PDFs into CITWiki pages with detailed summaries. Each wiki page should include: learning objectives, key concepts, step-by-step lab instructions adapted for virtual environment, and troubleshooting tips.

=== Slide Decks ===
* [x] '''SEG1 — Introduction to pfSense''' → [[Training: pfSense Introduction]]
* [x] '''SEG2 — Interfaces, VIPs, and Rules''' → [[Training: Interfaces and Firewall Rules]]
* [x] '''SEG3 — NAT and VIPs''' → [[Training: NAT and Virtual IPs]]
* [x] '''SEG4 — pfSense Services''' → [[Training: pfSense Services]]
* [x] '''SEG5 — VPNs and IPsec''' → [[Training: IPsec VPN]]
* [x] '''SEG6 — OpenVPN''' → [[Training: OpenVPN]]
* [x] '''SEG7 — WireGuard''' → [[Training: WireGuard]]
* [x] '''SEG8 — Multi-WAN''' → [[Training: Multi-WAN]]
* [x] '''SEG9 — Traffic Shaping''' → [[Training: Traffic Shaping]]
* [x] '''SEG10 — High Availability''' → [[Training: High Availability]]
* [x] '''SEG11 — Other Features''' → [[Training: Monitoring and Packages]]

=== Labs ===
* [x] '''Lab 1 — Intro, Getting Started, Backup/Restore''' → [[Training Lab 1: Introduction and Backup Restore]]
* [x] '''Lab 2 — Interfaces, Firewall Rules, Aliases''' → [[Training Lab 2: Firewall Rules and Aliases]]
* [x] '''Lab 3 — Virtual IPs and NAT''' → [[Training Lab 3: NAT and Virtual IPs]]
* [x] '''Lab 4 — Services and Branch Network Setup''' → [[Training Lab 4: Services and Branch Network]]
* [x] '''Lab 5 — IPsec''' → [[Training Lab 5: IPsec VPN]]
* [x] '''Lab 6 — OpenVPN''' → [[Training Lab 6: OpenVPN]]
* [x] '''Lab 7 — WireGuard''' → [[Training Lab 7: WireGuard]]
* [x] '''Lab 8 — Multi-WAN''' → [[Training Lab 8: Multi-WAN]]
* [x] '''Lab 9 — Traffic Shaping''' → [[Training Lab 9: Traffic Shaping]]
* [x] '''Lab 10 — High Availability''' → [[Training Lab 10: High Availability]]

=== Comfac Original Content ===
* [x] '''Introduction Training (Module 0)''' → [[Training: Setting Up a Firewall for Yourself]] — Personal/small business firewall
* [ ] '''the-pfsense-documentation.pdf''' → Summarize into [[Training: pfSense Complete Reference]] or link as external reference
* [ ] '''WindowsTrainingSupportFiles.zip''' → Extract and document client software requirements ([[Training: Client Software Requirements]])
* [ ] '''Training Videos (4× .mkv)''' → Catalog timestamps and link from relevant wiki pages

== Phase 1: Infrastructure Setup ==
Build the virtual training environment on a '''dedicated training machine''' — NOT the 200-core / 1TB RAM production server. The 200-core machine should remain fully available for ERPNext, AI workloads, and production services.

=== Resource Analysis (Completed) ===
* [x] '''R.1''' Compare Pure Linux (FOSS) vs Windows stacks -> [[Networking PfSense Index#Resource Estimates Per Student]]
* [x] '''R.2''' Calculate 20% server utilization targets -> 13 students (Linux), 6 students (Windows)
* [x] '''R.3''' Analyze container-based alternatives -> LXC for Linux routers; KVM still required for pfSense
* [x] '''R.4''' Define exercise-limited deployment model -> Right-size per lab; 0-4 vCPUs per student
* [x] '''R.5''' Specify smaller server options for 10 students -> Dell R630 (Linux) / R740 (Windows)
* [x] '''R.6''' Design AI evaluation pipeline -> Qwen 3.5 Coder 9GB + DeepSeek + OpenCode for automated readiness
* [x] '''R.7''' Decide against using 200-core server -> Training will run on dedicated used server or repurposed desktop

=== Hardware Selection ===
* [ ] '''H.1''' Audit retiring desktops from Win2Lin migration for reuse as training server
* [ ] '''H.2''' If no suitable desktop: procure used Dell R630/R640 (32c/64GB) or HP DL360 Gen9
* [ ] '''H.3''' If rack space/noise is issue: procure 3x Intel N100 mini-PCs for silent cluster
* [ ] '''H.4''' Install Intel i350-T4 quad-port NIC if machine only has 1 Ethernet port
* [ ] '''H.5''' Label machine as CIT-TRAINING-01; document in asset inventory

=== Host Preparation ===
* [ ] '''A.1''' Install Ubuntu Server LTS 22.04/24.04 on training hardware
* [ ] '''A.2''' Configure KVM/libvirt with storage pools (NVMe for golden images, SSD for ephemeral clones)
* [ ] '''A.3''' Set up network bridges: br-mgmt, br-lan, br-wan, br-dmz, br-internet
* [ ] '''A.4''' Configure VLANs for student isolation (one VLAN per student or per lab)
* [ ] '''A.5''' Install and configure Ansible controller (host or Docker container)
* [ ] '''A.6''' Verify training machine has no dependency on 200-core server (standalone)

=== Base Images ===
* [ ] '''B.1''' Download pfSense CE ISO and create qcow2 golden image (1 vCPU, 512 MB RAM, 4 GB disk - microVM)
* [ ] '''B.2''' Create Alpine Linux LXC golden image (0.5 vCPU, 256 MB RAM, 1 GB disk)
* [ ] '''B.3''' Create Debian XFCE LXC golden image for NoVNC client (0.5 vCPU, 256 MB RAM, 2 GB disk)
* [ ] '''B.4''' Create Ubuntu Server LXC golden image (0.5 vCPU, 256 MB RAM, 1 GB disk)
* [ ] '''B.5''' Create "Internet Router" LXC golden image (0.5 vCPU, 128 MB RAM, 0.5 GB disk)
* [ ] '''B.6''' Test each golden image boots and functions correctly

=== Automation ===
* [ ] '''C.1''' Write Ansible playbook: lab1-student-env.yml (1 pfSense microVM + 1 LXC client)
* [ ] '''C.2''' Write Ansible playbook: lab2-student-env.yml (1 pfSense + 1 client + 1 server LXC)
* [ ] '''C.3''' Write Ansible playbook: lab3-student-env.yml (1 pfSense + 1 server + internet router LXC)
* [ ] '''C.4''' Write Ansible playbook: lab4-student-env.yml (2 pfSense + 2 clients + 1 server)
* [ ] '''C.5''' Write Ansible playbooks for Labs 5-10 (VPNs, Multi-WAN, Shaping, HA)
* [ ] '''C.6''' Write Ansible playbook: cleanup-student-env.yml (destroy VMs/LXCs, free resources)
* [ ] '''C.7''' Write Ansible playbook: reset-student-env.yml (revert to snapshot/linked clone base)
* [ ] '''C.8''' Test all playbooks end-to-end with a single student ID

=== NoVNC Portal ===
* [ ] '''D.1''' Evaluate Kimchi vs Apache Guacamole vs custom NoVNC proxy
* [ ] '''D.2''' Install and configure chosen NoVNC solution
* [ ] '''D.3''' Integrate NoVNC with student authentication (LDAP, local wiki accounts, or simple token-based)
* [ ] '''D.4''' Build student dashboard: list of phases/labs, "Launch Lab" button, countdown timer
* [ ] '''D.5''' Test 5 concurrent NoVNC sessions for stability
* [ ] '''D.6''' Test 20 concurrent NoVNC sessions for performance

=== AI Evaluation Pipeline ===
* [ ] '''E.1''' Deploy Qwen 3.5 Instruct Coder 9GB on GPU box or 200-core host
* [ ] '''E.2''' Build pytest + Selenium test suite for pfSense GUI validation
* [ ] '''E.3''' Build SSH-based health check suite for VM/LXC connectivity
* [ ] '''E.4''' Integrate DeepSeek or OpenCode for playbook syntax validation
* [ ] '''E.5''' Create readiness dashboard (pass/fail per lab, resource usage graphs)
* [ ] '''E.6''' Schedule automated nightly tests of all lab environments

== Phase 2: Curriculum Development ==
Design the student-facing training program.

=== Introduction Course (Most Common Use Case) ===
* [x] '''E.1''' Define "Setting Up a Firewall for Yourself" scope: home office / small business
* [x] '''E.2''' Write Module 0: Why You Need a Firewall (threats, NAT basics, basic topology)
* [x] '''E.3''' Write Module 1: Install pfSense on Old PC or VM (hardware requirements, USB install, first boot wizard)
* [x] '''E.4''' Write Module 2: Basic WAN + LAN Setup (DHCP, DNS, first internet connection)
* [x] '''E.5''' Write Module 3: Essential Firewall Rules (block incoming, allow outgoing, ICMP)
* [x] '''E.6''' Write Module 4: Port Forwarding for Common Services (game server, camera, NAS)
* [x] '''E.7''' Write Module 5: VPN for Remote Access (WireGuard road warrior setup)
* [x] '''E.8''' Write Module 6: Backup and Updates (config.xml backup, update schedule)
* [x] '''E.9''' Create hands-on lab for Introduction Course (single pfSense + 1 client VM)
* [ ] '''E.10''' Record or source video walkthroughs for each module

=== Full FUND001 Adaptation ===
* [x] '''F.1''' Map each SEG slide deck to a wiki training page with summary + key takeaways
* [x] '''F.2''' Adapt Netgate labs from physical/virtualbox environment to KVM/Ansible environment
* [ ] '''F.3''' Update IP addressing schema for Comfac virtual lab (avoid conflicts with production)
* [ ] '''F.4''' Write pre-lab briefing pages (what you'll learn, expected outcomes)
* [ ] '''F.5''' Write post-lab review pages (common mistakes, verification steps, "show me" checklist)
* [ ] '''F.6''' Create quiz questions for each phase (5–10 questions, auto-graded if possible)

== Phase 3: Pilot & Refinement ==
Run the training with a small group before full rollout.

=== Internal Pilot ===
* [ ] '''G.1''' Recruit 3–5 internal Comfac IT staff as pilot students
* [ ] '''G.2''' Run Phase 1 (Foundations) with pilot group — collect feedback
* [ ] '''G.3''' Run Phase 2 (NAT & Services) with pilot group — collect feedback
* [ ] '''G.4''' Run one VPN lab (IPsec or OpenVPN) with pilot group — test resource limits
* [ ] '''G.5''' Document all bugs, confusion points, and timeouts
* [ ] '''G.6''' Refine playbooks and wiki pages based on pilot feedback

=== Resource Tuning ===
* [ ] '''H.1''' Measure actual CPU/RAM/disk usage per student during pilot
* [ ] '''H.2''' Adjust VM specs if over- or under-provisioned
* [ ] '''H.3''' Test memory overcommit ratios for safe concurrency scaling
* [ ] '''H.4''' Document maximum safe concurrent student count

== Phase 4: Deployment & Operations ==
Prepare for regular training delivery.

=== Student Onboarding ===
* [ ] '''I.1''' Create student onboarding guide (how to access portal, use NoVNC, reset lab)
* [ ] '''I.2''' Create instructor guide (how to monitor progress, assist students, grade labs)
* [ ] '''I.3''' Set up scheduling system (book lab time slots, prevent over-allocation)
* [ ] '''I.4''' Create completion certificates or badges

=== Monitoring & Maintenance ===
* [ ] '''J.1''' Set up host monitoring (Prometheus/Grafana or simple `libvirt` stats)
* [ ] '''J.2''' Configure alerts for host resource exhaustion
* [ ] '''J.3''' Schedule weekly base image updates (pfSense patches, OS updates)
* [ ] '''J.4''' Document disaster recovery (rebuild host from Ansible, restore golden images)

== Quick Status Dashboard ==
{| class="wikitable"
! Phase !! Status !! % Complete !! Blockers
|-
| Phase 0: Material Conversion || 🟢 Done (22/23) || 96% || Pending: reference PDF, support files, videos
|-
| Phase 1: Infrastructure Setup || 🟡 In Progress || 20% || Hardware decision made; acquire dedicated training machine
|-
| Phase 2: Curriculum Development || 🟡 In Progress || 65% || Need video recordings, quizzes, pre/post lab pages
|-
| Phase 3: Pilot & Refinement || 🔴 Not Started || 0% || Waiting on Phase 1 + 2
|-
| Phase 4: Deployment & Operations || 🔴 Not Started || 0% || Waiting on Phase 3
|}

== Resource Summary ==
'''Per-student minimum:''' 6 vCPUs, 6.5 GB RAM, 62 GB disk
'''Per-student full lab:''' 10 vCPUs, 10.5 GB RAM, 110 GB disk
'''200-core / 1TB capacity:''' 20–40 concurrent students (conservative to optimized)

'''Next Actions (This Week):'''
# Summarize the-pfsense-documentation.pdf into a reference page
# Document WindowsTrainingSupportFiles.zip contents
# Catalog training video timestamps
# Begin Ansible playbook drafting for Lab 1 environment
# Evaluate Kimchi vs Guacamole for NoVNC portal

Networking PfSense Index

2026-04-23T10:42:09Z

Justinaquino: Add Dedicated Training Server Strategy: recommend separate machine instead of 200-core server; include mini-PC cluster, used server, desktop repurpose, ARM SBC options; cost-benefit analysis

__NOTOC__
<div style="background:#f0f7ff; border:1px solid #b8d4f0; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
'''Consolidated index''' for all networking infrastructure guides, pfSense documentation, DNS/ad-blocking resources, and network equipment references at Comfac IT.
</div>

== pfSense Core Guides ==
* [[pfSense Sales Training Material]] — Product knowledge and sales positioning for Netgate/pfSense hardware and software
* [[Modern Guide: pfSense Captive Portal with FreeRADIUS & ACME]] — Enterprise Wi-Fi captive portal with RADIUS authentication and Let's Encrypt SSL
* [[pfSense CE → pfSense Plus Upgrade Guide]] — Step-by-step migration from Community Edition to pfSense Plus
* [[SOP: Network Troubleshooting & pfSense Monitoring 251130]] — Standard operating procedures for network diagnostics and pfSense health monitoring

== Network Infrastructure & Equipment ==
* [[Tplink Mikrotik Equivalent]] — Cross-reference of TP-Link and MikroTik models for network deployments
* [[Controller Systems 251213-01]] — Network and infrastructure controller systems
* [[Power Distribution Tree 251213]] — Power architecture for network and server racks
* [[NPM Migration to Homelab VPS Relay 260401]] — Nginx Proxy Manager migration; VPS as iptables/ZeroTier relay with homelab redundancy

== DNS, Ad Blocking & Pi-hole ==
* [https://github.com/Comfac-Global-Group/pi-hole Comfac Pi-hole Repository] — GitHub repository for Pi-hole DNS sinkhole deployment
* [https://github.com/Comfac-Global-Group/pi-hole/blob/master/How%20this%20Works.md How Pi-hole Works] — Technical overview of the Pi-hole DNS filtering architecture

== Training & Skills ==
* [[Skills and Competencies for IT Staff Trained in pfSense]] — Required competencies and certification path for pfSense-administering staff
* [[PfSense Training Project Tracker]] — '''Implementation tracker''' for the NoVNC virtual lab, material conversion, and curriculum development

== Practical Training System (NoVNC Virtual Lab) ==
'''Goal:''' Build a self-hosted, virtualized pfSense training environment where Comfac trainees can learn hands-on without physical hardware. All labs run via NoVNC in a browser, orchestrated on Comfac's 200-core / 1TB RAM machine.

=== Training Architecture Vision ===
Each student gets an isolated virtual network sandbox containing:
* 2× pfSense VMs (HQ HA pair or HQ + Branch)
* 1–2× Client VMs (Windows/Linux desktop)
* 1× Server VM (web/DNS/target)
* 1× Simulated "Internet" router VM

Access is through a NoVNC web portal. Students click a lab, and their environment is provisioned automatically via Ansible/Terraform or Docker/KVM.

=== Resource Estimates Per Student ===

==== Stack A: Pure Linux / FOSS (Recommended for Comfac) ====
All components run on open-source software. Clients are lightweight Linux VMs or LXC containers. No Windows licensing required.

{| class="wikitable"
! Component !! vCPUs !! RAM !! Disk !! Virtualization !! Notes
|-
| pfSense VM || 1 || 512 MB || 4 GB || KVM microVM || FreeBSD requires KVM; use tiny QEMU args
|-
| Linux Client (LXC) || 0.5 || 256 MB || 1 GB || LXC container || Alpine or Debian with XFCE; NoVNC access
|-
| Linux Server (LXC) || 0.5 || 256 MB || 1 GB || LXC container || nginx, BIND, or simple Python HTTP
|-
| Internet Router (LXC) || 0.5 || 128 MB || 0.5 GB || LXC container || Static routes only; FRR optional
|-
| NoVNC Proxy (Docker) || 0.5 || 256 MB || 0.5 GB || Docker container || websockify + nginx
|-
| '''Total per student''' || '''3''' || '''1.4 GB''' || '''7 GB''' || — || Thin-provisioned; linked clones
|}

==== Stack B: Windows Client (Full Desktop Experience) ====
For trainees who need a Windows desktop for browser-based management or specific client software.

{| class="wikitable"
! Component !! vCPUs !! RAM !! Disk !! Virtualization !! Notes
|-
| pfSense VM || 2 || 1 GB || 8 GB || KVM || Standard qcow2 image
|-
| Windows Client || 2 || 4 GB || 40 GB || KVM || Windows 10/11 thin client; needs GPU if GUI-heavy
|-
| Ubuntu Server || 1 || 1 GB || 10 GB || KVM || Full VM for compatibility
|-
| Internet Router || 1 || 512 MB || 4 GB || KVM || Ubuntu with static routes
|-
| NoVNC Proxy || 0.5 || 256 MB || 0.5 GB || Docker || Shared across students
|-
| '''Total per student''' || '''6.5''' || '''6.8 GB''' || '''63 GB''' || — || Higher resource cost
|}

==== Stack C: Hybrid — Containers for Linux Router Exercises ====
For basic routing/firewall concept labs only (not pfSense-specific), replace pfSense with Linux routers in containers.

{| class="wikitable"
! Component !! vCPUs !! RAM !! Disk !! Virtualization !! Notes
|-
| Linux Router (LXC) || 0.5 || 128 MB || 0.5 GB || LXC || Alpine + iptables/nftables + WireGuard
|-
| Linux Client (LXC) || 0.5 || 256 MB || 1 GB || LXC || Alpine or Debian
|-
| Linux Server (LXC) || 0.5 || 256 MB || 1 GB || LXC || nginx, BIND
|-
| Internet Router (LXC) || 0.5 || 128 MB || 0.5 GB || LXC || Static routes
|-
| '''Total per student''' || '''2''' || '''768 MB''' || '''3 GB''' || — || Cannot teach pfSense GUI; teaches concepts only
|}

'''Important:''' pfSense is FreeBSD-based and cannot run in Linux containers (Docker/LXC). Stack C is suitable for teaching routing/VPN concepts using Linux tools (iptables, nftables, WireGuard, strongSwan), but not for teaching the pfSense web interface. For pfSense GUI training, use Stack A or B.

=== Server Capacity: 20% Utilization Target ===
The goal is to run the training environment using only 20% of the 200-core / 1TB RAM server, leaving 80% for other Comfac workloads (ERPNext, AI models, file services).

'''20% of available resources:'''
* 40 vCPUs (20% of 200)
* 200 GB RAM (20% of 1 TB)
* ~2 TB SSD (assuming 10 TB array, 20% = 2 TB)

'''Concurrent student capacity at 20% utilization:'''

{| class="wikitable"
! Stack !! Per-Student Resources !! Students at 20% CPU !! Students at 20% RAM !! Limiting Factor
|-
| '''A: Pure Linux''' || 3 vCPU / 1.4 GB || 13 || 142 || '''CPU: 13 students'''
|-
| '''B: Windows''' || 6.5 vCPU / 6.8 GB || 6 || 29 || '''CPU: 6 students'''
|-
| '''C: Containers''' || 2 vCPU / 0.8 GB || 20 || 250 || '''CPU: 20 students'''
|}

'''Recommendation:''' Use Stack A (Pure Linux) for all labs. This yields ~13 concurrent students within the 20% budget, or up to ~30 students if spread across time slots (not everyone needs a lab simultaneously).

=== Smaller Server: What Hardware for 10 Students? ===
If buying a dedicated training server instead of using the 200-core machine:

{| class="wikitable"
! Stack !! CPU !! RAM !! Storage !! NICs !! Example Hardware
|-
| '''A: Pure Linux''' || 32 cores || 32 GB || 500 GB NVMe || 2x 1GbE || Used Dell R630/R640 (~$300-500)
|-
| '''B: Windows''' || 64 cores || 96 GB || 1 TB NVMe || 2x 1GbE || Used Dell R740 / HP DL360 (~$600-900)
|-
| '''C: Containers''' || 16 cores || 16 GB || 250 GB NVMe || 2x 1GbE || Old desktop + Intel NIC (~$100-200)
|}

=== Dedicated Training Server Strategy (Recommended) ===
The 200-core / 1TB RAM machine is Comfac's primary production server (ERPNext, AI models, file services, build pipelines). Running training labs on it consumes resources that could be used for revenue-generating workloads.

'''Recommendation: Do NOT run training on the 200-core server.''' Instead, deploy training on a dedicated, smaller machine.

{| class="wikitable"
! Option !! Hardware !! Cost (Used) !! Capacity (Stack A) !! Power !! Notes
|-
| '''A. Mini-PC Cluster''' || 3× Intel N100/N305 mini-PCs (4c/8t, 16GB RAM, 512GB SSD each) || ~$450 total || 12 students || ~45W total || Silent, no rack needed. One PC fails = 4 students affected.
|-
| '''B. Single Used Server''' || Dell R630 / HP DL360 Gen9 (2× E5-2680v4, 64GB RAM, 1TB NVMe) || ~$400-600 || 15-20 students || ~150W || Rackmount, redundant PSU, IPMI.
|-
| '''C. Desktop Repurpose''' || Old Comfac desktop (i5-8400, 32GB RAM, 500GB SSD) + Intel i350-T4 NIC || $0 + $50 NIC || 6-8 students || ~65W || Free if you have spare desktops.
|-
| '''D. ARM SBC Cluster''' || 4× Raspberry Pi 5 (4GB) + 1× Pi 5 (8GB as controller) || ~$300 total || 4-6 students || ~25W total || Cannot run x86 pfSense; must use Linux routers (Stack C only).
|}

'''Best choice for Comfac: Option B (Single Used Server) or Option C (Repurpose Desktop).'''
* Option B gives headroom for growth to 20 students
* Option C is free if you have retiring desktops from the Win2Lin migration
* Both keep the 200-core server 100% free for production

=== Cost-Benefit: 200-Core Server vs Dedicated Training Box ===
{| class="wikitable"
! Factor !! Training on 200-Core Server !! Dedicated Training Server
|-
| '''Hardware Cost''' || $0 (already owned) || $0-$600
|-
| '''Power Cost''' || Already running || +$10-30/month
|-
| '''Opportunity Cost''' || '''High''' — 20% of server unavailable for ERPNext/AI/builds || '''Zero''' — production server untouched
|-
| '''Risk''' || Training crashes could affect production VMs || Isolated; training issues contained
|-
| '''Noise/Location''' || Must stay in server room || Mini-PC or desktop can sit in training room
|-
| '''Maintenance Window''' || Must coordinate with production || Anytime; reboot freely
|}

'''Verdict:''' A $400 used server or a $0 repurposed desktop pays for itself in 1-2 months by keeping the 200-core machine fully available for production workloads.

=== Cluster-in-a-Box: Old PC + Proxmox VE ===
For the absolute lowest cost (repurposed old PC):
# Install Proxmox VE (Debian-based hypervisor with web GUI)
# Create LXC templates for Alpine/Debian clients
# Create KVM VMs for pfSense microVMs
# Install NoVNC via Proxmox built-in console or add Kimchi/Guacamole
# Students access via browser to the Proxmox web UI

'''Specs needed for 8 students (Stack A):'''
* CPU: 6-core / 12-thread (Intel 6th-gen i5 or better; AMD Ryzen 5)
* RAM: 32 GB DDR4
* Storage: 500 GB NVMe or SSD
* NIC: Intel i350-T4 quad-port (for VLANs and bridges)
* Cost: $0 (old PC) + $50 (NIC) if you already have the PC

This is the path of least resistance for Comfac given the Win2Lin migration will free up desktops.

=== Exercise-Limited Deployment (Right-Sizing per Lab) ===
Not every lab needs the full sandbox. Deploy only what is needed:

{| class="wikitable"
! Lab !! Stack A Deployed !! vCPUs Used !! RAM Used !! Disk Used
|-
| Day 1 — Theory only || None (wiki only) || 0 || 0 || 0
|-
| Lab 1 (Intro/Backup) || 1 pfSense + 1 client || 1.5 || 768 MB || 5 GB
|-
| Lab 2 (Rules) || 1 pfSense + 1 client + 1 server || 2 || 1 GB || 6 GB
|-
| Lab 3 (NAT) || 1 pfSense + 1 server + router || 2 || 900 MB || 5.5 GB
|-
| Lab 4 (Services) || 2 pfSense + 2 clients + 1 server || 4 || 2.1 GB || 11 GB
|-
| Lab 5-7 (VPNs) || 2 pfSense + 2 clients || 3 || 1.5 GB || 10 GB
|-
| Lab 8 (Multi-WAN) || 1 pfSense + 1 client + router || 2 || 900 MB || 5.5 GB
|-
| Lab 9 (Shaping) || 1 pfSense + 2 clients || 2.5 || 1.3 GB || 6 GB
|-
| Lab 10 (HA) || 2 pfSense + 1 client || 2.5 || 1.3 GB || 9 GB
|}

'''Scheduling strategy:''' If students are scheduled in 1-hour slots and labs are provisioned on-demand, the same 40 vCPUs / 200 GB RAM can serve 40-60 student-slots per day (not concurrently, but sequentially).

=== Phase 1: Resource Setup Validation ===
Before full student rollout, validate the resource model with these tests:

{| class="wikitable"
! Test !! Purpose !! Command / Method !! Pass Criteria
|-
| '''T1: MicroVM Boot''' || Verify pfSense runs in 512MB/1vCPU || qemu-system-x86_64 -m 512 -smp 1 -drive file=pfsense.qcow2 || Boots to login in < 120s
|-
| '''T2: LXC Container Spawn''' || Verify sub-1GB containers work || lxc launch images:alpine/3.19 client || Starts in < 10s; SSH reachable
|-
| '''T3: NoVNC Session''' || Verify one student can access console || websockify + TigerVNC || 640x480 responsive; < 500ms latency
|-
| '''T4: 5 Concurrent Students''' || Validate 20% CPU/RAM budget || Ansible: deploy 5x Stack A || Total < 8 vCPU, < 7 GB RAM
|-
| '''T5: Lab 4 Full Deploy''' || Heaviest lab (2 pfSense + 2 clients + server) || ansible-playbook lab4.yml || Deploys in < 5 min; all VMs pingable
|-
| '''T6: Snapshot Reset Speed''' || Time to reset between students || virsh snapshot-revert + virsh start || < 60 seconds total
|-
| '''T7: AI Evaluation Readiness''' || Validate environment for automated testing || See AI Evaluation section below || All labs pass synthetic health checks
|}

=== AI Evaluation: Automated Readiness Testing ===
Before students arrive, AI agents will validate that each lab environment is functional. This replaces manual smoke-testing.

'''Evaluation Stack:'''
* '''Qwen 3.5 Instruct Coder (9GB)''' — Runs locally on the 200-core server or a dedicated GPU box. Evaluates: pfSense GUI accessibility, rule syntax, VPN handshake status, config.xml validity.
* '''DeepSeek Coder (optional)''' — Cloud or local. Validates Ansible playbook correctness, network topology logic, resource allocation math.
* '''OpenCode (local agent)''' — Executes shell commands inside VMs/containers via SSH/API. Performs end-to-end tests: ping, curl, ipsec status, wg show, etc.

'''Automated Test Sequence (per lab):'''
# Deploy lab environment via Ansible
# AI agent logs into pfSense (admin credentials)
# Screenshot/check each configured page matches expected state
# Run connectivity tests from client VMs
# Verify services are listening on correct ports
# Generate pass/fail report with specific error details
# Destroy lab environment

'''Benefits:'''
* Catch broken base images before students arrive
* Validate that config.xml injections work correctly
* Ensure network isolation between students
* Measure actual resource usage vs. estimates
* Generate readiness dashboard for instructors

'''Implementation:'''
* Python + Selenium/Playwright for pfSense GUI testing
* Paramiko/fabric for SSH-based VM tests
* pytest framework for test organization
* GitHub Actions or local Cron for scheduled runs
* Output: Markdown report posted to wiki or sent via Matrix/Email

== Related Infrastructure ==
* [[System Hardening Strategy: Win2Lin Migration & Infrastructure 251129]] — Server migration and infrastructure hardening
* [[Introduction: Why Self-Host Your Email?]] — Self-hosted email infrastructure context
* [[Mailcow + Thunderbird Setup Guide (Email + Calendar)]] — Email server deployment
* [[Portainer to Docker Compose Migration Guide]] — Container orchestration for network services

----
''This index consolidates networking resources previously scattered across the [[Main Page]]. Last updated: 260423.''

PfSense Training Project Tracker

2026-04-23T10:14:45Z

Justinaquino: Update Phase 1: Resource analysis completed (R.1-R.6), add AI evaluation pipeline tasks, update status dashboard

__NOTOC__
<div style="background:#fff8e1; border:1px solid #ffcc80; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
'''Project Tracker''' for Comfac's pfSense Practical Training System implementation. This page tracks all tasks from material conversion to infrastructure deployment and course delivery.
</div>

== Phase 0: Material Conversion (FUND001 → Wiki) ==
Convert all Netgate FUND001 training PDFs into CITWiki pages with detailed summaries. Each wiki page should include: learning objectives, key concepts, step-by-step lab instructions adapted for virtual environment, and troubleshooting tips.

=== Slide Decks ===
* [x] '''SEG1 — Introduction to pfSense''' → [[Training: pfSense Introduction]]
* [x] '''SEG2 — Interfaces, VIPs, and Rules''' → [[Training: Interfaces and Firewall Rules]]
* [x] '''SEG3 — NAT and VIPs''' → [[Training: NAT and Virtual IPs]]
* [x] '''SEG4 — pfSense Services''' → [[Training: pfSense Services]]
* [x] '''SEG5 — VPNs and IPsec''' → [[Training: IPsec VPN]]
* [x] '''SEG6 — OpenVPN''' → [[Training: OpenVPN]]
* [x] '''SEG7 — WireGuard''' → [[Training: WireGuard]]
* [x] '''SEG8 — Multi-WAN''' → [[Training: Multi-WAN]]
* [x] '''SEG9 — Traffic Shaping''' → [[Training: Traffic Shaping]]
* [x] '''SEG10 — High Availability''' → [[Training: High Availability]]
* [x] '''SEG11 — Other Features''' → [[Training: Monitoring and Packages]]

=== Labs ===
* [x] '''Lab 1 — Intro, Getting Started, Backup/Restore''' → [[Training Lab 1: Introduction and Backup Restore]]
* [x] '''Lab 2 — Interfaces, Firewall Rules, Aliases''' → [[Training Lab 2: Firewall Rules and Aliases]]
* [x] '''Lab 3 — Virtual IPs and NAT''' → [[Training Lab 3: NAT and Virtual IPs]]
* [x] '''Lab 4 — Services and Branch Network Setup''' → [[Training Lab 4: Services and Branch Network]]
* [x] '''Lab 5 — IPsec''' → [[Training Lab 5: IPsec VPN]]
* [x] '''Lab 6 — OpenVPN''' → [[Training Lab 6: OpenVPN]]
* [x] '''Lab 7 — WireGuard''' → [[Training Lab 7: WireGuard]]
* [x] '''Lab 8 — Multi-WAN''' → [[Training Lab 8: Multi-WAN]]
* [x] '''Lab 9 — Traffic Shaping''' → [[Training Lab 9: Traffic Shaping]]
* [x] '''Lab 10 — High Availability''' → [[Training Lab 10: High Availability]]

=== Comfac Original Content ===
* [x] '''Introduction Training (Module 0)''' → [[Training: Setting Up a Firewall for Yourself]] — Personal/small business firewall
* [ ] '''the-pfsense-documentation.pdf''' → Summarize into [[Training: pfSense Complete Reference]] or link as external reference
* [ ] '''WindowsTrainingSupportFiles.zip''' → Extract and document client software requirements ([[Training: Client Software Requirements]])
* [ ] '''Training Videos (4× .mkv)''' → Catalog timestamps and link from relevant wiki pages

== Phase 1: Infrastructure Setup ==
Build the virtual training environment on Comfac's 200-core / 1TB RAM machine.

=== Resource Analysis (Completed) ===
* [x] '''R.1''' Compare Pure Linux (FOSS) vs Windows stacks -> [[Networking PfSense Index#Resource Estimates Per Student]]
* [x] '''R.2''' Calculate 20% server utilization targets -> 13 students (Linux), 6 students (Windows)
* [x] '''R.3''' Analyze container-based alternatives -> LXC for Linux routers; KVM still required for pfSense
* [x] '''R.4''' Define exercise-limited deployment model -> Right-size per lab; 0-4 vCPUs per student
* [x] '''R.5''' Specify smaller server options for 10 students -> Dell R630 (Linux) / R740 (Windows)
* [x] '''R.6''' Design AI evaluation pipeline -> Qwen 3.5 Coder 9GB + DeepSeek + OpenCode for automated readiness

=== Host Preparation ===
* [ ] '''A.1''' Install Ubuntu Server LTS on 200-core host
* [ ] '''A.2''' Configure KVM/libvirt with storage pools (NVMe for images, SSD for ephemeral clones)
* [ ] '''A.3''' Set up network bridges: br-mgmt, br-lan, br-wan, br-dmz, br-internet
* [ ] '''A.4''' Configure VLANs for student isolation (one VLAN per student or per lab)
* [ ] '''A.5''' Install and configure Ansible controller (host or container)

=== Base Images ===
* [ ] '''B.1''' Download pfSense CE ISO and create qcow2 golden image (1 vCPU, 512 MB RAM, 4 GB disk - microVM)
* [ ] '''B.2''' Create Alpine Linux LXC golden image (0.5 vCPU, 256 MB RAM, 1 GB disk)
* [ ] '''B.3''' Create Debian XFCE LXC golden image for NoVNC client (0.5 vCPU, 256 MB RAM, 2 GB disk)
* [ ] '''B.4''' Create Ubuntu Server LXC golden image (0.5 vCPU, 256 MB RAM, 1 GB disk)
* [ ] '''B.5''' Create "Internet Router" LXC golden image (0.5 vCPU, 128 MB RAM, 0.5 GB disk)
* [ ] '''B.6''' Test each golden image boots and functions correctly

=== Automation ===
* [ ] '''C.1''' Write Ansible playbook: lab1-student-env.yml (1 pfSense microVM + 1 LXC client)
* [ ] '''C.2''' Write Ansible playbook: lab2-student-env.yml (1 pfSense + 1 client + 1 server LXC)
* [ ] '''C.3''' Write Ansible playbook: lab3-student-env.yml (1 pfSense + 1 server + internet router LXC)
* [ ] '''C.4''' Write Ansible playbook: lab4-student-env.yml (2 pfSense + 2 clients + 1 server)
* [ ] '''C.5''' Write Ansible playbooks for Labs 5-10 (VPNs, Multi-WAN, Shaping, HA)
* [ ] '''C.6''' Write Ansible playbook: cleanup-student-env.yml (destroy VMs/LXCs, free resources)
* [ ] '''C.7''' Write Ansible playbook: reset-student-env.yml (revert to snapshot/linked clone base)
* [ ] '''C.8''' Test all playbooks end-to-end with a single student ID

=== NoVNC Portal ===
* [ ] '''D.1''' Evaluate Kimchi vs Apache Guacamole vs custom NoVNC proxy
* [ ] '''D.2''' Install and configure chosen NoVNC solution
* [ ] '''D.3''' Integrate NoVNC with student authentication (LDAP, local wiki accounts, or simple token-based)
* [ ] '''D.4''' Build student dashboard: list of phases/labs, "Launch Lab" button, countdown timer
* [ ] '''D.5''' Test 5 concurrent NoVNC sessions for stability
* [ ] '''D.6''' Test 20 concurrent NoVNC sessions for performance

=== AI Evaluation Pipeline ===
* [ ] '''E.1''' Deploy Qwen 3.5 Instruct Coder 9GB on GPU box or 200-core host
* [ ] '''E.2''' Build pytest + Selenium test suite for pfSense GUI validation
* [ ] '''E.3''' Build SSH-based health check suite for VM/LXC connectivity
* [ ] '''E.4''' Integrate DeepSeek or OpenCode for playbook syntax validation
* [ ] '''E.5''' Create readiness dashboard (pass/fail per lab, resource usage graphs)
* [ ] '''E.6''' Schedule automated nightly tests of all lab environments

== Phase 2: Curriculum Development ==
Design the student-facing training program.

=== Introduction Course (Most Common Use Case) ===
* [x] '''E.1''' Define "Setting Up a Firewall for Yourself" scope: home office / small business
* [x] '''E.2''' Write Module 0: Why You Need a Firewall (threats, NAT basics, basic topology)
* [x] '''E.3''' Write Module 1: Install pfSense on Old PC or VM (hardware requirements, USB install, first boot wizard)
* [x] '''E.4''' Write Module 2: Basic WAN + LAN Setup (DHCP, DNS, first internet connection)
* [x] '''E.5''' Write Module 3: Essential Firewall Rules (block incoming, allow outgoing, ICMP)
* [x] '''E.6''' Write Module 4: Port Forwarding for Common Services (game server, camera, NAS)
* [x] '''E.7''' Write Module 5: VPN for Remote Access (WireGuard road warrior setup)
* [x] '''E.8''' Write Module 6: Backup and Updates (config.xml backup, update schedule)
* [x] '''E.9''' Create hands-on lab for Introduction Course (single pfSense + 1 client VM)
* [ ] '''E.10''' Record or source video walkthroughs for each module

=== Full FUND001 Adaptation ===
* [x] '''F.1''' Map each SEG slide deck to a wiki training page with summary + key takeaways
* [x] '''F.2''' Adapt Netgate labs from physical/virtualbox environment to KVM/Ansible environment
* [ ] '''F.3''' Update IP addressing schema for Comfac virtual lab (avoid conflicts with production)
* [ ] '''F.4''' Write pre-lab briefing pages (what you'll learn, expected outcomes)
* [ ] '''F.5''' Write post-lab review pages (common mistakes, verification steps, "show me" checklist)
* [ ] '''F.6''' Create quiz questions for each phase (5–10 questions, auto-graded if possible)

== Phase 3: Pilot & Refinement ==
Run the training with a small group before full rollout.

=== Internal Pilot ===
* [ ] '''G.1''' Recruit 3–5 internal Comfac IT staff as pilot students
* [ ] '''G.2''' Run Phase 1 (Foundations) with pilot group — collect feedback
* [ ] '''G.3''' Run Phase 2 (NAT & Services) with pilot group — collect feedback
* [ ] '''G.4''' Run one VPN lab (IPsec or OpenVPN) with pilot group — test resource limits
* [ ] '''G.5''' Document all bugs, confusion points, and timeouts
* [ ] '''G.6''' Refine playbooks and wiki pages based on pilot feedback

=== Resource Tuning ===
* [ ] '''H.1''' Measure actual CPU/RAM/disk usage per student during pilot
* [ ] '''H.2''' Adjust VM specs if over- or under-provisioned
* [ ] '''H.3''' Test memory overcommit ratios for safe concurrency scaling
* [ ] '''H.4''' Document maximum safe concurrent student count

== Phase 4: Deployment & Operations ==
Prepare for regular training delivery.

=== Student Onboarding ===
* [ ] '''I.1''' Create student onboarding guide (how to access portal, use NoVNC, reset lab)
* [ ] '''I.2''' Create instructor guide (how to monitor progress, assist students, grade labs)
* [ ] '''I.3''' Set up scheduling system (book lab time slots, prevent over-allocation)
* [ ] '''I.4''' Create completion certificates or badges

=== Monitoring & Maintenance ===
* [ ] '''J.1''' Set up host monitoring (Prometheus/Grafana or simple `libvirt` stats)
* [ ] '''J.2''' Configure alerts for host resource exhaustion
* [ ] '''J.3''' Schedule weekly base image updates (pfSense patches, OS updates)
* [ ] '''J.4''' Document disaster recovery (rebuild host from Ansible, restore golden images)

== Quick Status Dashboard ==
{| class="wikitable"
! Phase !! Status !! % Complete !! Blockers
|-
| Phase 0: Material Conversion || 🟢 Done (22/23) || 96% || Pending: reference PDF, support files, videos
|-
| Phase 1: Infrastructure Setup || 🟡 In Progress || 15% || Resource analysis complete; need host access for image builds
|-
| Phase 2: Curriculum Development || 🟡 In Progress || 65% || Need video recordings, quizzes, pre/post lab pages
|-
| Phase 3: Pilot & Refinement || 🔴 Not Started || 0% || Waiting on Phase 1 + 2
|-
| Phase 4: Deployment & Operations || 🔴 Not Started || 0% || Waiting on Phase 3
|}

== Resource Summary ==
'''Per-student minimum:''' 6 vCPUs, 6.5 GB RAM, 62 GB disk
'''Per-student full lab:''' 10 vCPUs, 10.5 GB RAM, 110 GB disk
'''200-core / 1TB capacity:''' 20–40 concurrent students (conservative to optimized)

'''Next Actions (This Week):'''
# Summarize the-pfsense-documentation.pdf into a reference page
# Document WindowsTrainingSupportFiles.zip contents
# Catalog training video timestamps
# Begin Ansible playbook drafting for Lab 1 environment
# Evaluate Kimchi vs Guacamole for NoVNC portal

Networking PfSense Index

2026-04-23T10:10:50Z

Justinaquino: Update Resource Estimates: Add Linux FOSS vs Windows stacks, 20% utilization target, container analysis, AI evaluation, exercise-limited deployment

__NOTOC__
<div style="background:#f0f7ff; border:1px solid #b8d4f0; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
'''Consolidated index''' for all networking infrastructure guides, pfSense documentation, DNS/ad-blocking resources, and network equipment references at Comfac IT.
</div>

== pfSense Core Guides ==
* [[pfSense Sales Training Material]] — Product knowledge and sales positioning for Netgate/pfSense hardware and software
* [[Modern Guide: pfSense Captive Portal with FreeRADIUS & ACME]] — Enterprise Wi-Fi captive portal with RADIUS authentication and Let's Encrypt SSL
* [[pfSense CE → pfSense Plus Upgrade Guide]] — Step-by-step migration from Community Edition to pfSense Plus
* [[SOP: Network Troubleshooting & pfSense Monitoring 251130]] — Standard operating procedures for network diagnostics and pfSense health monitoring

== Network Infrastructure & Equipment ==
* [[Tplink Mikrotik Equivalent]] — Cross-reference of TP-Link and MikroTik models for network deployments
* [[Controller Systems 251213-01]] — Network and infrastructure controller systems
* [[Power Distribution Tree 251213]] — Power architecture for network and server racks
* [[NPM Migration to Homelab VPS Relay 260401]] — Nginx Proxy Manager migration; VPS as iptables/ZeroTier relay with homelab redundancy

== DNS, Ad Blocking & Pi-hole ==
* [https://github.com/Comfac-Global-Group/pi-hole Comfac Pi-hole Repository] — GitHub repository for Pi-hole DNS sinkhole deployment
* [https://github.com/Comfac-Global-Group/pi-hole/blob/master/How%20this%20Works.md How Pi-hole Works] — Technical overview of the Pi-hole DNS filtering architecture

== Training & Skills ==
* [[Skills and Competencies for IT Staff Trained in pfSense]] — Required competencies and certification path for pfSense-administering staff
* [[PfSense Training Project Tracker]] — '''Implementation tracker''' for the NoVNC virtual lab, material conversion, and curriculum development

== Practical Training System (NoVNC Virtual Lab) ==
'''Goal:''' Build a self-hosted, virtualized pfSense training environment where Comfac trainees can learn hands-on without physical hardware. All labs run via NoVNC in a browser, orchestrated on Comfac's 200-core / 1TB RAM machine.

=== Training Architecture Vision ===
Each student gets an isolated virtual network sandbox containing:
* 2× pfSense VMs (HQ HA pair or HQ + Branch)
* 1–2× Client VMs (Windows/Linux desktop)
* 1× Server VM (web/DNS/target)
* 1× Simulated "Internet" router VM

Access is through a NoVNC web portal. Students click a lab, and their environment is provisioned automatically via Ansible/Terraform or Docker/KVM.

=== Resource Estimates Per Student ===

==== Stack A: Pure Linux / FOSS (Recommended for Comfac) ====
All components run on open-source software. Clients are lightweight Linux VMs or LXC containers. No Windows licensing required.

{| class="wikitable"
! Component !! vCPUs !! RAM !! Disk !! Virtualization !! Notes
|-
| pfSense VM || 1 || 512 MB || 4 GB || KVM microVM || FreeBSD requires KVM; use tiny QEMU args
|-
| Linux Client (LXC) || 0.5 || 256 MB || 1 GB || LXC container || Alpine or Debian with XFCE; NoVNC access
|-
| Linux Server (LXC) || 0.5 || 256 MB || 1 GB || LXC container || nginx, BIND, or simple Python HTTP
|-
| Internet Router (LXC) || 0.5 || 128 MB || 0.5 GB || LXC container || Static routes only; FRR optional
|-
| NoVNC Proxy (Docker) || 0.5 || 256 MB || 0.5 GB || Docker container || websockify + nginx
|-
| '''Total per student''' || '''3''' || '''1.4 GB''' || '''7 GB''' || — || Thin-provisioned; linked clones
|}

==== Stack B: Windows Client (Full Desktop Experience) ====
For trainees who need a Windows desktop for browser-based management or specific client software.

{| class="wikitable"
! Component !! vCPUs !! RAM !! Disk !! Virtualization !! Notes
|-
| pfSense VM || 2 || 1 GB || 8 GB || KVM || Standard qcow2 image
|-
| Windows Client || 2 || 4 GB || 40 GB || KVM || Windows 10/11 thin client; needs GPU if GUI-heavy
|-
| Ubuntu Server || 1 || 1 GB || 10 GB || KVM || Full VM for compatibility
|-
| Internet Router || 1 || 512 MB || 4 GB || KVM || Ubuntu with static routes
|-
| NoVNC Proxy || 0.5 || 256 MB || 0.5 GB || Docker || Shared across students
|-
| '''Total per student''' || '''6.5''' || '''6.8 GB''' || '''63 GB''' || — || Higher resource cost
|}

==== Stack C: Hybrid — Containers for Linux Router Exercises ====
For basic routing/firewall concept labs only (not pfSense-specific), replace pfSense with Linux routers in containers.

{| class="wikitable"
! Component !! vCPUs !! RAM !! Disk !! Virtualization !! Notes
|-
| Linux Router (LXC) || 0.5 || 128 MB || 0.5 GB || LXC || Alpine + iptables/nftables + WireGuard
|-
| Linux Client (LXC) || 0.5 || 256 MB || 1 GB || LXC || Alpine or Debian
|-
| Linux Server (LXC) || 0.5 || 256 MB || 1 GB || LXC || nginx, BIND
|-
| Internet Router (LXC) || 0.5 || 128 MB || 0.5 GB || LXC || Static routes
|-
| '''Total per student''' || '''2''' || '''768 MB''' || '''3 GB''' || — || Cannot teach pfSense GUI; teaches concepts only
|}

'''Important:''' pfSense is FreeBSD-based and cannot run in Linux containers (Docker/LXC). Stack C is suitable for teaching routing/VPN concepts using Linux tools (iptables, nftables, WireGuard, strongSwan), but not for teaching the pfSense web interface. For pfSense GUI training, use Stack A or B.

=== Server Capacity: 20% Utilization Target ===
The goal is to run the training environment using only 20% of the 200-core / 1TB RAM server, leaving 80% for other Comfac workloads (ERPNext, AI models, file services).

'''20% of available resources:'''
* 40 vCPUs (20% of 200)
* 200 GB RAM (20% of 1 TB)
* ~2 TB SSD (assuming 10 TB array, 20% = 2 TB)

'''Concurrent student capacity at 20% utilization:'''

{| class="wikitable"
! Stack !! Per-Student Resources !! Students at 20% CPU !! Students at 20% RAM !! Limiting Factor
|-
| '''A: Pure Linux''' || 3 vCPU / 1.4 GB || 13 || 142 || '''CPU: 13 students'''
|-
| '''B: Windows''' || 6.5 vCPU / 6.8 GB || 6 || 29 || '''CPU: 6 students'''
|-
| '''C: Containers''' || 2 vCPU / 0.8 GB || 20 || 250 || '''CPU: 20 students'''
|}

'''Recommendation:''' Use Stack A (Pure Linux) for all labs. This yields ~13 concurrent students within the 20% budget, or up to ~30 students if spread across time slots (not everyone needs a lab simultaneously).

=== Smaller Server: What Hardware for 10 Students? ===
If buying a dedicated training server instead of using the 200-core machine:

{| class="wikitable"
! Stack !! CPU !! RAM !! Storage !! NICs !! Example Hardware
|-
| '''A: Pure Linux''' || 32 cores || 32 GB || 500 GB NVMe || 2x 1GbE || Used Dell R630/R640 (~$300-500)
|-
| '''B: Windows''' || 64 cores || 96 GB || 1 TB NVMe || 2x 1GbE || Used Dell R740 / HP DL360 (~$600-900)
|-
| '''C: Containers''' || 16 cores || 16 GB || 250 GB NVMe || 2x 1GbE || Old desktop + Intel NIC (~$100-200)
|}

=== Exercise-Limited Deployment (Right-Sizing per Lab) ===
Not every lab needs the full sandbox. Deploy only what is needed:

{| class="wikitable"
! Lab !! Stack A Deployed !! vCPUs Used !! RAM Used !! Disk Used
|-
| Day 1 — Theory only || None (wiki only) || 0 || 0 || 0
|-
| Lab 1 (Intro/Backup) || 1 pfSense + 1 client || 1.5 || 768 MB || 5 GB
|-
| Lab 2 (Rules) || 1 pfSense + 1 client + 1 server || 2 || 1 GB || 6 GB
|-
| Lab 3 (NAT) || 1 pfSense + 1 server + router || 2 || 900 MB || 5.5 GB
|-
| Lab 4 (Services) || 2 pfSense + 2 clients + 1 server || 4 || 2.1 GB || 11 GB
|-
| Lab 5-7 (VPNs) || 2 pfSense + 2 clients || 3 || 1.5 GB || 10 GB
|-
| Lab 8 (Multi-WAN) || 1 pfSense + 1 client + router || 2 || 900 MB || 5.5 GB
|-
| Lab 9 (Shaping) || 1 pfSense + 2 clients || 2.5 || 1.3 GB || 6 GB
|-
| Lab 10 (HA) || 2 pfSense + 1 client || 2.5 || 1.3 GB || 9 GB
|}

'''Scheduling strategy:''' If students are scheduled in 1-hour slots and labs are provisioned on-demand, the same 40 vCPUs / 200 GB RAM can serve 40-60 student-slots per day (not concurrently, but sequentially).

=== Phase 1: Resource Setup Validation ===
Before full student rollout, validate the resource model with these tests:

{| class="wikitable"
! Test !! Purpose !! Command / Method !! Pass Criteria
|-
| '''T1: MicroVM Boot''' || Verify pfSense runs in 512MB/1vCPU || qemu-system-x86_64 -m 512 -smp 1 -drive file=pfsense.qcow2 || Boots to login in < 120s
|-
| '''T2: LXC Container Spawn''' || Verify sub-1GB containers work || lxc launch images:alpine/3.19 client || Starts in < 10s; SSH reachable
|-
| '''T3: NoVNC Session''' || Verify one student can access console || websockify + TigerVNC || 640x480 responsive; < 500ms latency
|-
| '''T4: 5 Concurrent Students''' || Validate 20% CPU/RAM budget || Ansible: deploy 5x Stack A || Total < 8 vCPU, < 7 GB RAM
|-
| '''T5: Lab 4 Full Deploy''' || Heaviest lab (2 pfSense + 2 clients + server) || ansible-playbook lab4.yml || Deploys in < 5 min; all VMs pingable
|-
| '''T6: Snapshot Reset Speed''' || Time to reset between students || virsh snapshot-revert + virsh start || < 60 seconds total
|-
| '''T7: AI Evaluation Readiness''' || Validate environment for automated testing || See AI Evaluation section below || All labs pass synthetic health checks
|}

=== AI Evaluation: Automated Readiness Testing ===
Before students arrive, AI agents will validate that each lab environment is functional. This replaces manual smoke-testing.

'''Evaluation Stack:'''
* '''Qwen 3.5 Instruct Coder (9GB)''' — Runs locally on the 200-core server or a dedicated GPU box. Evaluates: pfSense GUI accessibility, rule syntax, VPN handshake status, config.xml validity.
* '''DeepSeek Coder (optional)''' — Cloud or local. Validates Ansible playbook correctness, network topology logic, resource allocation math.
* '''OpenCode (local agent)''' — Executes shell commands inside VMs/containers via SSH/API. Performs end-to-end tests: ping, curl, ipsec status, wg show, etc.

'''Automated Test Sequence (per lab):'''
# Deploy lab environment via Ansible
# AI agent logs into pfSense (admin credentials)
# Screenshot/check each configured page matches expected state
# Run connectivity tests from client VMs
# Verify services are listening on correct ports
# Generate pass/fail report with specific error details
# Destroy lab environment

'''Benefits:'''
* Catch broken base images before students arrive
* Validate that config.xml injections work correctly
* Ensure network isolation between students
* Measure actual resource usage vs. estimates
* Generate readiness dashboard for instructors

'''Implementation:'''
* Python + Selenium/Playwright for pfSense GUI testing
* Paramiko/fabric for SSH-based VM tests
* pytest framework for test organization
* GitHub Actions or local Cron for scheduled runs
* Output: Markdown report posted to wiki or sent via Matrix/Email

== Related Infrastructure ==
* [[System Hardening Strategy: Win2Lin Migration & Infrastructure 251129]] — Server migration and infrastructure hardening
* [[Introduction: Why Self-Host Your Email?]] — Self-hosted email infrastructure context
* [[Mailcow + Thunderbird Setup Guide (Email + Calendar)]] — Email server deployment
* [[Portainer to Docker Compose Migration Guide]] — Container orchestration for network services

----
''This index consolidates networking resources previously scattered across the [[Main Page]]. Last updated: 260423.''

PfSense Training Project Tracker

2026-04-23T07:22:44Z

Justinaquino: Update tracker - Phase 0 material conversion 96% complete

__NOTOC__
<div style="background:#fff8e1; border:1px solid #ffcc80; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
'''Project Tracker''' for Comfac's pfSense Practical Training System implementation. This page tracks all tasks from material conversion to infrastructure deployment and course delivery.
</div>

== Phase 0: Material Conversion (FUND001 → Wiki) ==
Convert all Netgate FUND001 training PDFs into CITWiki pages with detailed summaries. Each wiki page should include: learning objectives, key concepts, step-by-step lab instructions adapted for virtual environment, and troubleshooting tips.

=== Slide Decks ===
* [x] '''SEG1 — Introduction to pfSense''' → [[Training: pfSense Introduction]]
* [x] '''SEG2 — Interfaces, VIPs, and Rules''' → [[Training: Interfaces and Firewall Rules]]
* [x] '''SEG3 — NAT and VIPs''' → [[Training: NAT and Virtual IPs]]
* [x] '''SEG4 — pfSense Services''' → [[Training: pfSense Services]]
* [x] '''SEG5 — VPNs and IPsec''' → [[Training: IPsec VPN]]
* [x] '''SEG6 — OpenVPN''' → [[Training: OpenVPN]]
* [x] '''SEG7 — WireGuard''' → [[Training: WireGuard]]
* [x] '''SEG8 — Multi-WAN''' → [[Training: Multi-WAN]]
* [x] '''SEG9 — Traffic Shaping''' → [[Training: Traffic Shaping]]
* [x] '''SEG10 — High Availability''' → [[Training: High Availability]]
* [x] '''SEG11 — Other Features''' → [[Training: Monitoring and Packages]]

=== Labs ===
* [x] '''Lab 1 — Intro, Getting Started, Backup/Restore''' → [[Training Lab 1: Introduction and Backup Restore]]
* [x] '''Lab 2 — Interfaces, Firewall Rules, Aliases''' → [[Training Lab 2: Firewall Rules and Aliases]]
* [x] '''Lab 3 — Virtual IPs and NAT''' → [[Training Lab 3: NAT and Virtual IPs]]
* [x] '''Lab 4 — Services and Branch Network Setup''' → [[Training Lab 4: Services and Branch Network]]
* [x] '''Lab 5 — IPsec''' → [[Training Lab 5: IPsec VPN]]
* [x] '''Lab 6 — OpenVPN''' → [[Training Lab 6: OpenVPN]]
* [x] '''Lab 7 — WireGuard''' → [[Training Lab 7: WireGuard]]
* [x] '''Lab 8 — Multi-WAN''' → [[Training Lab 8: Multi-WAN]]
* [x] '''Lab 9 — Traffic Shaping''' → [[Training Lab 9: Traffic Shaping]]
* [x] '''Lab 10 — High Availability''' → [[Training Lab 10: High Availability]]

=== Comfac Original Content ===
* [x] '''Introduction Training (Module 0)''' → [[Training: Setting Up a Firewall for Yourself]] — Personal/small business firewall
* [ ] '''the-pfsense-documentation.pdf''' → Summarize into [[Training: pfSense Complete Reference]] or link as external reference
* [ ] '''WindowsTrainingSupportFiles.zip''' → Extract and document client software requirements ([[Training: Client Software Requirements]])
* [ ] '''Training Videos (4× .mkv)''' → Catalog timestamps and link from relevant wiki pages

== Phase 1: Infrastructure Setup ==
Build the virtual training environment on Comfac's 200-core / 1TB RAM machine.

=== Host Preparation ===
* [ ] '''A.1''' Install Ubuntu Server LTS on 200-core host
* [ ] '''A.2''' Configure KVM/libvirt with storage pools (NVMe for images, SSD for ephemeral clones)
* [ ] '''A.3''' Set up network bridges: `br-mgmt`, `br-lan`, `br-wan`, `br-dmz`, `br-internet`
* [ ] '''A.4''' Configure VLANs for student isolation (one VLAN per student or per lab)
* [ ] '''A.5''' Install and configure Ansible controller (host or container)

=== Base Images ===
* [ ] '''B.1''' Download pfSense CE ISO and create qcow2 golden image (2 vCPU, 1 GB RAM, 8 GB disk)
* [ ] '''B.2''' Create Ubuntu Server 22.04/24.04 golden image (1 vCPU, 1 GB RAM, 10 GB disk)
* [ ] '''B.3''' Create Windows 10/11 thin client golden image (2 vCPU, 4 GB RAM, 40 GB disk) — OR decide to use Linux clients only
* [ ] '''B.4''' Create "Internet Router" golden image (Ubuntu with FRR/Quagga or simple static routes, 1 vCPU, 512 MB RAM)
* [ ] '''B.5''' Test each golden image boots and functions correctly

=== Automation ===
* [ ] '''C.1''' Write Ansible playbook: `lab1-student-env.yml` (1 pfSense + 1 client)
* [ ] '''C.2''' Write Ansible playbook: `lab2-student-env.yml` (1 pfSense + 1 client + 1 server)
* [ ] '''C.3''' Write Ansible playbook: `lab3-student-env.yml` (1 pfSense + 1 server + internet)
* [ ] '''C.4''' Write Ansible playbook: `lab4-student-env.yml` (2 pfSense + 2 clients + 1 server)
* [ ] '''C.5''' Write Ansible playbooks for Labs 5–10 (VPNs, Multi-WAN, Shaping, HA)
* [ ] '''C.6''' Write Ansible playbook: `cleanup-student-env.yml` (destroy VMs, free resources)
* [ ] '''C.7''' Write Ansible playbook: `reset-student-env.yml` (revert to snapshot/linked clone base)
* [ ] '''C.8''' Test all playbooks end-to-end with a single student ID

=== NoVNC Portal ===
* [ ] '''D.1''' Evaluate Kimchi vs Apache Guacamole vs custom NoVNC proxy
* [ ] '''D.2''' Install and configure chosen NoVNC solution
* [ ] '''D.3''' Integrate NoVNC with student authentication (LDAP, local wiki accounts, or simple token-based)
* [ ] '''D.4''' Build student dashboard: list of phases/labs, "Launch Lab" button, countdown timer
* [ ] '''D.5''' Test 5 concurrent NoVNC sessions for stability
* [ ] '''D.6''' Test 20 concurrent NoVNC sessions for performance

== Phase 2: Curriculum Development ==
Design the student-facing training program.

=== Introduction Course (Most Common Use Case) ===
* [x] '''E.1''' Define "Setting Up a Firewall for Yourself" scope: home office / small business
* [x] '''E.2''' Write Module 0: Why You Need a Firewall (threats, NAT basics, basic topology)
* [x] '''E.3''' Write Module 1: Install pfSense on Old PC or VM (hardware requirements, USB install, first boot wizard)
* [x] '''E.4''' Write Module 2: Basic WAN + LAN Setup (DHCP, DNS, first internet connection)
* [x] '''E.5''' Write Module 3: Essential Firewall Rules (block incoming, allow outgoing, ICMP)
* [x] '''E.6''' Write Module 4: Port Forwarding for Common Services (game server, camera, NAS)
* [x] '''E.7''' Write Module 5: VPN for Remote Access (WireGuard road warrior setup)
* [x] '''E.8''' Write Module 6: Backup and Updates (config.xml backup, update schedule)
* [x] '''E.9''' Create hands-on lab for Introduction Course (single pfSense + 1 client VM)
* [ ] '''E.10''' Record or source video walkthroughs for each module

=== Full FUND001 Adaptation ===
* [x] '''F.1''' Map each SEG slide deck to a wiki training page with summary + key takeaways
* [x] '''F.2''' Adapt Netgate labs from physical/virtualbox environment to KVM/Ansible environment
* [ ] '''F.3''' Update IP addressing schema for Comfac virtual lab (avoid conflicts with production)
* [ ] '''F.4''' Write pre-lab briefing pages (what you'll learn, expected outcomes)
* [ ] '''F.5''' Write post-lab review pages (common mistakes, verification steps, "show me" checklist)
* [ ] '''F.6''' Create quiz questions for each phase (5–10 questions, auto-graded if possible)

== Phase 3: Pilot & Refinement ==
Run the training with a small group before full rollout.

=== Internal Pilot ===
* [ ] '''G.1''' Recruit 3–5 internal Comfac IT staff as pilot students
* [ ] '''G.2''' Run Phase 1 (Foundations) with pilot group — collect feedback
* [ ] '''G.3''' Run Phase 2 (NAT & Services) with pilot group — collect feedback
* [ ] '''G.4''' Run one VPN lab (IPsec or OpenVPN) with pilot group — test resource limits
* [ ] '''G.5''' Document all bugs, confusion points, and timeouts
* [ ] '''G.6''' Refine playbooks and wiki pages based on pilot feedback

=== Resource Tuning ===
* [ ] '''H.1''' Measure actual CPU/RAM/disk usage per student during pilot
* [ ] '''H.2''' Adjust VM specs if over- or under-provisioned
* [ ] '''H.3''' Test memory overcommit ratios for safe concurrency scaling
* [ ] '''H.4''' Document maximum safe concurrent student count

== Phase 4: Deployment & Operations ==
Prepare for regular training delivery.

=== Student Onboarding ===
* [ ] '''I.1''' Create student onboarding guide (how to access portal, use NoVNC, reset lab)
* [ ] '''I.2''' Create instructor guide (how to monitor progress, assist students, grade labs)
* [ ] '''I.3''' Set up scheduling system (book lab time slots, prevent over-allocation)
* [ ] '''I.4''' Create completion certificates or badges

=== Monitoring & Maintenance ===
* [ ] '''J.1''' Set up host monitoring (Prometheus/Grafana or simple `libvirt` stats)
* [ ] '''J.2''' Configure alerts for host resource exhaustion
* [ ] '''J.3''' Schedule weekly base image updates (pfSense patches, OS updates)
* [ ] '''J.4''' Document disaster recovery (rebuild host from Ansible, restore golden images)

== Quick Status Dashboard ==
{| class="wikitable"
! Phase !! Status !! % Complete !! Blockers
|-
| Phase 0: Material Conversion || 🟢 Done (22/23) || 96% || Pending: reference PDF, support files, videos
|-
| Phase 1: Infrastructure Setup || 🔴 Not Started || 0% || Need 200-core host access
|-
| Phase 2: Curriculum Development || 🟡 In Progress || 65% || Need video recordings, quizzes, pre/post lab pages
|-
| Phase 3: Pilot & Refinement || 🔴 Not Started || 0% || Waiting on Phase 1 + 2
|-
| Phase 4: Deployment & Operations || 🔴 Not Started || 0% || Waiting on Phase 3
|}

== Resource Summary ==
'''Per-student minimum:''' 6 vCPUs, 6.5 GB RAM, 62 GB disk
'''Per-student full lab:''' 10 vCPUs, 10.5 GB RAM, 110 GB disk
'''200-core / 1TB capacity:''' 20–40 concurrent students (conservative to optimized)

'''Next Actions (This Week):'''
# Summarize the-pfsense-documentation.pdf into a reference page
# Document WindowsTrainingSupportFiles.zip contents
# Catalog training video timestamps
# Begin Ansible playbook drafting for Lab 1 environment
# Evaluate Kimchi vs Guacamole for NoVNC portal

Training: Setting Up a Firewall for Yourself

2026-04-23T07:21:00Z

Justinaquino: Create Introduction Training Module 0 - personal/small business firewall setup

__NOTOC__
<div style="background:#fff3e0; border:1px solid #ffb74d; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
'''Comfac Entry-Level Training: Module 0''' — Setting Up a Firewall for Yourself. The most common, practical starting point before advancing to the full FUND001 curriculum.
</div>

== Target Audience ==
* Home users who want to secure their network
* Small business owners (1–10 employees)
* IT staff new to networking before they tackle enterprise deployments
* Anyone who has never configured a router or firewall before

== Learning Objectives ==
By the end of this module, you will be able to:
* Explain why a firewall is necessary for homes and small offices
* Install pfSense on an old PC or VM with minimum hardware
* Configure basic WAN and LAN interfaces
* Set up essential firewall rules (allow outgoing, block incoming)
* Configure port forwarding for common services
* Set up a basic WireGuard VPN for remote access
* Back up and update the firewall configuration
* Diagnose common connectivity problems

== Module 0: Why You Need a Firewall ==
=== The Threats at Home and Small Office ===
Most people rely on the "router" provided by their ISP. These devices are:
* '''Minimally configured''' — often with default passwords and outdated firmware
* '''Poorly maintained''' — ISPs rarely push security updates promptly
* '''Limited in features''' — no VPN, no traffic logging, no intrusion detection

'''Common risks:'''
* Unauthorized remote access to cameras, NAS, printers
* Malware spreading between family/employee devices
* Cryptojacking, ransomware, botnet participation
* Data exfiltration from poorly secured IoT devices

'''What a firewall gives you:'''
* '''Stateful inspection''' — only allows return traffic for connections you initiated
* '''Network segmentation''' — isolate guests, IoT, and work devices
* '''VPN access''' — securely access your home/office network from anywhere
* '''Logging & visibility''' — see what devices are doing on your network
* '''Ad and malware blocking''' — integrate with DNS blocklists (Pi-hole)

== Module 1: Hardware and Installation ==
=== Minimum Hardware ===
{| class="wikitable"
! Component !! Minimum !! Recommended
|-
| CPU || 64-bit, 1 GHz || 64-bit, 2+ cores, AES-NI support
|-
| RAM || 1 GB || 4 GB
|-
| Storage || 8 GB SSD/USB || 32 GB SSD
|-
| NICs || 2 Ethernet ports || Intel i210/i350 dual/quad port NIC
|}

'''Good sources of cheap hardware:'''
* Old office desktops (Dell OptiPlex, HP EliteDesk)
* Thin clients with PCIe slot for NIC
* Used 1U servers (noisy but cheap)
* Protectli/Qotom mini-PCs (purpose-built, fanless)

'''Installation methods:'''
# Download pfSense CE ISO from https://www.pfsense.org/downloads
# Write to USB with Rufus (Windows) or dd (Linux)
# Boot from USB, install to SSD/HDD
# Remove USB, reboot
# Default LAN: 192.168.1.1

== Module 2: First Boot and Basic Setup ==
=== The Setup Wizard ===
# Connect laptop to LAN port
# Browse to https://192.168.1.1
# Log in: admin / pfsense
# Complete the wizard:
#* '''General Info''' — Set hostname (e.g., homefw), domain (local)
#* '''Time Server''' — Use default or local NTP
#* '''WAN''' — Select DHCP (most home/DSL) or PPPoE (some fiber)
#* '''LAN''' — Leave 192.168.1.1/24 or change to obscure subnet (e.g., 10.47.83.1/24)
#* '''Password''' — Change from default immediately

'''Why change from 192.168.1.1?''' If you later connect via VPN from a coffee shop that also uses 192.168.1.x, your traffic may not route correctly. Using an obscure subnet avoids this.

=== Essential Post-Setup ===
# '''System -> General Setup''' — Set timezone, language
# '''System -> Advanced -> Networking''' — Disable NAT reflection if not needed
# '''System -> Update''' — Check for updates immediately
# '''Diagnostics -> Backup & Restore''' — Download first config backup

== Module 3: Essential Firewall Rules ==
=== Default Rules (pfSense handles these automatically) ===
* '''LAN''' — Allow all (default)
* '''WAN''' — Block all (implicit, not shown)

=== Best Practice: Restrict LAN Outbound ===
For a more secure home/small office, replace "LAN allow all" with specific allowed protocols:

{| class="wikitable"
! Protocol !! Port !! Purpose
|-
| TCP/UDP || 53 || DNS
|-
| TCP/UDP || 123 || NTP
|-
| TCP/UDP || 443 || HTTPS
|-
| TCP || 80 || HTTP (optional)
|-
| TCP/UDP || 5222 || XMPP/chat (optional)
|}

'''How to do it:'''
# Firewall -> Rules -> LAN
# Delete the default "Allow All" rule
# Add rules for each protocol/port above
# Add a final "Block" rule at the bottom (with logging enabled)

'''Note:''' This breaks some apps/games. For a family home, "Allow All" outbound is usually fine. For a business, restrict outbound.

== Module 4: Port Forwarding ===
=== Common Scenarios ===
{| class="wikitable"
! Service !! External Port !! Internal IP !! Internal Port !! Notes
|-
| Minecraft server || 25565 || 192.168.1.50 || 25565 || Gaming
|-
| Camera/DVR || 8080 || 192.168.1.60 || 80 || Change default port
|-
| NAS/Web || 443 || 192.168.1.70 || 443 || Use reverse proxy if multiple services
|-
| Plex || 32400 || 192.168.1.80 || 32400 || Remote streaming
|}

'''Steps:'''
# Firewall -> NAT -> Port Forward
# Click Add
# Interface: WAN
# Protocol: TCP (or TCP/UDP)
# Destination: WAN Address
# Destination Port Range: external port
# Redirect Target IP: internal server IP
# Redirect Target Port: internal port
# Save → Apply

'''Security tip:''' Don't forward RDP (3389) or SSH (22) directly. Use a VPN instead.

== Module 5: WireGuard VPN (Road Warrior) ==
=== Why VPN beats port forwarding ===
* One secure tunnel instead of many open ports
* Access your entire network as if you were there
* Works on phones, laptops, tablets
* No need to expose individual services

=== Setup Steps ===
# Install '''WireGuard package''' — System -> Package Manager -> Available Packages
# VPN -> WireGuard -> Settings → Enable
# Tunnels → Add Tunnel
#* Name: RoadWarrior
#* Listen Port: 51820
#* Interface Keys: Generate key pair
# Save
# Assign interface — Interfaces -> Assignments → add wg0 as OPTx
# Enable interface, set static IP: 10.200.200.1/24
# Peers → Add Peer
#* Tunnel: RoadWarrior
#* Public Key: [client's public key]
#* Allowed IPs: 10.200.200.2/32
#* Endpoint: [blank for roaming clients]
# Firewall -> Rules -> WireGuard interface → Allow All
# Firewall -> Rules -> LAN → Allow from WireGuard net
# Firewall -> NAT -> Outbound → Manual → Add rule for WireGuard net → WAN

'''Client config (phone/laptop):'''
* Install WireGuard app
* Create tunnel, scan QR code or paste config
* Peer: [server public key], Endpoint: your-public-ip:51820
* Allowed IPs: 0.0.0.0/0 (full tunnel) or 192.168.1.0/24 (split tunnel)

'''Opening the port:'''
# Firewall -> Rules -> WAN
# Add rule: Protocol UDP, Port 51820, Source Any, Destination WAN Address

== Module 6: Backup and Maintenance ==
=== Monthly Checklist ===
* [ ] System -> Update: Check for updates
* [ ] Diagnostics -> Backup & Restore: Download config backup
* [ ] Check Dashboard for interface errors, high CPU, or memory usage
* [ ] Review Firewall logs for blocked suspicious traffic
* [ ] Verify VPN clients can still connect

=== Yearly Checklist ===
* [ ] Rotate WireGuard keys
* [ ] Review all port forwards — remove unused ones
* [ ] Check certificate expiry (if using ACME/Let's Encrypt)
* [ ] Audit user accounts and passwords
* [ ] Test restore from backup on a spare VM

== Troubleshooting Common Problems ==
{| class="wikitable"
! Problem !! Likely Cause !! Fix
|-
| No Internet after install || WAN not getting IP || Check cable; set WAN to DHCP or PPPoE
|-
| Can't access web GUI || Wrong IP; HTTPS blocked || Try http://192.168.1.1; check laptop IP
|-
| Port forward not working || ISP CGNAT || Check WAN IP vs public IP; use VPN instead
|-
| VPN connects but no LAN access || Missing firewall/NAT rule || Add allow rule on WireGuard iface; add outbound NAT
|-
| Slow Internet || Hardware too weak || Check CPU usage; upgrade NIC or whole box
|-
| Can't reach some websites || DNS issue || Use 1.1.1.1 or 8.8.8.8 in DNS Resolver forwarders
|}

== Build Your Own Firewall — Capstone Exercise ==
'''Scenario:''' You have an old Dell OptiPlex, a 2-port Intel NIC, and a home fiber connection.

'''Requirements:'''
# Install pfSense CE
# Configure WAN (DHCP) and LAN (static 10.47.83.1/24)
# Set admin password
# Enable DNS Resolver with forwarding to Cloudflare (1.1.1.1)
# Create firewall rules: allow DNS, HTTPS, NTP outbound only
# Set up WireGuard for 2 devices (phone + laptop)
# Forward port 32400 to a Plex server at 10.47.83.50
# Enable AutoConfigBackup (or manual monthly backups)
# Document everything in a simple runbook

'''Success criteria:'''
* Family can browse web normally
* You can VPN in from outside and access LAN resources
* Plex is accessible remotely
* Configuration is backed up

== Next Steps ==
Once comfortable with this module, advance to the full '''FUND001 curriculum''':
# [[Training: pfSense Introduction]] — Phase 1, Day 1
# [[Training Lab 1: Introduction and Backup Restore]] — Hands-on lab

Or explore specialized topics:
* [[Training: pfSense Services]] — DHCP, DNS, Dynamic DNS deep dive
* [[Training: Multi-WAN]] — Add a backup ISP connection
* [[Networking PfSense Index]] — All Comfac networking resources

----
''This module was created for Comfac IT practical training. Built on real-world frequency of problems encountered from personal to small-business networks.''

Training: Monitoring and Packages

2026-04-23T07:16:09Z

Justinaquino:

__NOTOC__
<div style="background:#1e3a5f; color:#fff; padding:12px; border-radius:6px; margin-bottom:16px;">
<span style="font-size:1.2em; font-weight:bold;">📘 Netgate pfSense Training — Module 11</span><br/>
System Monitoring, Logging, and the Package System
</div>

== Learning Objectives ==

By the end of this module, you should be able to:

{| class="wikitable" style="width:100%;"
|-
! Objective
! Description
|-
| Monitor system health
| Use built-in Status pages, Traffic Graphs, and RRD Graphs to observe system performance.
|-
| Configure logging
| Access system logs and export them to an external log aggregation server.
|-
| Understand SNMP
| Enable and use SNMP for remote monitoring and integration with NMS tools.
|-
| Manage packages
| Install, update, and remove packages to extend pfSense functionality.
|-
| Evaluate package maturity
| Interpret version numbers (e.g., 0.x = young package) and assess stability.
|}

== System Monitoring ==

=== Status Pages ===

pfSense provides many built-in '''Status''' pages that give real-time and historical insight into system behavior:

* '''Dashboard''' — customizable overview with widgets for system info, interfaces, services, and gateways.
* '''Traffic Graph''' — live view of traffic per interface.
* '''RRD Graphs''' — historical data for CPU, memory, interface traffic, packets, states, and quality.
* '''System Logs''' — consolidated logging for the firewall, DHCP, DNS, VPN, and other services.

=== RRD Graphs ===

'''RRDtool''' is integrated into pfSense to store and graph time-series data. Available graphs include:

{| class="wikitable" style="width:100%;"
|-
! Category
! Metrics
|-
| System
| CPU usage, memory usage, swap usage, load average
|-
| Traffic
| Inbound/outbound bytes and packets per interface
|-
| Packets
| Passed, blocked, and error packet counts
|-
| Quality
| Gateway latency and packet loss over time
|-
| States
| Current firewall state table size
|}

=== SNMP Monitoring ===

pfSense includes an '''SNMP service''' (via '''bsnmpd''') that allows remote monitoring with tools such as:

* Zabbix
* Nagios / Icinga
* Cacti
* PRTG
* LibreNMS

Enable SNMP under '''Services → SNMP''' and configure community strings, traps, and binding interfaces as needed.

=== Logging ===

System logs are available under the '''Status → System Logs''' menu. Key capabilities:

* View logs by category (Firewall, DHCP, DNS Resolver, VPN, etc.)
* Adjust log verbosity and retention
* '''Export logs''' to an external log aggregation server (e.g., Syslog, Graylog, ELK stack, Splunk) for centralized analysis

== Package System ==

=== Overview ===

The '''Package System''' extends pfSense beyond the base installation. Packages are installed from the official Netgate repository via '''System → Package Manager'''.

=== Common and Popular Packages ===

{| class="wikitable" style="width:100%;"
|-
! Package
! Purpose
! Category
|-
| '''pfBlockerNG'''
| IP and DNS-based blocking for geo-location, threat feeds, and ad blocking
| Security / Filtering
|-
| '''Suricata'''
| High-performance Network IDS/IPS with rule-based threat detection
| Security
|-
| '''Snort'''
| Network intrusion detection and prevention system
| Security
|-
| '''HAProxy'''
| TCP/HTTP load balancer and reverse proxy
| Traffic Management
|-
| '''Squid / SquidGuard'''
| Web proxy with content filtering and access control
| Proxy / Filtering
|-
| '''pfSense-pkg-FRR'''
| Routing protocols (BGP, OSPF, RIP)
| Routing
|-
| '''ntopng'''
| Network traffic probe and flow analysis
| Monitoring
|-
| '''NRPE / Zabbix Agent'''
| Client agents for remote monitoring integration
| Monitoring
|-
| '''ACME'''
| Automatic SSL/TLS certificate issuance via Let's Encrypt
| Certificates
|-
| '''Telegraf'''
| Metrics collection agent for InfluxDB/Prometheus
| Monitoring
|}

=== Package Installation Best Practices ===

* '''Pay attention to version numbers!''' A version of '''0.n''' typically indicates a young or experimental package.
* Install packages only from the official repository or trusted sources.
* Use '''Backup / Restore''' to preserve package states for reinstallation after upgrades.
* Review package documentation before installing in production.

=== Backup and Restore for Packages ===

pfSense's built-in backup system includes an option to reinstall packages automatically after a restore. Ensure this option is enabled under '''Diagnostics → Backup & Restore''' when creating configuration backups.

== Summary ==

* pfSense provides robust '''system monitoring''' through Status pages, Traffic Graphs, '''RRD Graphs''', and '''SNMP'''.
* '''System logs''' can be viewed locally or exported to external aggregation servers for centralized analysis.
* The '''Package System''' dramatically extends pfSense capabilities with popular additions such as '''pfBlockerNG''', '''Suricata''', '''HAProxy''', and '''Squid'''.
* Always evaluate '''package maturity''' (version numbers) and maintain '''backups''' before making significant changes.

== Next Module ==

* Previous: [[Training: Firewall Rules and NAT]]
* Next: [[Training: VPN Configuration]]
* Return to [[Training: pfSense Course Index]]

== Source Attribution ==

* '''Source:''' Netgate pfSense Training Material
* '''Document:''' FUND001-LIVE-SLIDE-SEG11-OTHER.pdf
* '''Section:''' 11 — Other Features (Monitoring, Logging, Packages)
* '''Copyright:''' © 2017 Rubicon Communications dba Netgate
* '''Conversion Date:''' {{CURRENTYEAR}}-{{CURRENTMONTH}}-{{CURRENTDAY}}

[[Category:pfSense Training]]
[[Category:Network Security]]

Training: Monitoring and Packages

2026-04-23T07:14:48Z

Justinaquino: Created page with "__NOTOC__ <div style="background:#1e3a5f; color:#fff; padding:12px; border-radius:6px; margin-bottom:16px;"> <span style="font-size:1.2em; font-weight:bold;">📘 Netgate pfSense Training — Module 11</span><br/> System Monitoring, Logging, and the Package System </div> == Learning Objectives == By the end of this module, you should be able to: {| class="wikitable" style="width:100%;" |- ! Objective ! Description |- | Monitor system health | Use built-in Status pages..."

Training Lab 9: Traffic Shaping

2026-04-23T07:10:26Z

Justinaquino: Imported from FUND001-LIVE-Lab9-TrafficShaping.pdf

__NOTOC__

<div style="background:#005500; color:white; padding:12px; border-radius:6px; margin-bottom:16px;">
'''Netgate pfSense Plus Fundamentals — Lab 9: Traffic Shaping'''<br/>
<small>Training lab manual: FUND001-LIVE-Lab9-TrafficShaping.pdf</small>
</div>

== Overview ==

This lab covers limiters and traffic shaping at an introductory level.

We will configure limiters to restrict HQ LAN hosts to '''2 Mb down / 512 Kb up'''. The mask option of limiters is used to configure this limit on a '''per-IP basis''' — so each IP in the LAN gets its own 2 Mb down, 512 Kb up pipe.

== Understanding Limiter Direction ==

Limiters are applied to firewall rules by specifying them under '''In''' and '''Out''' in the advanced options. The direction of traffic is from the perspective of that interface of the firewall.

* '''Traffic coming into the LAN NIC''' = upload traffic
* '''Traffic leaving the LAN NIC''' = download traffic

The mask of limiters can be configured on a '''source address''' or '''destination address''' basis:

{| class="wikitable"
! Limiter !! Mask Setting !! Reason
|-
| Download (2M-down) || Destination addresses || Traffic leaving the LAN interface has internal clients' IPs as the destination.
|-
| Upload (512K-up) || Source addresses || Traffic entering the LAN interface is sourced from internal clients' IPs.
|}

== Configuring Limiters ==

On '''fw1-HQ''', browse to '''Firewall → Traffic Shaper → Limiters''' tab. Click '''New Limiter''' to add a new limiter.

=== Download Limiter ===

{| class="wikitable"
! Setting !! Value
|-
| Name || 2M-down
|-
| Enable || (checked)
|-
| Bandwidth || 2 Mbit/s
|-
| Mask || Destination addresses
|-
| Description || 2 Mb down per-IP
|}

Leave the remainder at defaults and click '''Save'''.

=== Upload Limiter ===

{| class="wikitable"
! Setting !! Value
|-
| Name || 512K-up
|-
| Enable || (checked)
|-
| Bandwidth || 512 Kbps
|-
| Mask || Source addresses
|-
| Description || 512 Kb up per-IP
|}

Leave the remainder at defaults, click '''Save''', then '''Apply Changes'''.

== Applying Limiters to Firewall Rules ==

Just configuring the limiters doesn't make them active. They must be assigned to a firewall rule to be applied.

# Browse to '''Firewall → Rules → LAN'''.
# Edit the '''"Default allow LAN to any"''' rule.
# Scroll down under '''Advanced''', and click the '''Advanced''' button to the right of '''In/Out'''.
# For the '''In''' limiter, choose '''512K-up'''.
# For the '''Out''' limiter, choose '''2M-down'''.
# Click '''Save''' and '''Apply Changes'''.

Back at the LAN firewall rules screen, you'll see the '''(a)''' icon to the left of the default LAN rule, meaning one or more advanced options are specified on that rule. Hover your mouse cursor over that button to see what is configured.

== Testing Limiters ==

# Pull up '''Status → Traffic Graph → WAN''' on fw1-HQ.
# Run a speed test (e.g., speedtest.net).
# You should see speeds of approximately '''2 Mb down, 512 Kb up'''.

== Traffic Shaper Basic Configuration (Wizard) ==

In this section we configure a basic traffic shaping setup prioritizing VoIP over all else at the branch location (fw1-branch).

=== Wizard Setup ===

# Browse to '''Firewall → Traffic Shaper → Wizards'''.
# Choose '''traffic_shaper_wizard_multi_all.xml'''.
# At the first screen, specify '''1''' for the number of WAN and LAN connections and click '''Next'''.
# Choose '''PRIQ''' for both download and upload schedulers.
# Specify connection bandwidth as '''100 Mbit/s''' upload and download.
# Click '''Next'''.
# Check '''"Prioritize Voice over IP traffic"'''. Fill in '''128 Kbit/s''' for upload and download bandwidth (not actually used with PRIQ).
# Click '''Next''' three times past penalty box, peer-to-peer networking, and network games.
# At the '''"Raise or lower other applications"''' screen, enable it and choose '''VNC''' as higher priority.
# Click '''Finish'''.

== Reviewing Firewall Rule Shaping Configuration ==

Browse to '''Firewall → Rules → Floating''' to see the traffic shaper rules added by the wizard. These are match rules which specify the appropriate queue for each type of traffic.

* The VoIP traffic classification ends up as a rule matching all UDP traffic from any source to any destination, with queue '''qVoIP'''.
* All traffic not matching a floating rule specifying a queue will go into the '''default queue'''.

== Reviewing Shaper Queue Configuration ==

Browse to '''Firewall → Traffic Shaper'''. The '''By Interface''' and '''By Queue''' tabs both show configured queues (two different layouts of the same data).

* '''By Queue''' is typically used for manual configuration.
* '''By Interface''' is the standard review view.
* You can click '''"Remove Shaper"''' on the '''By Interface''' tab to remove and disable traffic shaping.

== Testing and Checking Status ==

# Reset all states: '''Diagnostics → States → Reset States''' tab → click '''Reset'''.
# Browse to '''Status → Queues''' and monitor while generating traffic.
# Run a speed test — the speed test traffic will fall into the '''default queue'''.

== Generating SIP Traffic ==

Use '''SIPp''' on the test systems:

On '''remote-host''' (100.64.0.50):
<pre>
training@remote-host:~$ sipp -sn uas
</pre>

On '''branch-client''' (172.18.1.100):
<pre>
training@branch-client:~$ sipp -sn uac 100.64.0.50
</pre>

These commands initiate 10 SIP calls per second indefinitely. View '''Status → Queues''' while running to see traffic in the VoIP queue.

== Long-term Monitoring ==

When traffic shaping is enabled, RRD graphs include queue statistics and queue drops.

# Browse to '''Status → Monitoring''' and click the wrench icon.
# For '''Left Axis''', choose '''Queues'''.
# The '''Queue Drops''' graph shows packets dropped from each queue.

Ideally, you want to see '''0 drops''' across all high-priority queues, with drops limited to lower or default priority traffic.

----

<div style="background:#f0f8ff; padding:10px; border-left:4px solid #005500;">
'''Previous Module:''' [[Training:_Traffic_Shaping|Section 9 — Traffic Shaping (Slides)]]
</div>

== Source Attribution ==

* '''Document:''' FUND001-LIVE-Lab9-TrafficShaping.pdf
* '''Course:''' pfSense Plus Fundamentals and Practical Applications
* '''Copyright:''' © 2021 Rubicon Communications, LLC (Netgate)
* '''Extracted and formatted for internal training wiki.'''

Training: Traffic Shaping

2026-04-23T07:10:06Z

Justinaquino: Imported from FUND001-LIVE-SLIDE-SEG9-SHAPE.pdf

__NOTOC__

<div style="background:#003366; color:white; padding:12px; border-radius:6px; margin-bottom:16px;">
'''Netgate pfSense Plus Fundamentals — Section 9: Traffic Shaping'''<br/>
<small>Training slide deck: FUND001-LIVE-SLIDE-SEG9-SHAPE.pdf</small>
</div>

== Traffic Shaping — Overview ==

Traffic shaping is a form of '''managed unfairness of bandwidth'''. It helps avoid the default FIFO queueing behavior imposed by ISPs.

* '''Queues''' define traffic priorities.
* '''Rules''' assign traffic to queues.
* There are two separate methods for shaping:
** '''Limiters''' (dummynet pipes)
** '''Traffic Shaper''' (ALTQ)

== Limiters ==

Limiters provide a quick, easy means of imposing '''hard bandwidth limits'''.

* Can be applied on a '''group or per-IP basis'''.
* Optionally '''schedule-based'''.
* Advanced options include:
** Queue size
** Delay
** Packet Loss

== Traffic Shaping Rules ==

* Rules are evaluated from the '''point of view of traffic leaving an interface'''.
* Typically use '''floating rules''' to apply shaping.
* '''In/Out''' options under advanced rule options are used to assign queues.
* Matches only assign queues — they do not control access.

== Traffic Shaping Wizards ==

The wizards offer an easy way to implement queueing and attempt to automate common scenarios.

{| class="wikitable"
! Wizard Type !! Description
|-
| Multiple LAN/WAN || Most common scenario
|-
| Dedicated Links || For dedicated link configurations
|}

== Traffic Shaping Schedulers ==

Schedulers are methods of handling queueing. The following schedulers are available:

{| class="wikitable"
! Scheduler !! Notes
|-
| HFSC || Hierarchical Fair Service Curve
|-
| CBQ || Class-Based Queueing
|-
| FAIRQ || Legacy scheduler
|-
| CODELQ || Legacy scheduler
|-
| PRIQ || '''Easiest solution — recommended wherever possible'''
|}

== Section 9 Summary ==

* Try to keep configurations as simple as possible.
* Use '''PRIQ''' wherever possible.
* Limiter rules can be on a schedule.
* Limiters can be per-IP or per-network (masking).
* Ensure appropriate rule matches.
* Clear states if needed after making changes.
* Check the Traffic-Shaping section of the book for more details.

----

<div style="background:#f0f8ff; padding:10px; border-left:4px solid #003366;">
'''Next Module:''' [[Training_Lab_9:_Traffic_Shaping|Lab 9 — Traffic Shaping (Hands-on)]]
</div>

== Source Attribution ==

* '''Document:''' FUND001-LIVE-SLIDE-SEG9-SHAPE.pdf
* '''Course:''' pfSense Plus Fundamentals and Practical Applications
* '''Copyright:''' © 2017 Rubicon Communications, LLC dba Netgate
* '''Extracted and formatted for internal training wiki.'''

Training Lab 7: WireGuard

2026-04-23T07:09:24Z

Justinaquino: Created page with "__NOTOC__ <div style="background:#e7f3ff;border:1px solid #a3c6ff;padding:10px;margin-bottom:15px;"> '''Training Lab 7: WireGuard Site-to-Site VPN''' — pfSense Plus Fundamentals and Practical Application </div> == Overview == This lab goes through an example configuration of WireGuard for site-to-site VPNs. WireGuard has no concept of sessions or connections. The protocol uses public and private keys to authenticate and route traffic. WireGuard instances consist of..."

__NOTOC__

<div style="background:#e7f3ff;border:1px solid #a3c6ff;padding:10px;margin-bottom:15px;">
'''Training Lab 7: WireGuard Site-to-Site VPN''' — pfSense Plus Fundamentals and Practical Application
</div>

== Overview ==

This lab goes through an example configuration of WireGuard for site-to-site VPNs.

WireGuard has no concept of sessions or connections. The protocol uses public and private keys to authenticate and route traffic. WireGuard instances consist of a tunnel and one or more peer definitions which contain the necessary keys and other configuration data that allows the two sides to communicate.

== Step 1: Delete OpenVPN ==

First, since we have an OpenVPN configured here already, we need to delete it so it doesn’t interfere with our WireGuard setup. On both fw1-HQ and fw1-branch, browse to '''VPN → OpenVPN''' and delete all client and server instances.

== Step 2: Configure WireGuard Settings ==

Browse to '''VPN → WireGuard → Settings''' on both firewalls and:

* Click the '''Enable''' checkbox
* For Interface Group Membership, choose '''Only Unassigned Tunnels'''
* Uncheck '''Hide Secrets''' and '''Hide Peers'''
* Scroll down and click '''Save'''

== Step 3: Add a New Tunnel on Both Firewalls ==

On FW1-HQ and Branch-FW, navigate to '''VPN → WireGuard → Tunnels''' and click the green '''+Add Tunnel''' button.

{| class="wikitable"
|-
! Setting !! Value
|-
| Enabled || checked
|-
| Description || Site-to-Site VPN
|-
| Listen Port || 51820
|-
| Interface Keys || Press the blue Generate button
|}

Make a note of the public key on '''BOTH''' firewalls, as this will be required later. Then click '''Save'''.

== Step 4: Configure a Peer on FW1-HQ ==

Edit the tunnel on FW1-HQ and click '''+Add Peer'''.

{| class="wikitable"
|-
! Setting !! Value
|-
| Enable || checked
|-
| Description || Branch Office Peer
|-
| Dynamic Endpoint || unchecked
|-
| Endpoint || 203.0.113.10
|-
| Endpoint Port || 51820
|-
| Public Key || (paste public key from Branch-FW)
|-
| Pre-shared Key || (blank)
|-
| Allowed IPs || 10.6.210.0/30 (Tunnel Network), 172.18.1.0/24 (Branch LAN)
|}

Scroll down and click '''Save Peer'''.

== Step 5: Configure a Peer on Branch-FW ==

Edit the tunnel on Branch-FW and click '''+Add Peer'''.

{| class="wikitable"
|-
! Setting !! Value
|-
| Enable || checked
|-
| Description || HQ Peer
|-
| Dynamic Endpoint || unchecked
|-
| Endpoint || 192.0.2.2
|-
| Endpoint Port || 51820
|-
| Public Key || (paste public key from FW1-HQ)
|-
| Pre-shared Key || (blank)
|-
| Allowed IPs || 10.6.210.0/30 (Tunnel Network), 172.17.1.0/24 (HQ LAN)
|}

Scroll down and click '''Save Peer'''.

== Step 6: Assign Interfaces ==

=== Select Default Gateways ===

On both firewalls, navigate to '''System → Routing''' and set Default Gateway IPv4 to a specific gateway, such as WANGW. Click '''Save''' and '''Apply'''.

=== Assign WireGuard Interface on FW1-HQ ===

Navigate to '''Interfaces → Assignments''', choose the tun_gw0 interface, and click '''+Add''' (creates OPT4). Configure OPT4:

{| class="wikitable"
|-
! Setting !! Value
|-
| Enable || checked
|-
| Description || BRANCH_VPN
|-
| IPv4 Configuration Type || Static IPv4
|-
| IPv4 Address || 10.6.210.1/30
|-
| Gateway Name || VPN_BRANCHGW
|-
| Gateway IPv4 || 10.6.210.2
|}

=== Assign WireGuard Interface on Branch-FW ===

Navigate to '''Interfaces → Assignments''', choose the tun_gw0 interface, and click '''+Add''' (creates OPT1). Configure OPT1:

{| class="wikitable"
|-
! Setting !! Value
|-
| Enable || checked
|-
| Description || HQ_VPN
|-
| IPv4 Configuration Type || Static IPv4
|-
| IPv4 Address || 10.6.210.2/30
|-
| Gateway Name || VPN_HQGW
|-
| Gateway IPv4 || 10.6.210.1
|}

== Step 7: Create Firewall Rules on WAN ==

On both firewalls, navigate to '''Firewall → Rules → WAN''' and add a rule to the top:

{| class="wikitable"
|-
! Setting !! Value
|-
| Action || Pass
|-
| Protocol || UDP
|-
| Source || Any
|-
| Destination || WAN Address
|-
| Destination Port || 51820
|-
| Description || Pass traffic to WireGuard
|}

Click '''Save''' and '''Apply Changes'''.

== Step 8: Add Routing Between Sites ==

=== HQ-FW1 Static Route ===

Navigate to '''System → Routing → Static Routes''' and click '''+Add''':
* Destination Network: 172.18.1.0/24
* Gateway: VPN_BRANCHGW

=== Branch-FW Static Route ===

Navigate to '''System → Routing → Static Routes''' and click '''+Add''':
* Destination Network: 172.17.1.0/24
* Gateway: VPN_HQGW

== Step 9: Allow Tunnel Traffic ==

=== HQ-FW1 Tunnel Rule ===

On HQ-FW1, navigate to '''Firewall → Rules → BRANCH_VPN''' and add:

{| class="wikitable"
|-
! Setting !! Value
|-
| Action || Pass
|-
| Interface || BRANCH_VPN
|-
| Protocol || Any
|-
| Source || Any
|-
| Destination || Any
|-
| Description || Allow WireGuard VPN Traffic
|}

=== Branch-FW Tunnel Rule ===

On Branch-FW, navigate to '''Firewall → Rules → HQ_VPN''' and add the same rule (Interface: HQ_VPN).

== Step 10: Testing ==

WireGuard doesn’t have much status information. In most cases it either works if you configured it properly, or it does not. One place to look is for the existence of a recent “handshake.”

=== Check Status ===

On each firewall, navigate to '''VPN → WireGuard → Status'''. One of the only indicators that the VPN is up is the presence of the peer’s handshake.

=== Try to Ping Across ===

From the HQ-Client, try to ping the Branch-FW LAN interface at '''172.18.1.1'''. If the tunnel is up, your pings should be successful.

If the pings failed, you have a configuration issue and need to check your configuration.

== Troubleshooting ==

Due to its stateless nature, WireGuard doesn’t have status screens, and there is very little logging to be consulted. If your tunnel fails:

* Check the peer settings on both sides, paying particular attention to the public keys of the far-end peers
* Check for an active WireGuard state by navigating to '''Diagnostics → States''' and searching for a state that matches port 51820

The existence of this state can indicate that the VPN is connected. This state may age out, so you may need to try your ping again to bring it back up.

Once you are satisfied that WireGuard is working, you may delete it in order to simplify the next labs.

== Next Module ==
* [[Training: WireGuard|← Back to Training: WireGuard]]

----
<small>'''Source:''' Netgate pfSense Training — FUND001-LIVE-Lab7-WireGuard.pdf (© 2015-2021 Electric Sheep Fencing LLC)</small>

Training: WireGuard

2026-04-23T07:09:24Z

Justinaquino: Created page with "__NOTOC__ <div style="background:#e7f3ff;border:1px solid #a3c6ff;padding:10px;margin-bottom:15px;"> '''Training Module: WireGuard (Section 7)''' — pfSense Plus Fundamentals and Practical Application </div> == Introduction == WireGuard is a very new VPN technology that is entirely stateless. * Tends to be very performant * Lives in the kernel space * Uses “Crypto-Key Routing” * Ensures routing traffic to correct destination * Very little status info — it work..."

__NOTOC__

<div style="background:#e7f3ff;border:1px solid #a3c6ff;padding:10px;margin-bottom:15px;">
'''Training Module: WireGuard (Section 7)''' — pfSense Plus Fundamentals and Practical Application
</div>

== Introduction ==

WireGuard is a very new VPN technology that is entirely stateless.

* Tends to be very performant
* Lives in the kernel space
* Uses “Crypto-Key Routing”
* Ensures routing traffic to correct destination
* Very little status info — it works or it doesn’t
* Easy roaming between networks
* Endpoint IP always updated
* Configuration may be more time-consuming

== Simplified Codebase ==

WireGuard has a dramatically smaller codebase compared to traditional VPN solutions:

{| class="wikitable"
|-
! Protocol !! Lines of Code
|-
| IPsec || ~ 400,000
|-
| OpenVPN || ~ 600,000
|-
| '''WireGuard''' || '''~ 4,000'''
|}

Less Code = Greater Efficiency

== Rigid Crypto Protocols ==

WireGuard uses modern, rigidly defined cryptographic protocols:

* '''ChaCha20''' for symmetric encryption, authenticated with '''Poly1305'''
* '''Curve25519''' for ECDH
* '''BLAKE2s''' for hashing and keyed hashing
* '''SipHash24''' for hashtable keys
* '''HKDF''' for key derivation

== Site-to-Site ==

WireGuard creates a local wg0 interface. Peers have their own public & private keys.

* Exchange public key with peers
* Crypto-key routing — looks up peer wg0 address and public key
* Forwards traffic out local wg0 interface to peer

== Local Setup ==

Some assembly required:

# Activate the service
# Give wg0 a local IP/mask
# Generate Public/Private keys
# Assign wg0 to an OPT interface
# Create a gateway
# Open WG port on firewall
# Create firewall rules to allow traffic

== Peer Setup ==

Required information for peer configuration:

* Peer’s initial end-point IP
* Peer’s public key
* Peer’s wg0 IP (typically same as allowed IPs)

Assuming peer’s firewall is setup, try ping!

== Summary ==

* WireGuard is completely stateless
* Updated crypto protocols
* Uses crypto-key routing — routing table not a factor
* Requires its own OPT interface and gateway
* Very limited status information
* '''It works, or it doesn’t'''

== Next Module ==
* [[Training Lab 7: WireGuard|Lab 7: WireGuard — Site-to-Site VPN Configuration]]

----
<small>'''Source:''' Netgate pfSense Training — FUND001-LIVE-SLIDE-SEG7-WG.pdf (© 2017 Rubicon Communications dba Netgate)</small>

Training Lab 6: OpenVPN

2026-04-23T07:08:32Z

Justinaquino: Automated upload of Netgate pfSense training content

__NOTOC__

<div style="background:#e7f3ff; border-left:6px solid #2196F3; padding:10px; margin-bottom:15px;">
'''Training Lab 6: OpenVPN'''<br/>
Hands-on lab covering site-to-site SSL/TLS VPN, remote access VPN, certificate infrastructure, and testing in pfSense.
</div>

== Overview ==

This lab goes through example configurations of OpenVPN for site-to-site and remote access.

== OpenVPN SSL/TLS Site-to-Site VPN ==

We’re going to configure OpenVPN to connect the HQ and branch networks. HQ will run the server, and the branch will be the client.

There is no functional difference in whether HQ or branch runs the server side. Most often people put the server instances on the main location’s end. If one end has a dynamic IP and one static, run the server on the static IP side. If one end is behind NAT, that end should be the client. In this case, the server side will be on the fw1-hq firewall.

=== Delete IPsec ===

First, since we have an IPsec VPN configured here already, IPsec needs to be disabled. On both fw1-HQ and fw1-branch, browse to '''VPN > IPsec'''. Put a check mark by each IPsec tunnel and click '''Delete P1s'''. Click '''Save''', then '''Apply Changes'''.

=== Create the Certificate Infrastructure ===

OpenVPN makes use of a certificate infrastructure in authenticating the session as well as routing traffic to and from member sites. On the server we must create a new Certificate Authority (CA), as well as server and client certificate/key pairs. This will be done on fw1-hq.

==== Create the Certificate Authority (CA) ====

Navigate to '''System > Cert Manager''' and click the green '''+Add''' button to add a new CA.

{| class="wikitable"
! Field !! Value
|-
| Descriptive Name || S2SCA
|-
| Method || Create an Internal Certificate Authority
|-
| Randomize Serial || (checked)
|-
| Key Type || RSA 2048
|-
| Digest Algorithm || sha256
|-
| Lifetime || 3650
|-
| Common Name || S2SCA
|}

(Leave the rest blank and click '''Save'''.)

==== Create the Server Certificate ====

Next, click on the '''Certificates''' tab, and click the green '''+Add/Sign''' button near the bottom.

{| class="wikitable"
! Field !! Value
|-
| Method || Create an internal server certificate
|-
| Descriptive Name || VPNserver
|-
| Certificate Authority || S2SCA
|-
| Key Type || RSA 2048
|-
| Digest Algorithm || sha256
|-
| Lifetime || 398
|-
| Common Name || VPNserver
|-
| Certificate Type || Server Certificate
|}

Scroll down and click '''Save'''.

==== Create the Client Certificate ====

While still on the '''Certificates''' tab, click the green '''+Add/Sign''' button near the bottom to create the client certificate.

{| class="wikitable"
! Field !! Value
|-
| Method || Create an internal certificate
|-
| Descriptive Name || VPNclient
|-
| Certificate Authority || S2SCA
|-
| Key Type || RSA 2048
|-
| Digest Algorithm || sha256
|-
| Lifetime || 3650
|-
| Common Name || VPNclient
|-
| Certificate Type || User Certificate
|}

Scroll down and click '''Save'''.

==== Export Certificates and Keys ====

The next task is to export the certificates and keys which the client requires when connecting to the OpenVPN server.

# Navigate to '''System > Cert Manager > CAs''' and find the S2SCA. Click the export button to save the CA certificate to the downloads folder on HQ-Client.
# Next, click on the '''Certificates''' tab and scroll down until you see the VPNclient certificate entry. Click the export button to save the certificate data and the key data to the Downloads folder on HQ-Client.

=== Configure Server on fw1-HQ ===

Browse to '''VPN > OpenVPN''' on fw1-HQ. On the '''Server''' tab, click '''+Add''' to add a new server instance.

{| class="wikitable"
! Field !! Value
|-
| Server Mode || Peer to Peer (SSL/TLS)
|-
| Description || HQ to Branch VPN
|-
| TLS Configuration || (checked)
|-
| Automatically generate TLS key || (checked)
|-
| Peer Certificate Authority || S2SCA
|-
| Server Certificate || VPNserver
|-
| IPv4 Tunnel Network || 172.17.6.0/24
|-
| IPv4 Local Network(s) || 172.17.1.0/24, 172.17.2.0/24, 172.18.1.0/24
|-
| IPv4 Remote Network(s) || 172.18.1.0/24
|-
| Inactive || 0 (connections can stay up indefinitely)
|}

Click '''Save''' at the bottom, then click the edit icon to edit the server you just created. Highlight and copy the entire contents of the '''TLS Key''' box. Paste it into a file called '''TLS.key'''.

This TLS key will be needed on the client side of the connection.

=== Create Client-Specific Overrides ===

The purpose of the Client-Specific Override (CSO) is to tie a client’s subnet to their certificate. Navigate to '''VPN > OpenVPN''' and click the '''Client Specific Overrides''' tab. Click the green '''+Add''' button.

{| class="wikitable"
! Field !! Value
|-
| Server List || HQ to Branch VPN
|-
| Common Name || VPNclient
|-
| IPv4 Remote Network || 172.18.1.0/24
|}

Leave everything else blank or default, scroll down and click '''Save'''.

=== Permit Traffic to Server ===

Now we need to add a firewall rule to permit the outside portion of the VPN, from the client to the server. On fw1-HQ, browse to '''Firewall > Rules > WAN'''. Click '''Add'''.

{| class="wikitable"
! Field !! Value
|-
| Action || Pass
|-
| Interface || WAN
|-
| Protocol || UDP
|-
| Source || 203.0.113.10
|-
| Source port || any
|-
| Destination || WAN address
|-
| Destination port || 1194
|-
| Description || allow branch OpenVPN site to site
|}

Then click '''Save''' and '''Apply Changes'''.

=== Permit Traffic within VPN ===

Traffic within OpenVPN connections is filtered by the firewall rules on the OpenVPN tab. Browse to '''Firewall > Rules > OpenVPN'''. Click '''Add'''.

{| class="wikitable"
! Field !! Value
|-
| Interface || OpenVPN
|-
| Protocol || Any
|-
| Source || Network, 172.18.0.0/16
|-
| Destination || any
|-
| Description || allow branch network
|}

Click '''Save''' and '''Apply Changes'''.

The server-side configuration is now complete.

=== Configure Client on fw1-branch ===

Before we can create the client side of the VPN, we must first import the CA and Client Certificate and Keys into the fw1-branch firewall.

==== Import the CA Certificate ====

Click on '''System > Cert Manager''' and click the green '''+Add''' button.

{| class="wikitable"
! Field !! Value
|-
| Descriptive Name || S2SCA
|-
| Method || Import an existing Certificate Authority
|-
| Certificate Data || Paste contents of S2SCA.crt
|}

Highlight all the contents of the '''S2SCA.crt''' file, and paste it into the '''Certificate Data''' field on fw1-branch, and click '''Save'''.

==== Import the Client Certificate and Key ====

Click on the '''Certificates''' tab and click the green '''+Add/Sign''' button near the bottom to import your Client Certificate.

{| class="wikitable"
! Field !! Value
|-
| Method || Import an existing certificate
|-
| Descriptive Name || VPNclient
|-
| Certificate Data || Paste contents of VPNclient.crt
|-
| Certificate Key || Paste contents of VPNclient.key
|}

Click '''Save'''.

==== Create the OpenVPN Client ====

Navigate to '''VPN > OpenVPN''' and click on the '''Clients''' tab. Click the green '''+Add''' button.

{| class="wikitable"
! Field !! Value
|-
| Server Mode || Peer to Peer (SSL/TLS)
|-
| Device Mode || tun
|-
| Server host or address || 192.0.2.2
|-
| Description || Branch to HQ VPN
|-
| Automatically generate a TLS key || UNCHECKED
|-
| Peer Certificate Authority || S2SCA
|-
| Client Certificate || VPNclient
|}

(Here, you will edit the OpenVPN server configuration on fw1-hq, and copy the TLS key data from that server configuration into this client’s TLS key box. You may have saved this file on your HQ-Client as '''TLS.key'''.)

Scroll down and click '''Save'''.

==== Permit Traffic within VPN ====

Add a firewall rule to permit traffic within the VPN, same as the other side but changing the source to HQ’s 172.17.0.0/16.

{| class="wikitable"
! Field !! Value
|-
| Action || Pass
|-
| Interface || OpenVPN
|-
| Protocol || Any
|-
| Source || 172.17.0.0/16
|-
| Destination || any
|-
| Description || Allow HQ
|}

'''Save''' and '''Apply Changes'''.

=== Check Status and Test ===

On fw1-branch, browse to '''Status > OpenVPN'''. There you should see the status as up. If not, skip to the troubleshooting section.

'''Testing:'''

From HQ-client, try to ping fw1-branch and branch-client:

<pre>
training@hq-client:~$ ping -c 3 172.18.1.1
PING 172.18.1.1 (172.18.1.1) 56(84) bytes of data.
64 bytes from 172.18.1.1: icmp_seq=1 ttl=63 time=2.40 ms
...
--- 172.18.1.1 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2004ms
rtt min/avg/max/mdev = 2.406/3.841/4.843/1.043 ms

training@hq-client:~$ ping -c 3 172.18.1.100
PING 172.18.1.100 (172.18.1.100) 56(84) bytes of data.
64 bytes from 172.18.1.100: icmp_seq=1 ttl=62 time=4.26 ms
...
--- 172.18.1.100 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2003ms
rtt min/avg/max/mdev = 3.783/4.309/4.877/0.447 ms
</pre>

Then from branch-client, try to ping HQ-client and server1:

<pre>
training@branch-client:~$ ping -c 3 172.17.1.100
PING 172.17.1.100 (172.17.1.100) 56(84) bytes of data.
64 bytes from 172.17.1.100: icmp_seq=1 ttl=62 time=3.73 ms
64 bytes from 172.17.1.100: icmp_seq=2 ttl=62 time=5.21 ms
64 bytes from 172.17.1.100: icmp_seq=3 ttl=62 time=5.14 ms
--- 172.17.1.100 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2003ms
rtt min/avg/max/mdev = 3.730/4.698/5.219/0.685 ms

training@branch-client:~$ ping -c 3 172.17.2.10
PING 172.17.2.10 (172.17.2.10) 56(84) bytes of data.
64 bytes from 172.17.2.10: icmp_seq=1 ttl=62 time=4.02 ms
64 bytes from 172.17.2.10: icmp_seq=2 ttl=62 time=4.01 ms
64 bytes from 172.17.2.10: icmp_seq=3 ttl=62 time=5.19 ms
--- 172.17.2.10 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2004ms
rtt min/avg/max/mdev = 4.011/4.408/5.192/0.554 ms
</pre>

You can also try browsing to server1 from branch-client: <code>http://172.17.2.10</code>

=== Troubleshooting ===

If the client side status doesn’t show as up, check the troubleshooting section of the OpenVPN chapter in the book for guidance. The most likely causes are an incorrect or missing firewall rule on the WAN of the server (port 1194 rule created above). Check fw1-HQ firewall logs for any blocks. If it’s not getting blocked, and connectivity between the sites works in general, something in the OpenVPN server or client configuration is the likely cause. Double check your configuration on both the client and server, and ensure the shared key was pasted over correctly.

== OpenVPN Remote Access VPN ==

In this section we’re going to set up an OpenVPN remote access server for remote mobile clients.

=== Server Setup Wizard ===

On fw1-HQ, browse to '''VPN > OpenVPN''', and click the '''Wizard''' tab.

=== Authentication Backend ===

Choose '''Local User Access''' and click '''Next'''.

=== Create New Certificate Authority ===

Fill in these values as desired. The locale information has no functional impact and generally isn’t visible anywhere unless you go looking for it.

=== Create New Server Certificate ===

Again, fill in these values as desired.

=== OpenVPN Server Configuration ===

Most things can be left at defaults here. The port must be changed, since we’re already using port 1194 for the site-to-site VPN server.

{| class="wikitable"
! Field !! Value
|-
| Local Port || 1195
|-
| Description || Remote Access VPN
|-
| Tunnel Network || 172.17.4.0/24
|-
| Local Network || 172.16.0.0/12
|-
| DNS Server 1 || 172.17.1.1
|}

Leave everything not listed above at defaults and click '''Next'''.

=== Firewall Rule Configuration ===

The last step of the wizard prompts whether you want to add a rule to allow traffic from clients to the OpenVPN server, and allow traffic inside the VPN from clients when connected. Check both boxes and click '''Next'''.

Click '''Finish''' on the last page.

=== Configuration Complete ===

The configuration is now complete. The last screen reminds you to install the OpenVPN Client Export package if you’d like to use it. It’s already pre-installed on this system to save time. Click '''Finish'''.

Browse to '''Firewall > Rules''' to see the rules added by the wizard. On the '''WAN''' tab, you’ll see the rule allowing traffic to reach the OpenVPN server instance. Then click the '''OpenVPN''' tab to see the rule added to permit traffic from the connected clients.

This may be overly-permissive for real world scenarios since it allows all traffic coming in via OpenVPN from any source to any destination. In a real world setup, you may need to restrict this rule.

=== Special Configuration for Older Clients ===

Although this is rarely necessary, some older OpenVPN clients, like the one installed on your remote-host, will require some extra configuration in the OpenVPN server. Click the '''Edit''' button under the Remote Access VPN, and scroll down to the bottom of the screen. Place this into the '''Custom Options''' box and Save:

<pre>
tls-version-min 1.0;
tls-cipher DEFAULT:@SECLEVEL=0
</pre>

=== User Setup ===

Users need a certificate from the RemoteVPNCA to connect. We’ll add a certificate to the '''vpntest''' account created during the IPsec lab. Browse to '''System > User Manager''', and edit the vpntest user. Then click the '''Add''' button next to '''User Certificate''' to create the certificate.

Choose method '''Create an internal certificate.''' Both '''Descriptive name''' and '''Common Name''' should be set to the username. The other fields can be left to defaults.

{| class="wikitable"
! Field !! Value
|-
| User || vpntest
|-
| Certificate Method || Create an internal certificate
|-
| Descriptive Name || vpntest
|-
| Common Name || vpntest
|}

Click '''Save'''. Back at the user edit screen, you’ll see the user’s certificate. Click '''Save''' to save the user changes.

=== Client Configuration ===

The OpenVPN Client Export utility eases the process of client configuration. It’s a package that comes pre-installed on the lab VMs, but will need to be installed under '''System > Packages''' on your other systems.

Browse to '''VPN > OpenVPN''', and click the '''Client Export''' tab.

For our lab purposes, all other settings can be left at their defaults. Scroll down to the bottom to find the vpntest user’s client export options.

For Windows systems, the Windows installer is what you’ll want. Choose x86 for 32 bit versions of Windows and x64 for 64 bit versions. The Viscosity bundle is for Windows or Mac OS X clients running the Viscosity client. The inline configuration options are most commonly used for iOS and Android clients.

The '''Standard Configuration''' Archive option downloads a zip containing the user’s certificate, TLS key for the server, and OpenVPN config file.

Here you will see the remote access server just created in the wizard. Because the RemoteHost’s VPN client is older, we need to scroll down the page and make sure to put a check mark on '''Legacy Client'''.

=== Testing ===

In this lab environment, the only machine that’s available in the circumstance of a typical client out on the Internet is the remote-host VM. First, add it to the '''RemoteAdmin''' alias on fw1-HQ so you can log into fw1-HQ from that host to ease getting the OpenVPN configuration onto the client. Browse to '''Firewall > Aliases''', and edit the RemoteAdmin alias. Add '''100.64.0.50/32''' to that alias, save, then apply changes.

Now connect with VNC to '''100.64.0.50''' (remote-host) to begin the client-side setup. Bring up its web browser and browse to '''https://192.0.2.2'''. Log in and browse to '''VPN > OpenVPN > Client Export''' tab. Export the '''Configuration Archive''' option for the vpntest user.

Make a folder called OpenVPN in your Documents folder, and save the zip file there. Right click the zip file and choose '''Extract Here'''.

Click the Network Manager icon → VPN Connections → Configure VPN.

Click '''Add''' and scroll down to '''Import a Saved Configuration'''.

Navigate to the folder where the OpenVPN configuration archive was extracted. Click on the '''.ovpn''' file and choose '''Open'''.

Fill in the username and password portions of the next screen, and click '''Save'''.

You may get prompted to choose a password for a new keyring. If so, just enter “password” in both blanks and click '''Continue''' and then '''Close'''.

Now connect to the OpenVPN server by clicking on the Network Manager → VPN Connections and choosing your VPN configuration.

Enter your password and click '''Ok'''.

Now you should verify you can reach things on the HQ LAN and DMZ networks. Try HQ-client at '''172.17.1.100''', server1 at '''172.17.2.10''' and server2 at '''172.17.2.20'''.

Once you have verified that the OpenVPN connection is functioning as expected, please disconnect the OpenVPN session on the remote host.

== Conclusion ==

This concludes Lab 6.

== Source Attribution ==

''Source: Netgate pfSense Training Material — FUND001-LIVE-Lab6-OpenVPN.pdf © 2021 Rubicon Communications, LLC (Netgate)''

Training: OpenVPN

2026-04-23T07:08:32Z

Justinaquino: Automated upload of Netgate pfSense training content

__NOTOC__

<div style="background:#e7f3ff; border-left:6px solid #2196F3; padding:10px; margin-bottom:15px;">
'''Training Module: OpenVPN (Section 6)'''<br/>
This page covers the fundamentals of OpenVPN in pfSense — intro, site-to-site, remote access, and the Client Export Utility.
</div>

== Introduction ==

OpenVPN is an SSL/TLS open source VPN solution.

* '''Not''' a browser-based SSL VPN
* Supports site-to-site and remote access
* Uses client and server roles
* Runs over TCP or UDP (UDP is preferable)
* Built on a client/server relationship

== Remote Access ==

The OpenVPN Wizard in pfSense takes all the guess-work out of configuration.

* Install the '''Client Export Utility'''
* Users will need a '''user certificate'''
* Simple status screen
* Log files for troubleshooting

== Site-to-Site ==

=== Server-Side Requirements ===

* Must have a publicly-reachable TCP or UDP port
* Static IP is preferred (dynamic DNS is possible)

=== Client-Side Requirements ===

* Only needs outbound Internet access
* Works behind NAT or firewall with no issue
* Setup is initiated by Client → Server
* Remarkably simple configuration

=== Important Changes ===

* Peer-to-Peer (Shared Key) mode is '''deprecated'''
* Peer-to-Peer (SSL/TLS) is the only supported mode moving forward
* This opens the door to new capabilities like '''DCO''' (Data Channel Offload)

=== Configuration Checklist ===

{| class="wikitable"
! colspan="2" | Server Information Needed
|-
| CA and Certificate Infrastructure || Required for trust
|-
| Server and Client Certificates || Authenticate both ends
|-
| Server Mode || Peer to Peer (SSL/TLS)
|-
| TLS Key || Automatically created
|-
| Tunnel Network || Subnet for the VPN tunnel
|-
| Local Network || Networks on the server side
|-
| Remote Network || Networks on the client side
|-
| Client-Specific Overrides || Tie client subnets to certificates
|-
| Firewall Rules || Don’t forget to allow traffic!
|}

{| class="wikitable"
! colspan="2" | Client Information Needed
|-
| CA and Certificate/Keys from server || Import the server's CA
|-
| Server Mode || Peer to Peer (SSL/TLS)
|-
| TLS Key || Copy from the server side
|-
| Server IP Address || Public address of the server
|-
| Peer CA || Same CA as server
|-
| Client Certificate/Key || Generated for this client
|-
| Firewall Rules || Don’t forget to allow traffic!
|}

== Section Summary ==

* Pay attention to crypto settings — they '''must agree''' on both sides
* Very simple setup
* Very tenacious — comes up and recovers quickly
* Routed VPN instead of policy-based
* Can co-exist with IPsec
* '''Cannot''' route the same networks! (Policy > Routed)
* Still need firewall rules to allow traffic to pass

== Next Module ==

→ Continue to '''[[Training_Lab_6:_OpenVPN|Lab 6: OpenVPN]]'''

== Source Attribution ==

''Source: Netgate pfSense Training Material — FUND001-LIVE-SLIDE-SEG6-OVPN.pdf © 2017 Rubicon Communications dba Netgate''

Training Lab 5: IPsec VPN

2026-04-23T07:07:12Z

Justinaquino: Imported from Netgate pfSense training PDF via bot

__NOTOC__

<div style="background-color: #fff3cd; border-left: 6px solid #ffc107; padding: 10px; margin-bottom: 15px;">
<strong>Netgate pfSense Plus Fundamentals — Lab 5: IPsec VPN</strong><br/>
Hands-on lab covering site-to-site IPsec with pre-shared key and mobile IPsec remote access configuration.
</div>

= Lab 5: IPsec =

In this lab, we connect the '''HQ''' and '''branch''' networks with a site-to-site IPsec VPN, then configure mobile IPsec to offer a remote access option for mobile clients.

'''Lab topology references:'''
* HQ WAN IP: '''192.0.2.2'''
* Branch WAN IP: '''203.0.113.10'''
* HQ network: 172.17.0.0/16
* Branch network: 172.18.0.0/16

= Part 1: IPsec Pre-Shared Key Site-to-Site VPN =

== Enable fw1-HQ IPsec ==

On '''fw1-HQ''', browse to '''VPN > IPsec'''. Click '''+Add P1''' to add a new Phase 1 configuration.

=== HQ Phase 1 Configuration ===

At the resulting Edit Phase 1 screen:
* '''Remote Gateway:''' Branch WAN IP (203.0.113.10)
* '''Interface:''' WAN
* '''Description:''' (your choice)

=== Phase 1 Proposal Configuration ===

Scroll down to the Phase 1 proposal configuration.

'''Generating Pre-Shared Key:'''
* Click the yellow button to generate your pre-shared key automatically
* Make note of it — it will be needed to configure the other end of the VPN

'''Advanced Options:'''
* Leave '''NAT Traversal''' to '''Auto'''
* The underlying strongSwan service will determine if NAT-T is required and automatically enable it if so

Leave the other settings at their defaults, then click '''Save'''.

== Adding HQ Phase 2 ==

Back at the IPsec Tunnels tab, click the '''+''' under the newly-created Phase 1 to expose the Phase 2 configuration, then click '''+Add P2'''.

=== Configuring HQ Phase 2 ===

For local and remote networks, use the /16 network summarizing all available IP subnets for each location:
* '''Local Network:''' Type: Network, '''172.17.0.0/16'''
* '''Remote Network:''' Type: Network, '''172.18.0.0/16'''

=== Phase 2 Proposal Configuration ===

Choose specific parameters for each area rather than having multiple options enabled. This is always best for site-to-site VPNs.

{| class="wikitable"
! Setting !! Recommendation
|-
| Encryption || AES-256 (single option)
|-
| Hash || SHA256 (single option)
|-
| PFS || On (match group)
|}

Having multiple options enabled could lead to a less secure, slower algorithm like 3DES being chosen over a faster, more secure option like AES-256.

=== Automatically Ping Host ===

Enter an IP address within the remote subnet to keep the VPN alive:
* Use '''fw1-branch LAN IP''' (e.g., 172.18.1.1)
* IPsec is "dial-on-demand" — it doesn't try to connect unless traffic is trying to traverse the VPN
* The IP doesn't have to reply; it's the initiation of the request that triggers the VPN to come up

Then click '''Save''', and at the main IPsec Tunnels screen click '''Apply Changes'''.

== Configure HQ IPsec Firewall Rules ==

Traffic coming in via IPsec is filtered by the firewall rules on the '''IPsec tab'''. By default, this contains no rules, so all VPN traffic will be blocked.

Browse to '''Firewall > Rules''', IPsec tab. Click '''Add''' and configure:

{| class="wikitable"
! Field !! Value
|-
| Action || Pass
|-
| Interface || IPsec
|-
| Protocol || any
|-
| Source || 172.18.0.0/16
|-
| Destination || any
|-
| Description || allow branch network in via IPsec
|}

Click '''Save''', and '''Apply Changes'''.

'''Notes:'''
* The outer portion of the VPN requires UDP port 500 and ESP protocol on WAN — these rules are handled automatically
* Traffic is allowed out from HQ to branch by the default LAN rule
* The HQ DMZ subnet will not be able to initiate connections to the remote branch network because of the DMZ rule rejecting private network destinations

== Configure fw1-branch IPsec ==

Browse to '''https://172.18.1.1''' to reach fw1-branch.

=== Add Phase 1 Entry ===

Add a new Phase 1 entry for the HQ VPN:
* '''Remote Gateway:''' fw1-HQ's WAN IP — '''192.0.2.2'''
* Match all other parameters exactly with fw1-HQ

=== Phase 1 Proposal and Advanced ===

All Phase 1 proposal settings must match exactly to fw1-HQ. After matching up everything, click '''Save'''.

=== Branch Phase 2 Configuration ===

Add a new Phase 2 entry under the Phase 1 just added. Everything is identical to HQ's Phase 2, except flip local and remote networks:
* '''Local Network:''' 172.18.0.0/16
* '''Remote Network:''' 172.17.0.0/16

Leave '''Automatically ping host''' blank on this side (the other end will keep the tunnel active).

Then click '''Save''', and '''Apply Changes'''.

=== Add IPsec Firewall Rule ===

Browse to '''Firewall > Rules''', IPsec tab, and add an allow-all rule:

{| class="wikitable"
! Field !! Value
|-
| Action || Pass
|-
| Interface || IPsec
|-
| Protocol || any
|-
| Source || Network, 172.17.0.0/16
|-
| Destination || any
|-
| Description || allow HQ in via VPN
|}

Save and Apply Changes.

== Testing the VPN ==

Browse to '''Status > IPsec''' on the branch firewall. If the status shows "Disconnected", click the '''Connect VPN''' button.

Once something attempts to bring up the VPN, it should change status to '''ESTABLISHED'''.

=== Troubleshooting ===

If the VPN does not come up:
* Closely review all settings in Phase 1 and Phase 2 on both sides
* Check for typos in IP addresses
* Verify the pre-shared key was pasted correctly
* Ensure no inadvertently mismatched settings

=== Passing Traffic Across VPN ===

On '''HQ-client''', test connectivity:
<pre>
training@hq-client:~$ ping -c 3 172.18.1.1
training@hq-client:~$ ping -c 3 172.18.1.100
</pre>

On '''branch-client''', ping back:
<pre>
training@branch-client:~$ ping -c 3 172.17.1.1
training@branch-client:~$ ping -c 3 172.17.1.100
training@branch-client:~$ ping -c 3 172.17.2.10
</pre>

You should also be able to browse to web servers in the HQ DMZ network from branch-client.

= Part 2: IPsec Remote Access VPN =

Next, configure IPsec for mobile clients. This works with any standard IPsec clients, specifically focused towards the Cisco IPsec clients built into Mac OS X and Apple iOS. The Shrew Soft client is used in this lab.

== User and Group Setup ==

IPsec remote-access users require the '''"IPsec xauth Dialin"''' privilege.

=== Add IPsec Mobile Group ===

On '''fw1-HQ''', browse to '''System > User Manager''', Groups tab. Click '''+Add''':
* Give the group a name (e.g., "Mobile_IPsec") and description
* Save
* Edit the group and under '''Assigned Privileges''', click '''Add'''
* Choose only the '''"VPN - IPsec xauth Dialin"''' privilege
* Save again

=== Creating User for VPN ===

Go to the Users tab, click '''+Add''':
* '''Username:''' vpntest
* '''Password:''' password
* '''Group:''' Mobile_IPsec
* Save

== Server Configuration ==

On '''fw1-HQ''', browse to '''VPN > IPsec''', click the '''Mobile clients''' tab:

{| class="wikitable"
! Setting !! Value
|-
| Enable IPsec Mobile Client Support || Checked
|-
| User Authentication || Local Database
|-
| Group Authentication || Checked
|-
| Authentication Groups || Rights for Mobile IPsec (Mobile_IPsec)
|-
| Virtual Address Pool || 172.17.5.0/24
|-
| Network List || Checked — "Provide a list of accessible networks to clients"
|-
| DNS Default Domain || example.com
|-
| DNS Servers || 172.17.1.1
|}

Leave all other fields at defaults and click '''Save'''.

== Phase 1 Creation ==

After saving, you will see a prompt to create a Phase 1 definition for mobile clients. Click '''Create Phase 1'''.

{| class="wikitable"
! Parameter !! Value
|-
| Key Exchange Version || IKEv1
|-
| Description || Mobile clients
|-
| Authentication Method || Mutual PSK + Xauth
|-
| My Identifier || My IP address
|-
| Peer Identifier || User distinguished name, vpn@example.com
|-
| Pre-Shared Key || Generate new (make note)
|-
| Encryption Algorithm || AES 128 bit
|-
| Hash Algorithm || SHA1
|-
| DH Group || 2
|-
| Lifetime || 86400
|-
| NAT Traversal || Force
|}

Leave all else at defaults, and click '''Save'''.

== Configure Phase 2 ==

Back at the IPsec Tunnels screen, expand the mobile Phase 1 and click '''+Add P2''':

{| class="wikitable"
! Parameter !! Value
|-
| Mode || Tunnel IPv4
|-
| Local Network || Type: Network, 0.0.0.0/0
|-
| Encryption || AES 128
|-
| Hash || SHA1
|-
| PFS || off
|-
| Lifetime || 28800
|}

'''Note:''' The Phase 2 "Local Network" determines what networks are sent to the client. '''0.0.0.0/0''' sends all traffic across the VPN. To send only internal traffic, use '''172.17.0.0/16''' or '''172.16.0.0/12'''.

Then click '''Save''', and '''Apply Changes'''. The server-side IPsec configuration is now complete.

== Firewall Rule Configuration ==

Browse to '''Firewall > Rules''', IPsec tab. Add a new rule:

{| class="wikitable"
! Field !! Value
|-
| Action || Pass
|-
| Interface || IPsec
|-
| Protocol || Any
|-
| Source || Network 172.17.5.0/24
|-
| Destination || any
|-
| Description || allow in mobile client IPsec
|}

Then Save and Apply Changes.

== Client Configuration ==

On '''remote-host''', launch '''Shrew Soft VPN Access Manager'''. Click '''Add''' to create a new configuration.

=== General Tab ===
* Fill in the WAN IP of fw1-HQ: '''192.0.2.2'''
* Leave all else at defaults

=== Authentication Tab ===
* '''Authentication Method:''' Mutual PSK + XAuth
* '''Local Identity:''' User Fully Qualified Domain Name — '''vpn@example.com'''

=== Remote Identity Tab ===
* Choose '''Identification type:''' IP address

=== Credentials Tab ===
* Enter or paste the PSK generated during Phase 1 creation

=== Phase 1 Tab ===
* Change '''DH Exchange''' to '''group 2'''
* Leave all else at defaults

=== Phase 2 Tab ===
* Set '''Lifetime''' to '''28800''' seconds
* Leave everything else at defaults

Then click '''Save'''. You can rename the connection (e.g., "HQ VPN").

== Testing ==

Select the connection and click '''Connect'''. Fill in:
* '''Username:''' vpntest
* '''Password:''' password

Then click '''Connect'''. If you see "tunnel enabled" as the last line in the status, it's connected successfully.

Try to ping across to HQ-client (172.17.1.100) and server1 (172.17.2.10).

This concludes the IPsec lab.

= Next Module =

* [[Training:_IPsec_VPN|Section 5: IPsec VPN Concepts]] (review)

= Source Attribution =

* '''Document:''' FUND001-LIVE-Lab5-IPsec.pdf
* '''Course:''' pfSense Plus Fundamentals and Practical Application
* '''Copyright:''' © 2021 Rubicon Communications, LLC (Netgate)
* '''Extracted:''' 2026-04-23 via pdftotext

Training: IPsec VPN

2026-04-23T07:07:11Z

Justinaquino: Imported from Netgate pfSense training PDF via bot

__NOTOC__

<div style="background-color: #e7f3fe; border-left: 6px solid #2196F3; padding: 10px; margin-bottom: 15px;">
<strong>Netgate pfSense Plus Fundamentals — Section 5: VPNs and IPsec</strong><br/>
This page covers VPN concepts, IPsec remote access, site-to-site configurations, and IKE phase negotiations.
</div>

= VPNs and IPsec =

== VPNs — Remote Access ==

Remote access VPNs provide connectivity for mobile or remote users, enabling secure tunneling over untrusted networks.

'''Use cases:'''
* Tunneling for access or performance reasons
* Additional wireless protection

'''Available options:'''
{| class="wikitable"
! Option !! Best For
|-
| IPsec || Built-in clients (OS X, iOS, Android)
|-
| OpenVPN || Ease of client configuration
|-
| WireGuard || Good performance for simple setup
|}

The best option is largely a matter of '''personal preference''' and the specific client ecosystem in use.

== VPNs — Site to Site ==

Site-to-site VPNs provide a permanent connection between networks, commonly used for:
* Multiple company offices or data centers
* Service providers
* Partners

'''Available options:'''
{| class="wikitable"
! Option !! Best For
|-
| IPsec || Widely interoperable
|-
| OpenVPN || Client behind NAT
|-
| WireGuard || Client behind NAT, modern crypto
|}

Again, the best option depends on personal preference and a weighing of strengths and weaknesses. If a client is behind NAT, OpenVPN or WireGuard may be preferable. For wide interoperability, IPsec is the standard.

= About IPsec =

IPsec is a widely interoperable VPN protocol that typically offers higher performance than most alternatives.

'''Key characteristics:'''
* Peer-to-peer relationship
* Typically '''policy-based''' (but can be '''VTI / route-based''')
* '''Phase 1''' protects IKE messages between peers
* '''Phase 2''' protects IP traffic between endpoints
* Establishes a '''Security Association (SA)''' between networks
* The SA determines which traffic traverses the tunnel

== IPsec Phase 1 ==

Phase 1 protects IKE messages between peers.

'''Key points:'''
* Peers are typically a single IP address
* Encryption and authentication protocols are required
* Common example: '''AES-256 / SHA256'''
* Provides a secure path for Phase 2 negotiation

{| class="wikitable"
! Parameter !! Typical Value
|-
| Encryption || AES-256
|-
| Authentication || SHA256
|-
| DH Group || 14 (2048-bit) or higher
|}

== IPsec Phase 2 ==

Phase 2 protects IP traffic between endpoints.

'''Key points:'''
* Security Association is formed between networks
* Encryption is optional for Phase 2 traffic — but strongly recommended
* Authentication method is still required

= IPsec — How It Looks =

Conceptually, IPsec creates an encrypted tunnel between two peer gateways:

<pre>
[Network A] --- [Gateway A] ====== encrypted tunnel ====== [Gateway B] --- [Network B]
↑ ↑
Phase 1 (IKE) Phase 1 (IKE)
Phase 2 (ESP/AH) Phase 2 (ESP/AH)
</pre>

= Section 5 Summary =

{| class="wikitable"
! Point !! Detail
|-
| Style || Peer-to-peer VPN
|-
| Routing || Can be policy-based or route-based (VTI)
|-
| Routing table || Not considered if policy-based
|-
| Agreement || As long as both sides agree, the tunnel will come up
|-
| Firewall || Still need a firewall rule to allow tunnel traffic
|-
| Performance || Consider taking advantage of AES-NI for performance
|}

= Next Module =

* [[Training_Lab_5:_IPsec_VPN|Lab 5: IPsec VPN Hands-On]]

= Source Attribution =

* '''Document:''' FUND001-LIVE-SLIDE-SEG5-IPSEC.pdf
* '''Course:''' pfSense Plus Fundamentals and Practical Application
* '''Copyright:''' © 2017 Rubicon Communications, LLC dba Netgate
* '''Extracted:''' 2026-04-23 via pdftotext

Training Lab 10: High Availability

2026-04-23T07:07:10Z

Justinaquino: Created from Netgate pfSense training PDF

__NOTOC__
<div style="background:#003366; color:#ffffff; padding:10px; border-radius:5px; margin-bottom:15px;">
'''Netgate pfSense Plus Fundamentals — Lab 10: High Availability'''
</div>

== Overview ==

In this lab, we add high availability at HQ by configuring a secondary firewall ('''fw2-HQ''') to operate as the backup in an active/passive HA pair.

== Configuring fw2-HQ ==

From your machine or HQ-client, log into fw2-HQ at '''https://172.17.1.3'''.

=== Interface Assignment ===

On fw2-HQ, browse to '''Interfaces > Assign''' and verify that your 5 interfaces are assigned correctly.

=== Interface Configuration ===

==== WAN ====

{| class="wikitable"
! Setting !! Value
|-
| Description || WAN
|-
| IPv4 Configuration Type || Static IPv4
|-
| IPv4 Address || 192.0.2.3/24
|-
| Gateway || GW_WAN — 192.0.2.1 (default gateway)
|}

Then Save and Apply Changes.

==== DMZ ====

{| class="wikitable"
! Setting !! Value
|-
| Description || DMZ
|-
| IPv4 Configuration Type || Static IPv4
|-
| IPv4 Address || 172.17.2.3/24
|}

Save and Apply Changes.

==== WAN2 ====

{| class="wikitable"
! Setting !! Value
|-
| Description || WAN2
|-
| IPv4 Configuration Type || Static IPv4
|-
| IPv4 Address || 198.51.100.3/24
|-
| Gateway || GW_WAN2 — 198.51.100.1 (not default gateway)
|}

Save and Apply Changes.

==== SYNC ====

{| class="wikitable"
! Setting !! Value
|-
| Description || SYNC
|-
| IPv4 Configuration Type || Static IPv4
|-
| IPv4 Address || 172.17.3.3/24
|}

Save and Apply Changes.

=== HA Sync Configuration (fw2-HQ) ===

Browse to '''System > High Avail Sync'''. Only the top portion is configured on the secondary, enabling it to send and receive state synchronization traffic.

* Check '''Synchronize States'''
* Choose '''Synchronize Interface''' = SYNC
* '''pfsync Synchronize Peer IP''': 172.17.3.2

Then click Save at the very bottom of the page.

=== Increase FW2 GUI Processes ===

Navigate to '''System > Advanced''' and change '''Max Processes''' from the default 2 to '''5''', to account for the extra work of sync and configuration.

=== Firewall Rule Configuration (fw2-HQ) ===

Browse to '''Firewall > Rules''', SYNC tab, and click Add to allow the initial config sync:

{| class="wikitable"
! Setting !! Value
|-
| Action || Pass
|-
| Interface || SYNC
|-
| Protocol || any
|-
| Source || any
|-
| Destination || any
|}

Then Save and Apply Changes.

fw2-HQ is now ready.

== Configuring fw1-HQ ==

Switch over to fw1-HQ to continue the configuration.

=== Assign and Configure Sync Interface ===

Browse to '''Interfaces > Assign''' and verify the SYNC interface is assigned.

Browse to '''Interfaces > OPT3''' and configure:

{| class="wikitable"
! Setting !! Value
|-
| Enable || checked
|-
| Description || SYNC
|-
| IPv4 Configuration Type || Static IPv4
|-
| IPv4 Address || 172.17.3.2/24
|}

Save and Apply Changes.

=== Add Sync Firewall Rules (fw1-HQ) ===

Browse to '''Firewall > Rules''', Sync tab. Add:

{| class="wikitable"
! Setting !! Value
|-
| Action || Pass
|-
| Interface || Sync
|-
| Protocol || any
|-
| Source || any
|-
| Destination || any
|-
| Description || allow sync
|}

Save and apply changes.

=== Change Interface IPs (fw1-HQ) ===

The gateway IPs on the internal interfaces need to be CARP IPs so they fail over. Change the LAN and DMZ interface IPs:

* '''LAN''': change from 172.17.1.1 to '''172.17.1.2'''
* '''DMZ''': change from 172.17.2.1 to '''172.17.2.2'''

The .1 IPs will be added back as CARP IPs in the next step. Save and apply changes after each interface.

=== Add CARP VIPs (fw1-HQ) ===

Browse to '''Firewall > Virtual IPs''', and click '''+Add'''.

==== LAN CARP VIP ====

{| class="wikitable"
! Setting !! Value
|-
| Type || CARP
|-
| Interface || LAN
|-
| IP Address || 172.17.1.1/24
|-
| Virtual IP Password || random characters (syncs automatically)
|}

Leave the remainder at defaults. Save and Apply Changes.

==== DMZ CARP VIP ====

{| class="wikitable"
! Setting !! Value
|-
| Type || CARP
|-
| Interface || DMZ
|-
| IP Address || 172.17.2.1/24
|-
| Virtual IP Password || random string
|}

Note the VHID group increments to 2. Save and apply changes.

=== Edit Existing WAN VIPs (fw1-HQ) ===

==== WAN .4 VIP ====

Edit 192.0.2.4: change type from IP Alias to CARP, subnet mask /24, VHID Group 3, random Virtual IP Password. Save.

==== WAN .5 and .6 VIPs ====

Edit 192.0.2.5 and 192.0.2.6: keep as IP Alias but change parent interface to the WAN CARP IP (192.0.2.4). Save and apply changes.

==== WAN2 CARP VIPs ====

Change 198.51.100.4 to CARP, and change the interface of 198.51.100.5 and .6 to 198.51.100.4.

=== Configure HA Sync (fw1-HQ) ===

Browse to '''System > High Avail. Sync''':

{| class="wikitable"
! Setting !! Value
|-
| Synchronize States || checked
|-
| Synchronize Interface || SYNC
|-
| pfsync Synchronize Peer IP || 172.17.3.3
|-
| Synchronize Config to IP || 172.17.3.3
|-
| Remote System Username || admin
|-
| Remote System Password || pfsense
|}

Click '''toggle all''' to check all synchronize configuration boxes, then click Save.

Configuration and state synchronization are now fully enabled. Do not make config changes directly on the secondary from here out, as they’ll be overwritten by the primary.

=== Configure Outbound NAT ===

Browse to '''Firewall > NAT''', Outbound tab. Edit rules so traffic is NATed to IPs that fail over:

* Edit "HQ 172.17./16 out via WAN IP" — change Translation to '''192.0.2.6'''
* Edit "HQ 172.17./16 out via WAN2 IP" — change Translation to '''198.51.100.6'''

=== Configure LAN DHCP ===

Browse to '''Services > DHCP Server''', LAN tab:

* Set default gateway to the LAN CARP VIP '''172.17.1.1'''
* Set '''Failover Peer IP''' to fw2-HQ LAN IP '''172.17.1.3'''
* Save

== Check Status ==

Browse to '''Status > CARP''' on both fw1-HQ and fw2-HQ. All CARP IPs should show:
* '''master''' status on fw1-HQ
* '''backup''' status on fw2-HQ

== Testing Failover ==

=== Force Failover by Disabling CARP on Primary ===

On fw1-HQ, browse to '''Status > CARP''' and click '''Temporarily Disable CARP'''. After reload, all CARP IPs change to "disabled." Check fw2-HQ — they should all show master status.

=== Force Failover by Simulating Power Removal ===

Navigate to '''Diagnostics > Halt System''' and click '''Reboot''' on the primary. Within a second after rebooting, fw2-HQ should show master status on all CARP IPs. After fw1-HQ reboots, it will regain master status automatically.

<div style="background:#e6f2ff; padding:10px; border-left:4px solid #003366; margin-top:15px;">
'''Previous Module:''' [[Training: High Availability|Training: High Availability — HA Overview and Concepts]]
</div>

== Source Attribution ==

* ''Netgate pfSense Plus Fundamentals and Practical Application''
* © 2021 Rubicon Communications, LLC (Netgate)
* Source PDF: FUND001-LIVE-Lab10-HA.pdf
* Reference fw2-HQ IPs: WAN 192.0.2.3, LAN 172.17.1.3, DMZ 172.17.2.3

Training: High Availability

2026-04-23T07:07:10Z

Justinaquino: Created from Netgate pfSense training PDF

__NOTOC__
<div style="background:#003366; color:#ffffff; padding:10px; border-radius:5px; margin-bottom:15px;">
'''Netgate pfSense Plus Fundamentals — Section 10: High Availability'''
</div>

== Overview ==

High Availability (HA) in pfSense uses an '''active/passive pair''' of firewalls to provide hardware redundancy. This architecture offers:

* Increased redundancy options
* Less painful upgrades
* Seamless failover capabilities

HA relies on '''three separate functions''' working together:

{| class="wikitable"
! Function !! Purpose
|-
| '''CARP''' || Provides redundant IP addresses (Virtual IPs) shared between HA members
|-
| '''pfSync''' || Synchronizes the state table between HA members for seamless failover
|-
| '''XMLRPC''' || Synchronizes configuration from the primary to secondary firewalls
|}

== CARP (Common Address Redundancy Protocol) ==

* Uses multicast for announcements
* Every CARP VIP has a unique '''VHID''' (Virtual Host ID)
* CARP VIP is shared between VHID members
* VHID groups are password protected
* At least '''3 public IPs required''' per WAN
* WAN needs at least a '''/29''' subnet

== pfSync ==

* Syncs state table between the two HA members
* Enables seamless failover during an outage
* Can use multicast or unicast for updates
* No authentication for updates
* '''Likes a dedicated interface''' (recommended)

== XMLRPC (Configuration Sync) ==

* Syncs configuration between HA members
* Syncs from primary to secondaries
* Only need to configure one firewall
* May not sync everything — '''packages are responsible for their own config sync'''

== CARP Configuration Requirements ==

* At least one CARP VIP on WAN
* At least one CARP VIP on LAN
* Manual Outbound NAT to CARP VIP
* DHCP adjustments needed (use CARP VIP as default gateway)

== Typical Topology ==

=== Single WAN ===
<pre>
ISP1
|
[ HA Pair ] — LAN
</pre>

=== Multi-WAN ===
<pre>
ISP1 ISP2
| |
[ HA Pair ] — LAN
</pre>

== Common Failures ==

* '''Dual master''' on CARP VIPs
* Loss of active connections on failover
* Loss of connectivity on failover

== Section 10 Summary ==

* Active/Passive pair
* Will need at least '''/29''' of network space per WAN
* Use a '''unique VHID''' for every CARP VIP
* Use a '''separate private interface''' for pfSync data
* Packages are responsible for their own config sync
* Outbound NAT to CARP VIP
* DHCP adjusted for CARP VIP as default gateway

<div style="background:#e6f2ff; padding:10px; border-left:4px solid #003366; margin-top:15px;">
'''Next Module:''' [[Training Lab 10: High Availability|Training Lab 10: High Availability — Hands-on Configuration and Failover Testing]]
</div>

== Source Attribution ==

* ''Netgate pfSense Plus Fundamentals and Practical Application''
* © 2017–2021 Rubicon Communications, LLC (Netgate)
* Source PDF: FUND001-LIVE-SLIDE-SEG10-HA.pdf

Training Lab 8: Multi-WAN

2026-04-23T07:06:59Z

Justinaquino: Created page with "__NOTOC__ <div style="background:#fff3e6;border:1px solid #ff9900;padding:10px;margin-bottom:15px;"> '''Netgate pfSense Plus Fundamentals — Lab 8: Multi-WAN'''<br/> <i>Adding WAN2, configuring gateway groups, failover, failback, firewall rules, NAT, and testing.</i> </div> This lab covers adding a second WAN interface to HQ, configuring the interface, gateway groups, firewall rules, NAT and related topics for multi-WAN, then testing its failover and failback. == Con..."

__NOTOC__

<div style="background:#fff3e6;border:1px solid #ff9900;padding:10px;margin-bottom:15px;">
'''Netgate pfSense Plus Fundamentals — Lab 8: Multi-WAN'''<br/>
<i>Adding WAN2, configuring gateway groups, failover, failback, firewall rules, NAT, and testing.</i>
</div>

This lab covers adding a second WAN interface to HQ, configuring the interface, gateway groups, firewall rules, NAT and related topics for multi-WAN, then testing its failover and failback.

== Configuring WAN2 Interface ==

=== Adding the WAN2 Interface ===

Browse to '''Interfaces > Assign''', and verify that your OPT2 interface is assigned to vtnet3. Browse to '''Interfaces > OPT2'''. Configure the interface as follows:

{| class="wikitable"
! Setting !! Value
|-
| Enable || check
|-
| Description || WAN2
|-
| IPv4 Type || Static
|-
| IPv4 Address || 198.51.100.2/24
|-
| Gateway || add new
|-
| — Name || GW_WAN2
|-
| — IP || 198.51.100.1
|}

Save and Apply Changes.

=== Verifying WAN2 Connectivity ===

After adding a new WAN, the fastest way to verify it’s online is by browsing to '''Status > Gateways'''. It should show green and online there. To verify Internet connectivity, browse to '''Diagnostics > Ping'''. Enter any Internet host that replies to pings in the “Host” box (such as google.com), choose Source Address '''WAN2''', and click Ping. You should receive replies.

== Configuring DNS Servers ==

At least one DNS server must be reachable via each WAN so a single connection's failure doesn't result in DNS failing.

* In a production environment, at least one DNS server should be assigned to each WAN.
* In this lab network, DNS servers are local to the WAN and WAN2 networks, so we will not assign them to specific gateways.

Browse to '''System > General Setup'''. There you will see the existing entry for 192.0.2.1. In a real production environment, you may consider assigning this to GW_WAN, however that is not possible or necessary here as 192.0.2.1 exists in the same network as the WAN.

Add '''198.51.100.1''' as a secondary DNS server. In a real production environment, you may consider assigning this to GW_WAN2, however that is not possible or necessary here as 198.51.100.1 exists in the same network as the WANs.

Click Save.

== Configuring Monitor IPs ==

The system will ping its monitor IP for each gateway to determine gateway status. By default, the gateway's IP is used. For multi-WAN scenarios, that is probably not a good choice.

* Your default gateway may be a local router within your facility, unlikely to ever go down when your Internet goes down.
* Or problems in your ISP's network further upstream could cause loss of connectivity.
* Using an IP out on the Internet as the monitor IP offers a better test of connectivity.

Use of anycasted IPs is best:
* Google public DNS: 8.8.8.8 and 8.8.4.4
* OpenDNS: 208.67.220.220 and 208.67.222.222

Browse to '''System > Routing'''. Edit '''GW_WAN'''. For monitor IP, fill in '''8.8.8.8'''. Save. Then edit '''GW_WAN2''', and set its monitor IP to '''8.8.4.4'''. Save, then Apply Changes.

== Configuring Gateway Groups ==

Configure three gateway groups for use at HQ:
# One that prefers WAN and fails over to WAN2.
# One that prefers WAN2 and fails over to WAN.
# One that load balances across both.

Browse to '''System > Routing''', and click the '''Groups''' tab. Click '''+Add''' to add a new group.

=== WAN to WAN2 ===

This gateway group prefers WAN (tier 1) and fails over to WAN2 (tier 2). Then click Save.

=== WAN2 to WAN ===

Click the duplicate symbol to the right of the WANtoWAN2 group to create a new group based on this one, then flip the tiers, group name and description. This prefers WAN2, and fails over to WAN.

=== Load Balance ===

This load balances across both WAN and WAN2. If a WAN fails, it's removed from the load balancing pool.

== Configure NAT for Multi-WAN ==

The NAT configuration is all on a per-interface basis, specifying one particular interface and having IP information that's specific to that interface. When you add a new WAN, you also need NAT configuration specific to that new WAN.

=== Configuring Virtual IPs on WAN2 ===

WAN2 will have 3 virtual IPs configured as IP aliases:

{| class="wikitable"
! IP/mask !! Description
|-
| 198.51.100.4/32 || server1 WAN2 external address
|-
| 198.51.100.5/32 || server2 WAN2 external address
|-
| 198.51.100.6/32 || extra WAN2 external address
|}

Repeat the process for the remaining IPs.

=== Configuring Port Forwards on WAN2 ===

To open the same ports on WAN2 as on WAN, duplicate the existing port forward entries and change their interface from WAN to WAN2.

Browse to '''Firewall > NAT''', '''Port Forwards''' tab. Click the duplicate symbol to the right of the “VNC to hqclient” entry. In the resulting screen, change the interface from WAN to WAN2. Note how the destination address automatically changes to “WAN2 address.” Verify that change, update the description if desired, then save.

Repeat that process for the port 222 SSH port forward to hq-client.

=== Configuring 1:1 NAT on WAN2 ===

Configure 1:1 NAT for server1 and server2 on WAN2.

{| class="wikitable"
! Setting !! server1 !! server2
|-
| Interface || WAN2 || WAN2
|-
| External IP || 198.51.100.4 || 198.51.100.5
|-
| Internal IP || 172.17.2.10 || 172.17.2.20
|-
| Description || server1.example.com WAN2 || server2.example.com WAN2
|}

Save and apply changes.

=== Configuring Outbound NAT on WAN2 ===

Since the configuration is using manual outbound NAT, add outbound NAT rules for WAN2.

Browse to '''Firewall > NAT''', '''Outbound''' tab. Click the duplicate symbol to the right of “hq-client out via .6” to add a new entry based on that one. Change the interface to WAN2, and the Translation address to 198.51.100.6.

Repeat the same process for the two other outbound NAT rules.

== Configuring WAN2 Firewall Rules ==

We want the same external access on WAN2 as is already active on WAN, permitting certain traffic through the 1:1 NATs for server1 and server2. Interface groupings do not support return routing at this time, so the rules must be kept on each WAN separately.

Browse to '''Firewall > Rules''', WAN tab. Click the duplicate symbol to the right of “allow web ports to public web servers” to duplicate it, change the interface from WAN to WAN2, and click Save. Because the NAT applies first, the firewall rule is otherwise identical to the one on WAN.

Repeat the same process for rules “allow pings to public web servers” and “allow SSH to web servers from remote admin.”

== Configure Firewall Rules for Outbound Traffic ==

In a multi-WAN environment, outbound traffic is directed to a particular WAN or gateway group via policy routing with firewall rules.

=== Test WAN2 with Single Client ===

First, send only HQ-client out via WAN2. It's generally best to first test a new WAN with a single client.

Browse to '''Firewall > Rules''', LAN tab, and click Add to add a rule to the top of the list:

{| class="wikitable"
! Setting !! Value
|-
| Action || Pass
|-
| Interface || LAN
|-
| Protocol || any
|-
| Source || Single host or alias, 172.17.1.100
|-
| Destination || any
|-
| Description || hq-client1 prefer WAN2
|-
| Gateway (Advanced Options) || WAN2toWAN
|}

Save and apply changes.

=== Testing LAN out WAN2 ===

Open hq-client1's web browser and browse to http://100.64.0.50. You should be able to connect, and see you're coming from 198.51.100.6, the WAN2 VIP where hq-client1 is NATed.

=== Configure LAN for Failover Group ===

The “hq-client1 prefer WAN2” rule was only for testing. Delete that rule now.

Then edit the “Default allow LAN to any” rule, and choose Gateway '''WANtoWAN2'''. Verify Internet connectivity is still functioning from hq-client1.

=== LAN to DMZ Connectivity ===

Try to ping 172.17.2.10 from hq-client1. You won't receive a successful reply because traffic matching a firewall rule specifying a gateway is forced to that gateway. The attempt to get to DMZ is actually being sent to the WAN ISP's router, which can't route internal traffic.

=== Add LocalNetworks Alias ===

Add an alias containing destinations that will not be policy-routed to the Internet.

Browse to '''Firewall > Aliases''' and click '''+Add''':

{| class="wikitable"
! Setting !! Value
|-
| Name || LocalNetworks
|-
| Description || networks that will not be policy routed to Internet
|-
| Type || Network
|-
| Network 1 || 172.17.0.0/16 (HQ)
|-
| Network 2 || 172.18.0.0/16 (branch)
|}

Save and apply changes.

=== Add Firewall Rule for Negation ===

Browse to '''Firewall > Rules''', LAN, and click Add to add a new rule to the top of the list:

{| class="wikitable"
! Setting !! Value
|-
| Action || Pass
|-
| Interface || LAN
|-
| Protocol || any
|-
| Source || LAN net
|-
| Destination || Single host or alias, LocalNetworks alias
|-
| Description || allow local networks with no policy routing
|-
| Gateway || Leave at default
|}

Start a new ping to 172.17.2.10 and it will reply. If you still aren't getting a ping reply, it's probably because of an old firewall state. Reset states under '''Diagnostics > States''', or delete those specific states, and try again.

== Default Gateway Switching ==

At this point, all traffic sourced from inside the LAN or DMZ destined for the internet will follow the policy route. However, the default route on the firewall is still pointing to WAN1. In the event of a WAN1 failure, traffic sourced by the firewall itself will not be able to reach the internet.

Navigate to '''System > Routing''' and set '''Default gateway IPv4''' to '''Automatic''' and click Save.

== Testing Failover ==

Now that failover is configured, it's important to test it. Create a failure on WAN to verify it switches over to WAN2.

In the virtual lab environment, shutdown the WAN1 NIC on “Lab Internet router.” Point your web browser to your Lab Internet Router (http://100.64.0.1) and browse to '''Interfaces > HQ_WAN1'''. Uncheck the Enable box at the top and click OK, then Apply.

Now browse to '''Status > Gateways''' on fw1-HQ. Within a few seconds, WAN should show as offline. Once it does, try to browse out from LAN to the Internet. You should now be using WAN2.

Once tested, normalize your lab by logging back into your Lab Internet Router (http://100.64.0.1) and check the Enable box in the HQ-WAN1 interface. Your WAN gateway should then come back online.

This completes the multi-WAN lab.

----

<div style="background:#f0f0f0;border:1px solid #ccc;padding:8px;">
'''Source:''' Netgate pfSense Plus Fundamentals and Practical Application — Lab 8 (Multi-WAN).<br/>
© 2021 Rubicon Communications, LLC (Netgate).<br/>
'''Reference WAN2 IP:''' 198.51.100.2/24, Gateway: 198.51.100.1
</div>

'''Previous Module:''' [[Training:_Multi-WAN|Training: Multi-WAN]]

Training: Multi-WAN

2026-04-23T07:06:59Z

Justinaquino: Created page with "__NOTOC__ <div style="background:#e6f3ff;border:1px solid #0066cc;padding:10px;margin-bottom:15px;"> '''Netgate pfSense Plus Fundamentals — Section 8: Multi-WAN'''<br/> <i>Overview, redundancy, load balancing, gateway groups, and best practices for multiple Internet connections.</i> </div> == Multi-WAN Overview == Use of multiple Internet connections for: * '''Redundancy''' (common) * '''Bandwidth aggregation''' * '''Load balancing''' == Multi-WAN Best Practices ==..."

__NOTOC__

<div style="background:#e6f3ff;border:1px solid #0066cc;padding:10px;margin-bottom:15px;">
'''Netgate pfSense Plus Fundamentals — Section 8: Multi-WAN'''<br/>
<i>Overview, redundancy, load balancing, gateway groups, and best practices for multiple Internet connections.</i>
</div>

== Multi-WAN Overview ==

Use of multiple Internet connections for:
* '''Redundancy''' (common)
* '''Bandwidth aggregation'''
* '''Load balancing'''

== Multi-WAN Best Practices ==

Internet connectivity selection considerations:

{| class="wikitable"
! Consideration !! Description
|-
| Performance || Evaluate throughput, latency, and reliability of each link.
|-
| Cable path || Use physically diverse paths to avoid single points of failure.
|-
| Disparate ISP networks || Use different ISPs to reduce the risk of a common outage.
|-
| Plan for failure! || Always design with failure scenarios in mind.
|-
| Usage scenarios for load balancing || Understand traffic patterns before implementing load balancing.
|}

== Multi-WAN Gateways ==

Each gateway defines an Internet connection.

* Monitor IP can be changed.
* Advanced parameters available (latency and packet loss thresholds).

== Multi-WAN Gateway Groups ==

Gateway groups are containers of gateways (Internet connections).

{| class="wikitable"
! Attribute !! Description
|-
| Tiers 1-5 || Lowest tier number is highest priority.
|-
| One or more gateways per tier || Multiple gateways can share a tier.
|-
| Usage || Applied via policy routing, IPsec, OpenVPN, Dynamic DNS.
|}

== Multi-WAN Outbound Traffic ==

Controlled via '''policy routing''':

* Firewall rules specifying a gateway.
* Matching traffic is forced to the specified gateway.
* Overrides routing table in all circumstances.

== Multi-WAN Inbound Traffic ==

* Port forwards and 1:1 NAT are specific to one WAN.
* Duplicate port forwards for additional WANs.
* Add 1:1 NAT entries for additional WANs.
* Update how traffic comes in (DNS updates).
* Dynamic DNS on gateway group.
* Multiple inbound options always live (e.g., email — one MX record per WAN).

== Section 8 Summary ==

{| class="wikitable"
! Key Point !! Detail
|-
| Rule ordering || First match wins.
|-
| Bypass rule || A bypass rule may be required.
|-
| Gateway forcing || Matching traffic is forced to gateway.
|-
| Monitor IP || Use appropriate monitor IP per WAN.
|-
| Load balancing || Load-balance over equal-size links.
|-
| Per-flow balancing || Load-balancing is per-flow, not per-packet.
|-
| Reference || Check the Multi-WAN section of the book!
|}

----

<div style="background:#f0f0f0;border:1px solid #ccc;padding:8px;">
'''Source:''' Netgate pfSense Plus Fundamentals and Practical Application — Section 8 (Multi-WAN).<br/>
© 2017 Rubicon Communications, LLC dba Netgate.
</div>

'''Next Module:''' [[Training_Lab_8:_Multi-WAN|Training Lab 8: Multi-WAN]]

Training Lab 4: Services and Branch Network

2026-04-23T07:01:36Z

Justinaquino: Created from Netgate pfSense training PDFs

__NOTOC__

<div style="background-color: #fff3cd; border-left: 6px solid #ffc107; padding: 15px; margin-bottom: 20px;">
<strong>Lab:</strong> Lab 4 — Services and Branch Network Setup<br>
<strong>Course:</strong> Netgate FUND001-LIVE — pfSense Plus Fundamentals and Practical Application<br>
<strong>Objective:</strong> Configure common pfSense Plus services (DNS Resolver, DHCP Server) and bring up a branch network for use in the next lab.
</div>

== Lab Overview ==

In this lab, we will go through a couple of the common services used on pfSense Plus, then bring up the branch network to be used in the next lab.

The exercises cover:

* Configuring the '''DNS Resolver''' (domain overrides, host overrides)
* Configuring the '''DHCP Server''' (changing scope, adding static mappings)
* '''Branch network setup''' and remote management

== Prerequisites ==

* Access to fw1-HQ (172.17.1.1)
* Access to HQ-client (DHCP client on HQ-LAN)
* Access to branch firewall (172.18.1.1)
* Default admin/pfsense credentials

== Exercise 1: DNS Resolver Configuration ==

The DNS Resolver provides a local caching DNS resolver on the firewall. On smaller networks with no local DNS servers, using the local DNS Resolver as your clients' DNS server — rather than directly assigning DNS servers on the Internet — is preferable.

It provides:

* A local DNS cache
* Ability to query multiple DNS servers simultaneously, returning the fastest response
* Security protections such as DNS rebinding protection and DNSSEC

=== 1.1 DNS Server Configuration ===

By default, the DNS Resolver queries root DNS servers directly and does not use DNS servers configured under '''System > General Setup''' or those obtained automatically from a dynamic WAN.

'''Step 1:''' Browse to '''System > General Setup''' on fw1-HQ.

'''Step 2:''' Review the DNS server configuration. Currently, fw1-HQ is statically configured to use the DNS Resolver on lab-internet-router.

'''Step 3:''' The '''"Allow DNS server list to be overridden by DHCP/PPP on WAN"''' checkbox is checked by default. Since these systems do not have dynamic WANs, this option has no effect. '''Uncheck''' this option.

'''Step 4:''' Leave the remaining settings as they are and click '''Save'''.

=== 1.2 Domain Overrides ===

Domain overrides allow you to configure specific DNS servers to use for particular domains.

In this exercise, we will forward '''example.lan''' to '''172.17.2.10'''. This is functionally equivalent to what you would do in a Small Business Server (SBS) scenario for Active Directory.

'''Step 1:''' On HQ-client, open a terminal and test resolution '''before''' adding the domain override:

<pre>
training@HQ-client:~$ host server1.example.lan
Host server1.example.lan not found: 3(NXDOMAIN)
training@HQ-client:~$ host server2.example.lan
Host server2.example.lan not found: 3(NXDOMAIN)
training@HQ-client:~$ host hq-client.example.lan
Host hq-client.example.lan not found: 3(NXDOMAIN)
</pre>

NXDOMAIN means "no such name exists." To resolve example.lan, we must tell the DNS Resolver where to send those queries.

'''Step 2:''' On fw1-HQ, browse to '''Services > DNS Resolver'''.

'''Step 3:''' Scroll down to '''Domain Overrides''' and click '''+Add'''.

'''Step 4:''' Configure the domain override:

{| class="wikitable"
! Field
! Value
|-
| Domain
| example.lan
|-
| IP Address
| 172.17.2.10
|}

'''Step 5:''' Click '''Save'''.

=== 1.3 Testing Domain Override ===

'''Step 1:''' On HQ-client, open a terminal and test resolution again:

<pre>
training@hq-client:~$ host server1.example.lan
server1.example.lan has address 172.17.2.10
training@hq-client:~$ host server2.example.lan
server2.example.lan has address 172.17.2.20
training@hq-client:~$ host hq-client.example.lan
hq-client.example.lan has address 172.17.1.100
</pre>

These queries go to the DNS Resolver on fw1-HQ, which uses the domain override to send example.lan queries to server1. Server1 replies to the DNS Resolver, which replies back to HQ-client.

=== 1.4 Host Overrides ===

Host overrides allow you to configure how a specific hostname is resolved by the DNS Resolver. A common use is '''split DNS''': resolving public DNS hostnames to private IPs internally to eliminate the need for NAT reflection.

In this lab:

* www.example.com is hosted in the HQ DMZ on server1
* www.example.com publicly resolves to 192.0.2.4
* Without NAT reflection, HQ internal hosts cannot reach 192.0.2.4
* We will add a host override to resolve www.example.com to the internal IP 172.17.2.10

'''Step 1:''' On fw1-HQ, browse to '''Services > DNS Resolver''', scroll down to '''Host Overrides''', and click '''+Add'''.

'''Step 2:''' Configure the host override:

{| class="wikitable"
! Field
! Value
|-
| Host
| (leave blank)
|-
| Domain
| example.com
|-
| IP address
| 172.17.2.10
|-
| Alias Host
| www
|-
| Alias Domain
| example.com
|}

'''Step 3:''' Click '''Save''' and '''Apply Changes'''.

=== 1.5 Testing Host Override ===

'''Step 1:''' On HQ-client, test resolution:

<pre>
training@HQ-client:~$ host www.example.com
www.example.com has address 172.17.2.10
training@HQ-client:~$ host example.com
example.com has address 172.17.2.10
</pre>

'''Step 2:''' Open '''www.example.com''' in your web browser on HQ-client. The page should load, showing it is from server1 and displaying your source IP.

== Exercise 2: DHCP Server Configuration ==

The DHCP Server comes enabled by default on LAN, assigning IP information, a default gateway, and DNS server to LAN clients.

HQ-client is a DHCP client currently obtaining an IP from the general pool. Because it is the first and only device on HQ-LAN, it gets the first IP: '''172.17.1.100'''. We want to ensure HQ-client is always assigned the .100 IP and that it cannot be assigned to any other host.

=== 2.1 Checking DHCP Status ===

'''Step 1:''' On fw1-HQ, browse to '''Status > DHCP Leases'''.

'''Step 2:''' Locate the lease for HQ-client.

=== 2.2 Changing DHCP Scope ===

The underlying DHCP server (ISC dhcpd) requires statically mapped IPs to be '''outside of the DHCP scope'''. Since .100 is part of the currently active range, we must change the range to exclude it.

Note: Doing so will not immediately impact HQ-client. It will retain its existing .100 IP until its next renewal.

'''Step 1:''' Browse to '''Services > DHCP Server''' and click the '''LAN''' tab.

'''Step 2:''' Change the '''Start of the range''' to '''172.17.1.101'''.

'''Step 3:''' Click '''Save'''.

Now .100 will be available for a DHCP reservation.

=== 2.3 Adding DHCP Static Mapping for HQ-client ===

First, we need to renew the DHCP lease on HQ-client so it re-populates in the DHCP leases screen (its lease for .100 was deleted after changing the scope).

'''Step 1:''' On HQ-client, click the network icon in the top right corner and click '''"Ifupdown (eth0)"''' to renew the lease.

Note: Your VNC session will be dropped. Wait a few seconds.

'''Step 2:''' On fw1-HQ, refresh '''Status > DHCP Leases'''. After 20-30 seconds, you should see HQ-client obtained a lease for '''172.17.1.101'''. Reconnect to VNC using the .101 IP.

'''Step 3:''' Browse to '''Status > DHCP Leases'''.

'''Step 4:''' Click the '''+''' to the right of the HQ-client lease to add a DHCP static mapping.

'''Step 5:''' At the "Edit static mapping" screen, fill in:

{| class="wikitable"
! Field
! Value
|-
| IP address
| 172.17.1.100
|}

'''Step 6:''' Click '''Save''' and '''Apply Changes'''.

=== 2.4 Renewing DHCP Lease on HQ-client ===

'''Step 1:''' Force HQ-client to renew its DHCP lease again (click network icon → "Ifupdown (eth0)").

Note: This will drop your VNC session again. Wait a few seconds for it to pick up the lease for the static mapping, then reconnect using '''172.17.1.100'''.

'''Step 2:''' Browse to '''Status > DHCP Leases''' on fw1-HQ and verify HQ-client's static mapping status.

== Exercise 3: Branch Network Setup ==

Here we will bring the branch network online to be ready for use in the next lab.

=== 3.1 Initial Branch Firewall Access ===

'''Step 1:''' Browse to '''https://172.18.1.1''' from your system.

'''Step 2:''' Add an exception for the self-signed certificate.

'''Step 3:''' Log in with the default credentials '''admin / pfsense'''.

Note: This will not trigger the setup wizard, as this VM comes pre-configured past that point.

=== 3.2 Setting Up Remote Management ===

We will have a VPN connected into this location in the next lab. However, it is usually best to have a means into remote offices' firewalls without requiring a VPN, limited to specific trusted source IPs.

==== Add RemoteAdmin Alias ====

'''Step 1:''' Browse to '''Firewall > Aliases''' and click '''+Add'''.

'''Step 2:''' Create the alias with the following parameters:

{| class="wikitable"
! Parameter
! Value
|-
| Name
| RemoteAdmin
|-
| Type
| Networks
|-
| Members
| 192.0.2.0/24 (HQ WAN)<br>198.51.100.0/24 (HQ WAN2)
|}

'''Step 3:''' Click '''Save''' and '''Apply Changes'''.

==== Add Firewall Rule ====

'''Step 1:''' Browse to '''Firewall > Rules''', click the '''WAN''' tab, and click '''Add'''.

'''Step 2:''' Configure the rule:

{| class="wikitable"
! Parameter
! Value
|-
| Action
| Pass
|-
| Interface
| WAN
|-
| Protocol
| any
|-
| Source
| Single host or alias → RemoteAdmin
|-
| Destination
| WAN address
|-
| Description
| allow remote administration from trusted IPs
|}

'''Step 3:''' Click '''Save''' and '''Apply Changes'''.

=== 3.3 Test Remote Administration ===

'''Step 1:''' On HQ-client, browse to '''https://203.0.113.10'''.

'''Step 2:''' It should load, allowing you to log in and manage the branch system from HQ.

You have now reached the end of this lab.

== Lab Summary ==

{| class="wikitable"
! Exercise
! What We Did
! Key Takeaway
|-
| DNS Resolver
| Configured domain overrides and host overrides
| Use overrides for internal domains and split DNS
|-
| DHCP Server
| Changed scope and added static mapping
| Static IPs must be outside the DHCP pool
|-
| Branch Setup
| Brought branch firewall online, added remote admin access
| Restrict remote admin to trusted source IPs
|}

== Next Module ==

Continue to the next lab for VPN configuration and connecting the branch network.

----

''Source: Netgate FUND001-LIVE-Lab4-Services.pdf''

[[Category:Training]]
[[Category:pfSense]]
[[Category:Networking]]
[[Category:Lab]]

Training: pfSense Services

2026-04-23T07:01:36Z

Justinaquino: Created from Netgate pfSense training PDFs

__NOTOC__

<div style="background-color: #e7f3fe; border-left: 6px solid #2196F3; padding: 15px; margin-bottom: 20px;">
<strong>Module:</strong> Section 4 — pfSense Plus Services<br>
<strong>Course:</strong> Netgate FUND001-LIVE — pfSense Plus Fundamentals and Practical Application<br>
<strong>Topics Covered:</strong> DHCP, DNS Resolver/Forwarder, Dynamic DNS, NTP, SNMP, UPnP / NAT-PMP, IGMP Proxy, PPPoE Server, Wake on LAN<br>
<strong>Objective:</strong> Understand the built-in services available on pfSense Plus and how to configure and secure them.
</div>

== Learning Objectives ==

By the end of this module, you will be able to:

* Identify the core network services built into pfSense Plus
* Understand the difference between DHCP Server and DHCP Relay
* Configure the DNS Resolver for local caching and recursion
* Explain the purpose of Dynamic DNS, NTP, SNMP, and UPnP
* Apply security best practices for exposed services

== Overview of pfSense Plus Services ==

pfSense Plus includes a rich set of network services that can be enabled and configured as needed. These services help manage client connectivity, name resolution, time synchronization, monitoring, and more.

The available services include:

* '''DHCP Server''' — Assigns IP addresses and network information to clients
* '''DHCP Relay''' — Forwards DHCP requests to servers on another network
* '''DNS Forwarder (legacy)''' — Forwards DNS queries to external servers
* '''DNS Resolver''' — Caching DNS resolver with recursion support
* '''Dynamic DNS''' — Updates DNS records automatically when the WAN IP changes
* '''IGMP Proxy''' — Forwards IGMP multicast traffic between interfaces
* '''NTP Server''' — Provides Network Time Protocol services to local clients
* '''PPPoE Server''' — Terminates PPPoE client connections
* '''SNMP''' — Integrates with network monitoring systems
* '''UPnP / NAT-PMP''' — Allows internal clients to automatically open NAT ports
* '''Wake on LAN''' — Sends magic packets to wake up sleeping devices

== DHCP Service ==

=== DHCP Server ===

The DHCP Server assigns IP addresses and other network information (subnet mask, gateway, DNS) to clients. It is '''enabled by default on the LAN interface'''.

Key points:

* Supports many extensible options (custom DHCP options)
* Static mappings can reserve specific IPs for known MAC addresses
* The underlying server is ISC dhcpd

=== DHCP Relay ===

DHCP Relay sends DHCP requests from clients on one network to DHCP server(s) on another network, then returns the DHCP reply to the requesting client.

* Simple concept but very useful in segmented networks
* Only one of DHCP Server or DHCP Relay can be enabled on an interface (not both)

== DNS Resolver ==

The DNS Resolver (unbound) is the '''recommended DNS solution''' for pfSense Plus.

* It is a '''caching DNS resolver'''
* Requires DNS servers for recursion (queries root servers directly by default)
* Queries all configured DNS servers and takes the fastest response
* Should be configured for '''internal-only access''' to avoid reflected DDoS exploit risks
* Supports DNSSEC for verifiable and trustworthy DNS results
* Offers DNS rebinding protection

Key configuration options:

* '''Domain Overrides''' — Forward queries for specific domains to specific DNS servers
* '''Host Overrides''' — Resolve specific hostnames to custom IPs (useful for split DNS)
* '''DNS Query Forwarding''' — Optionally forward all queries to upstream DNS servers instead of querying roots directly

== DNS Forwarder (Legacy) ==

The DNS Forwarder (dnsmasq) is the legacy DNS option. The DNS Resolver is preferred for new deployments.

== Dynamic DNS ==

Dynamic DNS automatically updates DNS records when the WAN IP address changes. This is essential for:

* Hosting services on dynamic IP connections
* Remote access to networks with non-static public IPs

== NTP Server ==

The Network Time Protocol (NTP) Server provides time synchronization services to local clients.

* Time synchronization is '''very important''' for logging, certificates, and authentication
* Supports serial GPS as a time source
* The host's own NTP server is configured under '''System > General Setup'''
* Status can be checked under '''Status > NTP'''
* It is easy to offer NTP services to clients — enable the service and allow the traffic

== SNMP ==

SNMP (Simple Network Management Protocol) integrates pfSense Plus with network monitoring platforms.

Best practices:

* Use a '''strong community string'''
* Configure to send traps and allow polling as needed
* '''Protect with firewall rules''' or bind to specific interfaces
* '''Do not expose SNMP to the WAN!'''

== UPnP / NAT-PMP ==

UPnP (Universal Plug and Play) and NAT-PMP (NAT Port Mapping Protocol) allow internal clients to automatically request port forwards from the firewall.

* Useful for gaming consoles, VoIP, and peer-to-peer applications
* Can be a security risk if not properly restricted
* Consider limiting to specific interfaces and restricting port ranges

== Other Services ==

=== IGMP Proxy ===

Forwards IGMP multicast traffic between interfaces. Used for IPTV and other multicast applications.

=== PPPoE Server ===

Terminates PPPoE client connections. Used in ISP and WISP environments.

=== Wake on LAN ===

Sends magic packets to wake up sleeping devices on the local network.

== Security Best Practices ==

{| class="wikitable"
! Service
! Best Practice
|-
| DNS Resolver
| Bind to internal interfaces only; enable DNSSEC
|-
| SNMP
| Use strong community strings; do not expose to WAN
|-
| NTP
| Restrict to internal networks; use authenticated NTP where possible
|-
| UPnP
| Limit to trusted interfaces; restrict port ranges
|-
| DHCP
| Use static mappings for critical infrastructure
|}

== Summary ==

* Use the '''DNS Resolver''' as your primary DNS solution — it can point to internal DNS servers and offers caching, DNSSEC, and security protections
* Integrate pfSense Plus with '''network monitoring platforms''' via SNMP
* '''Protect SNMP, NTP, and DNS Resolver''' with firewall rules and interface bindings
* '''Offer NTP services to clients''' — it is easy to enable and critical for network operations
* Choose between DHCP Server and DHCP Relay based on your network topology
* Restrict or avoid exposing services to the WAN unless absolutely necessary

== Next Module ==

Continue to '''[[Training_Lab_4:_Services_and_Branch_Network|Lab 4: Services and Branch Network Setup]]''' for hands-on exercises configuring the DNS Resolver, DHCP Server, and bringing up a branch network.

----

''Source: Netgate FUND001-LIVE-SLIDE-SEG4-SERVICES.pdf''

[[Category:Training]]
[[Category:pfSense]]
[[Category:Networking]]

Training Lab 3: NAT and Virtual IPs

2026-04-23T06:58:56Z

Justinaquino: Created from Netgate pfSense training PDF

__NOTOC__

<div style="background-color: #fff3e0; border-left: 6px solid #FF9800; padding: 16px; margin-bottom: 20px;">
<strong>Lab Overview:</strong> This hands-on lab covers Virtual IPs, Port Forwards, 1:1 NAT, and Outbound NAT in pfSense Plus. You will configure VIPs on the WAN subnet <code>192.0.2.0/24</code> and implement various NAT scenarios using Virtual IPs <code>192.0.2.4</code>–<code>192.0.2.6</code>.
</div>

== Lab Environment ==

{| class="wikitable"
|+ WAN Subnet Allocation
|-
! IP Address !! Purpose
|-
| 192.0.2.1 || ISP router (default gateway)
|-
| 192.0.2.2 || fw1-HQ WAN IP
|-
| 192.0.2.3 || Reserved for fw2-HQ (Advanced Application class)
|-
| 192.0.2.4 || Virtual IP — server1 WAN external address
|-
| 192.0.2.5 || Virtual IP — server2 WAN external address
|-
| 192.0.2.6 || Virtual IP — hq-client / VoIP PBX alternate outbound
|}

== Exercise 1: Configuring Virtual IPs ==

At HQ, we have a /24 public IP subnet assigned by our ISP: <code>192.0.2.0/24</code>. In most real-world networks, this will be a smaller subnet such as a /29, /28, or /27. The concepts are the same regardless of subnet size.

Our WAN1 ISP router has IP <code>192.0.2.1</code>, used as the default gateway. fw1-HQ has a WAN IP of <code>192.0.2.2</code>. In order for us to use additional IPs in the WAN1 subnet, the firewall must answer ARP requests for those addresses — this tells the ISP router to send traffic destined to those addresses to the firewall.

=== Step 1.1 — Add VIP 192.0.2.4 ===

On fw1-HQ, browse to '''Firewall → Virtual IPs'''.

Click '''+ Add''' to add a new VIP.

{| class="wikitable"
|+ VIP Configuration for server1
|-
! Field !! Value
|-
| Type || IP alias
|-
| Interface || WAN
|-
| IP Address || 192.0.2.4/32
|-
| Description || server1 WAN external address
|}

'''Note:''' You can enter the IP without choosing a mask; the JavaScript on the page will automatically set the mask to /32 after detecting an IPv4 address.

Click '''Save''', then click '''+ Add''' again to add the second VIP.

=== Step 1.2 — Add VIP 192.0.2.5 ===

{| class="wikitable"
|+ VIP Configuration for server2
|-
! Field !! Value
|-
| Type || IP alias
|-
| Interface || WAN
|-
| IP Address || 192.0.2.5/32
|-
| Description || server2 WAN external
|}

Click '''Save''', then add the third VIP.

=== Step 1.3 — Add VIP 192.0.2.6 ===

{| class="wikitable"
|+ VIP Configuration for PBX / alternate outbound
|-
! Field !! Value
|-
| Type || IP alias
|-
| Interface || WAN
|-
| IP Address || 192.0.2.6/32
|-
| Description || VoIP PBX / alternate outbound IP
|}

Click '''Save''', then click '''Apply Changes'''.

Now <code>192.0.2.4</code>, <code>192.0.2.5</code>, and <code>192.0.2.6</code> are available for use. Adding VIPs only makes the firewall answer on the configured addresses; they are not yet used for NAT.

== Exercise 2: Configuring a Basic Port Forward ==

We will set up a port forward allowing remote desktop access from the host machine to hq-client using VNC.

'''Warning:''' Opening VNC to the Internet is not recommended in production. Use a VPN instead. This is for demonstration purposes only.

=== Step 2.1 — Create VNC Port Forward ===

On fw1-HQ, browse to '''Firewall → NAT''', Port Forward tab. Click '''Add'''.

{| class="wikitable"
|+ VNC Port Forward Rule
|-
! Field !! Value
|-
| Interface || WAN
|-
| Protocol || TCP
|-
| Source || any
|-
| Destination || WAN address
|-
| Destination port || 5900
|-
| Redirect target IP || 172.17.1.100
|-
| Redirect target port || 5900
|-
| Description || forward VNC to hq-client
|}

Click '''Save''', and '''Apply Changes'''.

=== Step 2.2 — Verify the Port Forward ===

From your host OS or the internet-host VM, connect to <code>192.0.2.2:5900</code> with VNC Viewer.

On fw1-HQ, browse to '''Diagnostics → States''' and filter for <code>:5900</code>. You will see two states: inbound (WAN) and outbound (LAN).

== Exercise 3: Port Forward on a Different External Port ==

Sometimes you need to use a different external port than the internal port. For example, opening SSH on port 222 externally to port 22 internally reduces SSH brute-force log noise.

=== Step 3.1 — Create Alternate SSH Port Forward ===

Instead of clicking '''Add''', click the '''copy''' icon to the right of the VNC port forward to duplicate it. Then change:

{| class="wikitable"
|+ Alternate SSH Port Forward Rule
|-
! Field !! Value
|-
| Destination port || 222
|-
| Redirect target port || 22
|-
| Description || external SSH port 222 to hq-client
|}

Click '''Save''' and '''Apply Changes'''.

=== Step 3.2 — Test SSH Connection ===

From your computer, run:

<pre>
ssh -p 222 training@192.0.2.2
</pre>

Or from Windows, use PuTTY with IP <code>192.0.2.2</code> and port <code>222</code>, ensuring SSH is selected.

== Exercise 4: Restricted Source Port Forward ==

Restrict the hq-client VNC port forward to the RemoteAdmins alias.

=== Step 4.1 — Edit VNC Port Forward ===

Edit the VNC port forward. In the '''Source''' field, click '''Advanced'''.

* Type: '''Single host or alias'''
* Address: Type <code>r</code> to populate the '''RemoteAdmin''' alias
* Source port: '''any'''

Save and apply changes.

=== Step 4.2 — Verify Restriction ===

* From the remote-host VM (if not in RemoteAdmin alias): connection should fail
* From the host OS (if in RemoteAdmin alias): connection should succeed

== Exercise 5: Alternate External IP Port Forward ==

Use the Virtual IPs added earlier instead of the WAN IP.

=== Step 5.1 — Create HTTP Port Forward on VIP ===

Click '''Add''' to add a new port forward.

{| class="wikitable"
|+ HTTP to server1 via VIP
|-
! Field !! Value
|-
| Interface || WAN
|-
| Protocol || TCP
|-
| Source || any
|-
| Destination || 192.0.2.4
|-
| Destination port || 80
|-
| Redirect target IP || 172.17.2.10
|-
| Redirect target port || 80
|-
| Description || HTTP to server1
|}

Save and apply changes.

=== Step 5.2 — Verify HTTP Access ===

Browse to <code>http://192.0.2.4</code> from your host OS or internet-host VM. It should display the server1 page.

'''Note:''' Reflection is not yet configured, so this will only work from outside the network.

== Exercise 6: Configuring 1:1 NAT ==

1:1 NAT maps one external IP to one internal IP. Port forwards take precedence over 1:1 NAT where they overlap.

=== Step 6.1 — Delete Overlapping Port Forward ===

First, delete the '''HTTP to server1''' port forward entry, then apply changes. This is preferable to letting 1:1 NAT handle the traffic.

=== Step 6.2 — Configure 1:1 NAT for server1 ===

Browse to '''Firewall → NAT''', 1:1 tab. Click '''Add'''.

{| class="wikitable"
|+ 1:1 NAT for server1
|-
! Field !! Value
|-
| Interface || WAN
|-
| External || 192.0.2.4
|-
| Internal || 172.17.2.10
|-
| Description || server1
|}

Save and apply changes.

'''Important:''' Adding a 1:1 NAT entry only defines how traffic is translated. Without firewall rules, no traffic will pass in or out.

=== Step 6.3 — Configure 1:1 NAT for server2 ===

Click '''Add''' to add another 1:1 NAT entry.

{| class="wikitable"
|+ 1:1 NAT for server2
|-
! Field !! Value
|-
| Interface || WAN
|-
| External || 192.0.2.5
|-
| Internal || 172.17.2.20
|-
| Description || server2.example.com
|}

Save and apply changes.

== Exercise 7: Firewall Rules for 1:1 NAT ==

=== Step 7.1 — Allow Pings to Public Web Servers ===

Browse to '''Firewall → Rules''', WAN tab. Click '''Add'''.

{| class="wikitable"
|+ ICMP Rule for Web Servers
|-
! Field !! Value
|-
| Interface || WAN
|-
| Protocol || ICMP
|-
| ICMP Type || Echo request
|-
| Source || any
|-
| Destination || Single host or alias — WebServers alias
|-
| Description || allow pings to public web servers
|}

Save and apply changes.

Test by pinging <code>192.0.2.4</code> from your host machine:

<pre>
ping 192.0.2.4
</pre>

Leave the ping running and browse to '''Diagnostics → States'''. Filter for <code>192.0.2.100:</code> (if from host OS) and observe the states. Traffic sourced from <code>192.0.2.100</code> to <code>192.0.2.4</code> is translated to <code>172.17.2.10</code>.

=== Step 7.2 — Allow SSH to Web Servers from RemoteAdmins ===

{| class="wikitable"
|+ SSH Rule for RemoteAdmins
|-
! Field !! Value
|-
| Interface || WAN
|-
| Protocol || TCP
|-
| Source || Single host or alias — RemoteAdmins alias
|-
| Destination || Single host or alias — WebServers alias
|-
| Destination port || 22
|-
| Description || allow SSH to web servers from remote admin
|}

Save and apply changes.

From your host machine, test:

<pre>
ssh training@192.0.2.4
</pre>

=== Step 7.3 — Allow Web Access to Public Web Servers ===

{| class="wikitable"
|+ HTTP/HTTPS Rule for Web Servers
|-
! Field !! Value
|-
| Interface || WAN
|-
| Protocol || TCP
|-
| Source || any
|-
| Destination || Single host or alias — WebServers
|-
| Destination port || WebPorts alias
|-
| Description || allow web ports to public web servers
|}

Save and apply changes.

Now browse to <code>http://192.0.2.4</code> (server1) and <code>http://192.0.2.5</code> (server2).

== Exercise 8: Configuring Outbound NAT ==

Outbound NAT defines whether and how the source IP of matching traffic will be translated when it leaves an interface.

=== Step 8.1 — Switch to Manual Outbound NAT ===

Browse to '''Firewall → NAT''', Outbound tab. Select '''Manual Outbound NAT''', then click '''Save'''.

The system auto-populates the outbound NAT ruleset with the rules it was automatically generating previously. The configured manual rules take effect only upon applying changes.

=== Step 8.2 — Clean Up Auto-Generated Rules ===

The auto-generated rules include:

* LAN subnet, DMZ subnet, and loopback <code>127.0.0.0/8</code>
* IPv6 rules
* Static port for UDP port 500 (for non-NAT-T IPsec VPN clients)

Clean up by:

* Deleting the <code>127.0.0.0/8</code> rule (unusual circumstance)
* Deleting IPv6 rules (not using IPv6)
* Deleting UDP port 500 rules (nearly unheard of today)
* Replacing LAN and DMZ subnets with the summarized <code>172.17.0.0/16</code>

Edit the '''LAN to WAN''' rule:

{| class="wikitable"
|+ Consolidated Outbound NAT Rule
|-
! Field !! Value
|-
| Interface || WAN
|-
| Source || 172.17.0.0/16
|-
| Destination || any
|-
| Translation || Interface address
|}

Delete all other outbound NAT rules. Your list should have one rule.

'''Important:''' 1:1 NAT entries take precedence over outbound NAT. server1 traffic goes out via <code>192.0.2.4</code> and server2 via <code>192.0.2.5</code> regardless of outbound NAT rules.

=== Step 8.3 — Send hq-client Out via Alternate IP ===

Click the top '''Add''' button to add the new rule at the top of the list.

{| class="wikitable"
|+ Outbound NAT for hq-client
|-
! Field !! Value
|-
| Interface || WAN
|-
| Source || 172.17.1.100/32
|-
| Destination || any
|-
| Translation || 192.0.2.6
|-
| Description || hq-client out via .6
|}

Ensure this rule is above the <code>172.17.0.0/16</code> rule, since the first match wins.

=== Step 8.4 — Static Port for VoIP PBX ===

NAT can break VoIP. If rewriting source ports breaks SIP/RTP, configure static port for the PBX.

Assume a PBX at <code>172.17.1.200</code>. Click the '''copy''' icon next to the hq-client outbound NAT rule, then change:

{| class="wikitable"
|+ Outbound NAT for VoIP PBX
|-
! Field !! Value
|-
| Source || 172.17.1.200/32
|-
| Destination || any
|-
| Translation || Address 192.0.2.6, Static port checked
|-
| Description || VoIP PBX static port
|}

Ensure this rule is above the <code>172.17.0.0/16</code> rule.

== Lab Summary ==

In this lab, you learned to:

* Configure IP Alias Virtual IPs on the WAN interface
* Create Port Forwards (same port, alternate port, restricted source, alternate external IP)
* Configure 1:1 NAT mappings
* Add firewall rules to permit traffic through 1:1 NAT
* Switch from Automatic to Manual Outbound NAT
* Configure alternate outbound IPs and static port for VoIP

== Next Module ==

Proceed to the next training module. Return to the '''[[Training:_NAT_and_Virtual_IPs|NAT and Virtual IPs — Lecture Slides]]''' for review.

----

''Source: Netgate FUND001-LIVE-SLIDE-SEG3-NATVIP.pdf / FUND001-LIVE-Lab3-NATandVIPs.pdf''

Training: NAT and Virtual IPs

2026-04-23T06:58:55Z

Justinaquino: Created from Netgate pfSense training PDF

__NOTOC__

<div style="background-color: #e7f3ff; border-left: 6px solid #2196F3; padding: 16px; margin-bottom: 20px;">
<strong>Module Overview:</strong> This module covers Network Address Translation (NAT) and Virtual IPs (VIPs) in pfSense Plus. You will learn the different types of NAT, how NAT interacts with firewall rules, and best practices for configuring translation in production networks.
</div>

== Learning Objectives ==

By the end of this module, you will be able to:

* Explain what NAT is and how it modifies IP packet headers
* Identify common uses for NAT (Internet access, conflicting networks, routing issues)
* Distinguish between NAT rules and firewall rules
* Describe Port Forwards, 1:1 NAT, and Outbound NAT
* Understand NAT Reflection and why it should be avoided
* Troubleshoot common NAT problems

== What is NAT? ==

'''Network Address Translation (NAT)''' is the modification of IP packet headers. It involves the replacement of:

* Source and/or destination IP addresses
* Source and/or destination ports for TCP and UDP

=== Common Uses of NAT ===

* Internet access for private networks
* Connection of conflicting networks (overlapping IP ranges)
* Working around routing issues

== NAT and Firewall Rules ==

NAT rules are '''not''' firewall rules. NAT rules only define translation. You still need firewall rules to allow traffic to pass.

=== Key Points ===

* NAT rules and firewall rules are matched in a top-down fashion
* '''LAN rules''' are evaluated '''pre-NAT''' (using private source IPs)
* '''WAN rules''' are evaluated '''post-NAT''' (using private destination IPs)
* Port forwards — pfSense Plus can automatically add corresponding firewall rules

== Types of NAT ==

=== Port Forwards ===

Port forwards provide traffic redirection. Common use cases include:

* Traditional port forward (e.g., external port to internal server)
* Transparent HTTP proxy
* Redirection of SMTP, DNS

=== 1:1 NAT ===

1:1 NAT is a mapping of one internal IP to one external IP. Key characteristics:

* Can also map one internal network to one external network
* Configured on a per-interface basis
* Can optionally be limited to specific destinations

{| class="wikitable"
|+ 1:1 NAT Example
|-
! Type !! External IP !! Internal IP
|-
| Host || 200.100.1.12 || 192.168.1.99
|}

=== Outbound NAT ===

Outbound NAT controls how traffic leaving the firewall is translated.

* '''Automatic outbound''' — Default behavior; pfSense Plus automatically creates rules
* '''Manual outbound''' — Administrator defines all rules explicitly
* '''Hybrid mode''' — Combines automatic and manual rules

Outbound NAT rule options include:

* '''Static port''' — Preserve the original source port
* '''Pool options''' — Distribute translation across multiple IPs

== NAT Reflection ==

NAT Reflection allows accessing services via their public IP from inside the network.

'''Best Practice:''' NAT Reflection should be avoided whenever possible because it:

* Adds unnecessary overhead
* Loses the original source IP information

'''Alternative:''' Use Split DNS (internal DNS server resolving to private IPs) instead.

== Troubleshooting NAT ==

Remember these key troubleshooting steps:

* '''First match wins''' — Rules are evaluated top-down
* Ensure the correct interface is selected
* Review firewall states (Diagnostics → States)
* Verify Virtual IP configuration if applicable
* Use Packet Capture for detailed inspection
* See the troubleshooting section in the NAT chapter of the pfSense book

== Summary ==

* NAT rules are '''not''' firewall rules
* Both are still matched in a top-down fashion
* You still need firewall rules to allow traffic to pass
* NAT Reflection is suboptimal — use an internal DNS server instead
* 1:1 NAT can be host-to-host or network-to-network
* NAT is interface-specific

== Next Module ==

Continue to '''[[Training_Lab_3:_NAT_and_Virtual_IPs|Lab 3: NAT and Virtual IPs]]''' for hands-on exercises configuring Virtual IPs, Port Forwards, 1:1 NAT, and Outbound NAT.

----

''Source: Netgate FUND001-LIVE-SLIDE-SEG3-NATVIP.pdf / FUND001-LIVE-Lab3-NATandVIPs.pdf''

Training Lab 2: Firewall Rules and Aliases

2026-04-23T06:58:28Z

Justinaquino: Created page with "__NOTOC__ <div style="background-color:#fff3e6; border:1px solid #cc6600; padding:10px; margin-bottom:15px;"> '''Lab 2: Interfaces, Firewall Rules, and Aliases'''<br> This hands-on lab covers configuring the HQ DMZ interface, building firewall rules, creating aliases, and applying restrictive access policies. All configuration is performed on '''fw1-HQ''' at <code>https://172.17.1.1</code>. </div> == Prerequisites == * Lab topology from Training_Lab_1:_Initial_Confi..."

__NOTOC__

<div style="background-color:#fff3e6; border:1px solid #cc6600; padding:10px; margin-bottom:15px;">
'''Lab 2: Interfaces, Firewall Rules, and Aliases'''<br>
This hands-on lab covers configuring the HQ DMZ interface, building firewall rules, creating aliases, and applying restrictive access policies. All configuration is performed on '''fw1-HQ''' at <code>https://172.17.1.1</code>.
</div>

== Prerequisites ==

* Lab topology from [[Training_Lab_1:_Initial_Configuration|Training Lab 1]] is in place
* '''HQ LAN:''' <code>172.17.1.0/24</code>
* '''HQ DMZ:''' <code>172.17.2.0/24</code>
* Access to fw1-HQ web interface and VPN connection

== Lab Overview ==

This lab starts with configuring the DMZ interface at HQ, going through the steps to assign and configure a new interface. This new interface will be used as an example of configuring an additional internal interface treated as a DMZ, with significant restrictions to the other internal networks.

Then we'll go through use cases and examples for firewall rules and aliases. Some firewall rules come in the context of NAT, which is covered in a later lab.

== Exercise 1: Configure the DMZ Interface ==

=== Step 1: Review Interface Assignments ===

Browse to '''Interfaces > Assign'''.

The firewall's interfaces are assigned in order, from <code>vtnet0</code> to <code>vtnet4</code>. Our DMZ interface will be '''OPT1''', which is assigned to <code>vtnet2</code>.

=== Step 2: Enable and Configure OPT1 ===

Browse to '''Interfaces > OPT1''' and configure:

{| class="wikitable"
! Setting
! Value
|-
| Enable
| ✓ Checked
|-
| Description
| DMZ
|-
| IPv4 Configuration Type
| Static IPv4
|-
| IPv4 Address
| 172.17.2.1/24
|}

'''Save and Apply Changes.'''

After saving, OPT1 is still the underlying identifier in <code>config.xml</code>, but the interface is displayed as '''DMZ'''.

== Exercise 2: Test Connectivity to DMZ ==

=== Ping the DMZ Gateway ===

From the HQ-Client VM:

<pre>
training@hq-client:~$ ping 172.17.2.1
PING 172.17.2.1 (172.17.2.1) 56(84) bytes of data.
64 bytes from 172.17.2.1: icmp_seq=1 ttl=64 time=0.298 ms
64 bytes from 172.17.2.1: icmp_seq=2 ttl=64 time=0.979 ms
64 bytes from 172.17.2.1: icmp_seq=3 ttl=64 time=1.27 ms
</pre>

=== Ping server1 from HQ-Client ===

<pre>
training@hq-client:~$ ping -c 5 172.17.2.10
PING 172.17.2.10 (172.17.2.10) 56(84) bytes of data.
64 bytes from 172.17.2.10: icmp_seq=1 ttl=63 time=0.711 ms
64 bytes from 172.17.2.10: icmp_seq=2 ttl=63 time=1.75 ms
...
5 packets transmitted, 5 received, 0% packet loss
</pre>

This ping traverses two virtual networks, so latency is roughly doubled. Steady replies indicate good connectivity.

== Exercise 3: Connectivity from DMZ Network ==

=== Verify Default Block Behavior ===

Newly-added interfaces have '''no firewall rules by default'''. All traffic initiated on that interface is blocked.

Log in to server1 via SSH from HQ-client:

<pre>
training@hq-client:~$ ssh training@172.17.2.10
Password for training@server1: password
</pre>

From server1, attempt to ping:

<pre>
training@server1:~ % ping -c 5 172.17.2.1
PING 172.17.2.1 (172.17.2.1): 56 data bytes
--- 172.17.2.1 ping statistics ---
5 packets transmitted, 0 packets received, 100.0% packet loss

training@server1:~ % ping google.com
ping: cannot resolve google.com: Host name lookup failure
</pre>

=== Troubleshooting: Check ARP Cache ===

Check the ARP cache to confirm Layer 2 connectivity:

<pre>
training@server1:~ % arp -an
? (172.17.2.10) at 08:00:27:ec:c0:6b on em0 permanent [ethernet]
? (172.17.2.1) at 08:00:27:59:b4:35 on em0 expires in 139 seconds [ethernet]
</pre>

A valid MAC address for the gateway confirms the server is on the correct network segment. An '''incomplete''' entry indicates a Layer 2 issue.

=== Check Firewall Logs ===

Browse to '''Status > System Logs > Firewall''' on fw1-HQ to see blocked traffic.

=== Add Temporary Allow-All Rule ===

On '''Firewall > Rules > DMZ''', add a temporary rule:

{| class="wikitable"
! Setting
! Value
|-
| Action
| Pass
|-
| Interface
| DMZ
|-
| Protocol
| any
|-
| Source
| any
|-
| Destination
| any
|}

'''Save and Apply Changes.'''

Verify connectivity from server1:

<pre>
training@server1:~ % ping -c 3 172.17.2.1
training@server1:~ % ping -c 3 google.com
training@server1:~ % ping -c 3 172.17.1.100
</pre>

All three should succeed with the allow-all rule in place.

== Exercise 4: Create Aliases ==

Aliases ease management by grouping IPs, networks, or ports.

Browse to '''Firewall > Aliases'''.

=== Alias: PrivateNetworks ===

{| class="wikitable"
! Field
! Value
|-
| Name
| PrivateNetworks
|-
| Description
| All RFC1918 private IP space
|-
| Type
| Network
|-
| Members
| 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
|}

=== Alias: server1 ===

{| class="wikitable"
! Field
! Value
|-
| Name
| server1
|-
| Description
| server1.example.com
|-
| Type
| Host
|-
| Member
| 172.17.2.10
|}

=== Alias: server2 ===

{| class="wikitable"
! Field
! Value
|-
| Name
| server2
|-
| Description
| server2.example.com
|-
| Type
| Host
|-
| Member
| 172.17.2.20
|}

=== Alias: DNSservers ===

{| class="wikitable"
! Field
! Value
|-
| Name
| DNSservers
|-
| Type
| Host
|-
| Members
| server1, server2
|}

=== Alias: SMTPservers ===

{| class="wikitable"
! Field
! Value
|-
| Name
| SMTPservers
|-
| Description
| authorized outbound SMTP servers
|-
| Type
| Host
|-
| Members
| server1
|}

=== Alias: RemoteAdmin ===

{| class="wikitable"
! Field
! Value
|-
| Name
| RemoteAdmin
|-
| Description
| IPs authorized for remote management
|-
| Type
| Host
|-
| Members
| 192.0.2.100 (student's system)
|}

=== Alias: WebServers ===

{| class="wikitable"
! Field
! Value
|-
| Name
| WebServers
|-
| Description
| publicly-reachable web servers
|-
| Type
| Host
|-
| Members
| server1, server2
|}

=== Alias: WebPorts ===

{| class="wikitable"
! Field
! Value
|-
| Name
| WebPorts
|-
| Description
| allowed ports to public web servers
|-
| Type
| Ports
|-
| Members
| 80, 443
|}

'''Save each alias, then Apply Changes.'''

== Exercise 5: Allow Remote Firewall Administration ==

Add a rule on '''Firewall > Rules > WAN''':

{| class="wikitable"
! Setting
! Value
|-
| Interface
| WAN
|-
| Protocol
| any
|-
| Source
| Single host or alias — RemoteAdmin
|-
| Destination
| WAN address
|-
| Description
| allow all from remote admin IPs
|}

'''Save and Apply Changes.'''

Verify from your host:

<pre>
$ ping 192.0.2.2
$ curl -I https://192.0.2.2
</pre>

== Exercise 6: Configure Restrictive DMZ Rules ==

Remove the temporary allow-all rule (or ensure it is at the top, to be deleted later). Then add the following rules in order using the '''Add''' button (add to bottom):

=== Rule 1: Allow Ping to Firewall DMZ IP ===

{| class="wikitable"
! Setting
! Value
|-
| Action
| Pass
|-
| Interface
| DMZ
|-
| Protocol
| ICMP
|-
| ICMP Type
| Echo request
|-
| Source
| DMZ net
|-
| Destination
| DMZ address
|-
| Description
| Allow ping to firewall's DMZ IP
|}

=== Rule 2: Allow DNS to DMZ IP ===

{| class="wikitable"
! Setting
! Value
|-
| Action
| Pass
|-
| Interface
| DMZ
|-
| Protocol
| TCP/UDP
|-
| Source
| DMZ net
|-
| Destination
| DMZ address
|-
| Destination Port
| DNS (53)
|-
| Description
| Allow DNS lookups to DNS Resolver
|}

=== Rule 3: Reject All Else to Private Networks ===

{| class="wikitable"
! Setting
! Value
|-
| Action
| Reject
|-
| Interface
| DMZ
|-
| Protocol
| any
|-
| Source
| any
|-
| Destination
| Single host or alias — PrivateNetworks
|-
| Log
| ✓ Checked
|-
| Description
| Reject all else from DMZ to private networks
|}

This prevents DMZ hosts from reaching any other internal services and logs blocked attempts.

=== Rule 4: Allow DNS Outbound to Internet ===

{| class="wikitable"
! Setting
! Value
|-
| Action
| Pass
|-
| Interface
| DMZ
|-
| Protocol
| TCP/UDP
|-
| Source
| Single host or alias — DNSservers
|-
| Destination
| any
|-
| Destination Port
| DNS (53)
|-
| Description
| Allow recursive queries from DNS servers to Internet
|}

=== Rule 5: Allow SMTP Outbound to Internet ===

{| class="wikitable"
! Setting
! Value
|-
| Action
| Pass
|-
| Interface
| DMZ
|-
| Protocol
| TCP
|-
| Source
| Single host or alias — SMTPservers
|-
| Destination
| any
|-
| Destination Port
| SMTP (25)
|-
| Description
| Allow SMTP servers to send to Internet
|}

=== Rule 6: Allow HTTP Outbound for Management (Disabled) ===

{| class="wikitable"
! Setting
! Value
|-
| Action
| Pass
|-
| Disabled
| ✓ Checked
|-
| Interface
| DMZ
|-
| Protocol
| TCP
|-
| Source
| DMZ net
|-
| Destination
| any
|-
| Destination Port
| HTTP (80)
|-
| Description
| Management — temp allow HTTP outbound from servers
|}

This rule is disabled by default and should only be enabled during updates.

'''Save and Apply Changes after each rule.'''

== Exercise 7: Verify Restrictive Ruleset ==

=== Review Rule Order ===

Ensure the temporary allow-all rule is at the top. With it at the top, all traffic matches it first and the restrictive rules are ineffective.

From server1, start a constant ping to HQ-client:

<pre>
training@server1:~ % ping 172.17.1.100
</pre>

Replies confirm the allow-all rule is passing traffic.

=== Delete Allow-All Rule ===

Delete the temporary allow-all rule and '''Apply Changes'''.

The restrictive ruleset is now enforced for all '''new''' connections. The running ping is still permitted because the firewall is stateful — already-permitted connections are never re-evaluated.

=== Kill the Ping State ===

Browse to '''Diagnostics > States'''. Filter for <code>172.17.2.10:</code> (note the colon to avoid matching similar IPs). Click the '''✕''' symbol next to the ping state to delete it.

The ping stops immediately.

=== Check Firewall Logs ===

Browse to '''Status > System Logs > Firewall'''. Log entries show the blocked traffic.

Click the red '''X''' in the Action column on a log entry to see which rule blocked the connection. User-defined rules show <code>USER_RULE</code> with the configured description.

== Troubleshooting Reference ==

{| class="wikitable"
! Symptom
! Likely Cause
! Resolution
|-
| Cannot ping gateway from DMZ host
| No firewall rules on DMZ interface
| Add pass rule or verify existing rules
|-
| Cannot resolve DNS from DMZ
| DNS port blocked; no DNS rule
| Add TCP/UDP pass rule to DMZ address port 53
|-
| Can reach Internet but not HQ LAN
| Reject rule to PrivateNetworks is working
| Verify rule order and alias contents
|-
| Ping stops after deleting allow-all rule
| Stateful firewall; existing state was killed
| Expected behavior — new connections follow current rules
|-
| Cannot SSH to server1
| Layer 2 / ARP issue or VPN problem
| Check <code>arp -an</code> on server1; verify MAC address
|-
| Firewall web UI unreachable from WAN
| No WAN allow rule for remote admin
| Add WAN rule with RemoteAdmin alias as source
|}

== IP Addressing Quick Reference ==

{| class="wikitable"
! Host / Network
! IP Address / Range
|-
| fw1-HQ LAN
| 172.17.1.1/24
|-
| fw1-HQ DMZ
| 172.17.2.1/24
|-
| fw1-HQ WAN
| 192.0.2.2
|-
| HQ-Client
| 172.17.1.100
|-
| server1
| 172.17.2.10
|-
| server2
| 172.17.2.20
|-
| RemoteAdmin
| 192.0.2.100
|-
| HQ LAN Network
| 172.17.1.0/24
|-
| HQ DMZ Network
| 172.17.2.0/24
|}

== Lab Completion Checklist ==

* [ ] DMZ interface enabled and configured (172.17.2.1/24)
* [ ] Connectivity tested from HQ-Client to DMZ
* [ ] Default block behavior verified from DMZ
* [ ] Aliases created (PrivateNetworks, DNSservers, SMTPservers, RemoteAdmin, WebServers, WebPorts, server1, server2)
* [ ] Remote admin rule added on WAN
* [ ] Restrictive DMZ rules configured and applied
* [ ] Stateful behavior demonstrated (ping continues after rule change, stops after state kill)
* [ ] Firewall logs reviewed and interpreted

This concludes Lab 2.

----

'''Previous Module:''' [[Training:_Interfaces_and_Firewall_Rules|Section 2 — Interfaces and Firewall Rules]]

''Source: Netgate FUND001-LIVE-Lab2-Rules.pdf''

Training: Interfaces and Firewall Rules

2026-04-23T06:58:28Z

Justinaquino: Created page with "__NOTOC__ <div style="background-color:#e6f3ff; border:1px solid #0066cc; padding:10px; margin-bottom:15px;"> '''Module: FUND001-LIVE Section 2 — Interfaces, VIPs, and Firewall Rules'''<br> This training module covers pfSense interface configuration, Virtual IP types, firewall rules, aliases, and best practices for rule management. </div> == Learning Objectives == By the end of this module, you will be able to: * Understand OS interface names versus pfSense interfa..."

__NOTOC__

<div style="background-color:#e6f3ff; border:1px solid #0066cc; padding:10px; margin-bottom:15px;">
'''Module: FUND001-LIVE Section 2 — Interfaces, VIPs, and Firewall Rules'''<br>
This training module covers pfSense interface configuration, Virtual IP types, firewall rules, aliases, and best practices for rule management.
</div>

== Learning Objectives ==

By the end of this module, you will be able to:

* Understand OS interface names versus pfSense interface identifiers
* Configure and manage interfaces in pfSense
* Identify and apply appropriate Virtual IP (VIP) types
* Create and manage firewall rules with proper ordering
* Use aliases to simplify and streamline rulesets
* Apply firewall best practices and troubleshooting techniques

== Interfaces ==

=== OS Interface Names vs. Interface Identifiers ===

In pfSense, network interfaces have two naming conventions:

* '''OS Interface Names''' — Physical or virtual NIC names assigned by the operating system (e.g., <code>igb0</code>, <code>re1</code>, <code>ixl2</code>)
* '''Interface Identifiers''' — User-friendly labels assigned within pfSense (e.g., <code>LAN</code>, <code>WAN</code>, <code>OPT1</code>)

Key tasks:
* Interface Assignments — mapping OS names to pfSense identifiers
* Configuring Interfaces — setting IP addresses, enabling/disabling, and renaming

== Virtual IPs (VIPs) ==

Virtual IPs allow multiple IP addresses to be assigned to a single interface.

=== VIP Types ===

{| class="wikitable"
! VIP Type
! MAC Address Binding
! NAT Service
! ARP
! HA
! Ping
! Single/Range
|-
| IP Alias
| Parent NIC
| Yes
| Yes
| Yes
| Yes
| Single
|-
| CARP
| Shared vMAC
| Yes
| Yes
| Yes
| Yes
| Single
|-
| Proxy ARP
| Parent NIC
| Yes
| No
| No
| No
| Either
|-
| Other
| N/A
| No
| No
| Yes
| No
| Either
|}

* '''IP Alias''' — Most common type; binds additional IPs to the parent NIC
* '''CARP''' — Used for high availability; shares a virtual MAC address between redundant firewalls
* '''Proxy ARP''' — Responds to ARP requests on behalf of another IP; no service binding
* '''Other''' — For miscellaneous purposes such as 1:1 NAT without ARP

== Firewall Rules ==

=== Core Concepts ===

* Rules apply '''inbound''' on the interface where traffic is sourced
* '''First match wins''' — all subsequent rules are ignored for matching traffic
* '''Stateful filtering''' — pfSense tracks connection states automatically
* Actions: '''Pass''', '''Block''', and '''Reject'''

=== Default Rules ===

The following default rules are present on a new installation:

* '''Block private networks''' — Blocks RFC 1918 traffic on WAN
* '''Block bogon networks''' — Blocks unassigned/reserved IP space
* '''Anti-lockout rule''' — Prevents administrators from locking themselves out
* '''Default LAN Allow rule''' — Permits all outbound traffic from LAN

=== Rule Evaluation Order ===

# Floating Rules
# Interface Group Rules
# Single Interface Rules

=== Floating Rules ===

* Can apply to '''all interfaces'''
* Checked '''first''' in evaluation order
* Extra '''"match"''' action available
* Can set traffic attributes (limiters, queues, etc.)
* '''Not meant for regular access rules''' — primarily for traffic-shaping and advanced filtering

=== Interface Groups ===

* Association of multiple interfaces
* '''Shared firewall ruleset''' across grouped interfaces
* Eliminates need to duplicate rules between interfaces

=== Advanced Settings ===

Firewall rules support numerous advanced options:

* Source OS (TCP only)
* Diffserv Code Point (DSCP)
* State type
* TCP flags
* No XMLRPC Sync
* 802.1p
* Schedule
* Gateway
* Limiters (In/Out)
* ACK queue / Queue

== Aliases ==

Aliases simplify firewall rule management by grouping IPs, networks, hostnames, or ports under a single name.

=== Benefits ===

* Ease management
* Faster, less error-prone updates
* Shorter, more manageable rulesets

=== Configuration Options ===

* Statically configured
* URL — one-time import, suitable for small lists
* URL table — configurable update frequency, supports large and small lists
* Nesting of aliases (aliases within aliases)
* Bulk import

== Best Practices ==

* Follow '''default deny philosophy''' — allow only what is required, block all else
* Keep rulesets '''short and clean'''
* '''Periodic review''' of rules (recommended: quarterly)
* Remember rules apply on the '''interface where traffic is sourced'''
* Use '''aliases''' extensively in your rules

== Troubleshooting ==

When diagnosing firewall issues:

* Remember: '''first match wins'''
* Verify rules apply on the correct interface
* '''Enable logging''' on suspect rules
* Check '''states''' (Diagnostics > States)
* Review '''System Logs > Firewall''' for blocked traffic

== Summary ==

{| class="wikitable"
! Key Takeaway
! Details
|-
| VIP Selection
| Use appropriate VIP types (IP Alias, CARP, Proxy ARP) based on needs
|-
| Rule Ordering
| Evaluation order: Floating → Interface Group → Single Interface
|-
| Aliases
| Use aliases to keep rulesets manageable and reduce errors
|-
| Review Schedule
| Check rules quarterly for accuracy and relevance
|-
| Interface Awareness
| Rules apply on the interface where traffic is sourced
|-
| Floating Rules
| Primarily for traffic-shaping, not regular access control
|}

This concludes Section 2.

----

'''Next Module:''' [[Training_Lab_2:_Firewall_Rules_and_Aliases|Lab 2 — Firewall Rules and Aliases]]

''Source: Netgate FUND001-LIVE-SLIDE-SEG2-RULES.pdf''

Training Lab 1: Introduction and Backup Restore

2026-04-23T06:52:40Z

Justinaquino: Convert FUND001 Lab1 to wiki training lab

__NOTOC__
<div style="background:#e8f5e9; border:1px solid #a5d6a7; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
'''Hands-On Lab: Phase 1, Day 2''' — Lab Environment Introduction, Initial Configuration, Backup and Restore. Based on Netgate FUND001-LIVE-Lab1-Intro.
</div>

== Learning Objectives ==
By the end of this lab, you will be able to:
* Navigate the virtual lab environment and understand its topology
* Complete the pfSense setup wizard
* Verify basic connectivity through the firewall
* Create manual configuration backups
* Enable and configure AutoConfigBackup
* Restore a previous configuration from web interface and console

== Lab Environment Overview ==
This lab uses a simulated corporate network with headquarters (HQ) and one branch office.

'''Network Topology:'''
* '''4 firewalls''' — fw1-HQ, fw2-HQ (HA pair), fw1-branch, lab-internet-router
* '''2 desktops''' — HQ-client, Branch-client
* '''2 servers''' — server1, server2 (DMZ)
* '''1 simulated Internet host''' — RemoteHost
* '''8 total networks''' — WAN, LAN, DMZ, sync, remote access, branch LAN, etc.

'''Lab access:'''
In the Netgate original lab, desktops are accessed via NoVNC at http://100.64.0.100/remote. In Comfac's virtual lab, you will access your student sandbox through the NoVNC portal.

== IP Addressing Scheme ==
'''Public/"Internet" IPs (RFC 5737 documentation ranges):'''
{| class="wikitable"
! Subnet !! Assignment
|-
| 192.0.2.0/24 || HQ WAN
|-
| 198.51.100.0/24 || HQ WAN2
|-
| 203.0.113.0/24 || Branch WAN
|-
| 100.64.0.0/24 || Remote Internet (CGNAT range)
|}

'''Private Internal IPs (RFC 1918):'''
{| class="wikitable"
! Subnet !! Assignment
|-
| 172.17.1.0/24 || HQ LAN
|-
| 172.17.2.0/24 || HQ DMZ
|-
| 172.17.3.0/24 || HQ Sync (HA)
|-
| 172.17.4.0/24 || HQ Remote Access OpenVPN
|-
| 172.17.5.0/24 || HQ Remote Access IPsec
|-
| 172.17.6.0/24 || OpenVPN Site-to-Site tunnel
|-
| 172.18.1.0/24 || Branch LAN
|}

'''Why use obscure subnets?''' Using 172.17.x.x instead of common 192.168.1.x minimizes VPN conflicts when remote users connect from home networks.

== Firewall VM Details ==
'''Default credentials for all firewalls:'''
* Username: '''admin'''
* Password: '''netgate'''

=== fw1-HQ (Primary HQ Firewall) ===
{| class="wikitable"
! Interface !! Assignment !! Initial IP !! HA IP (later)
|-
| vtnet0 || WAN || 192.0.2.2 || no change
|-
| vtnet1 || LAN || 172.17.1.1 || 172.17.1.2
|-
| vtnet2 || DMZ || 172.17.2.1 || 172.17.2.2
|-
| vtnet3 || WAN2 || 198.51.100.2 || no change
|-
| vtnet4 || Sync || 172.17.3.2 || no change
|}

=== fw2-HQ (Secondary HQ Firewall) ===
Initially inactive; configured in Advanced/HA lab later.
* WAN: 192.0.2.3
* LAN: 172.17.1.3
* DMZ: 172.17.2.3
* WAN2: 198.51.100.3
* Sync: 172.17.3.3

=== fw1-branch (Branch Office Firewall) ===
* WAN: 203.0.113.10
* LAN: 172.18.1.1

=== lab-internet-router (Simulated ISP) ===
Represents 4 ISP routers + Internet. Pre-configured; no lab changes needed.
* HQ-WAN1: 192.0.2.1
* HQ-WAN2: 198.51.100.1
* Branch-WAN: 203.0.113.1
* Remote Internet: 100.64.0.1

== Client & Server VMs ==
'''HQ-client (Xubuntu Linux desktop):'''
* IP: 172.17.1.100
* Credentials: training / password
* Purpose: Primary management workstation

'''Branch-client (Xubuntu Linux desktop):'''
* IP: 172.18.1.100
* Credentials: training / password

'''Internet host / RemoteHost (Xubuntu):'''
* IP: 100.64.0.50
* Credentials: training / password
* Purpose: Simulated external client + web server for testing

'''server1 & server2 (FreeBSD):'''
* server1: 172.17.2.10
* server2: 172.17.2.20
* Credentials: training / password (root: password)
* Pre-configured with nginx/PHP and BIND DNS

== Exercise 1: Initial Setup Wizard ==
'''Prerequisites:''' Your student environment should have fw1-HQ and HQ-client running.

'''Steps:'''
# From HQ-client, open browser and navigate to https://172.17.1.1
# Accept the self-signed certificate warning
# Log in with admin / netgate
# The setup wizard will launch automatically

'''Wizard configuration:'''
# '''General Information''' — Leave defaults (hostname: fw1-hq.example.com, DNS: lab-internet-router)
# '''Time Information''' — Leave NTP server as 0.pfsense.pool.ntp.org; set timezone as needed (e.g., Asia/Manila)
# '''WAN Configuration''' — Verify static IP: 192.0.2.2/24, gateway 192.0.2.1
#* '''Important:''' Leave "Block bogon networks" and "Block private networks" unchecked (these are documentation IPs, not real public IPs)
# '''LAN Configuration''' — Verify 172.17.1.1/24
# '''Admin Password''' — Change to a secure password (or leave default for lab)
# '''Reload''' — Click Reload to apply settings

'''Verification:'''
* HQ-client should be able to browse the real Internet through NAT
* Try browsing to any external website to confirm

== Exercise 2: Manual Configuration Backup ==
# Browse to Diagnostics -> Backup & Restore
# Click Download configuration as XML
# Save the config.xml file to HQ-client
# '''What this contains:''' Entire system configuration — interfaces, rules, NAT, users, certificates, etc.

== Exercise 3: Config History ==
# Stay on Diagnostics -> Backup & Restore
# Click the Config History tab
# You should see at least one revision (from the setup wizard)
# Click the diff icon to compare two revisions
# This shows exactly what changed between configurations

== Exercise 4: AutoConfigBackup (ACB) ==
AutoConfigBackup is Netgate's encrypted cloud backup service. Every configuration change is automatically backed up offsite.

'''Preparation (lab-specific step):'''
# Go to Diagnostics -> Command Prompt
# Run: rm /etc/ssh/ssh_host_* && /etc/rc.restart_sshd
# This regenerates SSH keys for ACB compatibility in the lab environment
#* ''Note: Not needed in production environments''

'''Enable ACB:'''
# Go to Services -> AutoConfigBackup
# Check Enable ACB
# Enter an encryption password (remember this!)
# Optional: Add a plain-text identifier to help Netgate support locate your backups
# Click Save

'''Verify backup:'''
# Click the Backup Now tab -> Backup
# Go to Restore tab — your backup should appear in the list
# Note your Device ID — save it securely with your encryption password

'''Important:''' If you lose the encryption password, backups are unrecoverable. If you lose the Device ID, Netgate support can help locate it using your identifier.

== Exercise 5: Configuration Restore ==
'''Scenario:''' You misconfigured something and need to roll back.

'''Method A — Web Interface (if you can still reach it):'''
# Diagnostics -> Backup & Restore -> Config History
# Find the revision before your mistake
# Click Restore

'''Method B — AutoConfigBackup (longer history):'''
# Services -> AutoConfigBackup -> Restore tab
# Select a previous backup
# Click Restore

'''Method C — Console (emergency, no web access):'''
# Access console via SSH or physical access
# Choose option 15: "Restore recent configuration"
# Choose option 1 to view recent configs
# Choose option 2 to restore a specific revision
# Enter the revision number
# Confirm with Y
# Reboot (option 5) to ensure clean application

== Troubleshooting ==
{| class="wikitable"
! Problem !! Solution
|-
| Can't reach https://172.17.1.1 || Check HQ-client IP (should be DHCP 172.17.1.x); verify cable/VLAN
|-
| Wizard doesn't start || Already completed; go to System -> Setup Wizard to re-run
|-
| No Internet from HQ-client || Verify WAN IP/gateway; check lab-internet-router is running
|-
| ACB won't enable || Run SSH key regeneration command first
|-
| Restore fails || Ensure restoring to equal or newer version; check encryption password
|}

== Verification Checklist ==
Before finishing this lab, confirm:
* [ ] Setup wizard completed successfully
* [ ] HQ-client can browse Internet
* [ ] Manual config backup downloaded
* [ ] Config History shows revisions
* [ ] AutoConfigBackup enabled and backup completed
* [ ] Device ID recorded
* [ ] Successfully restored a previous configuration (optional practice)

== Key Takeaways ==
* The lab simulates a real multi-site corporate network
* Using RFC 5737 documentation IPs prevents accidentally affecting real networks
* Always backup before making changes
* AutoConfigBackup provides 100 revisions of encrypted offsite backups
* Console restore (option 15) is your emergency recovery method

== Next Module ==
* [[Training: Interfaces and Firewall Rules]] — Phase 1, Day 3
* [[Training Lab 2: Firewall Rules and Aliases]] — Hands-on lab

----
''Source: Netgate FUND001-LIVE-Lab1-Intro.pdf''
''Comfac Virtual Lab Adaptation: VMs provisioned via Ansible; NoVNC access through student portal''

Training: pfSense Introduction

2026-04-23T06:50:06Z

Justinaquino: Convert FUND001 SEG1 Introduction slides to wiki training module

__NOTOC__
<div style="background:#e3f2fd; border:1px solid #90caf9; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
'''Training Module: Phase 1, Day 1''' — Introduction to pfSense Plus. Based on Netgate FUND001-LIVE-SLIDE-SEG1.
</div>

== Learning Objectives ==
By the end of this module, you will be able to:
* Explain what pfSense Plus is and its core value proposition
* Describe the project history and difference between pfSense CE and pfSense Plus
* Identify supported platforms and hardware requirements
* Perform initial setup using the web-based setup wizard
* Create and restore configuration backups
* Understand upgrade procedures and risks

== What is pfSense Plus? ==
pfSense Plus is a commercial, FreeBSD-based network firewall and routing platform developed by Netgate. It ties together multiple open-source networking components into a unified, entirely web-managed system.

'''Key Characteristics:'''
* '''FreeBSD-based''' — Uses the same trusted OS platform as Juniper, NetApp, Citrix, and Netflix
* '''Web-managed''' — Complete configuration through a browser-based GUI; no CLI required for day-to-day tasks
* '''Feature-rich''' — Richer feature set than most commercial firewalls at a fraction of the cost
* '''Open source core''' — Built on open-source components (pf, OpenVPN, WireGuard, etc.) made easy to use

== Project History ==
{| class="wikitable"
! Year !! Milestone
|-
| 2004 || Project started as a fork of m0n0wall
|-
| Feb 2008 || pfSense 1.2 released (FreeBSD 6.2)
|-
| Sept 2011 || pfSense 2.0 released (FreeBSD 8.1)
|-
| Oct 2017 || pfSense 2.4 released (FreeBSD 11.1)
|-
| Feb 2021 || '''pfSense Plus 21.02''' forks from pfSense CE; commercial-only; adds WireGuard
|}

'''pfSense Plus vs pfSense CE:'''
* '''pfSense Plus''' — Commercial license; available on Netgate hardware or Home+Lab (non-commercial); receives updates first
* '''pfSense CE''' — Community Edition; open source; free for all uses

== Platforms & Hardware ==
'''Installation Media:'''
* Full installer (CD or USB memstick)
* 64-bit only
* No Live CD or NanoBSD (deprecated)

'''Hardware Options:'''
# '''Netgate Official Hardware''' — Pre-installed, pre-configured, fully optimized
# '''DIY/Custom Build''' — Check compatibility list at [https://docs.netgate.com/pfsense/en/latest/hardware docs.netgate.com]
# '''Home+Lab Edition''' — Free for non-commercial use; available from [https://www.pfsense.org/downloads pfsense.org]

'''Key hardware considerations:'''
* CPU selection (AES-NI support recommended for VPN performance)
* NIC quality and driver support (Intel i210/i350 preferred)
* RAM (1 GB minimum; 2+ GB for packages/VPN)
* Storage (SSD recommended; 8 GB minimum)

== Initial Setup ==
'''Default LAN configuration:'''
* LAN IP: '''192.168.1.1/24'''
* DHCP server enabled on LAN
* Web interface: '''https://192.168.1.1'''
* Default credentials: '''admin / pfsense'''

'''Setup Wizard steps:'''
# Connect to LAN port; obtain DHCP address
# Browse to https://192.168.1.1
# Log in with default credentials
# Complete wizard: General Info → Time Server → WAN Config → LAN Config → Admin Password → Reload

'''Important:''' Always change the default admin password in production.

== Configuration Backup & Restore ==
'''Why back up?'''
* Hardware failure recovery
* Pre-upgrade safety net
* Configuration migration to new hardware
* Rollback after misconfiguration

'''Backup methods:'''
{| class="wikitable"
! Method !! Location !! Retention !! Notes
|-
| Manual download || Diagnostics → Backup/Restore || N/A (local file) || Full config.xml download
|-
| Config History || Diagnostics → Backup/Restore → Config History || 30 revisions (configurable) || Local to device
|-
| AutoConfigBackup (ACB) || Services → AutoConfigBackup || 100 revisions || Cloud backup; encrypted
|}

'''Backup best practices:'''
* Always backup '''before''' upgrades
* Store encryption password and Device ID safely (for ACB)
* Never restore to an '''older''' pfSense version; only equal or newer
* When restoring to different hardware, interface assignments will differ

'''Console restore (emergency):'''
* Option 15 at console menu — "Restore recent configuration"
* Useful when web interface is unreachable
* May require reboot after restore

== Upgrades ==
'''Pre-upgrade checklist:'''
# Create configuration backup
# Read release notes
# Check upgrade guide at [https://docs.netgate.com/pfsense/en/latest/install/upgrade-guide.html docs.netgate.com]
# Verify auto-upgrade URL (for Plus)

'''Upgrade methods:'''
* '''Auto-Update''' — Web GUI: System → Update
* '''Console Update''' — Option 13 at console menu

'''Upgrade risks (rare but possible):'''
* Hardware failure during reboot
* Package complications
* Hardware-specific regressions
* Dependency on bug fixes from current version

== Key Takeaways ==
* pfSense Plus is commercial-only; Home+Lab available for non-commercial use
* Always check hardware compatibility before DIY builds
* '''Backup before every upgrade''' — non-negotiable
* Restore only to equal or newer versions
* Use AutoConfigBackup for offsite, encrypted cloud backups
* Keep encryption password and Device ID in a safe place

== Quiz (Self-Check) ==
# What operating system is pfSense Plus based on?
# What is the difference between pfSense Plus and pfSense CE?
# Why should you avoid restoring a backup to an older pfSense version?
# Where do you find the Config History feature?
# What two pieces of information must you save when using AutoConfigBackup?

== Next Module ==
* [[Training: Interfaces and Firewall Rules]] — Phase 1, Day 2–3
* [[Training Lab 1: Introduction and Backup Restore]] — Hands-on lab

----
''Source: Netgate FUND001-LIVE-SLIDE-SEG1-INTRO.pdf''

Networking PfSense Index

2026-04-23T06:38:23Z

Justinaquino: Add link to PfSense Training Project Tracker

PfSense Training Project Tracker

2026-04-23T06:37:36Z

Justinaquino: Create project tracker for pfSense practical training system implementation

__NOTOC__
<div style="background:#fff8e1; border:1px solid #ffcc80; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
'''Project Tracker''' for Comfac's pfSense Practical Training System implementation. This page tracks all tasks from material conversion to infrastructure deployment and course delivery.
</div>

== Phase 0: Material Conversion (FUND001 → Wiki) ==
Convert all Netgate FUND001 training PDFs into CITWiki pages with detailed summaries. Each wiki page should include: learning objectives, key concepts, step-by-step lab instructions adapted for virtual environment, and troubleshooting tips.

=== Slide Decks ===
* [ ] '''SEG1 — Introduction to pfSense''' → [[Training: pfSense Introduction]]
* [ ] '''SEG2 — Interfaces, VIPs, and Rules''' → [[Training: Interfaces and Firewall Rules]]
* [ ] '''SEG3 — NAT and VIPs''' → [[Training: NAT and Virtual IPs]]
* [ ] '''SEG4 — pfSense Services''' → [[Training: pfSense Services]]
* [ ] '''SEG5 — VPNs and IPsec''' → [[Training: IPsec VPN]]
* [ ] '''SEG6 — OpenVPN''' → [[Training: OpenVPN]]
* [ ] '''SEG7 — WireGuard''' → [[Training: WireGuard]]
* [ ] '''SEG8 — Multi-WAN''' → [[Training: Multi-WAN]]
* [ ] '''SEG9 — Traffic Shaping''' → [[Training: Traffic Shaping]]
* [ ] '''SEG10 — High Availability''' → [[Training: High Availability]]
* [ ] '''SEG11 — Other Features''' → [[Training: Monitoring and Packages]]

=== Labs ===
* [ ] '''Lab 1 — Intro, Getting Started, Backup/Restore''' → [[Training Lab 1: Introduction and Backup Restore]]
* [ ] '''Lab 2 — Interfaces, Firewall Rules, Aliases''' → [[Training Lab 2: Firewall Rules and Aliases]]
* [ ] '''Lab 3 — Virtual IPs and NAT''' → [[Training Lab 3: NAT and Virtual IPs]]
* [ ] '''Lab 4 — Services and Branch Network Setup''' → [[Training Lab 4: Services and Branch Network]]
* [ ] '''Lab 5 — IPsec''' → [[Training Lab 5: IPsec VPN]]
* [ ] '''Lab 6 — OpenVPN''' → [[Training Lab 6: OpenVPN]]
* [ ] '''Lab 7 — WireGuard''' → [[Training Lab 7: WireGuard]]
* [ ] '''Lab 8 — Multi-WAN''' → [[Training Lab 8: Multi-WAN]]
* [ ] '''Lab 9 — Traffic Shaping''' → [[Training Lab 9: Traffic Shaping]]
* [ ] '''Lab 10 — High Availability''' → [[Training Lab 10: High Availability]]

=== Reference Materials ===
* [ ] '''the-pfsense-documentation.pdf''' → Summarize into [[Training: pfSense Complete Reference]] or link as external reference
* [ ] '''WindowsTrainingSupportFiles.zip''' → Extract and document client software requirements ([[Training: Client Software Requirements]])
* [ ] '''Training Videos (4× .mkv)''' → Catalog timestamps and link from relevant wiki pages

== Phase 1: Infrastructure Setup ==
Build the virtual training environment on Comfac's 200-core / 1TB RAM machine.

=== Host Preparation ===
* [ ] '''A.1''' Install Ubuntu Server LTS on 200-core host
* [ ] '''A.2''' Configure KVM/libvirt with storage pools (NVMe for images, SSD for ephemeral clones)
* [ ] '''A.3''' Set up network bridges: `br-mgmt`, `br-lan`, `br-wan`, `br-dmz`, `br-internet`
* [ ] '''A.4''' Configure VLANs for student isolation (one VLAN per student or per lab)
* [ ] '''A.5''' Install and configure Ansible controller (host or container)

=== Base Images ===
* [ ] '''B.1''' Download pfSense CE ISO and create qcow2 golden image (2 vCPU, 1 GB RAM, 8 GB disk)
* [ ] '''B.2''' Create Ubuntu Server 22.04/24.04 golden image (1 vCPU, 1 GB RAM, 10 GB disk)
* [ ] '''B.3''' Create Windows 10/11 thin client golden image (2 vCPU, 4 GB RAM, 40 GB disk) — OR decide to use Linux clients only
* [ ] '''B.4''' Create "Internet Router" golden image (Ubuntu with FRR/Quagga or simple static routes, 1 vCPU, 512 MB RAM)
* [ ] '''B.5''' Test each golden image boots and functions correctly

=== Automation ===
* [ ] '''C.1''' Write Ansible playbook: `lab1-student-env.yml` (1 pfSense + 1 client)
* [ ] '''C.2''' Write Ansible playbook: `lab2-student-env.yml` (1 pfSense + 1 client + 1 server)
* [ ] '''C.3''' Write Ansible playbook: `lab3-student-env.yml` (1 pfSense + 1 server + internet)
* [ ] '''C.4''' Write Ansible playbook: `lab4-student-env.yml` (2 pfSense + 2 clients + 1 server)
* [ ] '''C.5''' Write Ansible playbooks for Labs 5–10 (VPNs, Multi-WAN, Shaping, HA)
* [ ] '''C.6''' Write Ansible playbook: `cleanup-student-env.yml` (destroy VMs, free resources)
* [ ] '''C.7''' Write Ansible playbook: `reset-student-env.yml` (revert to snapshot/linked clone base)
* [ ] '''C.8''' Test all playbooks end-to-end with a single student ID

=== NoVNC Portal ===
* [ ] '''D.1''' Evaluate Kimchi vs Apache Guacamole vs custom NoVNC proxy
* [ ] '''D.2''' Install and configure chosen NoVNC solution
* [ ] '''D.3''' Integrate NoVNC with student authentication (LDAP, local wiki accounts, or simple token-based)
* [ ] '''D.4''' Build student dashboard: list of phases/labs, "Launch Lab" button, countdown timer
* [ ] '''D.5''' Test 5 concurrent NoVNC sessions for stability
* [ ] '''D.6''' Test 20 concurrent NoVNC sessions for performance

== Phase 2: Curriculum Development ==
Design the student-facing training program.

=== Introduction Course (Most Common Use Case) ===
* [ ] '''E.1''' Define "Setting Up a Firewall for Yourself" scope: home office / small business
* [ ] '''E.2''' Write Module 0: Why You Need a Firewall (threats, NAT basics, basic topology)
* [ ] '''E.3''' Write Module 1: Install pfSense on Old PC or VM (hardware requirements, USB install, first boot wizard)
* [ ] '''E.4''' Write Module 2: Basic WAN + LAN Setup (DHCP, DNS, first internet connection)
* [ ] '''E.5''' Write Module 3: Essential Firewall Rules (block incoming, allow outgoing, ICMP)
* [ ] '''E.6''' Write Module 4: Port Forwarding for Common Services (game server, camera, NAS)
* [ ] '''E.7''' Write Module 5: VPN for Remote Access (WireGuard road warrior setup)
* [ ] '''E.8''' Write Module 6: Backup and Updates (config.xml backup, update schedule)
* [ ] '''E.9''' Create hands-on lab for Introduction Course (single pfSense + 1 client VM)
* [ ] '''E.10''' Record or source video walkthroughs for each module

=== Full FUND001 Adaptation ===
* [ ] '''F.1''' Map each SEG slide deck to a wiki training page with summary + key takeaways
* [ ] '''F.2''' Adapt Netgate labs from physical/virtualbox environment to KVM/Ansible environment
* [ ] '''F.3''' Update IP addressing schema for Comfac virtual lab (avoid conflicts with production)
* [ ] '''F.4''' Write pre-lab briefing pages (what you'll learn, expected outcomes)
* [ ] '''F.5''' Write post-lab review pages (common mistakes, verification steps, "show me" checklist)
* [ ] '''F.6''' Create quiz questions for each phase (5–10 questions, auto-graded if possible)

== Phase 3: Pilot & Refinement ==
Run the training with a small group before full rollout.

=== Internal Pilot ===
* [ ] '''G.1''' Recruit 3–5 internal Comfac IT staff as pilot students
* [ ] '''G.2''' Run Phase 1 (Foundations) with pilot group — collect feedback
* [ ] '''G.3''' Run Phase 2 (NAT & Services) with pilot group — collect feedback
* [ ] '''G.4''' Run one VPN lab (IPsec or OpenVPN) with pilot group — test resource limits
* [ ] '''G.5''' Document all bugs, confusion points, and timeouts
* [ ] '''G.6''' Refine playbooks and wiki pages based on pilot feedback

=== Resource Tuning ===
* [ ] '''H.1''' Measure actual CPU/RAM/disk usage per student during pilot
* [ ] '''H.2''' Adjust VM specs if over- or under-provisioned
* [ ] '''H.3''' Test memory overcommit ratios for safe concurrency scaling
* [ ] '''H.4''' Document maximum safe concurrent student count

== Phase 4: Deployment & Operations ==
Prepare for regular training delivery.

=== Student Onboarding ===
* [ ] '''I.1''' Create student onboarding guide (how to access portal, use NoVNC, reset lab)
* [ ] '''I.2''' Create instructor guide (how to monitor progress, assist students, grade labs)
* [ ] '''I.3''' Set up scheduling system (book lab time slots, prevent over-allocation)
* [ ] '''I.4''' Create completion certificates or badges

=== Monitoring & Maintenance ===
* [ ] '''J.1''' Set up host monitoring (Prometheus/Grafana or simple `libvirt` stats)
* [ ] '''J.2''' Configure alerts for host resource exhaustion
* [ ] '''J.3''' Schedule weekly base image updates (pfSense patches, OS updates)
* [ ] '''J.4''' Document disaster recovery (rebuild host from Ansible, restore golden images)

== Quick Status Dashboard ==
{| class="wikitable"
! Phase !! Status !! % Complete !! Blockers
|-
| Phase 0: Material Conversion || 🟡 In Progress || 0% || Need bot/API access for bulk uploads
|-
| Phase 1: Infrastructure Setup || 🔴 Not Started || 0% || Need 200-core host access
|-
| Phase 2: Curriculum Development || 🔴 Not Started || 0% || Waiting on Phase 0 completion
|-
| Phase 3: Pilot & Refinement || 🔴 Not Started || 0% || Waiting on Phase 1 + 2
|-
| Phase 4: Deployment & Operations || 🔴 Not Started || 0% || Waiting on Phase 3
|}

== Resource Summary ==
'''Per-student minimum:''' 6 vCPUs, 6.5 GB RAM, 62 GB disk
'''Per-student full lab:''' 10 vCPUs, 10.5 GB RAM, 110 GB disk
'''200-core / 1TB capacity:''' 20–40 concurrent students (conservative to optimized)

'''Next Actions (This Week):'''
# Start converting FUND001-LIVE-SLIDE-SEG1-INTRO.pdf and FUND001-LIVE-Lab1-Intro.pdf to wiki
# Confirm 200-core host specifications and OS
# Evaluate Kimchi vs Guacamole for NoVNC portal

Networking PfSense Index

2026-04-23T06:36:05Z

Justinaquino: Add Practical Training System (NoVNC Virtual Lab) section with phases, resource estimates, and ZTP/IaC strategy

Main Page

2026-04-23T06:08:47Z

Justinaquino: Consolidate networking links into Networking PfSense Index

__NOTOC__
<div style="background:#f8f9fa; border:1px solid #ddd; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
Welcome to the '''Comfac IT Knowledge Base'''. Use the sections below to find guides, SOPs, and references organized by topic.
</div>

== ERPNext / Frappe ==
<div style="column-count:2; column-gap:2em;">
* [[Frappe HRMS]] — '''HR & Payroll''' (with Philippine Localization)
* [[Frappe ERPNext/Webshop]] — '''E-Commerce Webshop''' (setup, architecture, chapters)
* [[Manufacturing v16 260125]]
* [[ERpnext Asset Management Procedure 260113]]
* [[ERPNext HR Module Outline]]
* [[ERPNEXT Payroll POC 251212]]
* [[Comfac ERPNext Strategy Canvas (Expanded)]]
* [[PAD-Driven ERPNext Strategy 260303]] — PAD/AI-agentic implementation strategy for Frappe ERPNext
* [[ERPNext v15 Docker Setup Guide]] — Local Docker setup for evaluation, testing, and student use
* [[Frappe Links and References]]
* [[Using Frappe Wiki]]
* [https://docs.frappe.io/cloud/guidelines-for-contributing-regional-compliance-app Guidelines for Contributing Regional Compliance App]
* [https://docs.frappe.io/cloud/what-are-benches-and-bench-groups What are Benches?]
</div>

== System Administration & Self-Hosting ==
<div style="column-count:2; column-gap:2em;">
* [[Networking PfSense Index]] — Consolidated index of all networking, pfSense, DNS, and infrastructure guides
* [[System Hardening Strategy: Win2Lin Migration & Infrastructure 251129]]
* [[Controller Systems 251213-01]]
* [[Power Distribution Tree 251213]]
* [[Introduction: Why Self-Host Your Email?]]
* [[Mailcow + Thunderbird Setup Guide (Email + Calendar)]]
* [[Mailcow SOGo: Creating Filters for Events, Approvals, and Organizational Emails]]
* [[Spoof Timezone Extension – Setup Guide for Comfac Staff]]
* [[Viber Focus-Stealing]]
* [[🌐 WordPress Website — *You Own Everything, Learn Everything*]]
* [[Portainer to Docker Compose Migration Guide]]
* [[Editing Mastodon Docker Deployment Guide 260402]]
</div>

== Storage & Hardware ==
<div style="column-count:2; column-gap:2em;">
* [[TrueNAS Configuration Options & Scale Options 251130]]
* [[TrueNAS Business Plan: Project 251212]]
* [[Comparison: TrueNAS Mini X+ vs Dell Precision 3680 Tower (2025)]]
* [[Backblaze Drive Stats for Server and Storage Qualification]]
* [[Industrial Controllers and Water Utilities 251011]]
</div>

== AI & Machine Learning ==
<div style="column-count:2; column-gap:2em;">
* [[OpenWebUI - 251128-justin]]
* [[Comfac GPU Scaling and AI Research Goals]]
* [[🧠 Process: Selecting and Installing the Right Ollama Model for Your Hardware]]
* [[Ollama GNOME System Tray Panel 260401]] — GNOME system tray toggle to start/stop Ollama and reclaim VRAM
* [[Proceedural Agentic Development Methodology 260304]] — Methodology for systematic agent use
* [[Project OpenCoder: AI Independence Initiative]] — Strategic roadmap for manufacturing intelligence
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 Modelfile fix for tool calling in OpenCode; thinking mode suppression; HDD vs SSD findings
* [[OpenCode Multi-Provider Configuration Guide 260401]] — Dual-mode AI coding setup with Kimi cloud + Ollama local models via Distrobox
* [[PAD-Driven ERPNext Strategy 260303]] — Procedural Agentic Development for Frappe/ERPNext configuration and deployment
</div>

== Job Descriptions ==
<div style="column-count:2; column-gap:2em;">
* [[Job Descriptions]] — Index of all official job descriptions (IT, Engineering, Sales)
* [[JD IT Project Staff]] — IT Project Staff
* [[JD Security Compliance Assistant 260224]] — Security and Compliance Assistant (SCA)
* [[JD Engineering Designer 260108]] — Engineering Designer
* [[JD Engineering Supervisor 260109]] — Engineering Supervisor
* [[JD Technical Sales 260112]] — Technical Sales Engineer
* [[JD Marketing Assistant 251119]] — Marketing Assistant
</div>

== IT Operations & SOPs ==
<div style="column-count:2; column-gap:2em;">
* [[SCA Program Plan 260320]] — Security & Compliance Assistant Program Plan v3 (ISO 9001/27001, PDCA, distributed audit model)
* [[SOP: Inter-Company Ordering and Production Process 260203]] — Ordering and production workflow between Sister Companies and the Cabuyao Plant
* [[Memo: Team Roles & Reporting Process Clarification 260320]] — Role boundaries, data ownership, and the new ERPNext-driven reporting paradigm
* [[Standard Operating Procedure: Distributed Minute Taking & Task Ownership 251208]]
* [[Business Continuity]]
* [[Procedure: CC-Blast Data Breach Prevention]]
* [[8D (Eight Discipline) Problem Solving Procedure]]
* [[Offline Malware Remediation & Data Recovery]]
* [[Troubleshooting: Access & Permission Issues]]
* [[Steps to Repair and OCR a Scanned or Corrupted PDF in Ubuntu]]
* [[IT IMPORTS PROCESSES]]
* [[IT Purchase Requests 241126]]
* [[IT REQUEST (OP-ERP-ITR) - EDITED 250801]]
</div>

== Sales & Business ==
<div style="column-count:2; column-gap:2em;">
* [[Comfac Sales Knowledge Base]]
* [[Comfac CRM – Customer Qualification & Conversion Process]]
* [[Partner Reseller Pricing 251109]]
* [[Biz Analysis Methodology 251109]]
* [[2026 MIS IT KRA KPI Biz Plan]]
* [[SALES INVOICE TAX OUTPUT 250829]]
* [[Projects in Process Report 251023]]
</div>

== Tools & Productivity ==
<div style="column-count:2; column-gap:2em;">
* [[Excel Description Filler Tool 📝]]
* [https://github.com/Comfac-Global-Group/comfac-studies Comfac Studies - Spaced Repetiton Active Recall]
* [[LibreOffice / Nextcloud Office – "Due Tasks" Conditional Formatting]]
* [[Google Drive and Shared Drive Training]]
* [[260108 CGG- GitHub Administration Guide]]
</div>

== Wiki & Documentation ==
<div style="column-count:2; column-gap:2em;">
* [[Mediawiki Setting Up Guide]]
* [[Contributing to Only Office 260307]]
* [[Mediawiki Additional Configuration]]
* [[Mediawiki Docker Migration Guide]]
* [[Home]]
</div>

== Tutorials ==
<div style="column-count:2; column-gap:2em;">
* [[Claude Code Isolation and Burner Workflow 260211]] — Secure AI development environment setup
* [[Opencode isolation and burner workflow 260216]] — OpenCode CLI isolation procedures
* [[LibreOffice Calc NumToWords Extension Complete Guide]] — Extension development
* [[ERPNext v15 Docker Setup Guide]] — ERPNext v15 local Docker setup (students, evaluators, thin-client demos)
* [[Erpnextv15-SSH-setup-241111]] — ERPNext v15 SSH/Portainer production setup
* [[Git-Mediawiki Local Editing 260223]] — Wiki editing with Git
* [[Understanding & Fixing Kernel Panics 260212]] — System debugging
* [[OpenCode in Android Termux 260303]] — OpenCode in Android
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 agentic setup: Modelfile, tool calling fix, storage impact
* [[Lora Basics 260304]] — LORA research
* [https://github.com/anomalyco/opencode/issues/4283#issuecomment-4083399210 Opencode Copy-paste Clipboard doesnt Work - Solution] https://github.com/anomalyco/opencode/issues/4283#issuecomment-4083399210
</div>

== Research ==
<div style="column-count:2; column-gap:2em;">
* [[Ladybird Browser]] — Browser engine development
* [[Computing Architecture]] — System design principles
* [[Backblaze Drive Stats for Server and Storage Qualification 260219]] — Drive reliability analysis
</div>

----

== For Users Only ==
* [[Private:Private Ngani]]
* [[Private:Private Nganipart2]]

== CIT-OJT Project Documentations ==
* [[OJTDocs: For OJTs only]]

== Need Help? ==
<div style="column-count:2; column-gap:2em;">
* [[Troubleshooting: Access & Permission Issues]]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents MediaWiki User's Guide]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
</div>

Networking PfSense Index

2026-04-23T06:06:49Z

Justinaquino: Create consolidated Networking PfSense Index

Main Page

2026-04-06T13:38:30Z

Justinaquino: /* Tutorials */

__NOTOC__
<div style="background:#f8f9fa; border:1px solid #ddd; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
Welcome to the '''Comfac IT Knowledge Base'''. Use the sections below to find guides, SOPs, and references organized by topic.
</div>

== ERPNext / Frappe ==
<div style="column-count:2; column-gap:2em;">
* [[Frappe HRMS]] — '''HR & Payroll''' (with Philippine Localization)
* [[Frappe ERPNext/Webshop]] — '''E-Commerce Webshop''' (setup, architecture, chapters)
* [[Manufacturing v16 260125]]
* [[ERpnext Asset Management Procedure 260113]]
* [[ERPNext HR Module Outline]]
* [[ERPNEXT Payroll POC 251212]]
* [[Comfac ERPNext Strategy Canvas (Expanded)]]
* [[PAD-Driven ERPNext Strategy 260303]] — PAD/AI-agentic implementation strategy for Frappe ERPNext
* [[ERPNext v15 Docker Setup Guide]] — Local Docker setup for evaluation, testing, and student use
* [[Frappe Links and References]]
* [[Using Frappe Wiki]]
* [https://docs.frappe.io/cloud/guidelines-for-contributing-regional-compliance-app Guidelines for Contributing Regional Compliance App]
* [https://docs.frappe.io/cloud/what-are-benches-and-bench-groups What are Benches?]
</div>

== System Administration & Self-Hosting ==
<div style="column-count:2; column-gap:2em;">
* [[NPM Migration to Homelab VPS Relay 260401]] — Move NPM off a compromised VPS; VPS becomes a pure iptables/ZeroTier relay with homelab redundancy
* [[pfSense Sales Training Material]]
* [[SOP: Network Troubleshooting & pfSense Monitoring 251130]]
* [[Modern Guide: pfSense Captive Portal with FreeRADIUS & ACME]]
* [[pfSense CE → pfSense Plus Upgrade Guide]]
* [[Tplink Mikrotik Equivalent]]
* [[Skills and Competencies for IT Staff Trained in pfSense]]
* [[System Hardening Strategy: Win2Lin Migration & Infrastructure 251129]]
* [[Controller Systems 251213-01]]
* [[Power Distribution Tree 251213]]
* [[Introduction: Why Self-Host Your Email?]]
* [[Mailcow + Thunderbird Setup Guide (Email + Calendar)]]
* [[Mailcow SOGo: Creating Filters for Events, Approvals, and Organizational Emails]]
* [[Spoof Timezone Extension – Setup Guide for Comfac Staff]]
* [[Viber Focus-Stealing]]
* [[🌐 WordPress Website — *You Own Everything, Learn Everything*]]
* [[Portainer to Docker Compose Migration Guide]]
* [[Editing Mastodon Docker Deployment Guide 260402]]
</div>

== Storage & Hardware ==
<div style="column-count:2; column-gap:2em;">
* [[TrueNAS Configuration Options & Scale Options 251130]]
* [[TrueNAS Business Plan: Project 251212]]
* [[Comparison: TrueNAS Mini X+ vs Dell Precision 3680 Tower (2025)]]
* [[Backblaze Drive Stats for Server and Storage Qualification]]
* [[Industrial Controllers and Water Utilities 251011]]
</div>

== AI & Machine Learning ==
<div style="column-count:2; column-gap:2em;">
* [[OpenWebUI - 251128-justin]]
* [[Comfac GPU Scaling and AI Research Goals]]
* [[🧠 Process: Selecting and Installing the Right Ollama Model for Your Hardware]]
* [[Ollama GNOME System Tray Panel 260401]] — GNOME system tray toggle to start/stop Ollama and reclaim VRAM
* [[Proceedural Agentic Development Methodology 260304]] — Methodology for systematic agent use
* [[Project OpenCoder: AI Independence Initiative]] — Strategic roadmap for manufacturing intelligence
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 Modelfile fix for tool calling in OpenCode; thinking mode suppression; HDD vs SSD findings
* [[OpenCode Multi-Provider Configuration Guide 260401]] — Dual-mode AI coding setup with Kimi cloud + Ollama local models via Distrobox
* [[PAD-Driven ERPNext Strategy 260303]] — Procedural Agentic Development for Frappe/ERPNext configuration and deployment
</div>

== Job Descriptions ==
<div style="column-count:2; column-gap:2em;">
* [[Job Descriptions]] — Index of all official job descriptions (IT, Engineering, Sales)
* [[JD IT Project Staff]] — IT Project Staff
* [[JD Security Compliance Assistant 260224]] — Security and Compliance Assistant (SCA)
* [[JD Engineering Designer 260108]] — Engineering Designer
* [[JD Engineering Supervisor 260109]] — Engineering Supervisor
* [[JD Technical Sales 260112]] — Technical Sales Engineer
* [[JD Marketing Assistant 251119]] — Marketing Assistant
</div>

== IT Operations & SOPs ==
<div style="column-count:2; column-gap:2em;">
* [[SCA Program Plan 260320]] — Security & Compliance Assistant Program Plan v3 (ISO 9001/27001, PDCA, distributed audit model)
* [[SOP: Inter-Company Ordering and Production Process 260203]] — Ordering and production workflow between Sister Companies and the Cabuyao Plant
* [[Memo: Team Roles & Reporting Process Clarification 260320]] — Role boundaries, data ownership, and the new ERPNext-driven reporting paradigm
* [[Standard Operating Procedure: Distributed Minute Taking & Task Ownership 251208]]
* [[Business Continuity]]
* [[Procedure: CC-Blast Data Breach Prevention]]
* [[8D (Eight Discipline) Problem Solving Procedure]]
* [[Offline Malware Remediation & Data Recovery]]
* [[Troubleshooting: Access & Permission Issues]]
* [[Steps to Repair and OCR a Scanned or Corrupted PDF in Ubuntu]]
* [[IT IMPORTS PROCESSES]]
* [[IT Purchase Requests 241126]]
* [[IT REQUEST (OP-ERP-ITR) - EDITED 250801]]
</div>

== Sales & Business ==
<div style="column-count:2; column-gap:2em;">
* [[Comfac Sales Knowledge Base]]
* [[Comfac CRM – Customer Qualification & Conversion Process]]
* [[Partner Reseller Pricing 251109]]
* [[Biz Analysis Methodology 251109]]
* [[2026 MIS IT KRA KPI Biz Plan]]
* [[SALES INVOICE TAX OUTPUT 250829]]
* [[Projects in Process Report 251023]]
</div>

== Tools & Productivity ==
<div style="column-count:2; column-gap:2em;">
* [[Excel Description Filler Tool 📝]]
* [https://github.com/Comfac-Global-Group/comfac-studies Comfac Studies - Spaced Repetiton Active Recall]
* [[LibreOffice / Nextcloud Office – "Due Tasks" Conditional Formatting]]
* [[Google Drive and Shared Drive Training]]
* [[260108 CGG- GitHub Administration Guide]]
</div>

== Wiki & Documentation ==
<div style="column-count:2; column-gap:2em;">
* [[Mediawiki Setting Up Guide]]
* [[Contributing to Only Office 260307]]
* [[Mediawiki Additional Configuration]]
* [[Mediawiki Docker Migration Guide]]
* [[Home]]
</div>

== Tutorials ==
<div style="column-count:2; column-gap:2em;">
* [[Claude Code Isolation and Burner Workflow 260211]] — Secure AI development environment setup
* [[Opencode isolation and burner workflow 260216]] — OpenCode CLI isolation procedures
* [[LibreOffice Calc NumToWords Extension Complete Guide]] — Extension development
* [[ERPNext v15 Docker Setup Guide]] — ERPNext v15 local Docker setup (students, evaluators, thin-client demos)
* [[Erpnextv15-SSH-setup-241111]] — ERPNext v15 SSH/Portainer production setup
* [[Git-Mediawiki Local Editing 260223]] — Wiki editing with Git
* [[Understanding & Fixing Kernel Panics 260212]] — System debugging
* [[OpenCode in Android Termux 260303]] — OpenCode in Android
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 agentic setup: Modelfile, tool calling fix, storage impact
* [[Lora Basics 260304]] — LORA research
* [https://github.com/anomalyco/opencode/issues/4283#issuecomment-4083399210 Opencode Copy-paste Clipboard doesnt Work - Solution] https://github.com/anomalyco/opencode/issues/4283#issuecomment-4083399210
</div>

== Research ==
<div style="column-count:2; column-gap:2em;">
* [[Ladybird Browser]] — Browser engine development
* [[Computing Architecture]] — System design principles
* [[Backblaze Drive Stats for Server and Storage Qualification 260219]] — Drive reliability analysis
</div>

----

== For Users Only ==
* [[Private:Private Ngani]]
* [[Private:Private Nganipart2]]

== CIT-OJT Project Documentations ==
* [[OJTDocs: For OJTs only]]

== Need Help? ==
<div style="column-count:2; column-gap:2em;">
* [[Troubleshooting: Access & Permission Issues]]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents MediaWiki User's Guide]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
</div>

Main Page

2026-04-02T12:08:47Z

Justinaquino: /* System Administration & Self-Hosting */

__NOTOC__
<div style="background:#f8f9fa; border:1px solid #ddd; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
Welcome to the '''Comfac IT Knowledge Base'''. Use the sections below to find guides, SOPs, and references organized by topic.
</div>

== ERPNext / Frappe ==
<div style="column-count:2; column-gap:2em;">
* [[Frappe HRMS]] — '''HR & Payroll''' (with Philippine Localization)
* [[Frappe ERPNext/Webshop]] — '''E-Commerce Webshop''' (setup, architecture, chapters)
* [[Manufacturing v16 260125]]
* [[ERpnext Asset Management Procedure 260113]]
* [[ERPNext HR Module Outline]]
* [[ERPNEXT Payroll POC 251212]]
* [[Comfac ERPNext Strategy Canvas (Expanded)]]
* [[PAD-Driven ERPNext Strategy 260303]] — PAD/AI-agentic implementation strategy for Frappe ERPNext
* [[ERPNext v15 Docker Setup Guide]] — Local Docker setup for evaluation, testing, and student use
* [[Frappe Links and References]]
* [[Using Frappe Wiki]]
* [https://docs.frappe.io/cloud/guidelines-for-contributing-regional-compliance-app Guidelines for Contributing Regional Compliance App]
* [https://docs.frappe.io/cloud/what-are-benches-and-bench-groups What are Benches?]
</div>

== System Administration & Self-Hosting ==
<div style="column-count:2; column-gap:2em;">
* [[NPM Migration to Homelab VPS Relay 260401]] — Move NPM off a compromised VPS; VPS becomes a pure iptables/ZeroTier relay with homelab redundancy
* [[pfSense Sales Training Material]]
* [[SOP: Network Troubleshooting & pfSense Monitoring 251130]]
* [[Modern Guide: pfSense Captive Portal with FreeRADIUS & ACME]]
* [[pfSense CE → pfSense Plus Upgrade Guide]]
* [[Tplink Mikrotik Equivalent]]
* [[Skills and Competencies for IT Staff Trained in pfSense]]
* [[System Hardening Strategy: Win2Lin Migration & Infrastructure 251129]]
* [[Controller Systems 251213-01]]
* [[Power Distribution Tree 251213]]
* [[Introduction: Why Self-Host Your Email?]]
* [[Mailcow + Thunderbird Setup Guide (Email + Calendar)]]
* [[Mailcow SOGo: Creating Filters for Events, Approvals, and Organizational Emails]]
* [[Spoof Timezone Extension – Setup Guide for Comfac Staff]]
* [[Viber Focus-Stealing]]
* [[🌐 WordPress Website — *You Own Everything, Learn Everything*]]
* [[Portainer to Docker Compose Migration Guide]]
* [[Editing Mastodon Docker Deployment Guide 260402]]
</div>

== Storage & Hardware ==
<div style="column-count:2; column-gap:2em;">
* [[TrueNAS Configuration Options & Scale Options 251130]]
* [[TrueNAS Business Plan: Project 251212]]
* [[Comparison: TrueNAS Mini X+ vs Dell Precision 3680 Tower (2025)]]
* [[Backblaze Drive Stats for Server and Storage Qualification]]
* [[Industrial Controllers and Water Utilities 251011]]
</div>

== AI & Machine Learning ==
<div style="column-count:2; column-gap:2em;">
* [[OpenWebUI - 251128-justin]]
* [[Comfac GPU Scaling and AI Research Goals]]
* [[🧠 Process: Selecting and Installing the Right Ollama Model for Your Hardware]]
* [[Ollama GNOME System Tray Panel 260401]] — GNOME system tray toggle to start/stop Ollama and reclaim VRAM
* [[Proceedural Agentic Development Methodology 260304]] — Methodology for systematic agent use
* [[Project OpenCoder: AI Independence Initiative]] — Strategic roadmap for manufacturing intelligence
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 Modelfile fix for tool calling in OpenCode; thinking mode suppression; HDD vs SSD findings
* [[OpenCode Multi-Provider Configuration Guide 260401]] — Dual-mode AI coding setup with Kimi cloud + Ollama local models via Distrobox
* [[PAD-Driven ERPNext Strategy 260303]] — Procedural Agentic Development for Frappe/ERPNext configuration and deployment
</div>

== Job Descriptions ==
<div style="column-count:2; column-gap:2em;">
* [[Job Descriptions]] — Index of all official job descriptions (IT, Engineering, Sales)
* [[JD IT Project Staff]] — IT Project Staff
* [[JD Security Compliance Assistant 260224]] — Security and Compliance Assistant (SCA)
* [[JD Engineering Designer 260108]] — Engineering Designer
* [[JD Engineering Supervisor 260109]] — Engineering Supervisor
* [[JD Technical Sales 260112]] — Technical Sales Engineer
* [[JD Marketing Assistant 251119]] — Marketing Assistant
</div>

== IT Operations & SOPs ==
<div style="column-count:2; column-gap:2em;">
* [[SCA Program Plan 260320]] — Security & Compliance Assistant Program Plan v3 (ISO 9001/27001, PDCA, distributed audit model)
* [[SOP: Inter-Company Ordering and Production Process 260203]] — Ordering and production workflow between Sister Companies and the Cabuyao Plant
* [[Memo: Team Roles & Reporting Process Clarification 260320]] — Role boundaries, data ownership, and the new ERPNext-driven reporting paradigm
* [[Standard Operating Procedure: Distributed Minute Taking & Task Ownership 251208]]
* [[Business Continuity]]
* [[Procedure: CC-Blast Data Breach Prevention]]
* [[8D (Eight Discipline) Problem Solving Procedure]]
* [[Offline Malware Remediation & Data Recovery]]
* [[Troubleshooting: Access & Permission Issues]]
* [[Steps to Repair and OCR a Scanned or Corrupted PDF in Ubuntu]]
* [[IT IMPORTS PROCESSES]]
* [[IT Purchase Requests 241126]]
* [[IT REQUEST (OP-ERP-ITR) - EDITED 250801]]
</div>

== Sales & Business ==
<div style="column-count:2; column-gap:2em;">
* [[Comfac Sales Knowledge Base]]
* [[Comfac CRM – Customer Qualification & Conversion Process]]
* [[Partner Reseller Pricing 251109]]
* [[Biz Analysis Methodology 251109]]
* [[2026 MIS IT KRA KPI Biz Plan]]
* [[SALES INVOICE TAX OUTPUT 250829]]
* [[Projects in Process Report 251023]]
</div>

== Tools & Productivity ==
<div style="column-count:2; column-gap:2em;">
* [[Excel Description Filler Tool 📝]]
* [https://github.com/Comfac-Global-Group/comfac-studies Comfac Studies - Spaced Repetiton Active Recall]
* [[LibreOffice / Nextcloud Office – "Due Tasks" Conditional Formatting]]
* [[Google Drive and Shared Drive Training]]
* [[260108 CGG- GitHub Administration Guide]]
</div>

== Wiki & Documentation ==
<div style="column-count:2; column-gap:2em;">
* [[Mediawiki Setting Up Guide]]
* [[Contributing to Only Office 260307]]
* [[Mediawiki Additional Configuration]]
* [[Mediawiki Docker Migration Guide]]
* [[Home]]
</div>

== Tutorials ==
<div style="column-count:2; column-gap:2em;">
* [[Claude Code Isolation and Burner Workflow 260211]] — Secure AI development environment setup
* [[Opencode isolation and burner workflow 260216]] — OpenCode CLI isolation procedures
* [[LibreOffice Calc NumToWords Extension Complete Guide]] — Extension development
* [[ERPNext v15 Docker Setup Guide]] — ERPNext v15 local Docker setup (students, evaluators, thin-client demos)
* [[Erpnextv15-SSH-setup-241111]] — ERPNext v15 SSH/Portainer production setup
* [[Git-Mediawiki Local Editing 260223]] — Wiki editing with Git
* [[Understanding & Fixing Kernel Panics 260212]] — System debugging
* [[OpenCode in Android Termux 260303]] — OpenCode in Android
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 agentic setup: Modelfile, tool calling fix, storage impact
* [[Lora Basics 260304]] — LORA research
</div>

== Research ==
<div style="column-count:2; column-gap:2em;">
* [[Ladybird Browser]] — Browser engine development
* [[Computing Architecture]] — System design principles
* [[Backblaze Drive Stats for Server and Storage Qualification 260219]] — Drive reliability analysis
</div>

----

== For Users Only ==
* [[Private:Private Ngani]]
* [[Private:Private Nganipart2]]

== CIT-OJT Project Documentations ==
* [[OJTDocs: For OJTs only]]

== Need Help? ==
<div style="column-count:2; column-gap:2em;">
* [[Troubleshooting: Access & Permission Issues]]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents MediaWiki User's Guide]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
</div>

Editing Mastodon Docker Deployment Guide 260402

2026-04-02T12:08:27Z

Justinaquino: Created page with "= Mastodon on Docker — Self-Hosted Deployment Guide = '''Behind Nginx Proxy Manager with Let's Encrypt SSL''' Using linuxserver.io image | Ubuntu 24 | Docker Compose {{Tip|This guide is written so that a thinking model AI agent (such as one running on your local server via Ollama/Open WebUI) can follow these instructions step-by-step and get Mastodon running without human intervention. Every command is verified against a successful real-world deployment. Verify all..."

= Mastodon on Docker — Self-Hosted Deployment Guide =

'''Behind Nginx Proxy Manager with Let's Encrypt SSL'''

Using linuxserver.io image | Ubuntu 24 | Docker Compose

{{Tip|This guide is written so that a thinking model AI agent (such as one running on your local server via Ollama/Open WebUI) can follow these instructions step-by-step and get Mastodon running without human intervention. Every command is verified against a successful real-world deployment. Verify all outputs at each stage before proceeding.}}

== Why Mastodon Is More Complex Than Other Docker Apps ==

Most Docker apps are a single process that sits behind a reverse proxy. Mastodon is different in three important ways:

# It runs '''five processes simultaneously''' inside one container: Rails (web), Puma (app server), Sidekiq (background jobs), a Node.js streaming server, and its own internal nginx. This is managed by s6-overlay.
# It assumes it owns ports 80 and 443 directly. Placing it behind NPM requires overriding its internal nginx SSL behavior, which it resists.
# It enforces cryptographic secrets before it will even start. Unlike most apps, Mastodon refuses to boot without SECRET_KEY_BASE, OTP_SECRET, VAPID keys, and ACTIVE_RECORD_ENCRYPTION keys all pre-generated.

{{Warning|Mastodon also takes 30-60 seconds to fully boot. Always check logs before assuming something is wrong.}}

== Prerequisites ==

* Ubuntu 24 server (bare metal or VM)
* Docker and Docker Compose installed
* Nginx Proxy Manager (NPM) already running on ports 80 and 443
* A domain name with an A record pointing to your server's public IP
* Gmail account with an App Password generated (for SMTP)

{{Critical|To generate a Gmail App Password: go to myaccount.google.com/apppasswords, create a new app password, and save it in a password manager immediately. Do not paste it into any chat or shared document.}}

== Step 1 — Create the Directory ==

All Mastodon files live in one directory. Create it and navigate into it:

<syntaxhighlight lang="bash">
mkdir -p /opt/mastodon
cd /opt/mastodon
</syntaxhighlight>

The volume mount <code>/opt/mastodon/config:/config</code> will be auto-created by linuxserver on first run and will populate with nginx config, keys, and logs.

== Step 2 — Generate All Secrets Before Starting ==

{{Warning|The linuxserver image entrypoint interferes with rails commands. Always override with <code>--entrypoint=""</code> and use the full path <code>/app/www/bin/rails</code>. You must also set the working directory with <code>-w /app/www</code> for rake tasks.}}

=== SECRET_KEY_BASE (run once) ===

<syntaxhighlight lang="bash">
docker run --rm --entrypoint="" lscr.io/linuxserver/mastodon:latest /app/www/bin/rails secret
</syntaxhighlight>

=== OTP_SECRET (run again for a different value) ===

<syntaxhighlight lang="bash">
docker run --rm --entrypoint="" lscr.io/linuxserver/mastodon:latest /app/www/bin/rails secret
</syntaxhighlight>

=== VAPID Keys ===

<syntaxhighlight lang="bash">
docker run --rm --entrypoint="" -w /app/www lscr.io/linuxserver/mastodon:latest /app/www/bin/rails mastodon:webpush:generate_vapid_key
</syntaxhighlight>

Output will look like:

<syntaxhighlight lang="text">
VAPID_PRIVATE_KEY=OqZ07QTRwoO...
VAPID_PUBLIC_KEY=BA7IhTSGcf0...
</syntaxhighlight>

=== ACTIVE_RECORD_ENCRYPTION Keys (new requirement in Mastodon 4.3+) ===

<syntaxhighlight lang="bash">
docker run --rm --entrypoint="" -w /app/www lscr.io/linuxserver/mastodon:latest /app/www/bin/rails db:encryption:init
</syntaxhighlight>

Output will look like:

<syntaxhighlight lang="text">
ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=Xf3Rvl...
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=TK5DQU...
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=f8cyBe...
</syntaxhighlight>

{{Critical|Copy all seven values now. You will not be able to change them after the database is initialized without risking data loss.}}

== Step 3 — Create docker-compose.yml ==

Create the file:

<syntaxhighlight lang="bash">
nano /opt/mastodon/docker-compose.yml
</syntaxhighlight>

Paste the following, replacing all placeholder values with your actual secrets and domain:

<syntaxhighlight lang="yaml">
services:
mastodon:
image: lscr.io/linuxserver/mastodon:latest
container_name: mastodon
environment:
- PUID=1000
- PGID=1000
- TZ=Asia/Manila
- LOCAL_DOMAIN=toot.yourdomain.com
- NO_SSL=true
- FORCE_SSL=false
- TRUSTED_PROXY_IP=127.0.0.1/8,::1/128,192.168.0.0/16
- REDIS_HOST=redis
- REDIS_PORT=6379
- DB_HOST=db
- DB_USER=mastodon
- DB_NAME=mastodon_production
- DB_PASS=your_db_password
- DB_PORT=5432
- ES_ENABLED=false
- SECRET_KEY_BASE=<from step 2>
- OTP_SECRET=<from step 2>
- VAPID_PRIVATE_KEY=<from step 2>
- VAPID_PUBLIC_KEY=<from step 2>
- ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=<from step 2>
- ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=<from step 2>
- ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=<from step 2>
- SMTP_SERVER=smtp.gmail.com
- SMTP_PORT=587
- SMTP_LOGIN=your_gmail@gmail.com
- SMTP_PASSWORD=your_gmail_app_password
- SMTP_FROM_ADDRESS=notifications@yourdomain.com
- SMTP_AUTH_METHOD=plain
- SMTP_OPENSSL_VERIFY_MODE=peer
- S3_ENABLED=false
volumes:
- /opt/mastodon/config:/config
ports:
- 8667:80
networks:
- mastodon-net
depends_on:
- db
- redis
restart: unless-stopped

redis:
image: redis:7-alpine
container_name: mastodon-redis
volumes:
- /opt/mastodon/redis:/data
networks:
- mastodon-net
restart: unless-stopped

db:
image: postgres:14-alpine
container_name: mastodon-db
environment:
- POSTGRES_DB=mastodon_production
- POSTGRES_USER=mastodon
- POSTGRES_PASSWORD=your_db_password
volumes:
- /opt/mastodon/postgres:/var/lib/postgresql/data
networks:
- mastodon-net
restart: unless-stopped

networks:
mastodon-net:
driver: bridge
</syntaxhighlight>

{{Note|Port 8667:80 maps host port 8667 to the container's internal port 80. This avoids conflict with NPM which already owns ports 80 and 443. Choose any unused host port.}}

== Step 4 — Start the Stack ==

<syntaxhighlight lang="bash">
cd /opt/mastodon
docker compose up -d
</syntaxhighlight>

Watch the logs and wait for the boot sequence to complete (30-60 seconds):

<syntaxhighlight lang="bash">
docker compose logs -f mastodon
</syntaxhighlight>

A successful boot ends with lines like:

<syntaxhighlight lang="text">
Connection to localhost (127.0.0.1) 3000 port [tcp/*] succeeded!
[ls.io-init] done.
Sidekiq 8.x connecting to Redis with options...
</syntaxhighlight>

{{Warning|Do not proceed until you see <code>[ls.io-init] done</code>. Mastodon takes 30-60 seconds to fully initialize on first boot. The ACTIVE_RECORD_ENCRYPTION crash loop means those keys are missing or not being read from the compose file.}}

== Step 5 — Fix Internal nginx SSL Conflict ==

The linuxserver image generates an nginx config that listens on both port 80 and port 443, and passes <code>X-Forwarded-Proto: http</code> to Rails. This causes Rails to issue a 301 redirect to HTTPS even when NO_SSL=true and FORCE_SSL=false are set. The fix is to edit the nginx config directly and hardcode X-Forwarded-Proto to https.

{{Warning|This must be done after first boot because the config files are generated on first run into <code>/opt/mastodon/config/nginx/</code>. You must edit both the active .conf and the .conf.sample so changes survive container restarts.}}

=== Remove 443 listeners and hardcode X-Forwarded-Proto ===

<syntaxhighlight lang="bash">
# Fix active config
docker exec mastodon sed -i 's/listen 443 ssl default_server;//g' /config/nginx/site-confs/default.conf
docker exec mastodon sed -i 's/listen \[\:\:\]:443 ssl default_server;//g' /config/nginx/site-confs/default.conf
docker exec mastodon sed -i 's/include \/config\/nginx\/ssl.conf;//g' /config/nginx/site-confs/default.conf
docker exec mastodon sed -i 's/proxy_set_header X-Forwarded-Proto $scheme;/proxy_set_header X-Forwarded-Proto https;/g' /config/nginx/site-confs/default.conf

# Fix sample so it survives restarts
docker exec mastodon sed -i 's/listen 443 ssl default_server;//g' /config/nginx/site-confs/default.conf.sample
docker exec mastodon sed -i 's/listen \[\:\:\]:443 ssl default_server;//g' /config/nginx/site-confs/default.conf.sample
docker exec mastodon sed -i 's/include \/config\/nginx\/ssl.conf;//g' /config/nginx/site-confs/default.conf.sample
docker exec mastodon sed -i 's/proxy_set_header X-Forwarded-Proto $scheme;/proxy_set_header X-Forwarded-Proto https;/g' /config/nginx/site-confs/default.conf.sample

# Reload nginx without restarting the container
docker exec mastodon s6-svc -r /run/service/svc-nginx
</syntaxhighlight>

=== Verify the fix ===

<syntaxhighlight lang="bash">
curl -v http://localhost:8667 -H "Host: toot.yourdomain.com"
</syntaxhighlight>

You should see <code>HTTP/1.1 200 OK</code>. If you still see <code>301 Moved Permanently</code>, check that the sed commands ran correctly:

<syntaxhighlight lang="bash">
docker exec mastodon cat /config/nginx/site-confs/default.conf | grep -n "301\|https\|ssl\|443"
</syntaxhighlight>

== Step 6 — Configure Nginx Proxy Manager ==

In NPM, create a new Proxy Host with these settings:

{| class="wikitable"
! Setting !! Value
|-
| Domain Name || toot.yourdomain.com
|-
| Scheme || http
|-
| Forward Hostname / IP || Your server's LAN IP (e.g. 192.168.1.100)
|-
| Forward Port || 8667 (or whichever host port you chose)
|-
| Cache Assets || Off
|-
| Block Common Exploits || On
|-
| Websockets Support || On (critical for live feed)
|-
| SSL Certificate || Request via Let's Encrypt
|-
| Force SSL || On
|-
| HTTP/2 Support || On
|-
| HSTS Enabled || Off (optional, enable after confirming working)
|}

{{Warning|Websockets Support must be On. Mastodon uses WebSockets for the live timeline feed. Without it the interface loads but does not update in real time.}}

{{Note|The domain must already have a DNS A record pointing to your public IP before requesting a Let's Encrypt certificate. Verify with: <code>curl -s https://dns.google/resolve?name=toot.yourdomain.com | grep data</code>}}

== Step 7 — Create Admin Account ==

Mastodon starts with zero accounts. Create your owner account from the command line:

<syntaxhighlight lang="bash">
docker exec -it mastodon /app/www/bin/tootctl accounts create YOUR_USERNAME --email YOUR@EMAIL --confirmed --role Owner
</syntaxhighlight>

The command outputs a randomly generated password. Copy it immediately. Log in at <code>https://toot.yourdomain.com</code> with your email and that password.

{{Warning|After logging in you will see a 'pending review' banner even on your own account. This is because registrations require admin approval. Approve yourself with:}}

<syntaxhighlight lang="bash">
docker exec -it mastodon /app/www/bin/tootctl accounts approve YOUR_USERNAME
</syntaxhighlight>

Then change your password immediately in Settings > Account > Account Settings.

== Problems Encountered and Countermeasures ==

{| class="wikitable"
! Problem !! Cause !! Fix
|-
| Crash loop: ACTIVE_RECORD_ENCRYPTION keys missing || New requirement in Mastodon 4.3+. Container exits immediately without these three keys set. || Generate with: <code>docker run --rm --entrypoint="" -w /app/www lscr.io/... /app/www/bin/rails db:encryption:init</code>
|-
| Redis: connect ECONNREFUSED 127.0.0.1:6379 || Redis service not in same compose file, or containers not on same Docker network. || Add redis service to same docker-compose.yml with a shared named network (mastodon-net).
|-
| bin/rails: no such file or directory || linuxserver entrypoint intercepts the command before rails runs. || Always use <code>--entrypoint=""</code> and full path: <code>/app/www/bin/rails</code>
|-
| No Rakefile found error for rake tasks || Working directory not set; rake cannot find the app root. || Add <code>-w /app/www</code> to the docker run command.
|-
| 301 redirect loop at toot.yourdomain.com || Internal nginx passes X-Forwarded-Proto: http to Rails. Rails sees HTTP and redirects to HTTPS infinitely. || Sed-edit both default.conf and default.conf.sample to hardcode X-Forwarded-Proto https. Reload nginx with s6-svc.
|-
| NO_SSL=true and FORCE_SSL=false not working || FORCE_SSL was removed in newer Mastodon. NO_SSL prevents regenerating the config but cannot fix an already-generated config. || Edit the nginx config files directly. The sample must also be edited or changes are overwritten on restart.
|-
| 403 Forbidden on curl test || Host header mismatch. Mastodon's nginx rejects requests where the Host header does not match LOCAL_DOMAIN. || Always test with: <code>curl -v http://localhost:8667 -H "Host: toot.yourdomain.com"</code>
|-
| Pending review banner after login || Mastodon requires admin approval for all accounts including ones created via tootctl. || Run: <code>docker exec -it mastodon /app/www/bin/tootctl accounts approve YOUR_USERNAME</code>
|-
| Port 80/443 already in use || NPM is already running on those ports on the host. || Map Mastodon to an unused host port (e.g. 8667:80). NPM proxies to it. Drop the 443 mapping entirely.
|-
| Container still starting when testing || Mastodon takes 30-60 seconds to fully boot. curl or browser tests fail during this window. || Watch logs: <code>docker compose logs -f mastodon</code>. Only test after seeing [ls.io-init] done.
|}

== Instructions for AI Agent Execution ==

If you are an AI agent following this guide, use this decision tree at each stage:

=== At each step, verify before proceeding ===

# Run the command exactly as written.
# Check the output against the expected output described.
# If the output does not match, consult the Problems table above before retrying.
# Never proceed to the next step if the current step has not produced the expected output.

=== Key verification commands ===

<syntaxhighlight lang="bash">
# Is the container running?
docker compose ps

# Is it fully booted?
docker compose logs mastodon | tail -20
# Look for: [ls.io-init] done.

# Is nginx listening on port 80 inside the container?
docker exec mastodon netstat -tlnp
# Look for: 0.0.0.0:80 LISTEN nginx

# Is Mastodon responding correctly?
curl -v http://localhost:8667 -H "Host: toot.yourdomain.com"
# Look for: HTTP/1.1 200 OK
# A 301 means the nginx X-Forwarded-Proto fix has not been applied yet.

# Are all env vars present?
docker exec mastodon env | grep -E 'ACTIVE_RECORD|SECRET|VAPID|NO_SSL|FORCE'
# All seven secrets must appear with non-empty values.

# What ports are in use on the host?
docker ps --format "table {{.Names}}\t{{.Ports}}"
</syntaxhighlight>

{{Tip|If the container is crash-looping, you cannot exec into it. Use <code>docker run --rm --entrypoint=""</code> to run one-off commands against the image instead.}}

== Post-Setup Checklist ==

* [ ] Change your admin password in Settings > Account > Account Settings
* [ ] Enable Two-Factor Authentication in Settings > Account > Two-Factor Auth
* [ ] Set up server rules and description in Admin > Server Settings
* [ ] Close registrations or set to invite-only in Admin > Server Settings > Registrations
* [ ] Revoke any SMTP credentials exposed during setup and generate new ones
* [ ] Back up /opt/mastodon/config and /opt/mastodon/postgres regularly
* [ ] Back up your docker-compose.yml and store it in Forgejo or another version-controlled location

{{Critical|The ACTIVE_RECORD_ENCRYPTION keys and all secrets in docker-compose.yml are the most critical backup. If these are lost and the database is intact, recovery is extremely difficult.}}

[[Category:Open Source]]
[[Category:Tutorials]]
[[Category:Docker]]
[[Category:Self-Hosting]]
[[Category:System Administration]]

Portainer to Docker Compose Migration Guide

2026-04-02T12:07:31Z

Justinaquino: Created page with "= Migrating from Portainer to Docker Compose = == A Field-Tested Guide with Real Mistakes and How to Fix Them == '''Context:''' This tutorial was built from a real migration of a home server (Dell Optiplex 3070 Micros) running multiple services in Portainer, moved to pure Docker Compose under <code>/opt/stacks/</code>. It includes every mistake made along the way and how to recover. '''Target audience:''' Someone who knows basic Linux and Docker but may forget steps,..."

= Migrating from Portainer to Docker Compose =

== A Field-Tested Guide with Real Mistakes and How to Fix Them ==

'''Context:''' This tutorial was built from a real migration of a home server (Dell Optiplex 3070 Micros) running multiple services in Portainer, moved to pure Docker Compose under <code>/opt/stacks/</code>. It includes every mistake made along the way and how to recover.

'''Target audience:''' Someone who knows basic Linux and Docker but may forget steps, mix up machines, or make assumptions that get them in trouble.

== The Big Picture ==

=== What we are doing ===
Moving services managed by Portainer (which has its own hidden config layer) into clean, self-contained Docker Compose stacks stored under <code>/opt/stacks/</code>. Each service gets its own folder with a <code>compose.yml</code> and <code>.env</code> file.

=== Why this matters for backup ===
Everything lives under <code>/opt/stacks/</code> — one folder to back up, one folder to restore. No hunting for Portainer's hidden volumes or config files.

=== The 3-2-1 backup goal ===
* '''Copy 1:''' Live data on PC03 (primary server)
* '''Copy 2:''' Warm backup on PC02 (sleeps, wakes via WoL 3x/day and on failure)
* '''Copy 3:''' Synology NAS (cold archive, always on)

== Before You Start: Know Your Environment ==

=== Check which machine you are on ===
<syntaxhighlight lang="bash">
hostname
# Should print something like PC03dell3050
</syntaxhighlight>

'''Common mistake:''' Running commands on PC02 when you think you are on PC03, or vice versa. Always check <code>hostname</code> before doing anything destructive.

=== Know your folder structure ===
<pre>
/opt/stacks/
├── wordpress/
│ ├── compose.yml
│ ├── .env
│ ├── wordpress_data/ ← webroot files
│ └── db_data/ ← database files
├── mediawiki/
├── zulip/
├── openwebui/
└── ...
</pre>

All data lives INSIDE the stack folder as bind mounts. No named Docker volumes. This makes backup and restore straightforward.

=== Know your user situation ===
Most of these operations require root. If you are logged in as a regular user:
<syntaxhighlight lang="bash">
sudo -i
# or
su -
# enter root password when prompted
</syntaxhighlight>

'''If you cannot write to /opt/stacks/,''' you are not root. Do not proceed until you are.

== Step 0: Preparation Checklist ==

Before migrating any service, do these once:

=== Create the shared Docker network ===
All services and NPM (your reverse proxy) share this network:
<syntaxhighlight lang="bash">
docker network create npm_proxy
</syntaxhighlight>
Safe to run even if it already exists — it will just say it already exists.

=== Create the base stacks directory ===
<syntaxhighlight lang="bash">
mkdir -p /opt/stacks
</syntaxhighlight>

== Step 1: Read the Portainer Stack ==

In Portainer, go to '''Stacks → [stack name] → Editor''' and copy the entire compose content.

'''What to look for:'''

{| class="wikitable"
! Field !! What it tells you
|-
| <code>image:</code> || The Docker image and version
|-
| <code>ports:</code> || Host port → container port mapping
|-
| <code>volumes:</code> || Where data lives — see below
|-
| <code>environment:</code> || Credentials and config — '''do not lose these'''
|-
| <code>container_name:</code> || The exact name Docker uses — you will need this
|}

=== Understanding volumes — the most important thing ===

Portainer stacks can use two types of volumes:

'''Type 1 — Named volumes''' (Portainer manages them, hidden location):
<syntaxhighlight lang="yaml">
volumes:
- mydata:/var/lib/data
volumes:
mydata:
</syntaxhighlight>
The actual files are at <code>/var/lib/docker/volumes/STACKNAME_mydata/_data/</code>

'''Type 2 — Bind mounts''' (explicit path on the host):
<syntaxhighlight lang="yaml">
volumes:
- /home/user/myapp/data:/var/lib/data
</syntaxhighlight>
The files are exactly where the path says.

'''How to tell which type you have:''' If the volume line has a full path starting with <code>/</code>, it is a bind mount. If it is just a name with no <code>/</code>, it is a named volume.

== Step 2: Find Where the Data Actually Is ==

=== For named volumes — Portainer renames them ===
'''Critical:''' Portainer adds the stack name as a prefix. If your stack is named <code>wp240927</code> and your volume is named <code>db</code>, the actual Docker volume name is <code>wp240927_db</code>.

Find the real names:
<syntaxhighlight lang="bash">
docker volume ls | grep -i KEYWORD
# Example:
docker volume ls | grep -i wordpress
</syntaxhighlight>

Find the actual path on disk:
<syntaxhighlight lang="bash">
docker volume inspect VOLUMENAME
# Look for "Mountpoint" in the output
# Example output:
# "Mountpoint": "/var/lib/docker/volumes/wp240927_db/_data"
</syntaxhighlight>

=== For bind mounts ===
Just check if the path exists:
<syntaxhighlight lang="bash">
ls /home/user/wp250223-8070/
</syntaxhighlight>

== Step 3: Create the New Stack Files ==

=== Directory structure ===
<syntaxhighlight lang="bash">
mkdir -p /opt/stacks/SERVICENAME/data_folder_name
</syntaxhighlight>

=== Create compose.yml ===
Use <code>cat ></code> to write the file directly in the terminal. This avoids file transfer issues:

<syntaxhighlight lang="bash">
cat > /opt/stacks/SERVICENAME/compose.yml << 'EOF'
services:
app:
image: someimage:latest
restart: unless-stopped
ports:
- "PORT:PORT"
environment:
SOME_VAR: ${SOME_VAR}
volumes:
- ./data:/app/data
networks:
- proxy

networks:
proxy:
external: true
name: npm_proxy
EOF
</syntaxhighlight>

'''Key changes from the Portainer version:'''
* Remove <code>version:</code> line (obsolete in modern Compose)
* Change <code>restart: always</code> to <code>restart: unless-stopped</code>
* Move credentials out of <code>environment:</code> into <code>.env</code> using <code>${VAR_NAME}</code> syntax
* Change named volume paths to <code>./foldername</code> (relative bind mounts)
* Add the <code>npm_proxy</code> network so NPM can reach the service

=== Create .env file ===
<syntaxhighlight lang="bash">
cat > /opt/stacks/SERVICENAME/.env << 'EOF'
DB_NAME=mydb
DB_USER=myuser
DB_PASSWORD=change_this_password
EOF
</syntaxhighlight>

'''Critical:''' The values in <code>.env</code> must match what is already inside your database files. If you copy the DB files from the old stack, use the same credentials the old stack had. Changing them will break the connection.

'''How to find the original credentials:''' Before stopping the old stack, go to Portainer → Stack → Editor and read the environment variables.

== Step 4: Copy the Data ==

=== Stop the old Portainer stack first ===
Go to Portainer → Stacks → [stack name] → '''Stop'''.

'''Do NOT delete it yet.''' It is your rollback. Only delete after you confirm the new stack works.

=== For bind mount data (path already known) ===
<syntaxhighlight lang="bash">
rsync -av --progress \
/old/path/data/ \
/opt/stacks/SERVICENAME/data/
</syntaxhighlight>

'''The trailing slash on the source matters.''' With a trailing slash, rsync copies the contents. Without it, rsync copies the folder itself (creating an extra nesting level).

=== For named volume data (path from docker volume inspect) ===
<syntaxhighlight lang="bash">
rsync -av --progress \
/var/lib/docker/volumes/STACKNAME_VOLUMENAME/_data/ \
/opt/stacks/SERVICENAME/data/
</syntaxhighlight>

=== For data on another machine (SSH) ===
If rsync is available on both machines:
<syntaxhighlight lang="bash">
# Run on the destination machine, pulling from source
rsync -av --progress -e ssh \
root@SOURCE_IP:/var/lib/docker/volumes/STACKNAME_VOLUMENAME/_data/ \
/opt/stacks/SERVICENAME/data/
</syntaxhighlight>

If rsync is NOT installed on the source machine:
<syntaxhighlight lang="bash">
# On source machine: create a tar archive
tar -czvf /home/user/service-backup.tar.gz \
/var/lib/docker/volumes/STACKNAME_vol1/_data \
/var/lib/docker/volumes/STACKNAME_vol2/_data

# Transfer via SCP from destination
scp root@SOURCE_IP:/home/user/service-backup.tar.gz /opt/stacks/SERVICENAME/
</syntaxhighlight>

Then extract directly into target folders:
<syntaxhighlight lang="bash">
cd /opt/stacks/SERVICENAME

tar -xzvf service-backup.tar.gz \
--strip-components=6 \
-C data/subfolder \
var/lib/docker/volumes/STACKNAME_vol1/_data
</syntaxhighlight>

'''The <code>--strip-components</code> number''' = how many path levels to strip. Count the slashes in <code>var/lib/docker/volumes/STACKNAME_vol1/_data</code> — that is 6 components (var, lib, docker, volumes, STACKNAME_vol1, _data).

'''If you cannot write to /opt/stacks/ via SFTP:''' Upload to <code>/home/user/</code> instead, then move:
<syntaxhighlight lang="bash">
mv /home/user/service-backup.tar.gz /opt/stacks/SERVICENAME/
</syntaxhighlight>

=== Fix file ownership after copying ===
Different services run as different users inside their containers:

{| class="wikitable"
! Service !! uid:gid !! Why
|-
| WordPress (webroot) || 33:33 || www-data
|-
| MariaDB / MySQL || 999:999 || mysql
|-
| PostgreSQL || 70:70 || postgres
|-
| Most Node apps || 1000:1000 || node
|-
| RabbitMQ || 999:999 || rabbitmq
|-
| Redis || 999:999 || redis
|}

<syntaxhighlight lang="bash">
chown -R 33:33 /opt/stacks/wordpress/wordpress_data/
chown -R 999:999 /opt/stacks/wordpress/db_data/
</syntaxhighlight>

== Step 5: Start the New Stack ==

<syntaxhighlight lang="bash">
cd /opt/stacks/SERVICENAME
docker compose up -d
</syntaxhighlight>

Watch the logs:
<syntaxhighlight lang="bash">
docker compose logs -f
</syntaxhighlight>

Press <code>Ctrl+C</code> to stop watching logs. '''This does NOT stop the containers.'''

Test locally before checking the public URL:
<syntaxhighlight lang="bash">
curl -I http://localhost:PORT
</syntaxhighlight>

Expected responses:
* <code>200 OK</code> — service is up and working
* <code>301 Moved Permanently</code> — service is up, redirecting (usually HTTP→HTTPS, this is fine)
* <code>500 Internal Server Error</code> — service is up but something is wrong (usually credentials)
* <code>Connection refused</code> — container is not running or wrong port

== Common Mistakes and How to Fix Them ==

=== Mistake 1: Old container still running, new one cannot start ===

'''Symptom:'''
<pre>
Error response from daemon: Conflict. The container name "/myapp" is already in use
</pre>

'''Cause:''' Stopping a Portainer stack does not always stop the containers. Portainer stopped managing them but left them running.

'''Fix:'''
<syntaxhighlight lang="bash">
docker rm -f CONTAINERNAME
# Then retry:
docker compose up -d
</syntaxhighlight>

=== Mistake 2: Wrong credentials in .env — database refuses connection ===

'''Symptom:''' <code>500 Internal Server Error</code> or "Error establishing database connection"

'''Cause:''' The <code>.env</code> credentials do not match what is stored inside the database files. The database files remember what credentials they were initialized with.

'''Diagnosis — check what the container actually sees:'''
<syntaxhighlight lang="bash">
docker compose exec SERVICENAME env | grep DB_
# or for WordPress specifically:
docker compose exec wordpress env | grep WORDPRESS_DB
</syntaxhighlight>

'''Diagnosis — test the credentials directly:'''
<syntaxhighlight lang="bash">
docker compose exec db mariadb -u USERNAME -p'PASSWORD' DBNAME -e "SELECT 1;"
# If it returns "1", those credentials work.
</syntaxhighlight>

'''Fix:''' Edit <code>.env</code> to match the credentials that actually work, then do a FULL restart:
<syntaxhighlight lang="bash">
docker compose down
docker compose up -d
</syntaxhighlight>

'''Critical:''' <code>docker compose restart</code> does NOT re-read <code>.env</code>. You must use <code>down</code> + <code>up</code>.

=== Mistake 3: Portainer volume names are different from what the compose file says ===

'''Symptom:''' <code>docker volume inspect VOLUMENAME</code> returns <code>no such volume</code>

'''Cause:''' Portainer prefixes volumes with the stack name. If your stack is <code>wp240927</code> and your volume is <code>db</code>, the real name is <code>wp240927_db</code>.

'''Fix:'''
<syntaxhighlight lang="bash">
docker volume ls | grep -i KEYWORD
# Use the full name shown in the output
</syntaxhighlight>

=== Mistake 4: Data lands in the wrong place after extraction ===

'''Symptom:''' <code>ls data/postgresql/</code> shows <code>_data</code> instead of actual database files

'''Cause:''' <code>--strip-components</code> count was wrong, or the tar had an unexpected nesting level.

'''Fix — check what is actually there:'''
<syntaxhighlight lang="bash">
find /opt/stacks/SERVICENAME -name "PG_VERSION" 2>/dev/null
find /opt/stacks/SERVICENAME -name "*.conf" 2>/dev/null | head -5
</syntaxhighlight>

Then move the contents up:
<syntaxhighlight lang="bash">
mv data/postgresql/_data/* data/postgresql/
rmdir data/postgresql/_data
</syntaxhighlight>

=== Mistake 5: .env changes not taking effect ===

'''Symptom:''' You edited <code>.env</code> and restarted, but the container still uses old values.

'''Cause:''' <code>docker compose restart</code> only restarts the process, it does not rebuild the environment.

'''Fix:'''
<syntaxhighlight lang="bash">
docker compose down
docker compose up -d
</syntaxhighlight>

Verify the new values are actually injected:
<syntaxhighlight lang="bash">
docker compose exec SERVICENAME env | grep VARNAME
</syntaxhighlight>

=== Mistake 6: NPM proxy still pointing to old IP/port after migration ===

'''Symptom:''' Service is running locally (<code>curl -I http://localhost:PORT</code> returns 200) but the public domain gives 502 Bad Gateway.

'''Cause:''' NPM's proxy host was pointing to the old machine's IP or old port.

'''Fix:''' In NPM → Proxy Hosts → Edit the domain → update Forward Hostname to the new IP or <code>localhost</code>.

=== Mistake 7: Zulip/service doing HTTP→HTTPS redirect loop through NPM ===

'''Symptom:''' "This page isn't redirecting properly" error in browser.

'''Cause:''' Service internally redirects HTTP to HTTPS, but NPM is sending HTTP. The service sends back a 301 to HTTPS, which loops.

'''Fix:''' In NPM, change the scheme to <code>https</code> and expose the service's HTTPS port instead of the HTTP port. Also disable SSL verification in NPM since services often use self-signed certs.

== Verifying Everything Works ==

After bringing up each service:

<syntaxhighlight lang="bash">
# 1. Check containers are running
docker compose ps

# 2. Check logs for errors
docker compose logs --tail=20

# 3. Test local connectivity
curl -I http://localhost:PORT

# 4. Check the public domain loads
# (Do this in your browser)

# 5. Verify data survived (service-specific)
# For WordPress: log into wp-admin and check posts
# For Wiki: browse to a page you know exists
# For Zulip: log in and check message history
</syntaxhighlight>

== After Confirming a Service Works ==

Wait 24–48 hours of stable operation, then:

# In Portainer: '''Delete''' the old stack
# Clean up old data directories if they were bind mounts:
<syntaxhighlight lang="bash">
rm -rf /home/user/old-stack-data/
</syntaxhighlight>
# Clean up orphaned named volumes:
<syntaxhighlight lang="bash">
docker volume ls | grep OLDSTACKNAME
docker volume rm OLDSTACKNAME_volumename
</syntaxhighlight>

== Backup Strategy (What This All Feeds Into) ==

Once all services are under <code>/opt/stacks/</code>, the backup is simple:

'''PC03 → Synology (3x daily via Restic):'''
<syntaxhighlight lang="bash">
restic -r sftp:synology:/backups/pc03 backup /opt/stacks/
</syntaxhighlight>

'''PC02 warm backup:'''
* PC02 sleeps most of the time
* Synology watchdog pings PC03 every 60s
* If PC03 fails 3 checks → Synology sends WoL magic packet → PC02 wakes
* PC06 relay (iptables DNAT) switches traffic to PC02
* When PC03 comes back → Restic syncs PC02→PC03 → manual confirm → traffic switches back

'''PC00 desktop → Synology (daily):'''
<syntaxhighlight lang="bash">
restic -r sftp:synology:/backups/pc00 backup /home/USERNAME/
</syntaxhighlight>

== Quick Reference: Ports Used ==

{| class="wikitable"
! Service !! Port !! Domain
|-
| WordPress || 8070 || blog.gi7b.org
|-
| MediaWiki || 8191 || wiki.gi7b.org
|-
| Open WebUI || 3000 || —
|-
| SearXNG || 8290 || —
|-
| Zulip || 8010 (HTTP), 8011 (HTTPS) || chat.gi7b.org
|-
| Forgejo || 3001 || —
|-
| Gemini sites || 27081 || —
|-
| Jitsi || TBD || meet.gi7b.org
|-
| Grafana || TBD || —
|-
| Frappe || TBD || —
|}

== Giving This Context to a New AI Chat ==

Paste this block at the start of a new conversation:

<pre>
I am continuing a home server migration project. Here is the context:

Setup:
- PC03 (192.168.196.76) = primary server, Dell Optiplex 3070, Ubuntu, Docker Compose
- PC02 (192.168.196.189) = warm backup, same hardware, sleeps until needed
- PC06 = Contabo Japan VPS, pure iptables DNAT relay (no NGINX), forwards traffic to PC03
- Synology NAS = always on, cold backup archive, runs watchdog container
- ZeroTier connects all machines

All stacks live under /opt/stacks/SERVICENAME/ on PC03
Each stack has: compose.yml, .env, and data folders as bind mounts
Shared Docker network: npm_proxy (external)
Reverse proxy: NGINX Proxy Manager (NPM) running as its own stack on PC03

Completed migrations (Portainer → Docker Compose):
- WordPress (blog.gi7b.org) → port 8070 ✓
- MediaWiki (wiki.gi7b.org) → port 8191 ✓ (check status)
- Open WebUI → port 3000 ✓
- SearXNG → port 8290 ✓
- Zulip (chat.gi7b.org) → port 8010/8011 ✓ (troubleshooting NPM HTTPS)
- Forgejo → port 3001 ✓ (fresh install, no data migration)
- Gemini-sites → port 27081 ✓

Still to do:
- Jitsi (meet.gi7b.org)
- Grafana + Prometheus
- Frappe / ERPNext
- PC06 iptables watchdog script
- Synology WoL watchdog container
- Restic backup setup (PC03→Synology, PC02 agent, PC00→Synology)
- Clean up abandoned Mastodon volumes on PC03
</pre>

[[Category:Tutorials]]
[[Category:Docker]]
[[Category:System Administration]]
[[Category:Self-Hosting]]

NPM Migration to Homelab VPS Relay 260401

2026-03-31T18:20:36Z

Justinaquino: "Add NPM migration to homelab VPS relay guide"

= Migrating NGINX Proxy Manager Off a Compromised VPS =

''A practical runbook for moving NPM to your homelab and turning your VPS into a pure relay.''

----

== Background and Lessons Learned ==

This tutorial documents a real incident where a VPS running NGINX Proxy Manager (NPM) became compromised. The infection vector was a Minecraft server setup tutorial that turned out to be malware — it used the server's open Postfix port to send approximately 28,000 spam emails before being detected.

'''The core lesson:''' Never install experimental software directly on a bare server. Use Distrobox containers or Docker for anything you are testing or following a tutorial for. The host OS should only run what you deliberately chose to put there.

'''The architectural lesson:''' NPM is surprisingly easy to back up and restore. This means you do not need to keep it on an expensive VPS. A cheap VPS can be reduced to a pure traffic relay, with NPM and all services running on hardware you own at home.

----

== Architecture Overview ==

<pre>
Internet → VPS (pure relay, iptables DNAT) → ZeroTier → Home server NPM → your services
</pre>

{| class="wikitable"
|-
! Component !! Role
|-
| VPS (e.g. Contabo) || Public IP relay only — iptables forwards port 80/443 over ZeroTier
|-
| PC03 (primary) || Runs NPM + all Docker services
|-
| PC02 (warm backup) || NPM mirror, ready to take over
|-
| Synology NAS || Always-on backup repository, watchdog, cold archive
|}

The failover flow is: '''detect''' (PC06 watchdog, 3 fails trigger) → '''wake''' (PC06 → Synology sends WoL → PC02 boots) → '''failover''' (DNAT swaps to PC02 once NPM responds). Restic runs 3×/day to Synology from PC03, and mirrors to PC02 on wake.

=== Why this works without a static home IP ===

Your home ISP likely does not give you a static public IP. That does not matter here. Both the VPS and your home servers are connected via ZeroTier, which assigns fixed private IPs regardless of what your ISP does. The VPS always knows where to forward traffic.

=== Approximate hardware costs (Philippine Peso) ===

{| class="wikitable"
|-
! Hardware !! Cost
|-
| VPS (e.g. Contabo, annual) || ₱5,000/yr
|-
| Dell OptiPlex micro (16GB RAM, 256GB SSD) × 2 || ₱10,000 each
|-
| Synology NAS with 2 × 3.5TB IronWolf || ₱28,000
|}

A system good for 7–10 years, with full redundancy, for roughly what a single mid-tier cloud server costs annually.

----

== Part 1 — Backing Up NPM ==

=== Step 1 — Identify your NPM setup ===

First confirm whether your NPM is using SQLite (simpler) or MariaDB (more common in older installs):

<syntaxhighlight lang="bash">
docker ps
</syntaxhighlight>

If you see a separate <code>mariadb</code> or <code>mariadb-aria</code> container alongside NPM, you are on the MariaDB variant. This tutorial covers that setup.

Find your compose file:

<syntaxhighlight lang="bash">
find /root /opt /etc/docker -name "docker-compose.yml" 2>/dev/null
</syntaxhighlight>

Check where NPM mounts its data:

<syntaxhighlight lang="bash">
docker inspect <npm-container-name> | grep -A 20 '"Mounts"'
docker inspect <db-container-name> | grep -A 20 '"Mounts"'
</syntaxhighlight>

Note the <code>Source</code> paths — everything NPM needs is in those directories.

=== Step 2 — Create the backup ===

Run this as root. Replace <code>/data/compose/3</code> with your actual mount paths if different.

<syntaxhighlight lang="bash">
# Create staging directory
mkdir -p /root/npm-backup/zt

# Back up ZeroTier identity (preserves your ZT IP after reformat)
cp /var/lib/zerotier-one/identity.secret /root/npm-backup/zt/
cp /var/lib/zerotier-one/identity.public /root/npm-backup/zt/

# Back up the compose file
cp /root/nginx-pm<your-folder>/docker-compose.yml /root/npm-backup/

# Dump the database (do this while containers are running)
docker exec <db-container-name> \
mysqldump -u npm -pnpm npm > /root/npm-backup/npm-db-dump.sql

# Archive all NPM data (app config, SSL certs, MySQL files)
tar -czvf /root/npm-backup/npm-data.tar.gz /data/compose/3/

# Verify
ls -lh /root/npm-backup/
</syntaxhighlight>

Check that <code>npm-db-dump.sql</code> is not zero bytes. If it is, the dump failed silently — the raw MySQL files in <code>npm-data.tar.gz</code> will be your restore source instead.

=== Step 3 — Transfer to your NAS or local machine ===

<syntaxhighlight lang="bash">
rsync -avz --progress \
/root/npm-backup/ \
user@<NAS-IP>:/volume1/backups/npm/
</syntaxhighlight>

Or compress first:

<syntaxhighlight lang="bash">
cd /root
tar -czvf npm-backup.tar.gz npm-backup/
rsync -avz --progress npm-backup.tar.gz user@<NAS-IP>:/volume1/backups/npm/
</syntaxhighlight>

----

== Part 2 — Restoring NPM on a New Machine ==

All commands run as root. The backup file goes in <code>/root/</code>.

'''Important:''' NPM data always restores to the same absolute path (<code>/data/compose/3/</code>) regardless of which machine you are on. This is hardcoded in the compose file. Do not change it.

=== Step 1 — Extract the backup ===

<syntaxhighlight lang="bash">
cd /root
tar -xzvf npm-backup.tar.gz
ls npm-backup/
</syntaxhighlight>

You should see: <code>docker-compose.yml</code>, <code>npm-data.tar.gz</code>, <code>npm-db-dump.sql</code>, <code>zt/</code>

=== Step 2 — Restore data files ===

<syntaxhighlight lang="bash">
# Extract directly to / — this recreates /data/compose/3/ automatically
tar -xzvf /root/npm-backup/npm-data.tar.gz -C /

# Verify
ls /data/compose/3/
# Should show: data letsencrypt mysql
</syntaxhighlight>

=== Step 3 — Deploy the stack ===

<syntaxhighlight lang="bash">
mkdir -p /root/nginx-pm
cp /root/npm-backup/docker-compose.yml /root/nginx-pm/

cd /root/nginx-pm
docker compose up -d

docker ps
</syntaxhighlight>

Both the NPM app container and the MariaDB container should show as running.

=== Step 4 — Verify ===

Open <code>http://<machine-IP>:81</code> in a browser. Your proxy hosts, SSL certificates, and settings should all be present exactly as they were.

----

== Part 3 — Setting Up the VPS as a Pure Relay ==

After reformatting your VPS, the entire setup is:

=== Step 1 — Install ZeroTier and join your network ===

<syntaxhighlight lang="bash">
curl -s https://install.zerotier.com | bash
zerotier-cli join <your-network-id>
</syntaxhighlight>

Then go to your ZeroTier Central dashboard, authorize the new node, and assign it your chosen fixed IP (e.g. the same IP it had before).

'''Note on ZeroTier IP preservation:''' You do not need to restore the ZeroTier identity files to keep the same IP. Simply authorize the new node in ZT Central and manually assign the same managed IP there. The identity restore is only needed if you specifically want the same node ID.

'''Contabo UI warning:''' Contabo's control panel is easy to misclick. Always double-check which server you have selected before clicking reformat. The interface can make it easy to accidentally act on the wrong server.

=== Step 2 — Enable IP forwarding and set up relay rules ===

Replace <code>192.168.196.76</code> with your home server's ZeroTier IP.

<syntaxhighlight lang="bash">
# Enable forwarding
echo "net.ipv4.ip_forward=1" >> /etc/sysctl.conf
sysctl -p

# Forward web traffic to home NPM
iptables -t nat -A PREROUTING -p tcp --dport 80 -j DNAT --to-destination 192.168.196.76:80
iptables -t nat -A PREROUTING -p tcp --dport 443 -j DNAT --to-destination 192.168.196.76:443
iptables -t nat -A POSTROUTING -j MASQUERADE

# Make rules persistent across reboots
apt install iptables-persistent -y
netfilter-persistent save
</syntaxhighlight>

=== Step 3 — Verify ===

<syntaxhighlight lang="bash">
iptables -t nat -L -n -v
</syntaxhighlight>

You should see packet counters incrementing on the DNAT rules as traffic arrives.

----

== Part 4 — Hardening WordPress Behind NPM ==

After migrating, a brute force attack on <code>/wp-login.php</code> was detected within hours. Two layers of protection:

=== Layer 1 — Hide the login URL ===

Install the '''WPS Hide Login''' plugin in WordPress:

# WordPress admin → Plugins → Add New → search <code>WPS Hide Login</code>
# Install and activate
# Settings → WPS Hide Login → set a custom login path (e.g. <code>/your-secret-path</code>)
# Save

The default <code>/wp-login.php</code> now returns 404 to everyone.

=== Layer 2 — Restrict via NPM custom location ===

In NPM, edit your WordPress proxy host → Custom Locations tab:

Add location: <code>/wp-login.php</code>
* Forward Hostname/IP: <code><wordpress-server-IP></code>
* Forward Port: <code><wordpress-port></code>
* In the gear/config box, add:

<syntaxhighlight lang="nginx">
allow 192.168.196.0/24;
deny all;
</syntaxhighlight>

Repeat for <code>/wp-admin/</code>.

This means even if someone discovers your hidden login URL, they cannot reach it unless they are on your ZeroTier network.

----

== Key Takeaways ==

'''On security:'''
* Never follow tutorials directly on a bare server. Use Distrobox or Docker to isolate experiments.
* Check for open mail relays — an open Postfix is a common infection consequence.
* Bots scan for <code>/wp-login.php</code> within hours of a site going live. Hide it and restrict it immediately.

'''On operations:'''
* NPM is stateless enough to be fully backed up in a single tar file and restored in under 15 minutes.
* ZeroTier makes home servers first-class infrastructure — a cheap VPS becomes just a public IP rental.
* Always run <code>docker ps</code> and <code>ss -tlnp</code> before and after a migration to confirm port ownership.
* When restoring, mind whether you are logged in as root or a regular user — file paths differ and commands like <code>tar -C /</code> require root.

'''On architecture:'''
* A ₱5,000/yr VPS as a pure relay is far more resilient than a ₱15–30k/yr VPS running everything. When it gets compromised again, you reformat it in 15 minutes with nothing to lose.
* SSL certificate renewals continue to work transparently through the relay — Let's Encrypt ACME challenges on port 80 get forwarded to your home NPM automatically.

[[Category:System Administration]]
[[Category:Networking]]
[[Category:Docker]]
[[Category:Tutorials]]
[[Category:ZeroTier]]
[[Category:Security]]

Main Page

2026-03-31T18:20:36Z

Justinaquino: "Add NPM migration to homelab VPS relay guide"

__NOTOC__
<div style="background:#f8f9fa; border:1px solid #ddd; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
Welcome to the '''Comfac IT Knowledge Base'''. Use the sections below to find guides, SOPs, and references organized by topic.
</div>

== ERPNext / Frappe ==
<div style="column-count:2; column-gap:2em;">
* [[Frappe HRMS]] — '''HR & Payroll''' (with Philippine Localization)
* [[Frappe ERPNext/Webshop]] — '''E-Commerce Webshop''' (setup, architecture, chapters)
* [[Manufacturing v16 260125]]
* [[ERpnext Asset Management Procedure 260113]]
* [[ERPNext HR Module Outline]]
* [[ERPNEXT Payroll POC 251212]]
* [[Comfac ERPNext Strategy Canvas (Expanded)]]
* [[PAD-Driven ERPNext Strategy 260303]] — PAD/AI-agentic implementation strategy for Frappe ERPNext
* [[ERPNext v15 Docker Setup Guide]] — Local Docker setup for evaluation, testing, and student use
* [[Frappe Links and References]]
* [[Using Frappe Wiki]]
* [https://docs.frappe.io/cloud/guidelines-for-contributing-regional-compliance-app Guidelines for Contributing Regional Compliance App]
* [https://docs.frappe.io/cloud/what-are-benches-and-bench-groups What are Benches?]
</div>

== System Administration & Self-Hosting ==
<div style="column-count:2; column-gap:2em;">
* [[NPM Migration to Homelab VPS Relay 260401]] — Move NPM off a compromised VPS; VPS becomes a pure iptables/ZeroTier relay with homelab redundancy
* [[pfSense Sales Training Material]]
* [[SOP: Network Troubleshooting & pfSense Monitoring 251130]]
* [[Modern Guide: pfSense Captive Portal with FreeRADIUS & ACME]]
* [[pfSense CE → pfSense Plus Upgrade Guide]]
* [[Tplink Mikrotik Equivalent]]
* [[Skills and Competencies for IT Staff Trained in pfSense]]
* [[System Hardening Strategy: Win2Lin Migration & Infrastructure 251129]]
* [[Controller Systems 251213-01]]
* [[Power Distribution Tree 251213]]
* [[Introduction: Why Self-Host Your Email?]]
* [[Mailcow + Thunderbird Setup Guide (Email + Calendar)]]
* [[Mailcow SOGo: Creating Filters for Events, Approvals, and Organizational Emails]]
* [[Spoof Timezone Extension – Setup Guide for Comfac Staff]]
* [[Viber Focus-Stealing]]
* [[🌐 WordPress Website — *You Own Everything, Learn Everything*]]
</div>

== Storage & Hardware ==
<div style="column-count:2; column-gap:2em;">
* [[TrueNAS Configuration Options & Scale Options 251130]]
* [[TrueNAS Business Plan: Project 251212]]
* [[Comparison: TrueNAS Mini X+ vs Dell Precision 3680 Tower (2025)]]
* [[Backblaze Drive Stats for Server and Storage Qualification]]
* [[Industrial Controllers and Water Utilities 251011]]
</div>

== AI & Machine Learning ==
<div style="column-count:2; column-gap:2em;">
* [[OpenWebUI - 251128-justin]]
* [[Comfac GPU Scaling and AI Research Goals]]
* [[🧠 Process: Selecting and Installing the Right Ollama Model for Your Hardware]]
* [[Ollama GNOME System Tray Panel 260401]] — GNOME system tray toggle to start/stop Ollama and reclaim VRAM
* [[Proceedural Agentic Development Methodology 260304]] — Methodology for systematic agent use
* [[Project OpenCoder: AI Independence Initiative]] — Strategic roadmap for manufacturing intelligence
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 Modelfile fix for tool calling in OpenCode; thinking mode suppression; HDD vs SSD findings
* [[OpenCode Multi-Provider Configuration Guide 260401]] — Dual-mode AI coding setup with Kimi cloud + Ollama local models via Distrobox
* [[PAD-Driven ERPNext Strategy 260303]] — Procedural Agentic Development for Frappe/ERPNext configuration and deployment
</div>

== Job Descriptions ==
<div style="column-count:2; column-gap:2em;">
* [[Job Descriptions]] — Index of all official job descriptions (IT, Engineering, Sales)
* [[JD IT Project Staff]] — IT Project Staff
* [[JD Security Compliance Assistant 260224]] — Security and Compliance Assistant (SCA)
* [[JD Engineering Designer 260108]] — Engineering Designer
* [[JD Engineering Supervisor 260109]] — Engineering Supervisor
* [[JD Technical Sales 260112]] — Technical Sales Engineer
* [[JD Marketing Assistant 251119]] — Marketing Assistant
</div>

== IT Operations & SOPs ==
<div style="column-count:2; column-gap:2em;">
* [[SCA Program Plan 260320]] — Security & Compliance Assistant Program Plan v3 (ISO 9001/27001, PDCA, distributed audit model)
* [[SOP: Inter-Company Ordering and Production Process 260203]] — Ordering and production workflow between Sister Companies and the Cabuyao Plant
* [[Memo: Team Roles & Reporting Process Clarification 260320]] — Role boundaries, data ownership, and the new ERPNext-driven reporting paradigm
* [[Standard Operating Procedure: Distributed Minute Taking & Task Ownership 251208]]
* [[Business Continuity]]
* [[Procedure: CC-Blast Data Breach Prevention]]
* [[8D (Eight Discipline) Problem Solving Procedure]]
* [[Offline Malware Remediation & Data Recovery]]
* [[Troubleshooting: Access & Permission Issues]]
* [[Steps to Repair and OCR a Scanned or Corrupted PDF in Ubuntu]]
* [[IT IMPORTS PROCESSES]]
* [[IT Purchase Requests 241126]]
* [[IT REQUEST (OP-ERP-ITR) - EDITED 250801]]
</div>

== Sales & Business ==
<div style="column-count:2; column-gap:2em;">
* [[Comfac Sales Knowledge Base]]
* [[Comfac CRM – Customer Qualification & Conversion Process]]
* [[Partner Reseller Pricing 251109]]
* [[Biz Analysis Methodology 251109]]
* [[2026 MIS IT KRA KPI Biz Plan]]
* [[SALES INVOICE TAX OUTPUT 250829]]
* [[Projects in Process Report 251023]]
</div>

== Tools & Productivity ==
<div style="column-count:2; column-gap:2em;">
* [[Excel Description Filler Tool 📝]]
* [https://github.com/Comfac-Global-Group/comfac-studies Comfac Studies - Spaced Repetiton Active Recall]
* [[LibreOffice / Nextcloud Office – "Due Tasks" Conditional Formatting]]
* [[Google Drive and Shared Drive Training]]
* [[260108 CGG- GitHub Administration Guide]]
</div>

== Wiki & Documentation ==
<div style="column-count:2; column-gap:2em;">
* [[Mediawiki Setting Up Guide]]
* [[Contributing to Only Office 260307]]
* [[Mediawiki Additional Configuration]]
* [[Mediawiki Docker Migration Guide]]
* [[Home]]
</div>

== Tutorials ==
<div style="column-count:2; column-gap:2em;">
* [[Claude Code Isolation and Burner Workflow 260211]] — Secure AI development environment setup
* [[Opencode isolation and burner workflow 260216]] — OpenCode CLI isolation procedures
* [[LibreOffice Calc NumToWords Extension Complete Guide]] — Extension development
* [[ERPNext v15 Docker Setup Guide]] — ERPNext v15 local Docker setup (students, evaluators, thin-client demos)
* [[Erpnextv15-SSH-setup-241111]] — ERPNext v15 SSH/Portainer production setup
* [[Git-Mediawiki Local Editing 260223]] — Wiki editing with Git
* [[Understanding & Fixing Kernel Panics 260212]] — System debugging
* [[OpenCode in Android Termux 260303]] — OpenCode in Android
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 agentic setup: Modelfile, tool calling fix, storage impact
* [[Lora Basics 260304]] — LORA research
</div>

== Research ==
<div style="column-count:2; column-gap:2em;">
* [[Ladybird Browser]] — Browser engine development
* [[Computing Architecture]] — System design principles
* [[Backblaze Drive Stats for Server and Storage Qualification 260219]] — Drive reliability analysis
</div>

----

== For Users Only ==
* [[Private:Private Ngani]]
* [[Private:Private Nganipart2]]

== CIT-OJT Project Documentations ==
* [[OJTDocs: For OJTs only]]

== Need Help? ==
<div style="column-count:2; column-gap:2em;">
* [[Troubleshooting: Access & Permission Issues]]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents MediaWiki User's Guide]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
</div>

OpenCode Multi-Provider Configuration Guide 260401

2026-03-31T16:40:51Z

Justinaquino: "Add OpenCode Multi-Provider Configuration Guide wiki entry"

= OpenCode Multi-Provider Configuration Guide =

'''Date:''' 2026-04-01<br>
'''Author:''' Justin / Comfac IT / CGG R&D & BD<br>
'''Status:''' 📋 Reference Configuration<br>
'''Related:''' [[OpenCoder Qwen35 Agentic Setup 260330]], [[Project OpenCoder: AI Independence Initiative]]

----

== Overview ==

This configuration enables a '''dual-mode AI coding environment''':
* '''Cloud''': Kimi's managed models (<code>kimi-for-coding</code>) via Kimi API
* '''Local''': Multiple Qwen models via Ollama (running in Distrobox)

{{mbox | type = warning | text = ⚠️ '''Critical Note''': This setup runs inside a '''Distrobox container''' with a custom home directory mapping (non-standard <code>$HOME</code> location). All paths in this config are relative to that mapped directory.}}

----

== Architecture Overview ==

<pre>
┌─────────────────────────────────────────┐
│ MCP Client (Host) │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Kimi Managed │ │ Local Ollama │ │
│ │ (Cloud API) │ │ (Container) │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────┘
│
┌──────┴──────┐
▼ ▼
[Claude] [OpenCode] [Aider] [Qwen]
MCP MCP MCP MCP
</pre>

'''Key Feature''': You can use '''Kimi as an MCP server''' to power other MCP clients (Claude Desktop, OpenCode, Aider, etc.) while leveraging local models.

----

== Configuration Sections ==

=== 1. Default Behavior (<code>[defaults]</code>) ===

<pre>
default_model = "kimi-code/kimi-for-coding"
default_thinking = true # Enable reasoning/thinking tokens
default_yolo = false # Require confirmation for destructive ops
default_editor = "" # Auto-detect editor
</pre>

{{mbox | type = warning | text = ⚠️ '''Critical''': <code>default_yolo = false</code> is recommended for production code. Set to <code>true</code> only for fully automated workflows.}}

----

=== 2. Managed Provider: Kimi ===

<pre>
[models."kimi-code/kimi-for-coding"]
provider = "managed:kimi-code"
model = "kimi-for-coding"
max_context_size = 262144 # 256k context window
capabilities = ["thinking", "image_in", "video_in"]
</pre>

'''Key Points''':
* '''Context Size''': 262144 tokens (256k) — suitable for large codebases
* '''Capabilities''':
** <code>thinking</code>: Reasoning/research mode
** <code>image_in</code>: Screenshot/UI analysis
** <code>video_in</code>: Video processing (if supported)
* '''OAuth Storage''': Credentials stored in <code>oauth/kimi-code</code> (relative to mapped home)

{{mbox | type = notice | text = 💡 '''Distrobox Note''': Since home is remapped, OAuth tokens persist in your chosen directory, not <code>~/.config</code>.}}

----

=== 3. Local Provider: Ollama ===

You have '''6 local models''' configured covering different use cases:

{| class="wikitable"
! Model !! Size !! Context !! Best For
|-
| <code>qwen3.5-4b</code> || 4B || 131k || Quick tasks, low latency
|-
| <code>qwen3.5-9b</code> || 9B || 131k || General coding, reasoning
|-
| <code>qwen3.5-9b-instruct</code> || 9B || 32k || Instruction following
|-
| <code>qwen2.5-coder-7b</code> || 7B || 32k || Code-specific tasks
|-
| <code>qwen3-vl-2b</code> || 2B || 32k || Vision + coding
|-
| <code>qwen3-vl-grammar</code> || - || 32k || Grammar/validation tasks
|}

<pre>
[providers.ollama]
type = "openai_legacy"
base_url = "http://localhost:11434/v1"
api_key = "ollama"
</pre>

{{mbox | type = notice | text = 💡 '''Distrobox Networking''': <code>localhost:11434</code> refers to the container's localhost. Ensure Ollama is running inside the same Distrobox or exposed to the container.}}

----

=== 4. Loop Control (<code>[loop_control]</code>) ===

<pre>
max_steps_per_turn = 100 # Max operations per request
max_retries_per_step = 3 # Retry failed operations
max_ralph_iterations = 0 # Legacy/compatibility setting
reserved_context_size = 50000 # Reserve 50k tokens for system
compaction_trigger_ratio = 0.85 # Compact memory at 85% usage
</pre>

'''Tuning Tips''':
* Increase <code>max_steps_per_turn</code> for complex refactoring (risk: higher API costs)
* Lower <code>compaction_trigger_ratio</code> to 0.75 if working with very large files
* <code>reserved_context_size</code> prevents context overflow crashes

----

=== 5. Background Processing (<code>[background]</code>) ===

<pre>
max_running_tasks = 4 # Parallel background operations
read_max_bytes = 30000 # 30KB file read limit
notification_tail_lines = 20 # Lines in status notifications
</pre>

{{mbox | type = notice | text = 💡 '''Distrobox Consideration''': Background tasks write to the mapped home directory. Ensure sufficient disk space in that location.}}

----

=== 6. Moonshot Services (<code>[services.*]</code>) ===

<pre>
[services.moonshot_search]
base_url = "https://api.kimi.com/coding/v1/search"

[services.moonshot_fetch]
base_url = "https://api.kimi.com/coding/v1/fetch"
</pre>

These enable '''web search''' and '''URL fetching''' capabilities within the Kimi ecosystem. OAuth credentials are shared with the main provider.

----

=== 7. MCP Client Settings (<code>[mcp.client]</code>) ===

<pre>
[mcp.client]
tool_call_timeout_ms = 60000 # 60 second timeout for tools
</pre>

{{mbox | type = notice | text = 💡 '''Important''': When using Kimi as an MCP for local models, this timeout applies to operations triggered by the local model via Kimi's tools.}}

----

== Advanced Usage Patterns ==

=== Pattern 1: Kimi as MCP Server for Local Models ===

'''Scenario''': You want to use <code>qwen3.5-9b</code> (local) for code generation, but leverage Kimi's search/fetch tools.

'''Setup''':
# Configure your MCP client (Claude/OpenCode/Aider) to point to this config
# Set <code>default_model</code> to an Ollama model in the client
# The client can still invoke Kimi's tools (search, fetch) via the MCP bridge

'''Config Override''':
<pre>
# Temporarily switch to local
default_model = "qwen3.5-9b"
default_thinking = true # Qwen supports thinking
</pre>

----

=== Pattern 2: Distrobox Path Mapping ===

Since your home is remapped (e.g., <code>/mnt/projects/ai-home</code> instead of <code>/home/user</code>):

<pre>
# OAuth paths are relative to the mapped home
[providers."managed:kimi-code".oauth]
storage = "file"
key = "oauth/kimi-code" # Resolves to /mnt/projects/ai-home/oauth/kimi-code
</pre>

'''Verification''':
<pre>
# Inside Distrobox
echo $HOME # Should show /mnt/projects/ai-home (or your mapping)
ls $HOME/oauth/kimi-code # Should contain OAuth tokens
</pre>

----

=== Pattern 3: Model Switching Workflows ===

<pre>
# High-level architecture discussion
default_model = "kimi-code/kimi-for-coding"

# Quick local edits (low latency)
alias_model = "qwen3.5-4b"

# Complex reasoning (local, private)
secure_model = "qwen3.5-9b"
</pre>

'''Command Palette''' (if your client supports it):
* <code>/model kimi-code/kimi-for-coding</code> — Cloud, full capabilities
* <code>/model qwen3.5-9b</code> — Local, private, reasoning
* <code>/model qwen3-vl-2b</code> — Vision tasks with local image analysis

----

== Distrobox-Specific Configuration ==

=== Volume Mounts Checklist ===

Ensure your Distrobox creation included:
<pre>
distrobox create --name ai-dev \
--home /mnt/projects/ai-home \ # Matches your config
--additional-flags "--volume /mnt/projects:/mnt/projects"
</pre>

----

=== Ollama Inside Distrobox ===

If Ollama runs in the same container:
<pre>
# Start Ollama before the MCP client
ollama serve & # Binds to localhost:11434 inside container

# Verify models are available
ollama list | grep qwen
</pre>

----

=== Persisting OAuth Tokens ===

Since home is custom, tokens survive container recreation:
<pre>
# Backup
tar czf oauth-backup.tar.gz $HOME/oauth/

# Restore (new container)
tar xzf oauth-backup.tar.gz -C $HOME/
</pre>

----

== Security & Best Practices ==

# '''API Keys''': Empty strings in config (<code>api_key = ""</code>) indicate OAuth-only. Never hardcode keys in the TOML file.
# '''YOLO Mode''': Keep <code>default_yolo = false</code> unless running in a fully containerized/throwaway environment.
# '''Context Window''': The 256k context for Kimi vs 32k/131k for local models — be mindful when switching contexts.
# '''Distrobox Isolation''': Your remapped home provides natural isolation. Sensitive data stays in your mapped directory, not system home.

----

== Troubleshooting ==

=== Issue: "Ollama connection refused" ===

'''Cause''': Ollama not running or not exposed to Distrobox

'''Fix''':
<pre>
# Check if Ollama is listening
curl http://localhost:11434/api/tags

# If using host Ollama from inside Distrobox, use host IP
# Edit base_url to: http://host.docker.internal:11434/v1
</pre>

----

=== Issue: OAuth token not found ===

'''Cause''': Wrong home directory mapping

'''Fix''': Verify <code>$HOME</code> inside Distrobox matches where you expect <code>oauth/</code> to live.

----

=== Issue: Context overflow with local models ===

'''Cause''': <code>max_context_size</code> mismatch

'''Fix''': Ensure your prompt + file contents < model's <code>max_context_size</code> (32k for most Qwen models vs 256k for Kimi).

----

== Quick Reference: Model Selection ==

{| class="wikitable"
! Task !! Recommended Model !! Why
|-
| Architecture decisions || <code>kimi-code/kimi-for-coding</code> || 256k context, reasoning
|-
| Quick bug fixes || <code>qwen3.5-4b</code> || Fast, sufficient context
|-
| Complex refactoring || <code>qwen3.5-9b</code> (131k) || Large context, private
|-
| Image → Code || <code>qwen3-vl-2b</code> || Vision capabilities, local
|-
| Documentation || <code>qwen2.5-coder-7b</code> || Code-optimized, offline
|}

----

== See Also ==

* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 Modelfile fix for tool calling
* [[Project OpenCoder: AI Independence Initiative]] — Strategic roadmap
* [[Proceedural Agentic Development Methodology 260304]] — PAD methodology
* [[Opencode isolation and burner workflow 260216]] — Distrobox burner workflow
* [[Ollama GNOME System Tray Panel 260401]] — Ollama system tray toggle
* [[🧠 Process: Selecting and Installing the Right Ollama Model for Your Hardware]] — Model selection guide

[[Category:AI]]
[[Category:OpenCode]]
[[Category:Ollama]]
[[Category:Tutorials]]
[[Category:Comfac IT]]

Main Page

2026-03-31T16:40:51Z

Justinaquino: "Add OpenCode Multi-Provider Configuration Guide wiki entry"

__NOTOC__
<div style="background:#f8f9fa; border:1px solid #ddd; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
Welcome to the '''Comfac IT Knowledge Base'''. Use the sections below to find guides, SOPs, and references organized by topic.
</div>

== ERPNext / Frappe ==
<div style="column-count:2; column-gap:2em;">
* [[Frappe HRMS]] — '''HR & Payroll''' (with Philippine Localization)
* [[Frappe ERPNext/Webshop]] — '''E-Commerce Webshop''' (setup, architecture, chapters)
* [[Manufacturing v16 260125]]
* [[ERpnext Asset Management Procedure 260113]]
* [[ERPNext HR Module Outline]]
* [[ERPNEXT Payroll POC 251212]]
* [[Comfac ERPNext Strategy Canvas (Expanded)]]
* [[PAD-Driven ERPNext Strategy 260303]] — PAD/AI-agentic implementation strategy for Frappe ERPNext
* [[ERPNext v15 Docker Setup Guide]] — Local Docker setup for evaluation, testing, and student use
* [[Frappe Links and References]]
* [[Using Frappe Wiki]]
* [https://docs.frappe.io/cloud/guidelines-for-contributing-regional-compliance-app Guidelines for Contributing Regional Compliance App]
* [https://docs.frappe.io/cloud/what-are-benches-and-bench-groups What are Benches?]
</div>

== System Administration & Self-Hosting ==
<div style="column-count:2; column-gap:2em;">
* [[pfSense Sales Training Material]]
* [[SOP: Network Troubleshooting & pfSense Monitoring 251130]]
* [[Modern Guide: pfSense Captive Portal with FreeRADIUS & ACME]]
* [[pfSense CE → pfSense Plus Upgrade Guide]]
* [[Tplink Mikrotik Equivalent]]
* [[Skills and Competencies for IT Staff Trained in pfSense]]
* [[System Hardening Strategy: Win2Lin Migration & Infrastructure 251129]]
* [[Controller Systems 251213-01]]
* [[Power Distribution Tree 251213]]
* [[Introduction: Why Self-Host Your Email?]]
* [[Mailcow + Thunderbird Setup Guide (Email + Calendar)]]
* [[Mailcow SOGo: Creating Filters for Events, Approvals, and Organizational Emails]]
* [[Spoof Timezone Extension – Setup Guide for Comfac Staff]]
* [[Viber Focus-Stealing]]
* [[🌐 WordPress Website — *You Own Everything, Learn Everything*]]
</div>

== Storage & Hardware ==
<div style="column-count:2; column-gap:2em;">
* [[TrueNAS Configuration Options & Scale Options 251130]]
* [[TrueNAS Business Plan: Project 251212]]
* [[Comparison: TrueNAS Mini X+ vs Dell Precision 3680 Tower (2025)]]
* [[Backblaze Drive Stats for Server and Storage Qualification]]
* [[Industrial Controllers and Water Utilities 251011]]
</div>

== AI & Machine Learning ==
<div style="column-count:2; column-gap:2em;">
* [[OpenWebUI - 251128-justin]]
* [[Comfac GPU Scaling and AI Research Goals]]
* [[🧠 Process: Selecting and Installing the Right Ollama Model for Your Hardware]]
* [[Ollama GNOME System Tray Panel 260401]] — GNOME system tray toggle to start/stop Ollama and reclaim VRAM
* [[Proceedural Agentic Development Methodology 260304]] — Methodology for systematic agent use
* [[Project OpenCoder: AI Independence Initiative]] — Strategic roadmap for manufacturing intelligence
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 Modelfile fix for tool calling in OpenCode; thinking mode suppression; HDD vs SSD findings
* [[OpenCode Multi-Provider Configuration Guide 260401]] — Dual-mode AI coding setup with Kimi cloud + Ollama local models via Distrobox
* [[PAD-Driven ERPNext Strategy 260303]] — Procedural Agentic Development for Frappe/ERPNext configuration and deployment
</div>

== Job Descriptions ==
<div style="column-count:2; column-gap:2em;">
* [[Job Descriptions]] — Index of all official job descriptions (IT, Engineering, Sales)
* [[JD IT Project Staff]] — IT Project Staff
* [[JD Security Compliance Assistant 260224]] — Security and Compliance Assistant (SCA)
* [[JD Engineering Designer 260108]] — Engineering Designer
* [[JD Engineering Supervisor 260109]] — Engineering Supervisor
* [[JD Technical Sales 260112]] — Technical Sales Engineer
* [[JD Marketing Assistant 251119]] — Marketing Assistant
</div>

== IT Operations & SOPs ==
<div style="column-count:2; column-gap:2em;">
* [[SCA Program Plan 260320]] — Security & Compliance Assistant Program Plan v3 (ISO 9001/27001, PDCA, distributed audit model)
* [[SOP: Inter-Company Ordering and Production Process 260203]] — Ordering and production workflow between Sister Companies and the Cabuyao Plant
* [[Memo: Team Roles & Reporting Process Clarification 260320]] — Role boundaries, data ownership, and the new ERPNext-driven reporting paradigm
* [[Standard Operating Procedure: Distributed Minute Taking & Task Ownership 251208]]
* [[Business Continuity]]
* [[Procedure: CC-Blast Data Breach Prevention]]
* [[8D (Eight Discipline) Problem Solving Procedure]]
* [[Offline Malware Remediation & Data Recovery]]
* [[Troubleshooting: Access & Permission Issues]]
* [[Steps to Repair and OCR a Scanned or Corrupted PDF in Ubuntu]]
* [[IT IMPORTS PROCESSES]]
* [[IT Purchase Requests 241126]]
* [[IT REQUEST (OP-ERP-ITR) - EDITED 250801]]
</div>

== Sales & Business ==
<div style="column-count:2; column-gap:2em;">
* [[Comfac Sales Knowledge Base]]
* [[Comfac CRM – Customer Qualification & Conversion Process]]
* [[Partner Reseller Pricing 251109]]
* [[Biz Analysis Methodology 251109]]
* [[2026 MIS IT KRA KPI Biz Plan]]
* [[SALES INVOICE TAX OUTPUT 250829]]
* [[Projects in Process Report 251023]]
</div>

== Tools & Productivity ==
<div style="column-count:2; column-gap:2em;">
* [[Excel Description Filler Tool 📝]]
* [https://github.com/Comfac-Global-Group/comfac-studies Comfac Studies - Spaced Repetiton Active Recall]
* [[LibreOffice / Nextcloud Office – "Due Tasks" Conditional Formatting]]
* [[Google Drive and Shared Drive Training]]
* [[260108 CGG- GitHub Administration Guide]]
</div>

== Wiki & Documentation ==
<div style="column-count:2; column-gap:2em;">
* [[Mediawiki Setting Up Guide]]
* [[Contributing to Only Office 260307]]
* [[Mediawiki Additional Configuration]]
* [[Mediawiki Docker Migration Guide]]
* [[Home]]
</div>

== Tutorials ==
<div style="column-count:2; column-gap:2em;">
* [[Claude Code Isolation and Burner Workflow 260211]] — Secure AI development environment setup
* [[Opencode isolation and burner workflow 260216]] — OpenCode CLI isolation procedures
* [[LibreOffice Calc NumToWords Extension Complete Guide]] — Extension development
* [[ERPNext v15 Docker Setup Guide]] — ERPNext v15 local Docker setup (students, evaluators, thin-client demos)
* [[Erpnextv15-SSH-setup-241111]] — ERPNext v15 SSH/Portainer production setup
* [[Git-Mediawiki Local Editing 260223]] — Wiki editing with Git
* [[Understanding & Fixing Kernel Panics 260212]] — System debugging
* [[OpenCode in Android Termux 260303]] — OpenCode in Android
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 agentic setup: Modelfile, tool calling fix, storage impact
* [[Lora Basics 260304]] — LORA research
</div>

== Research ==
<div style="column-count:2; column-gap:2em;">
* [[Ladybird Browser]] — Browser engine development
* [[Computing Architecture]] — System design principles
* [[Backblaze Drive Stats for Server and Storage Qualification 260219]] — Drive reliability analysis
</div>

----

== For Users Only ==
* [[Private:Private Ngani]]
* [[Private:Private Nganipart2]]

== CIT-OJT Project Documentations ==
* [[OJTDocs: For OJTs only]]

== Need Help? ==
<div style="column-count:2; column-gap:2em;">
* [[Troubleshooting: Access & Permission Issues]]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents MediaWiki User's Guide]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
</div>

Ollama GNOME System Tray Panel 260401

2026-03-31T16:38:11Z

Justinaquino: "Add Ollama GNOME System Tray Panel guide"

= Adding an Ollama System Tray Control to GNOME (Ubuntu) =

== Overview ==

When using Ollama locally, large language models (LLMs) are loaded directly into your GPU's VRAM for fast processing. However, Ollama keeps these models "hot" in memory for a period of time after you finish chatting. If you are running heavy models (like a 7B or 8B parameter model), this can easily consume 5GB+ of VRAM, leaving little room for gaming, video editing, or other GPU-intensive tasks.

Instead of repeatedly opening a terminal to run <code>systemctl</code> commands to kill the service, you can create a lightweight GNOME panel application (system tray icon). This utility provides a simple, two-click visual interface to start and stop the Ollama background service, immediately freeing up your VRAM when needed.

----

== Features ==

* '''One-Click Controls:''' Start or stop the Ollama systemd service directly from the top panel.
* '''Visual Status:''' The icon dynamically changes to show whether Ollama is currently running (<code>▶</code>) or stopped (<code>⏸</code>).
* '''Asynchronous Execution:''' Uses background threading so password prompts (<code>pkexec</code>) do not freeze your desktop environment.
* '''Auto-Polling:''' Detects if Ollama was started or stopped from a terminal and updates the panel icon automatically.

----

== Installation ==

=== Step 1: Install Prerequisites ===

You will need the Python bindings for GTK3 and AppIndicator to allow the script to integrate with the GNOME top panel.

Open your terminal and run:

<syntaxhighlight lang="bash">
sudo apt update
sudo apt install python3-gi python3-gi-cairo gir1.2-appindicator3-0.1
</syntaxhighlight>

=== Step 2: Create the Python Script ===

Create a new Python file in a permanent location, such as your home directory or a dedicated scripts folder.

<syntaxhighlight lang="bash">
nano ~/ollama-panel.py
</syntaxhighlight>

Paste the following code into the file:

<syntaxhighlight lang="python">
#!/usr/bin/env python3
import gi
import subprocess
import threading

# Require the necessary GTK and AppIndicator versions
gi.require_version('Gtk', '3.0')
gi.require_version('AppIndicator3', '0.1')
from gi.repository import Gtk, AppIndicator3, GLib

class OllamaIndicator:
def __init__(self):
# Initialize with a placeholder icon; it will update immediately
self.indicator = AppIndicator3.Indicator.new(
"ollama_indicator",
"system-run",
AppIndicator3.IndicatorCategory.APPLICATION_STATUS
)
self.indicator.set_status(AppIndicator3.IndicatorStatus.ACTIVE)

self.menu = Gtk.Menu()

# Start Button
self.start_item = Gtk.MenuItem(label='▶ Start Ollama')
self.start_item.connect('activate', lambda _: self.run_systemctl('start'))
self.menu.append(self.start_item)

# Stop Button
self.stop_item = Gtk.MenuItem(label='⏹ Stop Ollama')
self.stop_item.connect('activate', lambda _: self.run_systemctl('stop'))
self.menu.append(self.stop_item)

self.menu.append(Gtk.SeparatorMenuItem())

# Quit Button
quit_item = Gtk.MenuItem(label='Quit Panel App')
quit_item.connect('activate', Gtk.main_quit)
self.menu.append(quit_item)

self.menu.show_all()
self.indicator.set_menu(self.menu)

# Run an initial status check
self.update_status()

# Poll systemctl every 3 seconds to catch external changes
GLib.timeout_add_seconds(3, self.update_status)

def get_ollama_status(self):
# Suppress errors/output so it fails gracefully if cancelled
result = subprocess.run(
["systemctl", "is-active", "ollama"],
capture_output=True, text=True
)
return result.stdout.strip() == "active"

def update_status(self):
active = self.get_ollama_status()

if active:
self.indicator.set_icon_full("media-playback-start", "Ollama is running")
self.start_item.set_sensitive(False)
self.stop_item.set_sensitive(True)
else:
self.indicator.set_icon_full("media-playback-pause", "Ollama is stopped")
self.start_item.set_sensitive(True)
self.stop_item.set_sensitive(False)

return True # Returning True keeps the GLib timer running

def run_systemctl(self, command):
def execute():
# Run the command and wait for it to finish (or be cancelled)
subprocess.run(["pkexec", "systemctl", command, "ollama"])
# Schedule a UI update on the main GTK thread once done
GLib.idle_add(self.update_status)

# Fire in a background thread so the polkit prompt doesn't freeze the panel
threading.Thread(target=execute, daemon=True).start()

def main():
app = OllamaIndicator()
Gtk.main()

if __name__ == "__main__":
main()
</syntaxhighlight>

Save the file and exit your text editor.

=== Step 3: Make the Script Executable ===

Grant the script permission to run as an executable program:

<syntaxhighlight lang="bash">
chmod +x ~/ollama-panel.py
</syntaxhighlight>

You can test it immediately by running <code>python3 ~/ollama-panel.py</code>. An icon should appear in your top-right system tray.

----

== Optional: Configure Passwordless Toggling ==

By default, clicking "Start" or "Stop" will bring up a graphical prompt asking for your sudo password. If you want to bypass this for convenience:

# Open the sudoers editor safely:
<syntaxhighlight lang="bash">
sudo visudo
</syntaxhighlight>
# Add this line to the very bottom of the file (replace <code>your_username</code> with your actual Ubuntu username):
<pre>
your_username ALL=(ALL) NOPASSWD: /bin/systemctl start ollama, /bin/systemctl stop ollama
</pre>
# Save and exit.
# Open <code>~/ollama-panel.py</code> and change the <code>subprocess.run</code> line inside the <code>execute()</code> function from <code>"pkexec"</code> to <code>"sudo"</code>:
<syntaxhighlight lang="python">
subprocess.run(["sudo", "systemctl", command, "ollama"])
</syntaxhighlight>

----

== Setting Up Autostart (Run on Boot) ==

To ensure the control panel is always available when you log in:

# Open the '''Startup Applications''' tool from your Ubuntu application menu.
# Click '''Add'''.
# Fill in the fields:
#* '''Name:''' Ollama Control Panel
#* '''Command:''' <code>/usr/bin/python3 /home/YOUR_USERNAME/ollama-panel.py</code> — ensure you use the absolute path to your script
#* '''Comment:''' System tray toggle for the Ollama service.
# Click '''Save'''.

[[Category:System Administration]]
[[Category:AI]]
[[Category:Ollama]]
[[Category:Tutorials]]
[[Category:GNOME]]

Main Page

2026-03-31T16:38:11Z

Justinaquino: "Add Ollama GNOME System Tray Panel guide"

__NOTOC__
<div style="background:#f8f9fa; border:1px solid #ddd; border-radius:4px; padding:12px 16px; margin-bottom:20px;">
Welcome to the '''Comfac IT Knowledge Base'''. Use the sections below to find guides, SOPs, and references organized by topic.
</div>

== ERPNext / Frappe ==
<div style="column-count:2; column-gap:2em;">
* [[Frappe HRMS]] — '''HR & Payroll''' (with Philippine Localization)
* [[Frappe ERPNext/Webshop]] — '''E-Commerce Webshop''' (setup, architecture, chapters)
* [[Manufacturing v16 260125]]
* [[ERpnext Asset Management Procedure 260113]]
* [[ERPNext HR Module Outline]]
* [[ERPNEXT Payroll POC 251212]]
* [[Comfac ERPNext Strategy Canvas (Expanded)]]
* [[PAD-Driven ERPNext Strategy 260303]] — PAD/AI-agentic implementation strategy for Frappe ERPNext
* [[ERPNext v15 Docker Setup Guide]] — Local Docker setup for evaluation, testing, and student use
* [[Frappe Links and References]]
* [[Using Frappe Wiki]]
* [https://docs.frappe.io/cloud/guidelines-for-contributing-regional-compliance-app Guidelines for Contributing Regional Compliance App]
* [https://docs.frappe.io/cloud/what-are-benches-and-bench-groups What are Benches?]
</div>

== System Administration & Self-Hosting ==
<div style="column-count:2; column-gap:2em;">
* [[pfSense Sales Training Material]]
* [[SOP: Network Troubleshooting & pfSense Monitoring 251130]]
* [[Modern Guide: pfSense Captive Portal with FreeRADIUS & ACME]]
* [[pfSense CE → pfSense Plus Upgrade Guide]]
* [[Tplink Mikrotik Equivalent]]
* [[Skills and Competencies for IT Staff Trained in pfSense]]
* [[System Hardening Strategy: Win2Lin Migration & Infrastructure 251129]]
* [[Controller Systems 251213-01]]
* [[Power Distribution Tree 251213]]
* [[Introduction: Why Self-Host Your Email?]]
* [[Mailcow + Thunderbird Setup Guide (Email + Calendar)]]
* [[Mailcow SOGo: Creating Filters for Events, Approvals, and Organizational Emails]]
* [[Spoof Timezone Extension – Setup Guide for Comfac Staff]]
* [[Viber Focus-Stealing]]
* [[🌐 WordPress Website — *You Own Everything, Learn Everything*]]
</div>

== Storage & Hardware ==
<div style="column-count:2; column-gap:2em;">
* [[TrueNAS Configuration Options & Scale Options 251130]]
* [[TrueNAS Business Plan: Project 251212]]
* [[Comparison: TrueNAS Mini X+ vs Dell Precision 3680 Tower (2025)]]
* [[Backblaze Drive Stats for Server and Storage Qualification]]
* [[Industrial Controllers and Water Utilities 251011]]
</div>

== AI & Machine Learning ==
<div style="column-count:2; column-gap:2em;">
* [[OpenWebUI - 251128-justin]]
* [[Comfac GPU Scaling and AI Research Goals]]
* [[🧠 Process: Selecting and Installing the Right Ollama Model for Your Hardware]]
* [[Ollama GNOME System Tray Panel 260401]] — GNOME system tray toggle to start/stop Ollama and reclaim VRAM
* [[Proceedural Agentic Development Methodology 260304]] — Methodology for systematic agent use
* [[Project OpenCoder: AI Independence Initiative]] — Strategic roadmap for manufacturing intelligence
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 Modelfile fix for tool calling in OpenCode; thinking mode suppression; HDD vs SSD findings
* [[PAD-Driven ERPNext Strategy 260303]] — Procedural Agentic Development for Frappe/ERPNext configuration and deployment
</div>

== Job Descriptions ==
<div style="column-count:2; column-gap:2em;">
* [[Job Descriptions]] — Index of all official job descriptions (IT, Engineering, Sales)
* [[JD IT Project Staff]] — IT Project Staff
* [[JD Security Compliance Assistant 260224]] — Security and Compliance Assistant (SCA)
* [[JD Engineering Designer 260108]] — Engineering Designer
* [[JD Engineering Supervisor 260109]] — Engineering Supervisor
* [[JD Technical Sales 260112]] — Technical Sales Engineer
* [[JD Marketing Assistant 251119]] — Marketing Assistant
</div>

== IT Operations & SOPs ==
<div style="column-count:2; column-gap:2em;">
* [[SCA Program Plan 260320]] — Security & Compliance Assistant Program Plan v3 (ISO 9001/27001, PDCA, distributed audit model)
* [[SOP: Inter-Company Ordering and Production Process 260203]] — Ordering and production workflow between Sister Companies and the Cabuyao Plant
* [[Memo: Team Roles & Reporting Process Clarification 260320]] — Role boundaries, data ownership, and the new ERPNext-driven reporting paradigm
* [[Standard Operating Procedure: Distributed Minute Taking & Task Ownership 251208]]
* [[Business Continuity]]
* [[Procedure: CC-Blast Data Breach Prevention]]
* [[8D (Eight Discipline) Problem Solving Procedure]]
* [[Offline Malware Remediation & Data Recovery]]
* [[Troubleshooting: Access & Permission Issues]]
* [[Steps to Repair and OCR a Scanned or Corrupted PDF in Ubuntu]]
* [[IT IMPORTS PROCESSES]]
* [[IT Purchase Requests 241126]]
* [[IT REQUEST (OP-ERP-ITR) - EDITED 250801]]
</div>

== Sales & Business ==
<div style="column-count:2; column-gap:2em;">
* [[Comfac Sales Knowledge Base]]
* [[Comfac CRM – Customer Qualification & Conversion Process]]
* [[Partner Reseller Pricing 251109]]
* [[Biz Analysis Methodology 251109]]
* [[2026 MIS IT KRA KPI Biz Plan]]
* [[SALES INVOICE TAX OUTPUT 250829]]
* [[Projects in Process Report 251023]]
</div>

== Tools & Productivity ==
<div style="column-count:2; column-gap:2em;">
* [[Excel Description Filler Tool 📝]]
* [https://github.com/Comfac-Global-Group/comfac-studies Comfac Studies - Spaced Repetiton Active Recall]
* [[LibreOffice / Nextcloud Office – "Due Tasks" Conditional Formatting]]
* [[Google Drive and Shared Drive Training]]
* [[260108 CGG- GitHub Administration Guide]]
</div>

== Wiki & Documentation ==
<div style="column-count:2; column-gap:2em;">
* [[Mediawiki Setting Up Guide]]
* [[Contributing to Only Office 260307]]
* [[Mediawiki Additional Configuration]]
* [[Mediawiki Docker Migration Guide]]
* [[Home]]
</div>

== Tutorials ==
<div style="column-count:2; column-gap:2em;">
* [[Claude Code Isolation and Burner Workflow 260211]] — Secure AI development environment setup
* [[Opencode isolation and burner workflow 260216]] — OpenCode CLI isolation procedures
* [[LibreOffice Calc NumToWords Extension Complete Guide]] — Extension development
* [[ERPNext v15 Docker Setup Guide]] — ERPNext v15 local Docker setup (students, evaluators, thin-client demos)
* [[Erpnextv15-SSH-setup-241111]] — ERPNext v15 SSH/Portainer production setup
* [[Git-Mediawiki Local Editing 260223]] — Wiki editing with Git
* [[Understanding & Fixing Kernel Panics 260212]] — System debugging
* [[OpenCode in Android Termux 260303]] — OpenCode in Android
* [[OpenCoder Qwen35 Agentic Setup 260330]] — Qwen3.5 agentic setup: Modelfile, tool calling fix, storage impact
* [[Lora Basics 260304]] — LORA research
</div>

== Research ==
<div style="column-count:2; column-gap:2em;">
* [[Ladybird Browser]] — Browser engine development
* [[Computing Architecture]] — System design principles
* [[Backblaze Drive Stats for Server and Storage Qualification 260219]] — Drive reliability analysis
</div>

----

== For Users Only ==
* [[Private:Private Ngani]]
* [[Private:Private Nganipart2]]

== CIT-OJT Project Documentations ==
* [[OJTDocs: For OJTs only]]

== Need Help? ==
<div style="column-count:2; column-gap:2em;">
* [[Troubleshooting: Access & Permission Issues]]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Contents MediaWiki User's Guide]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings]
* [https://www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
</div>