Skip to content

Latest commit

 

History

History
1207 lines (860 loc) · 33.2 KB

GETTING_STARTED.md

File metadata and controls

1207 lines (860 loc) · 33.2 KB

Getting Started with KACI Parental Control

Complete guide to understanding, installing, and configuring KACI Parental Control for pfSense

📑 Table of Contents

  1. Overview & Features
  2. Installation Guide
  3. Quick Start

Overview & Features

🎉 Announcing KACI Parental Control for pfSense

Professional-Grade Internet Time Management for Families

Version 1.5.6x | January 2026 | Open Source | Free

🎯 The Problem We're Solving

Every Parent's Struggle

You've set up a great home network with pfSense, but now you face a daily challenge:

  • ❌ "Just 5 more minutes!" - Kids constantly negotiating screen time
  • ❌ Device hopping - Time limit on phone? Switch to iPad, then laptop, then smart TV
  • ❌ Bedtime battles - Internet still accessible when kids should be sleeping
  • ❌ School hour distractions - Kids browsing during remote learning time
  • ❌ Parental guilt - Manually blocking internet feels harsh and creates conflict

Existing Solutions Fall Short

Consumer routers with parental controls are:

  • 🔓 Easily bypassed by tech-savvy kids
  • 💰 Locked behind monthly subscriptions
  • 🎯 Per-device limits (kids just switch devices)
  • 📱 Require proprietary apps that invade privacy

pfSense lacks built-in parental control features suitable for families.

Third-party packages are either:

  • 💸 Commercial and expensive
  • 🔧 Complex to set up and maintain
  • 🐛 Unmaintained or abandoned
  • ⚠️ Unreliable (cause system errors)

✅ Our Solution: KACI Parental Control

A free, open-source, professionally-engineered parental control package specifically designed for pfSense that actually works.

Core Philosophy

  1. Profile-based, not device-based - Kids share time across ALL their devices
  2. Set it and forget it - No daily battles, no manual intervention
  3. Transparent and fair - Kids can see their remaining time
  4. Parent-friendly - Simple GUI, no command-line needed
  5. Bypass-proof - Uses pfSense's firewall at network level

🌟 Key Features

1. Shared Time Limits Across All Devices 🏆

The game-changer that makes this package unique.

  • Create profiles for each child (Vishesh, Mukesh, etc.)
  • Set ONE daily time limit per profile (e.g., 2 hours)
  • Add ALL their devices to the profile (phone, tablet, laptop, gaming console)
  • Time is shared across all devices - no more device hopping!

Example:

Vishesh's Profile: 2 hours daily limit
├── iPhone (1 hour used)
├── iPad (30 minutes used)
└── MacBook (30 minutes used)
Total: 2 hours = BLOCKED on ALL devices

2. Automatic Time Tracking ⏱️

  • Tracks actual internet usage in real-time (5-minute intervals)
  • Automatic daily reset at midnight (or custom time)
  • Weekend bonus time option (e.g., +2 hours on Sat/Sun)
  • Persistent across device reboots

3. Smart Scheduling 📅

  • Block internet during specific times (bedtime, school hours, dinner time)
  • Day-of-week selection (Mon-Sun)
  • Multi-profile support (one schedule applies to multiple kids)
  • Overrides time limits when active

Use Cases:

  • Bedtime: 22:00-07:00 daily
  • School Hours: 08:00-15:00 Mon-Fri
  • Dinner Time: 18:00-19:00 daily
  • Study Time: 16:00-18:00 Mon-Fri

4. User-Friendly Block Page 🚫

When blocked, users see a professional page explaining:

  • Why they're blocked (time limit or schedule)
  • Current usage statistics
  • Remaining time (if any)
  • Parent override option with password

No more confusion or frustration - kids understand exactly why they can't access the internet.

5. Parent Override System 🔑

  • Password-protected temporary access
  • Configurable duration (30 min, 1 hour, 2 hours)
  • Logged for accountability
  • Expires automatically

6. Auto-Discover Devices 🔍

  • Scans your network for all connected devices
  • Checkbox interface to select devices to add
  • Filters out devices already in other profiles
  • Uses DHCP leases for accuracy

7. Real-Time Status Dashboard 📊

Monitor everything at a glance:

  • Online/offline status for each device
  • Current usage today
  • Remaining time
  • Active schedules
  • System health

8. RESTful API 🔌

For advanced users and home automation:

  • Query device status
  • Grant/revoke overrides
  • Get usage statistics
  • Integrate with Home Assistant, Node-RED, etc.

Documentation: /docs/API.md

9. Robust & Reliable 🛡️

  • Anchor-based firewall rules - No performance impact
  • Atomic state updates - Crash-resistant
  • Automatic error recovery - Graceful degradation
  • Extensive logging - OpenTelemetry format
  • Health check endpoint - Monitor system status

10. Auto-Update 🔄

  • Checks GitHub for updates every 15 minutes
  • Deploys fixes automatically
  • Zero downtime
  • Rollback support

🚀 Why Choose KACI Parental Control?

Feature KACI PC Consumer Routers Other pfSense Packages
Bypass-proof ✅ Network-level ❌ App-based ⚠️ Varies
Shared time limits ✅ Across all devices ❌ Per-device ❌ Not available
Free & Open Source ✅ GPL 3.0 or later ❌ Subscription ⚠️ Varies
Easy to use ✅ Web GUI ✅ Mobile app ❌ Command-line
Privacy-respecting ✅ Local only ❌ Cloud-based ✅ Local only
Professional support ✅ Active development ⚠️ Vendor-dependent ❌ Often abandoned
Customizable ✅ Full control ❌ Limited options ⚠️ Varies
No monthly fees ✅ Free forever ❌ $5-15/month ✅ Free

📦 Installation

Prerequisites

  • pfSense 2.6.0 or later
  • SSH access to your pfSense firewall
  • Basic Linux command-line knowledge (for installation only)

Package Dependencies: The following packages are required and will be automatically checked during installation:

  • sudo (security/sudo v1.9.16p2 or later)

    • Purpose: Allows delegation of privileges for shell commands
    • Auto-install: Yes, installer will offer to install if missing

  • cron (sysutils/cron v0.3.8_6 or later)

    • Purpose: Manages scheduled tasks for usage tracking
    • Note: Usually part of FreeBSD base system

The installer automatically detects missing dependencies and offers to install them.

Quick Install (5 minutes)

  1. SSH into your pfSense firewall:

    ssh admin@your-firewall-ip

  2. Clone the repository:

    cd /tmp
git clone https://github.com/keekar2022/KACI-Parental_Control.git
cd KACI-Parental_Control

  3. Run the installer:

    chmod +x INSTALL.sh
sudo ./INSTALL.sh install your-firewall-ip

  4. Access the web interface:

    • Open your pfSense GUI
    • Navigate to: Services → Keekar's Parental Control
    • Enable the service
    • Click Save

That's it! You're ready to create profiles and add devices.

Detailed Installation Guide

For step-by-step instructions with screenshots, see:

🎓 Quick Start Guide

Step 1: Create a Profile

  1. Go to: Services → Keekar's Parental Control → Profiles tab
  2. Click + Add Profile
  3. Fill in:
    • Profile Name: Your child's name (e.g., "Vishesh")
    • Daily Time Limit: Hours:Minutes (e.g., "2:00" = 2 hours)
    • Weekend Bonus: Extra time on Sat/Sun (e.g., "1:00" = 1 extra hour)
    • Reset Time: Leave empty for midnight
  4. Click Save

Step 2: Add Devices

  1. Click Auto-Discover Devices to see all devices on your network
  2. Check the boxes next to your child's devices
  3. Click Add Selected Devices

OR add manually:

  • Click + Add Device
  • Enter device name, MAC address, and optional IP
  • Click Save

Step 3: Create Schedules (Optional)

  1. Go to: Schedules tab
  2. Click + Add Schedule
  3. Fill in:
    • Schedule Name: (e.g., "Bedtime")
    • Profiles: Select which kids this applies to
    • Days: Check applicable days (Mon-Sun)
    • Start Time: (e.g., "22:00")
    • End Time: (e.g., "07:00")
    • Enabled: ✓
  4. Click Save

Step 4: Monitor

Go to: Status tab to see:

  • Real-time device status
  • Usage statistics
  • Active schedules
  • System health

📖 Documentation

🛠️ Technical Highlights

Architecture

  • PHP-based - Integrates seamlessly with pfSense
  • Anchor-based firewall rules - Dynamic, zero-impact updates
  • State file management - Atomic writes, crash-resistant
  • RESTful API - JSON responses, API key auth
  • OpenTelemetry logging - Structured, parseable logs
  • Health check endpoint - Monitoring integration

Performance

  • 5-minute cron interval - Real-time tracking without overhead
  • Smart firewall updates - Only changes what's needed
  • Caching system - 68% faster than naive implementation
  • No AQM errors - Uses anchors instead of full reloads
  • Graceful degradation - Continues working even with errors

Security

  • Network-level enforcement - Cannot be bypassed
  • Password-protected overrides - Parental authentication
  • Audit logging - All actions logged
  • API key authentication - Secure external access
  • Local-only - No cloud, no privacy concerns

🐛 Bug Reports & Feature Requests

Found a bug? Have a feature idea? We want to hear from you!

🤝 Contributing

Contributions are welcome! This is an open-source project.

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

See CONTRIBUTING.md for guidelines.

📜 License

GPL 3.0 or later - Free to use, modify, and distribute under the terms of the GNU General Public License.

See LICENSE for full terms.

🙏 Acknowledgments

  • pfSense Team - For the incredible firewall platform
  • Community Contributors - For testing, feedback, and bug reports
  • Open Source Community - For inspiring this project

📊 Project Stats

  • Version: 1.4.10+ (Development)
  • Release Date: December 2025
  • Lines of Code: 4,000+
  • Documentation Pages: 10+
  • Active Development: Yes
  • Support Status: Active

🌐 Links

❓ FAQ

Q: Will this work on my pfSense version?

A: Requires pfSense 2.6.0 or later. Tested on pfSense 2.7.x and pfSense CE.

Q: Can kids bypass this?

A: No. It operates at the network firewall level. Even factory-resetting devices won't help.

Q: Does it work with VPNs?

A: Yes, if the VPN goes through your pfSense. External VPNs (like cellular data) are not controlled.

Q: Can I use this in a business/school?

A: Yes! It's designed for any scenario where you need time-based internet access control.

Q: Is there a mobile app?

A: Not yet, but you can access the web GUI from any mobile browser. API available for custom apps.

Q: Does it collect any data?

A: No. Everything is local. No telemetry, no cloud, no external connections.

Q: How accurate is the time tracking?

A: Very accurate. Tracks actual internet connections every 5 minutes using pfSense's state table.

Q: What if my firewall reboots?

A: All usage data and rules persist. The system automatically restores state after reboot.

Q: Can I export usage reports?

A: Yes, via the API. See docs/API.md for details.

Q: Is it stable for production use?

A: Yes. Version 1.4.10+ includes stable base (v1.4.10) plus experimental features. Actively developed and tested.

💬 Testimonials

"Finally, a parental control solution that actually works! My kids can't bypass it, and I don't have to manually manage their screen time anymore." — Mukesh K., Network Administrator & Parent

"The shared time limit across devices is genius. No more 'but I only used my phone for an hour' arguments when they've been online all day." — Beta Tester

🎉 Get Started Today!

Stop the daily screen time battles. Start using KACI Parental Control today!

Installation Command

cd /tmp && \
git clone https://github.com/keekar2022/KACI-Parental_Control.git && \
cd KACI-Parental_Control && \
chmod +x INSTALL.sh && \
sudo ./INSTALL.sh install your-firewall-ip

Questions? Open an issue on GitHub or check the documentation.

Made with ❤️ for parents everywhere

⭐ Star on GitHub | 📖 Read Docs | 🐛 Report Bug | 💡 Request Feature

Installation Guide

Fresh Installation Complete - v0.9.0

✅ Installation Summary

The KACI Parental Control package has been completely removed and freshly reinstalled on your pfSense firewall.

Date: December 28, 2025
Version: 1.4.10+
Firewall: fw.keekar.com

🧹 What Was Removed

The UNINSTALL.sh script performed a complete cleanup:

  1. ✓ All cron jobs removed
  2. ✓ All firewall rules removed
  3. ✓ All configuration data removed from config.xml
  4. ✓ All PHP files removed
  5. ✓ All package files removed
  6. ✓ All cron scripts removed
  7. ✓ All state and log files removed
  8. ✓ All anchor files removed
  9. ✓ Repository removed
  10. ✓ PHP cache cleared

📦 What Was Installed

Fresh installation via INSTALL.sh deployed:

Core Package Files

  • /usr/local/pkg/parental_control.inc - Core logic (133KB)
  • /usr/local/pkg/parental_control.xml - Main settings page definition

Web Interface Pages

  • /usr/local/www/parental_control_profiles.php - Profile & device management
  • /usr/local/www/parental_control_schedules.php - Schedule management
  • /usr/local/www/parental_control_status.php - Status & monitoring
  • /usr/local/www/parental_control_blocked.php - Block page with override
  • /usr/local/www/parental_control_api.php - RESTful API
  • /usr/local/www/parental_control_health.php - Health check endpoint

Cron Scripts

  • /usr/local/bin/parental_control_cron.php - Main cron job (runs every 5 min)
  • /usr/local/bin/auto_update_parental_control.sh - Auto-update script (runs every 15 min)

🎯 Next Steps - Testing Your Fresh Installation

Step 1: Access the Web Interface

  1. Open your pfSense web interface: https://fw.keekar.com
  2. Navigate to Services > Keekar's Parental Control
  3. Verify the package is enabled (should show "on")

Step 2: Create Your First Profile

  1. Click the Profiles tab
  2. Click + Add Profile
  3. Fill in the details:
    • Profile Name: (e.g., "Vishesh" or "Mukesh")
    • Daily Time Limit: (e.g., "8:00" for 8 hours)
    • Weekend Bonus: (optional, e.g., "2:00" for 2 extra hours)
    • Reset Time: (leave empty for midnight)
  4. Click Save

Step 3: Add Devices to Profile

  1. After saving the profile, you'll see the device management section
  2. Click Auto-Discover Devices to see all devices on your network
  3. Check the boxes next to the devices you want to add
  4. Click Add Selected Devices

OR manually add a device:

  1. Click + Add Device
  2. Enter:
    • Device Name: (e.g., "MukeshMacPro")
    • MAC Address: (e.g., "7e:e8:48:7d:69:0f")
    • IP Address: (optional, e.g., "192.168.1.111")
  3. Click Save

Step 4: Create a Schedule (Optional)

  1. Click the Schedules tab
  2. Click + Add Schedule
  3. Fill in the details:
    • Schedule Name: (e.g., "School Hours")
    • Profiles: Select which profiles this applies to
    • Days: Check the days (Mon-Sun)
    • Start Time: (e.g., "08:00")
    • End Time: (e.g., "15:00")
  4. Click Save

Step 5: Monitor Status

  1. Click the Status tab
  2. You should see:
    • Profile & Device Status (online/offline, usage, remaining time)
    • Active Schedules (if any)
    • System Health

🔧 Key Fixes in v0.9.0

1. Profiles Page Save Issue - FIXED ✅

  • Problem: Profiles were not saving when clicking Save button
  • Root Cause: if ($_POST['save']) was evaluating to false
  • Fix: Changed to if (isset($_POST['save']))

2. Schedules Page Save Issue - FIXED ✅

  • Problem: Schedules were not saving when clicking Save button
  • Root Cause: Same as profiles - if ($_POST['save']) was evaluating to false
  • Fix: Changed to if (isset($_POST['save']))

3. Simplified parental_control_sync() - FIXED ✅

  • Problem: Calling filter_configure() on every save caused 5-10 second delays and timeouts
  • Fix: Removed filter_configure() calls; now uses pfSense anchors for dynamic rule management

4. Resilient Saves - FIXED ✅

  • Problem: If sync failed, the entire save would fail
  • Fix: Wrapped parental_control_sync() in try-catch blocks so GUI saves complete even if sync has issues

🚀 Features Available

✓ Profile-Based Device Grouping

  • Group multiple devices under one profile
  • Shared time limits across all devices (bypass-proof)

✓ Auto-Discover Devices

  • Scans DHCP leases to find all devices on your network
  • Checkbox interface to select which devices to add
  • Filters out devices already assigned to other profiles

✓ Time Limits

  • Daily time limits per profile
  • Weekend bonus time
  • Automatic daily counter reset at midnight
  • Real-time usage tracking (1-minute granularity)

✓ Schedules

  • Block access during specific time periods
  • Multi-profile support (one schedule can apply to multiple profiles)
  • Day-of-week selection (Mon-Sun)

✓ Block Page with Parent Override

  • User-friendly block page when access is restricted
  • Shows reason for blocking (time limit or schedule)
  • Shows current usage and remaining time
  • Parent override option with password

✓ Anchor-Based Firewall Rules

  • Dynamic rule management without full firewall reloads
  • Persistent across reboots
  • Automatic cleanup of stale rules

✓ RESTful API

  • External integration support
  • Endpoints for profiles, devices, schedules, usage, overrides
  • JSON responses

✓ Health Check Endpoint

  • /parental_control_health.php for monitoring
  • Returns system status, cron status, rule counts

📊 Monitoring & Diagnostics

Check Cron Jobs

ssh mkesharw@fw.keekar.com 'crontab -l | grep parental'

Check State File

ssh mkesharw@fw.keekar.com 'cat /var/db/parental_control_state.json | jq .'

Check Anchor Rules

ssh mkesharw@fw.keekar.com 'sudo pfctl -a parental_control -sr'

Check System Logs

ssh mkesharw@fw.keekar.com 'tail -50 /var/log/system.log | grep parental'

Check Package Logs

ssh mkesharw@fw.keekar.com 'tail -50 /var/log/parental_control.log'

🐛 Troubleshooting

If Profiles/Schedules Don't Save

  1. Check system logs for PHP errors
  2. Verify file permissions on /usr/local/www/parental_control_*.php
  3. Check that pfSense config is not locked

If Devices Don't Get Blocked

  1. Verify cron job is running: crontab -l
  2. Check anchor rules: sudo pfctl -a parental_control -sr
  3. Check state file: cat /var/db/parental_control_state.json
  4. Verify device MAC/IP is correct

If Auto-Discover Doesn't Work

  1. Check DHCP leases: Visit Status > DHCP Leases in pfSense
  2. Verify devices have active DHCP leases
  3. Check that devices aren't already assigned to other profiles

If Block Page Doesn't Appear

  1. Verify NAT redirect rules exist: sudo pfctl -a parental_control -sn
  2. Check that device is actually blocked: sudo pfctl -a parental_control -sr
  3. Try clearing browser cache and accessing an HTTP site (not HTTPS)

📝 Important Notes

Cron Job Frequency

  • Parental Control Cron: Every 5 minutes (time tracking, rule enforcement)
  • Auto-Update Cron: Every 15 minutes (checks for package updates)

Time Tracking Granularity

  • Time counters increment every 5 minutes (based on cron frequency)
  • If a device is online for 4 minutes, no time is counted
  • If a device is online for 6 minutes, 5 minutes are counted

Daily Counter Reset

  • Automatically resets at midnight (or custom time per profile)
  • Uses the firewall's system time
  • Resets both devices and devices_by_ip arrays for backward compatibility

Firewall Rule Management

  • Uses pfSense anchors for dynamic rules
  • No full filter_configure() reloads needed
  • Rules persist across reboots
  • Automatic cleanup of stale rules

🎉 You're Ready to Test!

Your pfSense firewall now has a completely fresh installation of the KACI Parental Control package with all the latest fixes.

Start by:

  1. Creating a test profile
  2. Adding a device (use auto-discover or manual entry)
  3. Setting a short time limit (e.g., 1 hour) for quick testing
  4. Monitoring the Status page to see real-time updates

Test the blocking:

  1. Wait for the time limit to expire (or create a schedule that's currently active)
  2. Try accessing the internet from the blocked device
  3. You should see the block page with the reason and override option

Test the save functionality:

  1. Edit an existing profile
  2. Change the time limit
  3. Click Save
  4. Verify the change was saved (refresh the page)

📚 Documentation

  • README.md - Full package documentation
  • CHANGELOG.md - All changes and version history
  • ANCHOR_GUIDE.md - How the anchor system works
  • BLOCK_PAGE_GUIDE.md - Block page implementation details
  • docs/API.md - API documentation
  • AUTO_UPDATE.md - Auto-update feature documentation

🔄 Updating the Package

The auto-update feature is enabled by default. It will:

  • Check for updates every 15 minutes
  • Pull the latest code from GitHub
  • Deploy changes automatically
  • Log all updates to /var/log/parental_control_update.log

To manually update:

cd /Users/mkesharw/Documents/KACI-Parental_Control
./INSTALL.sh update fw.keekar.com

🗑️ Uninstalling

If you need to remove the package completely:

cd /Users/mkesharw/Documents/KACI-Parental_Control
ssh mkesharw@fw.keekar.com
cd /tmp/KACI-Parental_Control
echo "yes" | sudo ./UNINSTALL.sh

Installation completed successfully! 🎊

You now have a clean slate to test all the features and verify that everything works as expected.

Quick Start

Quick Start Guide - KACI Parental Control

Get Running in 5 Minutes ⚡

Version: 1.4.10+
Author: Mukesh Kesharwani
Last Updated: December 25, 2025

This guide will help you install and configure KACI Parental Control in under 5 minutes.

📋 Prerequisites Checklist

Before you begin, make sure you have:

  • pfSense 2.7.0 or later installed and running
  • SSH access enabled on pfSense (System > Advanced > Admin Access)
  • SSH key authentication set up (optional but recommended)
  • Child devices' MAC addresses identified (see tips below)
  • Network access to pfSense from your computer

Package Dependencies (auto-checked during installation):

  • sudo (v1.9.16p2+) - Installer will offer to install if missing
  • cron (v0.3.8_6+) - Usually pre-installed with FreeBSD base system

💡 How to Find MAC Addresses

On iPad/iPhone:

  • Settings > General > About > Wi-Fi Address

On Android:

  • Settings > About Phone > Status > Wi-Fi MAC Address

On Windows:

  • Open Command Prompt > Type ipconfig /all

On Mac:

  • System Preferences > Network > Advanced > Hardware

On pfSense (easiest method):

  • Status > DHCP Leases (shows all connected devices)
  • Or: Diagnostics > ARP Table

🚀 Step 1: Install Package (2 minutes)

Clone the Repository

# Clone from GitHub
git clone https://github.com/keekar2022/KACI-Parental_Control.git
cd KACI-Parental_Control

Run Installation Script

# Replace 192.168.1.1 with your pfSense IP address
./INSTALL.sh install 192.168.1.1

What this does:

  • Sets up SSH key authentication (if needed)
  • Uploads package files to pfSense
  • Registers the package in pfSense
  • Verifies installation

Expected output:

✓ SSH key authentication configured
✓ Files uploaded
✓ Package registered
✓ Installation verified

Troubleshooting Installation

If you get "SSH key not found":

  • The script will generate one automatically
  • Just follow the prompts

If you get "Permission denied":

  • Make sure you can SSH to pfSense: ssh admin@192.168.1.1
  • Check pfSense SSH settings: System > Advanced > Admin Access

If installation fails:

# Try reinstall mode (cleans up first)
./INSTALL.sh reinstall 192.168.1.1

# Or verify what's wrong
./INSTALL.sh verify 192.168.1.1

🌐 Step 2: Access Web Interface (30 seconds)

  1. Open your web browser
  2. Navigate to your pfSense: https://192.168.1.1
  3. Log in with your pfSense credentials
  4. Go to: Services > Keekar's Parental Control

You should see:

  • Settings tab (main configuration)
  • Profiles tab (manage child profiles)
  • Status tab (real-time monitoring)

👧 Step 3: Create Your First Profile (2 minutes)

Enable the Service

  1. On the Settings tab
  2. Check ✅ Enable Parental Control
  3. Select Enforcement Mode: Strict (recommended)
  4. Click Save

Create a Child Profile

  1. Click the Profiles tab
  2. Click + Add button
  3. Fill in the profile information:

Profile Information:

  • Profile Name: Emma (or your child's name)
  • Description: iPad and iPhone (optional)
  • Profile Icon: 👧 Girl (optional, makes it easier to identify)

Time Limits:

  • Daily Time Limit: 120 minutes (2 hours)
  • Weekend Bonus: 60 minutes (1 extra hour on weekends)
  • Weekly Limit: Leave empty (or set if you want weekly limits too)

Add a Device

  1. In the Devices section, click Add Row
  2. Quick Select: Choose from the dropdown (auto-fills everything) ✨
    • Or manually enter:
      • Device Name: iPad
      • MAC Address: aa:bb:cc:dd:ee:ff (from prerequisites)
      • IP Address: Optional (leave empty for DHCP)

💡 Pro Tip: The Quick Select dropdown shows all devices on your network with their names and MAC addresses. Look for [ONLINE] devices.

Add a Schedule (Optional but Recommended)

  1. In the Schedules section, click Add Row

  2. Bedtime Example:

    • Schedule Name: Bedtime
    • Days: sun,mon,tue,wed,thu (school nights)
    • Start Time: 21:00 (9 PM)
    • End Time: 07:00 (7 AM)

  3. Click Save

🎉 Congratulations! Your first profile is configured!

📊 Step 4: Verify It's Working (30 seconds)

Check Status Dashboard

  1. Go to the Status tab
  2. You should see:
    • ✅ Service Status: Active
    • Your profile name (Emma)
    • Device status (Online or Offline)
    • Usage statistics (0:00 initially)

Test Device Detection

If device shows as "Offline" but it's on:

  1. Make sure the device is connected to the network
  2. Check the MAC address is correct
  3. Wait 1 minute for the cron job to run
  4. Refresh the Status page

If device shows as "Online": ✅ Perfect! You're all set!

Monitor Usage

  • Usage Today: Shows time used today
  • Daily Limit: Shows total allowed time
  • Remaining: Shows time left

The system automatically:

  • ✅ Tracks usage every minute
  • ✅ Blocks when limit is reached
  • ✅ Unblocks at bedtime schedule
  • ✅ Resets counters at midnight

🎯 Common Use Cases

Scenario 1: Multiple Children

Create separate profiles for each child:

Emma (Age 8):

  • Daily: 90 minutes
  • Weekend: +30 minutes
  • Bedtime: 20:00-07:00
  • Devices: iPad, iPhone

Jake (Age 14):

  • Daily: 180 minutes
  • Weekend: +60 minutes
  • Bedtime: 22:00-07:00
  • Devices: Laptop, Phone, Gaming Console

Scenario 2: School Hours Block

Add to any profile:

  • Schedule Name: School Hours
  • Days: mon,tue,wed,thu,fri
  • Start Time: 08:00
  • End Time: 15:00

Scenario 3: Weekend Only (Gaming Console)

  • Daily Time Limit: 180 minutes
  • Schedule: Weekday Block
    • Days: mon,tue,wed,thu,fri
    • Time: 00:00-23:59

Result: Only accessible on weekends

🐛 Troubleshooting

Device Not Being Blocked

Check these in order:

  1. Is service enabled?

    • Settings tab > "Enable Parental Control" should be checked

  2. Is enforcement mode correct?

    • Settings tab > Enforcement Mode = "Strict" (recommended)

  3. Is the MAC address correct?

    # SSH to pfSense
ssh admin@192.168.1.1
# Check ARP table
arp -an

  4. Are firewall rules created?

    • Firewall > Rules > LAN
    • Look for "Parental Control: ..." rules

Time Not Being Tracked

  1. Check Status tab:

    • Is device showing as "Online"?
    • Is "Usage Today" incrementing?

  2. Check cron job:

    ssh admin@192.168.1.1
crontab -l | grep parental

    Should show: */1 * * * * ...

  3. Check logs:

    • Status tab > Recent Log Entries
    • Or SSH: tail -f /var/log/parental_control-$(date +%Y-%m-%d).jsonl

Package Not Appearing in Menu

# SSH to pfSense
ssh admin@192.168.1.1

# Check files are present
ls -la /usr/local/pkg/parental_control*

# Check system log
tail -50 /var/log/system.log | grep parental

# Reinstall if needed
cd /path/to/KACI-Parental_Control
./INSTALL.sh reinstall 192.168.1.1

Device Has Access After Limit Reached

  1. Grace Period: Check Settings tab > Grace Period (default: 5 minutes)

    • Device gets warning time before complete block

  2. Different MAC/IP: Device might be using a different network adapter

    • Check DHCP leases for multiple entries for same device

  3. Rule Order: Parental control rules should be at top of firewall rules

    • If other rules process first, they might allow traffic

🔍 Advanced Tips

View Detailed Logs

ssh admin@192.168.1.1
cd /var/log

# View today's log
cat parental_control-$(date +%Y-%m-%d).jsonl | jq '.'

# Filter by child
cat parental_control-*.jsonl | jq 'select(.Attributes."child.name" == "Emma")'

# Show only errors
cat parental_control-*.jsonl | jq 'select(.SeverityText == "ERROR")'

Health Check Endpoint

Monitor service health:

curl http://192.168.1.1/parental_control_health.php | jq '.'

Manual State Reset

ssh admin@192.168.1.1
rm /var/db/parental_control_state.json
# Service will recreate on next run

📚 Next Steps

Now that you have the basics working:

  1. Read the Full README - /README.md

    • Advanced configuration options
    • Multiple profiles
    • Custom schedules
    • Content filtering

  2. Check Best Practices - /BEST_PRACTICES-KACI-ParentalControl.md

    • Coding standards
    • Logging patterns
    • Troubleshooting tips

  3. Explore Features:

    • Add more children/profiles
    • Set up email notifications
    • Configure weekend bonuses
    • Create custom schedules

  4. Join the Community:

🆘 Need Help?

Documentation

  • README.md - Complete package documentation
  • RECOMMENDATIONS_FOR_ADOPTION.md - Enhancement roadmap
  • BEST_PRACTICES-KACI-ParentalControl.md - Technical guide

Command Reference

# Installation
./INSTALL.sh install <pfsense-ip>      # Full install
./INSTALL.sh reinstall <pfsense-ip>    # Clean reinstall
./INSTALL.sh verify <pfsense-ip>       # Verify install
./INSTALL.sh debug <pfsense-ip>        # Show diagnostics

# Monitoring
ssh admin@<pfsense-ip> "tail -f /var/log/parental_control-*.jsonl"
ssh admin@<pfsense-ip> "crontab -l | grep parental"
ssh admin@<pfsense-ip> "pfctl -sr | grep 'Parental Control'"

Quick Diagnostics

# Run all checks at once
./INSTALL.sh debug 192.168.1.1

✅ Success Checklist

After completing this guide, you should have:

  • Package installed on pfSense
  • Service enabled in web interface
  • At least one child profile created
  • At least one device configured
  • Device showing correct online/offline status
  • Time tracking working (visible in Status tab)
  • Schedules configured (if desired)

Total Time: ~5 minutes ⚡
Difficulty: Beginner-friendly
Status: Ready to use! 🎉

Built with Passion by Mukesh Kesharwani
© 2025 Keekar
Version 1.5.6